Skip to content

Telemetry

A box records every policy decision it makes, every change to its own authority, each unmatched MCP route, and every span, log record, and metric the workload exports. A [telemetry.*] table in box.toml declares the target those records reach, and include states which records that target receives.

This page covers a file target, which appends records to a path the operator names, and the endpoints a box sends to directly: an otlp endpoint, Langfuse, LangSmith, and CloudWatch. A box that declares no table writes to a default target. See The default target.

A box with no [telemetry] table writes one file inside its own box directory:

<box_dir>/private/telemetry/records.jsonl

That target receives every record: each effective denial, each effective permit, the box’s own control-plane records and MCP routing diagnostics, and the workload’s relayed spans, log records, and metrics. The workload cannot reach the file.

The file grows for as long as the box is used. Rotate or remove it as the operator’s own task.

The file is not tamper evident. Box signs no record and chains no record to the next, so anything running under the operator’s own account can edit it afterwards. What the box keeps out is the workload.

A declared target replaces this default rather than adding to it, so a box that declares a file of its own writes no record to private/telemetry/records.jsonl.

[telemetry.decisions] is the target a box declares:

[telemetry.decisions] # every decision this box takes, recorded
kind = "file"
destination = "~/boxes/codex/records.jsonl"
include = ["deny", "permit", "trace", "logs"]

A file table takes three keys. An unknown key is refused.

KeyTypeDefaultMeaning
kindstringnone, requiredfile. Endpoints lists the other kinds.
destinationstringnone, requiredThe file the records go to, as stated below.
includearray of stringsevery recordWhich records reach this target: deny, permit, trace, logs, or metrics.

A file target receives one OTLP-JSON request per line, appended. Each line is a complete resourceLogs, resourceSpans, or resourceMetrics request.

The destination is an absolute path, ~, or a path that begins with ~/. Box expands a leading ~ to the operator’s home. These destinations are refused:

DestinationMessage
A relative path, such as records.jsonla file destination must be absolute or begin with `~/`
A path that carries a .. componentcarries a `..` component
A path inside box_dir and outside private/is inside the box directory ... but outside its private tree

Name a destination outside every path the agent may write. Box does not compare the destination against [agent.filesystem], so a file inside a granted directory is a file the agent can truncate. The default destination needs no such care, because it sits in the box directory, which the agent cannot reach.

Declare one target per file. Two boxes that append to one file can tear a line.

Omit include and the target receives every record. Write include and the target receives only the records the words in the list name:

WordThe target then receives
denyEvery effective denial.
permitEvery effective permit.
traceThe workload’s own spans, and this box’s control-plane records.
logsBox’s unmatched MCP routing diagnostics and the workload’s log records.
metricsThe workload’s metrics.

So include = ["deny"] writes a file of refusals, and leaves out the permits, control-plane records, and MCP routing diagnostics.

The workload’s log records and metrics are on by default. They reach every target, and no value of include keeps them out. The word logs selects Box’s MCP routing diagnostics; the workload’s own logs arrive even without it. The word metrics is optional. The file include = ["deny"] writes therefore holds the denials, plus whatever log records and metrics the workload itself exported.

trace names two things at once. A target that omits trace receives no control-plane record, so this box’s box_started, policy_installed, and box_stopped records are absent from it.

An empty list is refused, and so is a repeated word.

An endpoint target sends each batch from the box itself, over OTLP/HTTP with protobuf. The batch does not go through the egress gateway, and policy makes no decision for it. The workload never holds the target’s credential.

Write the vendor’s kind, and Box sets the vendor’s path, headers, and credential placement:

[telemetry.langfuse]
kind = "langfuse"
destination = "https://us.cloud.langfuse.com"
secret.ref = "env://LANGFUSE_AUTH" # public-key:secret-key
[telemetry.cloudwatch_logs]
kind = "cloudwatch_logs"
region = "us-west-2"
log_group = "my-group"
log_stream = "my-stream"
secret.ref = "aws://my-profile"
KindWhat it receivesWhat the operator writes
otlpevery payload, or the payloads accepts namesdestination, and optionally accepts, headers, and secret
langfusespanssecret.ref, and destination for a region or a self-hosted Langfuse
langsmithspanssecret.ref, and optionally project and destination
cloudwatch_logslog recordsregion, log_group, log_stream, and an aws:// or credsd:// secret.ref
cloudwatch_tracesspansregion, and an aws:// or credsd:// secret.ref

A vendor that takes only spans is sent no log or metric batch. That is the one exception to the rule that the workload’s log records and metrics reach every target.

