Signature Journal (Timeline History)

Note: This script requires an API Token to run.

Simscope includes a script simscope-sig-search --journal to search and dump timeline-based Signature Updates from the command-line (or from API) in CSV (comma-separated) or TSV (tab-separated value) formats.

• These updates can either be manual assignment updates, rule executions, or signature/job comments.

Output

The output is returned as a CSV or TSV file (tab-separated value).

The assignee and issue fields are special case fields. They can have any of the following values:

• Blank string — ignore the value (keep the previous record value for this field)
• <null> — special string meaning to clear the field value to a blank value
• Any other string (for example hello) — update the field to this literal string

Each record is a single update to a single Signature job.

NOTE: the results are returned in ascending signature and time order (ie oldest first/newest last), so updates can be applied in order of the results.

Output to File

To output to a file (instead of STDOUT), use the option --output=FILENAME

TSV Output Format

To emit as TSV format, use the option --output-format=tsv

Filter Updates by Signature ID or Job ID

To filter by Signature ID, use the option: --sigid=SIGID

• Example: --sigid=1249

To filter by Job ID, use the option: --sigid=SIGID/JOBID

• Example: --jobid=1249/abcdef

CSV Example

This example dumps all updates between the dates 2020-02-03 to 2020-02-04 in CSV format:

> simscope-sig-search --journal --date-low=2023-02-03 --date-high=2020-02-04

jobid,transaction-type,timestamp,ruleid,state,assignee,issue,comment
1190/cq6yw9t8yszc,rule-extra,2023-02-01 00:13:32.410493052 -0500 -5:00,1190.5,OPEN,pdq,SIM-39,
1190/cq6z8ph9e5wg,rule-extra,2023-02-01 00:29:45.250423014 -0500 -5:00,1190.5,OPEN,pdq,SIM-39,
1190/cq8ie9g57wvc,rule-extra,2023-02-02 19:43:17.688051032 -0500 -5:00,1190.5,OPEN,pdq,SIM-39,
1190/cq9e23a4dgwo,rule-extra,2023-02-03 20:31:51.339249042 -0500 -5:00,1190.5,OPEN,pdq,SIM-39,
1190/cqa01gwe4qls,rule-extra,2023-02-04 13:45:40.909727045 -0500 -5:00,1190.5,OPEN,pdq,SIM-39,
1230/cpooqenysqls,jobs-update,2023-02-01 21:37:05.530047032 -0500 -5:00,,,,,Hello world: this is a comment
1230/cpkqnygdetfs,jobs-update,2023-02-01 21:37:05.530047032 -0500 -5:00,,,,.HELLO,
1230/cpooqenysqls,jobs-update,2023-02-01 21:37:39.027759037 -0500 -5:00,,NEW,<null>,<null>,
1230/cpkqnygdetfs,jobs-update,2023-02-01 21:38:00.025863043 -0500 -5:00,,NEW,<null>,<null>,

Job Metadata Fields

Simscope can dump any additional job metadata fields into the TSV output. Use the --metadata argument for each field.

Note: adding metadata will slow down the search dramatically.

For example, this command will request two additional metadata fields:

> simscope-sig-search --journal --days=1 --metadata=classification --metadata=num_instructions

To see all available metadata registered, go to http://SIMSCOPE:8080/search-help and click the Job Fields Available link.

Metadata Fields available

There are many available metadata fields:

• classification
• designation
• category
• host
• regr
• component
• branch
• or any custom job fields