Job Field Reference
Simscope Jobs are defined with a JSON input format.
Fields with a ✅ are required fields in the JSON.
| Field | Description | Req | Example |
|---|---|---|---|
build | Build configuration/environment for the job | "vcs+2core+cov" | |
category | Job Category | ✅ | "sim" |
compute_ms | Job compute time, in milliseconds See also runtime_ms | ✅ | 12345 (ie 12.345 seconds) |
config | Job test configuration or job command-line (rerun string) | ✅ | "sim +rand +tbuf +seed=1794 LOC=4" |
cycles | Simulation cycles completed (both for pass and fail jobs) | 17237 | |
exit_code | Shell exit code for the job | 100 | |
extid | External service job ID (example: LSF ID) | "1234", "83a203cb6f", etc | |
fail_message | Raw error message (for failing jobs only) | ✅ | "t.cpu.core0.fs7 data mismatch filling store buffer: expected=24'h16a7 actual=24'h76a7" → or use "" for passing jobs |
finish_time | Timestamp when the job finished (RFC-3339) | "0001-01-01T00:00:00Z" | |
host | Host machine where the job ran | "compute-12" | |
jobdir | Directory (path) where job was run. You can alternatively store a URL and Simscope will render a hyperlink. | "/home/runs/myregr/2/job-2" (path)"http://server123/path/to/job/data" (URL) | |
metadata | Custom metadata for this job. (see Job Metadata) | [["transactions", "100"]] | |
result | Job result (pass / fail / skip) | ✅ | "pass" or "fail" or "skip"(NOTE: this value must be lowercase) |
runtime_ms | optional Job wallclock runtime, in milliseconds See also compute_ms | 12345 (ie 12.345 seconds) | |
seed | Job seed (encoded as a string value) | "1794" | |
sourcecode | Test source code. This is similar to the config field, for implementing job rerun, and allows any characters (whitespace, etc).This field requires JSON string escaping. | "# This is JSON\nrun_test(\"stim\", 123)" | |
start_time | Timestamp when the job started (RFC-3339) | ✅ | "2019-05-07T02:00:10.000111-05:00" |
testgroup | Test group | "rand" | |
username | Username (only if different than regression) | "infra" | |
bucket | advanced: custom Signature bucket (see below) | "" (blank: use Simscope's bucketizer)"store buffer" (custom bucketizer) | |
classification | advanced: Classify Signature: auto-classify signature during job import (useful for timeout or perf scenarios). | "timeout" |
Runtime vs Compute Time
→ see Job Runtime.
Custom Job Metadata
You can store arbitrary job metadata fields (string, integer, or float data types). This is useful for tracking performance metrics.
For example, num_transactions = 1280
→ see Custom Job Metadata.
Advanced: Custom Job Bucket
Warning: this
bucketfield should only be used if you have your own bucketizer algorithm. Do not store raw fail messages into thebucketJSON field (this will disable Simscope's signature bucketizer).
Simscope has a built-in Error Bucketizer, which groups and sanitizes error messages into signatures. For smaller organizations, this generic bucketizer works well.
- To use Simscope's built-in bucketizer, omit the
bucketfield from your job JSON.
However, if your group has its own bucketizer, you can bypass Simscope's bucketizer by
providing both a job raw fail_message, and a bucket field into the job JSON.
Here is an example job JSON, using a custom bucketized signature:
{
...
"fail_message": "t.cpu.core0.fs7 data mismatch filling store buffer: expected=24'h16a7 actual=24'h76a7",
"bucket": "core0 store buffer"`
...
}
- Note: if using a custom bucketizer, you must strip numbers, paths, and hierarchies. Otherwise Simscope will create duplicate signatures.
Default Simscope Bucketizer
By default, the builtin Simscope bucketizer will automatically generate the following
Signature bucket, based on the above fail_message:
{
...
"fail_message": "t.cpu.core0.fs7 data mismatch filling store buffer: expected=24'h16a7 actual=24'h76a7",
"bucket": "[HIER].fs_ data mismatch filling store buffer expected ... actual ..."
...
}