Tracing

Start with console logging while building your agent. Add OpenTelemetry when you want to inspect runs in Radiant Platform or another trace backend. TracingPlugin installs the shared subscriber and graph/model/tool instrumentation; DevToolsPlugin adds per-system metadata and optional graph event logs.

Console logging

Register tracing once per process, before running agent work:

use polaris_ai::plugins::{FmtConfig, ServerInfoPlugin, TracingPlugin};
use polaris_ai::system::server::Server;

let mut server = Server::new();
server
    .add_plugins(ServerInfoPlugin)
    .add_plugins(TracingPlugin::default().with_fmt(
        FmtConfig::default().env_filter("info,polaris=debug")
    ));
server.finish().await?;
// Execute your agent here.
server.cleanup().await;

This is a fragment inside an async function returning Result. Without with_fmt, the plugin does not add console output. FmtConfig::format accepts Pretty, Compact or Json; span_events(true) also prints span entry and exit. Use with_level(tracing::Level::DEBUG) when you need to change the plugin’s default level.

Export to Radiant Platform

Add otel to the features of your existing pinned Polaris dependency (retain any provider features you already use):

[dependencies]
polaris-ai = { git = "https://github.com/RadiantAILabs/polaris", rev = "5ff84646db63589d58bf87956976d749b8c754de", features = ["otel"] }

Use the traces endpoint and ingestion key from your Platform project. The endpoint may have a different host from the dashboard.

use polaris_ai::plugins::{OpenTelemetryPlugin, ServerInfoPlugin, TracingPlugin};
use polaris_ai::system::server::Server;

let endpoint = std::env::var("RADIANT_TRACES_ENDPOINT")?;
let key = std::env::var("RADIANT_INGESTION_KEY")?;
let mut server = Server::new();
server
    .add_plugins(ServerInfoPlugin)
    .add_plugins(TracingPlugin::default())
    .add_plugins(
        OpenTelemetryPlugin::new(endpoint)
            .with_service_name("my-agent")
            .with_env_filter("info,polaris=debug")
            .with_export_header("Authorization", format!("Bearer {key}"))
    );
server.finish().await?;
// Execute your agent here, using its model/tool/session plugins.
server.cleanup().await;

The header above uses an ordinary space after Bearer; percent encoding is only needed when encoding exporter headers into an environment-variable list. The plugin exports OTLP over HTTP, using binary protobuf by default. cleanup().await flushes pending spans before process exit.

Session turns emit invoke_agent spans with agent identity and conversation identifiers. Model and tool spans provide the execution beneath that invocation. Check Platform connection setup and traces and runs if traces arrive but do not appear as expected in agent views.

Decide what content to capture

Model inputs/outputs are opt-in through TracingPlugin::with_capture_genai_content(). Enable this only for payloads you intend to export. InspectionPlugin separately supports parameter captures declared with #[system(inspect(...))]; its inspection policy is off by default and supports redaction rules. See the public inspection reference.

Graph debugging

Add DevToolsPlugin::new().with_event_tracing() to log graph events at debug level. Ensure your subscriber filter permits those events. A system can read the injected SystemInfo:

use polaris_ai::graph::SystemInfo;
use polaris_ai::system::{system, param::Res};

#[system]
async fn instrumented(info: Res<SystemInfo>) {
    tracing::info!(system = info.system_name(), node = ?info.node_id(), "executing");
}

The event stream includes graph, system, branch, loop, parallel, scope and dynamic-node activity. Use it to identify the first failed step, which branch ran and how many iterations were required.

Custom subscriber layers

A plugin can contribute a layer through the build-time TracingLayers resource before TracingPlugin::ready installs the subscriber. Declare that the plugin extends the TracingLayers capability, then call push during build. The current type is TracingLayers, not TracingLayersApi.

See the TracingLayers API for a complete custom-layer example. For most applications, with_fmt and OpenTelemetryPlugin cover the required setup.