config.md lists every key, and what each kind sets.

secret.ref names where the box reads the key: env://NAME or secret://NAME for a variable in the environment of strands-box run, or aws://PROFILE or credsd://ENVIRONMENT for a SigV4 signature. The box holds the key in a vault of its own for each target, and attaches it on each request. A literal key is refused, and so is a file:// or op:// reference.

A credential needs an https:// destination, unless the destination is loopback.

Box sends each batch once, with one four-second deadline that covers the credential lookup and the send. A batch that fails is counted, and the box does not retry it. When the run ends, Box prints one line on stderr with the count (see Errors and exit codes). To see why a send failed, set STRANDS_BOX_TELEMETRY_DEBUG to any non-empty value in the environment of strands-box run. Box then also prints each failure on stderr as it happens, with its full cause and the start of the endpoint’s answer. Box redacts each credential it attached from that answer, so an endpoint that echoes a refused key does not put the key in your logs:

strands-box: telemetry export failed: https://cloud.langfuse.com/api/public/otel/v1/traces answered 401 Unauthorized: ...

OpenTelemetry calls each kind of telemetry a signal. Three of them apply here: traces, logs, and metrics.

Box relays the workload’s spans, log records, and metrics. These records exist only when the workload exports them, so two settings apply: the workload’s own exporter setting, and a target that accepts the signal.

Box binds one loopback port for the workload and sets three variables in its environment:

VariableValue
OTEL_EXPORTER_OTLP_ENDPOINThttp://127.0.0.1:<port>, where the port is this box’s own
OTEL_EXPORTER_OTLP_TRACES_ENDPOINTthe same address with /v1/traces appended
OTEL_EXPORTER_OTLP_PROTOCOLhttp/protobuf

Box owns every name that begins with OTEL_EXPORTER_OTLP_, so [agent] env may not set one. The receiver answers /v1/traces, /v1/logs, and /v1/metrics, and answers 404 on every other route.

The exporter switches belong to the workload, so write them in [agent] env:

[agent.env]
OTEL_TRACES_EXPORTER = "otlp"
OTEL_LOGS_EXPORTER = "otlp"
OTEL_METRICS_EXPORTER = "otlp"

A switch left at none means that signal never arrives, whatever include names. The OpenTelemetry default metric interval is 60 seconds, so a short run ends before the first metric leaves. Set OTEL_METRIC_EXPORT_INTERVAL in [agent] env for a short run.

Each box record names its origin on its resource:

KeyValue
service.namestrands-box
strands.box.namethis box’s ID: the one the library caller supplied, or a generated box- and 16 hexadecimal characters
strands.box.sourcebox for a record the box wrote, and agent for a relayed payload
strands.box.run.idone identifier per strands-box run invocation

Each effective decision produces one log record and one span that share a trace ID and a span ID. The log record’s event_name field is strands.box.policy.decision, and the scope is strands-box.policy.

GroupKeys
The decisionstrands.box.policy.action, .resource, .verdict, .cause, .reason on a denial, and .principal
The governing rulestrands.box.policy.rule, .description, .category, and .determining.ids, which lists every policy that determined the decision
Correlationstrands.box.request.id on an egress decision, jsonrpc.request.id on an MCP request, and strands.box.trace.parent_span_id on the log record
What it was aboutserver.address and server.port on a network decision, http.request.method on a request, file.path on an fs:* decision, and process.command, process.command_args, and process.working_directory on a shell decision

strands.box.policy.verdict holds deny or permit. strands.box.policy.cause holds one of six values: permitted, forbidden, no_match, policy_pending, internal_fault, and enforcement.

A record whose cause is internal_fault also carries the key error.type, with the value strands.box.policy.evaluation_error.

The action value carries the vocabulary term alone, so a reader sees fs:read rather than Box::Action::"fs:read". Every other value is reported as the enforcement point holds it. A spawn that a tool grammar decides reports the grammar action, so Tool::git::Action::"push" reads as the action push in the category Tool::git.

Two keys are excluded: url.full and process.command_line.

process.command_args reports each argument after expansion, because the Shell does not say which words the script stated literally. For each argument, the record reports:

The expanded argumentWhat the record carries
A short flag, such as -lthe flag
A long flag of at most 32 lowercase letters and dashes, such as --verbosethe flag
A long flag with a value, such as --output=secretthe name, and <redacted> for the value
Anything else<redacted>

At most 64 arguments are reported. One attribute carries at most 4 KiB, and a longer value is cut on a character boundary and ends with … (truncated).

