Telemetry

Polytoken can export trace data to an OpenTelemetry collector using the OTLP protocol. When you enable telemetry, Polytoken sends spans for agent invocations, model requests, tool executions, and facet transitions.

Enabling telemetry

Polytoken disables telemetry by default. You can enable and configure trace export in the Data pane of polytoken config ui. To enable trace export by editing your user (global) config file, add a telemetry block:

[telemetry]
protocol = "grpc"
endpoint = "http://localhost:4317"

Polytoken reads this block only from your user config. A project config cannot set or override telemetry settings. This prevents repository-owned configuration from redirecting trace data or injecting headers.

Corresponding OTEL_* environment variables supersede the values in this block per the OpenTelemetry SDK environment variable specification. Env vars do not enable export without a telemetry block. Polytoken warns about invalid values and treats them as unset. See the OTel SDK env var spec for the full specification.

Config field	Signal-specific env var	General env var
telemetry.protocol	OTEL_EXPORTER_OTLP_TRACES_PROTOCOL	OTEL_EXPORTER_OTLP_PROTOCOL
telemetry.endpoint	OTEL_EXPORTER_OTLP_TRACES_ENDPOINT	OTEL_EXPORTER_OTLP_ENDPOINT
telemetry.headers	OTEL_EXPORTER_OTLP_TRACES_HEADERS	OTEL_EXPORTER_OTLP_HEADERS
telemetry.service_name	OTEL_SERVICE_NAME	OTEL_RESOURCE_ATTRIBUTES (service.name key)
(no config field)	OTEL_EXPORTER_OTLP_TRACES_TIMEOUT	OTEL_EXPORTER_OTLP_TIMEOUT

Protocols

Polytoken supports two OTLP transports:

• http/protobuf: sends trace data as HTTP POST requests with Protocol Buffers encoding. Configure the collector’s HTTP endpoint (typically port 4318). Polytoken appends the /v1/traces path automatically.
• grpc: sends trace data over a gRPC connection. Configure the collector’s gRPC endpoint (typically port 4317).

Endpoint format

Set telemetry.endpoint to the collector’s origin (scheme, host, and optional port). Polytoken removes a trailing slash and rejects endpoints with other paths, query parameters, fragments, or userinfo.

Endpoints set via OTEL_EXPORTER_OTLP_TRACES_ENDPOINT or OTEL_EXPORTER_OTLP_ENDPOINT follow OTel OTLP rules and may include base paths. Polytoken uses the signal-specific endpoint as-is. For the general endpoint, Polytoken appends /v1/traces for HTTP/protobuf and preserves any base path the endpoint carries.

Valid examples:

# HTTP/protobuf (collector on port 4318)
[telemetry]
protocol = "http/protobuf"
endpoint = "http://localhost:4318"

# gRPC (collector on port 4317)
[telemetry]
protocol = "grpc"
endpoint = "http://localhost:4317"

For remote collectors with TLS:

[telemetry]
protocol = "grpc"
endpoint = "https://collector.example.com:4317"

Custom headers

Use telemetry.headers to attach authentication tokens or routing metadata to each export request. Header values support environment variable substitution:

[telemetry]
protocol = "grpc"
endpoint = "http://localhost:4317"
headers = { "x-api-key" = "${COLLECTOR_API_KEY}" }

Polytoken treats header keys and values as secrets and never writes them to diagnostics, logs, or exported spans.

Service name

By default, Polytoken identifies itself with the service name polytoken. You can override this:

[telemetry]
protocol = "grpc"
endpoint = "http://localhost:4317"
service_name = "my-polytoken-deployment"

The daemon and exec mode both report the same service name. Polytoken distinguishes them with a separate polytoken.execution_mode resource attribute (daemon or exec).

What Polytoken exports

Polytoken exports agent invocation, model request, tool execution, and facet transition spans. The agent, model, and tool spans follow the draft OpenTelemetry GenAI semantic conventions (Development status, revision July 2026).

Agent invocation

Polytoken emits one agent invocation span (INTERNAL kind) per agent turn. The span name is invoke_agent for the main session and invoke_agent {subagent_type} for a subagent. Each span covers the entire turn, including model requests, tool calls, and compaction, and records the provider, model, session ID, prompt ID, and final token usage.

Model request

Polytoken emits one chat {model} span (CLIENT kind) per provider attempt, including a separate span for each retry. Each span has gen_ai.operation.name = chat and records the provider name, model name, and per-request token usage (input, output, cache creation, cache read).

Tool execution

Polytoken emits one execute_tool {tool_name} span (INTERNAL kind) per tool call. Each span has gen_ai.operation.name = execute_tool and records the tool name, tool call ID, session ID, and prompt ID. The span covers the full tool lifecycle including timeout promotion to a background job.

Facet transition

Polytoken emits a point-in-time facet_switch span (INTERNAL kind) after a successful facet transition. Each span records the session ID, previous facet, new facet, and transition trigger. The span also records the prompt ID when the transition has an associated prompt; a rewind restoration has no prompt, so the span omits the prompt ID.

What Polytoken never exports

Polytoken does not export any of the following as span content, regardless of configuration:

• Prompt content, system instructions, or message bodies
• Tool arguments or tool results
• Project paths or filesystem paths
• Environment variable values
• Authentication tokens or header values
• Provider error messages that may contain payloads

The configured service name and request headers intentionally affect telemetry resource attributes and export requests. These are configuration values that you set, not exported data content.

The GenAI semantic conventions mark prompt content, system instructions, message bodies, and tool arguments and results as Opt-In categories; Polytoken does not implement the opt-in. Its own policy excludes the remaining categories.

Failure behavior

Telemetry export is fail-open. If the collector is unreachable, rejects connections, or returns errors, Polytoken continues operating normally. Export failures do not block agent turns. Polytoken does not retry dropped spans beyond the OpenTelemetry SDK’s bounded batch behavior.

Shutdown behavior

When the daemon or exec process exits, Polytoken attempts to flush pending trace data within a bounded deadline. If the collector does not respond in time, Polytoken abandons the flush and exits. Pending spans that the flush did not deliver are lost.