Observability Configuration

Use this page when an application should install standard observability exporters from one plugin configuration document instead of manually registering each subscriber.

The plugin kind is observability. It is registered by the core runtime, so applications do not need to register a plugin implementation before validation or initialization.

For plugin file discovery, precedence, merge behavior, editor controls, and gateway conflict rules, see Plugin Configuration Files.

What It Installs

Every exporter section is optional and defaults to disabled. A section is active only when it includes enabled: true.

subscriber_name is not part of this config. The runtime infers component-local subscriber names and registers them under the observability plugin namespace:

• Agent Trajectory Observability Format (ATOF): __nemo_relay_plugin__observability__atof
• Agent Trajectory Interchange Format (ATIF) dispatcher: __nemo_relay_plugin__observability__atif
• Per-agent ATIF scope subscriber: __nemo_relay_plugin__observability__atif-{agent_scope_uuid}
• OpenTelemetry: __nemo_relay_plugin__observability__opentelemetry
• OpenInference: __nemo_relay_plugin__observability__openinference

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.atif]
17
enabled = true
18
output_directory = "logs"
19
filename_template = "trajectory-{session_id}.json"
20
21
[components.config.opentelemetry]
22
enabled = true
23
transport = "http_binary"
24
endpoint = "http://localhost:4318/v1/traces"
25
service_name = "nemo-relay"
26
service_namespace = "agent"
27
service_version = "0.4.0"
28
instrumentation_scope = "nemo-relay-observability"
29
timeout_millis = 3000
30
31
[components.config.opentelemetry.headers]
32
authorization = "Bearer <token>"
33
34
[components.config.opentelemetry.resource_attributes]
35
"deployment.environment" = "dev"
36
"service.instance.id" = "local"
37
38
[components.config.openinference]
39
enabled = true
40
transport = "http_binary"
41
endpoint = "http://localhost:6006/v1/traces"
42
service_name = "nemo-relay"
43
service_namespace = "agent"
44
service_version = "0.4.0"
45
instrumentation_scope = "nemo-relay-openinference"
46
timeout_millis = 3000
47
48
[components.config.openinference.headers]
49
authorization = "Bearer <token>"
50
51
[components.config.openinference.resource_attributes]
52
"deployment.environment" = "dev"
53
"service.instance.id" = "local"
54
55
[components.config.policy]
56
unknown_component = "warn"
57
unknown_field = "warn"
58
unsupported_value = "error"

Include only the sections you want to configure. In layered plugins.toml files, omission inherits lower-precedence values; write enabled = false to disable an inherited section.

Per-Language Plugin Configuration

1
import asyncio
2
3
from nemo_relay import plugin, scope, ScopeType
4
from nemo_relay.observability import (
5
    AtifConfig,
6
    AtofConfig,
7
    ComponentSpec,
8
    ObservabilityConfig,
9
    OtlpConfig,
10
)
11
12
config = plugin.PluginConfig(
13
    components=[
14
        ComponentSpec(
15
            ObservabilityConfig(
16
                atof=AtofConfig(
17
                    enabled=True,
18
                    output_directory="logs",
19
                    filename="events.jsonl",
20
                    mode="overwrite",
21
                ),
22
                atif=AtifConfig(
23
                    enabled=True,
24
                    output_directory="logs",
25
                    filename_template="trajectory-{session_id}.json",
26
                ),
27
                opentelemetry=OtlpConfig(
28
                    enabled=True,
29
                    endpoint="http://localhost:4318/v1/traces",
30
                    service_name="nemo-relay",
31
                    service_namespace="agent",
32
                    service_version="0.4.0",
33
                    instrumentation_scope="nemo-relay-observability",
34
                    resource_attributes={"deployment.environment": "dev"},
35
                ),
36
                openinference=OtlpConfig(
37
                    enabled=True,
38
                    endpoint="http://localhost:6006/v1/traces",
39
                    service_name="nemo-relay",
40
                    service_namespace="agent",
41
                    service_version="0.4.0",
42
                    instrumentation_scope="nemo-relay-openinference",
43
                    resource_attributes={"deployment.environment": "dev"},
44
                ),
45
            )
46
        )
47
    ]
48
)
49
50
report = plugin.validate(config)
51
if any(diagnostic["level"] == "error" for diagnostic in report["diagnostics"]):
52
    raise RuntimeError(report["diagnostics"])
53
54
async def arun():
55
    async with plugin.plugin(config):
56
        with scope.scope("agent", ScopeType.Agent):
57
            pass
58
59
asyncio.run(arun())

Validation And Teardown

Validate plugin configuration before activating it. The plugin reports unsupported transports, unsupported ATOF modes, unsafe ATIF filename templates, unknown fields according to policy, and enabled exporters that are unavailable in the current build or target.

Call plugin.clear() or clear_plugin_configuration() during teardown. Clearing the plugin config deregisters inferred subscribers, flushes file exporters, and shuts down owned OTLP subscribers.

Use manual subscriber/exporter APIs instead of the plugin when you need custom subscriber names, explicit per-run exporter objects, or direct control over the collection window.