Agent Trajectory Observability Format (ATOF)

Use the atof section when you want the raw Agent Trajectory Observability Format (ATOF) 0.1 event stream written as JSONL or streamed to raw-event collectors.

ATOF JSONL export is useful for local debugging, offline inspection, and preserving the canonical event stream before it is translated into another format. Streaming endpoints are useful when a collector wants the same raw event shape in near real time.

plugins.toml Example

1
version = 1
2
3
[[components]]
4
kind = "observability"
5
enabled = true
6
7
[components.config]
8
version = 1
9
10
[components.config.atof]
11
enabled = true
12
output_directory = "logs"
13
filename = "events.jsonl"
14
mode = "overwrite"
15
16
[[components.config.atof.endpoints]]
17
url = "http://localhost:8080/events"
18
transport = "http_post"
19
timeout_millis = 3000

This configuration registers the plugin-managed ATOF exporter and writes one JSON object per lifecycle event to logs/events.jsonl. It also sends each raw ATOF event to the configured endpoint.

Fields

Streaming Endpoints

Each endpoint receives the same raw ATOF JSON object that the file exporter writes as one JSONL line. Endpoints are independent: a failed endpoint is skipped or retried without blocking file output or other endpoints.

• http_post sends each event as one JSONL record in an HTTP POST request with Content-Type: application/x-ndjson. Any 2xx response is treated as success.
• websocket opens one connection and sends each event as one JSON text message.
• ndjson opens one long-lived HTTP upload and writes each event as one newline-delimited JSON record.

force_flush() flushes file output and drains queued endpoint events without closing streaming connections. shutdown() is terminal: it flushes pending work, closes streaming connections, and makes later events no-op.

Expected Output

Each emitted scope, tool, LLM, middleware, or mark event is written as one ATOF JSON object per line. For event field semantics, see Events.

Register the plugin before instrumented work starts and clear it during shutdown so file handles flush.

Plugin Configuration

Use plugin configuration when the application should let NeMo Relay own the ATOF exporter lifecycle.

1
from nemo_relay import plugin
2
from nemo_relay.observability import (
3
    AtofConfig,
4
    AtofEndpointConfig,
5
    ComponentSpec,
6
    ObservabilityConfig,
7
)
8
9
config = plugin.PluginConfig(
10
    components=[
11
        ComponentSpec(
12
            ObservabilityConfig(
13
                atof=AtofConfig(
14
                    enabled=True,
15
                    output_directory="logs",
16
                    filename="events.jsonl",
17
                    mode="overwrite",
18
                    endpoints=[
19
                        AtofEndpointConfig(
20
                            url="http://localhost:8080/events",
21
                            transport="http_post",
22
                        )
23
                    ],
24
                )
25
            )
26
        )
27
    ]
28
)
29
30
report = plugin.validate(config)
31
if any(diagnostic["level"] == "error" for diagnostic in report["diagnostics"]):
32
    raise RuntimeError(report["diagnostics"])
33
34
await plugin.initialize(config)
35
try:
36
    # Run instrumented application work here.
37
    pass
38
finally:
39
    plugin.clear()

Manual API

Use the manual AtofExporter API when a test or script needs a custom subscriber name or explicit registration window.

1
from nemo_relay import AtofEndpointConfig, AtofExporter, AtofExporterConfig, AtofExporterMode
2
3
config = AtofExporterConfig()
4
config.output_directory = "logs"
5
config.filename = "events.jsonl"
6
config.mode = AtofExporterMode.Overwrite
7
config.endpoints = [
8
    AtofEndpointConfig("http://localhost:8080/events", transport="http_post")
9
]
10
11
exporter = AtofExporter(config)
12
exporter.register("atof-exporter")
13
14
# Run instrumented application work here.
15
16
exporter.force_flush()
17
exporter.deregister("atof-exporter")
18
exporter.shutdown()

Common Validation Failures

• mode is not append or overwrite.
• endpoints[i].url is empty, endpoints[i].transport is not supported, or endpoints[i].timeout_millis is 0.
• The output directory is not writable at runtime.
• nemo-relay doctor cannot deliver its synthetic ATOF mark probe to a configured endpoint.
• ATOF is enabled in a target that cannot access the native filesystem.