Annotations

Learn how to annotate traces in Explorer to add context and structure

In addition to hosting agent traces, Explorer can also be used to annotate traces with additional information, as created in error analysis, human labeling or by other means.

Annotations provide additional context, facilitating collaboration and agent error and security analysis.

An annotated trace in Explorer

Annotation Format

You can add annotations to traces at upload time. For this, both during file upload and via the Push API, you can include an annotations field in the trace data. This field should be an array of objects, each representing an annotation. Each annotation object should have the following fields:

content string

The content of the annotation.

address string

The address of the span to annotate. This should be in the format <path>:<start>-<end>, where <path> is the path to an object in the event log, and <start> and <end> are the start and end indices of the character range to annotate.

extra_metadata Optional[Dict[Any, Any]]

Additional metadata for the annotation.

Each metadata dictionary can have arbitrary keys and values for storing additional information about the annotation.

Example Annotation

{
    "content": "This is an example annotation",
    "address": "messages.0.content:5-10",
    "extra_metadata": {
        "source": "my-analyzer"
    }
}