94. Matcher runs

A matcher run searches the ingested log generated during an ingestion run for occurrences of match scenarios. The matcher operates on the ingestion step results. It reads the provided OSC2 top-level file that specifies the scenarios to look for. Each scenario definition can include scenario-specific coverage and KPI collection instructions. See an example of an OSC2 top-level file.

The matcher scans the provided run and tries to identify instances of the provided scenarios. It considers all possible actors for every actor role specified in the scenario declaration. If all assigned actors behave as specified by the scenario, a match instance is found.

94.0.1 Making a matcher run

Invoke the Evaluation Pipeline matcher by executing $FTX/logiq/bin/logiq_matcher using the parameters described below.

Parameters

Mandatory flags:

--osc_file <OSC file path>: The top OSC2 file path. The top file should invoke all the evaluation scenarios to match against, under a top.main extension. See example blow.
--object_list <object list path>: Path to the object list file used during ingestion in the Foretellix-defined object list data structure.
--input_dir <ingestion directory path: Path of the ingestion run directory.

Optional flags:

--output_prefix <string>: Matcher output directory name prefix. The default name of an output directory is composed of the date, time and a four-character hash string, similar to Foretify output directories. If this flag is used, the provided prefix will be prepended to the automatically generated default name.
--output_dir <prefix> (DEPRECATED): Matcher output directory name prefix. The default name of an output directory is composed of the date, time and a four-character hash string, similar to Foretify output directories. If this flag is used, the provided prefix will be prepended to the automatically generated default name.
--work_dir <work dir path>: Evaluation Pipeline work directory. The matcher results directory will be created under <work directory>/runs/<run directory name>. Note that the run directory name is auto-generated. All relative paths provided will be resolved using the work directory as the current directory.
--match_only: Skip the OSC compilation step, when using pre-compilation. Pre-compilation is useful when multiple Evaluation Pipeline matcher runs use the same OSC evaluation scenarios for matching. See the following section for more information about pre-compilation.
--comp_dir <compilation dir path>: The path of the pre-compiled OSC scenario file, when used with --match_only. Otherwise it directs the compilation output to the specified directory path

94.0.2 Top OSC file for matching

The following is an example of a top level file for scenario matching.

# Copyright (c) 2019-2024 Foretellix Ltd. All Rights Reserved.

# Import required scenarios from the scenario library
import "$FTX/logiq/scenario_library/junctions/ego_traverse_junction_with_npc/ego_traverse_junction_with_npc_top.osc"

# Invoke the scenarios
match:
    # Add instantiations here, using the following pattern
    #
    # match:
    #    <label>: sut.<scenario_name>(<list of arguments>)

    ego_traverse_junction_with_npc: sut.ego_traverse_junction_with_npc(min_offset_from_junction_end: -5m, max_offset_from_junction_end: 5m)

    # Wait until the end of test
    wait @top.end_of_test

94.0.3 Pre-compiling the evaluation scenarios

The same list of evaluation scenarios is often used in multiple Evaluation Pipeline matcher runs. Instead of compiling the OSC files for each individual matcher run, you can pre-compile the files and provide the compilation directory using the --comp_dir flag.

When running with the pre-compiled option, there is no need to specify the --osc_file parameter which is otherwise required.

To prepare a pre-compiled output, use the following command:

$FTX/logiq/bin/logiq_matcher --compile_only --osc_file <top OSC file path> --comp_dir <directory for compiler output>

To run with pre-compiled OSC files, the --match_only flag should be used.

94.1 After running the matcher

Once you run the matcher, you upload the results directories to Foretify Manager for analysis and debugging.