When an MCP alias invocation matches no declared command, Box writes an informational log record with event name strands.box.mcp.unmatched in the strands-box.mcp scope. process.command names the received program, and process.command_args follows the expanded-argument redaction rules above. The record includes request identifiers and parent trace context when available.

The diagnostic carries no policy verdict, action, or rule. Box writes it before replying to the alias, so it does not say whether ordinary execution starts or succeeds. It produces no span. Targets receive it when include is omitted or contains logs.

A control-plane record states one change to the authority this box holds. The scope is strands-box.control, and each operation also produces a span named control <operation>.

KeyValue
strands.box.control.operationpolicy_installed, policy_refused, schema_installed, discovery_complete, box_started, or box_stopped
strands.box.control.outcomeok, or refused
strands.box.control.subjectwhat the operation was about
strands.box.control.reasonwhy a refusal happened
strands.box.control.detailfurther text the operation carries

A records file can hold several scopes, so a query selects one. A box records that it started before it decides anything, so the first record in the file is a control-plane record.

Every denial, one per line:

Terminal window
jq -r 'select(.resourceLogs)
| .resourceLogs[].scopeLogs[]
| select(.scope.name == "strands-box.policy")
| .logRecords[].attributes
| map({(.key): .value.stringValue}) | add
| select(.["strands.box.policy.verdict"] == "deny")
| "\(.["strands.box.policy.action"]) \(.["strands.box.policy.resource"])"' \
~/boxes/codex/records.jsonl

Example output:

fs:read ~/.ssh/id_rsa

What this box did to its own authority:

Terminal window
jq -r 'select(.resourceLogs)
| .resourceLogs[].scopeLogs[]
| select(.scope.name == "strands-box.control")
| .logRecords[].attributes
| map({(.key): .value.stringValue}) | add
| "\(.["strands.box.control.operation"]) \(.["strands.box.control.outcome"])"' \
~/boxes/codex/records.jsonl

Example output:

box_started ok
policy_installed ok
discovery_complete ok
box_stopped ok

Select on strands.box.source to tell a box record from a relayed one. A severity number is the box’s own routing, and it is not a filter for a reader.

The file needs no conversion, so any viewer that reads OTLP-JSON opens it directly. otel-tui is one such tool:

Terminal window
otel-tui --from-json-file ~/boxes/codex/records.jsonl

A telemetry error stops the run before the workload starts, so the agent never runs. strands-box prints the reason on stderr and exits 1.

Exit 1 alone does not prove that Box refused, because a workload is free to exit 1 as well. The message does: Box prefixes every line it prints with strands-box:.

What the operator seesCause
names no signal, so nothing would reach itinclude is an empty list.
names <word> twiceinclude repeats a word.
a file destination must be absolute or begin with `~/` A file destination is relative.
carries a `..` componentA destination carries ...
is inside the box directory ... but outside its private treeA file destination sits where a process could truncate it.
a `<kind>` target sets `<key>` itself, so leave it outA vendor kind names a key it sets.
`<key>` does not apply to a `<kind>` targetA key belongs to another kind.
a `cloudwatch_logs` target needs `log_group` and `log_stream` A CloudWatch Logs target names no group or stream.
needs `region`, an AWS region such as `us-west-2` A CloudWatch target names no region, or an invalid one.
`secret.ref` names no scheme this box readsThe reference is a literal value, or a scheme other than env://, secret://, aws://, or credsd://.
its destination is neither https nor loopbackA credential would cross the network in the clear.
the `aws://` credential cannot signThe profile is missing, or holds no static keys. The run stops before the workload starts.

Each message names the table it came from.

A target that fails while the box runs loses the record, and Box does not retry. When the run ends, Box prints one line on stderr if an export to a configured target failed, or if the final export did not finish in time:

strands-box: warning: telemetry records were lost: 2 exports to the configured targets failed

The count is exports, not records: one export can carry many records. The run’s exit code does not change. The line does not cover everything that can be lost: a record that the telemetry queue refuses when it is full, an agent payload that Box refuses, a batch that a slow target does not accept before its export deadline while the box runs, and a relayed payload still in flight at shutdown are not counted. So the absence of this line does not prove that nothing was lost.

Set STRANDS_BOX_TELEMETRY_DEBUG to also print each failed export as it happens, with its cause. See Failed sends.

  • Getting started: install Box, then run Claude Code or Codex in a box.
  • How telemetry works: which process records, what a workload cannot forge, and where a record can be lost.