Observability Plugin

Agent Trajectory Observability Format (ATOF)

View as Markdown

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

ATOF JSONL export is useful for local debugging, offline inspection, and preserving the canonical event stream before it is translated into another format.

plugins.toml Example

1version = 1
2
3[[components]]
4kind = "observability"
5enabled = true
6
7[components.config]
8version = 1
9
10[components.config.atof]
11enabled = true
12output_directory = "logs"
13filename = "events.jsonl"
14mode = "overwrite"

This configuration registers the plugin-managed ATOF exporter and writes one JSON object per lifecycle event to logs/events.jsonl.

Fields

FieldDefaultNotes
enabledfalseMust be true to write events.
output_directoryCurrent working directoryDirectory containing the JSONL file.
filenameTimestamped nemo-relay-events-*.jsonlExplicit output filename.
modeappendappend or overwrite.

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.

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

Manual API

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

1from nemo_relay import AtofExporter, AtofExporterConfig, AtofExporterMode
2
3config = AtofExporterConfig()
4config.output_directory = "logs"
5config.filename = "events.jsonl"
6config.mode = AtofExporterMode.Overwrite
7
8exporter = AtofExporter(config)
9exporter.register("atof-exporter")
10
11# Run instrumented application work here.
12
13exporter.force_flush()
14exporter.deregister("atof-exporter")
15exporter.shutdown()

Common Validation Failures

  • mode is not append or overwrite.
  • The output directory is not writable at runtime.
  • ATOF is enabled in a target that cannot access the native filesystem.