13. Custom data

Custom data allows you to attach metadata to object lists at two levels: per-object and per-log (root level). This metadata flows through the Evaluation Pipeline, is available for evaluator definition, appears as run attributes in Foretify Manager, and is visible in the Single Run Debugger.

13.1 Object-level custom data

Attach key-value pairs to individual objects in the object list to pass object-specific information. Use this data for checking, coverage collection, and custom modifiers.

In the protobuf definition, each object has a custom_data field:

repeated Pair custom_data = 21; // key-value string pairs

Each Pair contains a string key and a string value. The key must follow variable name conventions.

13.1.1 Setting object-level custom data

When creating an object list, add custom data entries to each object as needed:

custom_data = obj.custom_data.add()
custom_data.key = "my_attribute"
custom_data.value = "my_value"

Object-level custom data is available in OSC2 scenarios through the custom_data field of actors and can be used in watcher modifiers, checkers, and coverage functions.

13.2 Root-level custom data

Attach global metadata that describes log-level properties to the Root message. This is the recommended approach for metadata that applies to the entire log rather than to individual objects.

map<string, ftx.proto.AdditionalInfoData> custom_data = 16;

Unlike object-level custom data (which uses simple string pairs), root-level custom data supports rich typed values through the AdditionalInfoData message.

13.2.1 Supported value types

13.2.2 Setting root-level custom data

When building the object list, populate the custom_data map on the Root message:

from shared_pb2 import AdditionalInfoData

root = Root()
entry = root.custom_data["source_url"]
entry.string_value = "s3://my-bucket/data/my-recording.zip"

entry = root.custom_data["record_id"]
entry.string_value = "2990270a-34b1-4104-aa50-1dd685fb12fa"

The map keys must follow variable name conventions (alphanumeric characters and underscores).

13.3 Custom data in the Evaluation Pipeline

13.3.1 Denoising

The denoiser can filter object-level custom data based on configuration. Define filter parameters in the denoiser configuration YAML file using the custom_data_filter_params section.

13.3.2 Evaluation traceability

Root-level custom data is propagated into the EvaluationTraceability message during pipeline processing:

message EvaluationTraceability {
    // ...
    map<string, AdditionalInfoData> custom_data = 7;
}

This ensures the metadata is preserved through ingestion and is included in the run summary that gets uploaded to Foretify Manager.

13.4 Custom data in Foretify Manager

When run results are uploaded to Foretify Manager, each key-value pair in evaluationTraceability.customData is automatically registered as a run attribute in the database.

• If the attribute does not already exist, Foretify Manager creates it (similar to custom attributes in triage).
• The attribute name is the custom data key, and the attribute value is the custom data value.
• Attributes are subject to a slot limit. The default limit is 200 attributes and the maximum is 800. If the limit is reached, additional keys are dropped and a warning is logged. To change the limit, set the following property in application.properties:

test-run.evaluation-attributes.max-attributes=200

13.4.1 Viewing custom data in the Runs page

Custom data attributes appear as columns in the Runs page table. Add or remove these columns using the column selector to display the custom data fields relevant to your analysis.

13.4.2 Filtering by custom data

Custom data attributes are available as run filters in workspaces. For example, filter by source_url to focus on runs from a specific data source, or by record_id to locate a specific recording.

To filter and sort runs programmatically, see Evaluation Attributes in SDK.

13.4.3 Viewing custom data in the Single Run Debugger

Custom data is visible in the Single Run Debugger in two places:

• Summary page — Root-level custom data fields appear under Evaluation Data alongside other evaluation traceability information such as split count and overlap.
• Trace area — Root-level custom data appears under Evaluation Data.

For example, if you set source_url and record_id as root-level custom data in the object list, these fields appear in the summary page under Evaluation Data with their corresponding values.