Regression Names

Example regression names:

alpha_cpu_smoke_daily/1234
alpha_cpu_smoke_daily/2023.04.01_12.22.53 (timestamp based)
beta_lsu_interop-202 (using - separator)

Uniqueness Constraint

Regressions can have any string name, but they must be unique globally within Simscope.

If two Components launch a regression called smoke/10, these will automatically be merged into one regression, which may not be the desired behavior.

To fix this, these regressions should have a unique prefix or suffix, like alpha_cpu_smoke_nightly/10 or beta_gpu_smoke/10.

Regression Series Name Grouping

Simscope will automatically group regressions together into a Regression Series, if they have a name suffixed by /<NUMBER> (ie slash-number).

For example, a regression named alpha_cpu_smoke_nightly/99
- Simscope automatically assumes this is followed by alpha_cpu_smoke_nightly/100 and is preceded by alpha_cpu_smoke_nightly/98.

Series Separator Configuration

Administrators can change the regression separator character to any character of your choice, via simscope.config by setting the seriesseparator field to your desired separator:

/ (slash)
. (dot)
- (dash)
: (colon)
etc.

This example changes the separator to a - dash (e.g. cpu_smoke_nightly-99):

[regr]
# Regression name separator.
# Example: "beta_cpu_smoke_nightly/123"
#seriesseparator = "/"

# Example: "beta_cpu_smoke_nightly.123"
#seriesseparator = "."

# Example: "beta_cpu_smoke_nightly-123"
seriesseparator = "-"

Latest Series Regression (`$`)

Simscope has a magic $ suffix, to indicate Latest Regression in a series, using a fixed URL.

If you replace a regression with SERIES_PATTERN/$, Simscope will open the latest regression.

For example, if the latest beta_cpu_smoke regression is 1204
- Then the regression name beta_cpu_smoke/$ will point to beta_cpu_smoke/1204 automatically

This feature allows both scripts to locate the latest regression with a $, and allows a fixed browser bookmark to always point to the latest regression.

Also, Simscope will now autorefresh if your browser is on a $ URL, it will automatically point toward the latest run. This allows a user to have a browser tab that continually updates as new regressions launch.

This example screenshot shows monitoring the latest cpu_core_saturn_daily regression:

Latest regression

Latest via Script/Curl

Latest $ feature works with scripts or curl as well:

For example, if you access the Simscope URL:

/api/r/cpu_score_saturn_daily/$

This URL will point to the latest regression in the series.

Python Regression ID from Timestamp (YMD)

If you want to generate a timestamp-based regression name (based on the regression start timestamp):

Here is a Python code snippet (assuming you have a datetime variable called regr_start):

# Note: if you need a start timestamp variable:
# regr_start = datetime.now()

run_name = 'my_block_smoke'
run_id = '%s/%s' % (run_name, regr_start.strftime('%Y.%m.%d-%H.%M.%S'))

Example run:

my_block_smoke/2024.04.11-14.30.48

Python Series ID generator

If your regression flow does not have a unique regression series ID, you can use this Python code to create one.

Notes:

This code is safe to use from multiple processes, as it uses OS file locking.
- This requires the filelock Python package (see installation below).

# next_series_id: make a unique run/regression ID for Simscope.
#
# VerOps, Inc.
# https://verops.com

# Note: to install the filelock library, run:
# > python3 -mpip install filelock

import filelock
import os
import sys

def next_series_id(id_path, permissions=0o664, timeout=60):
    '''
    next_series_id returns the next series integer from an id file (returning a unique series ID).
    It auto-increments the file after completion.
    permissions: file read/write permissions (for group sharing)
    timeout: number of seconds before lock acquisition times out (or set to zero for unlimited wait time).
    Note: this uses a filelock library, to ensure safe multithreaded access.
    '''

    id = 1
    try:
        lock = filelock.FileLock(id_path + '.lock', timeout=timeout, mode=permissions)

        with lock:
            if os.path.isfile(id_path):
                f = open(id_path, 'r')
                content = f.read().strip()
                f.close()

                if content.isdigit():
                    # read-modify-write
                    id = int(content)
                    id += 1

            f = open(id_path, 'w')
            f.write(str(id))
            f.close()
            os.chmod(id_path, permissions)

    except Exception as e:
        # Lock failed, likely due to timeout or permissions
        sys.stderr.write('WARNING: failed to acquire next_series_id(%s): %s\n' % (id_path, e))
        raise

    return id

Example usage in a regression script:

run_id = next_series_id('/shared/project/alpha_my_smoke.num', timeout=30)
run_name = 'alpha_my_smoke/%d' % run_id

print(run_name)

# After running, this will print a unique regression name, similar to:

→ "alpha_my_smoke/3"

Simscope Administration Guide