Telemetry¶

Telemetry is disabled by default. When enabled, the server exports correlated MCP request spans, fixed operational events and request count/duration metrics to an OTLP collector over HTTP/protobuf or gRPC. It works with both stdio and HTTP MCP connections.

For an HTTP/protobuf collector on port 4318:

export JUSTPEN_UTILITY_OTEL_ENABLED=true
export JUSTPEN_UTILITY_OTEL_PROTOCOL=http/protobuf
export JUSTPEN_UTILITY_OTEL_ENDPOINT=http://127.0.0.1:4318
export JUSTPEN_SESSION_ID=pentest-example
export JUSTPEN_UTILITY_OTEL_RESOURCE_ATTRIBUTES=justpen.run.id=run-example,deployment.environment.name=local
export JUSTPEN_UTILITY_OTEL_REQUIRE_SESSION=true
uv run python -m justpen_utility_mcp

The endpoint above is the telemetry collector, separate from the MCP listener. Pass these environment variables through the MCP client when it launches a stdio server.

Session and process identity¶

justpen.session.id is a resource attribute on every enabled signal and comes only from JUSTPEN_SESSION_ID. Additional resource attributes cannot replace it. Missing or invalid values do not fall back to request metadata, HTTP headers or native client session fields. Set JUSTPEN_UTILITY_OTEL_REQUIRE_SESSION=true to reject enabled startup without a valid session.

Use the same session ID for one assessment and its retests. An optional justpen.run.id can distinguish runs. One process has one fixed session/run resource and a generated service.instance.id. IDs accept 1–128 ASCII letters, digits, periods, underscores, colons and hyphens. Additional resource attributes use comma-separated, percent-encoded key=value entries.

The default resource contains service.name=justpen-utility-mcp, the package version and a process instance ID. Filter the backend on the resource field justpen.session.id. Sampling, retention and collector delivery still determine which records are available.

Settings¶

All settings below use the prefix JUSTPEN_UTILITY_OTEL_. JUSTPEN_SESSION_ID is the sole exception. Booleans accept true or false, case-insensitively. Invalid values produce diagnostics without printing their contents.

Suffix	Meaning / default
`ENABLED`	Master switch; `false`.
`TRACES_ENABLED`, `LOGS_ENABLED`, `METRICS_ENABLED`	Individual signals; each `true` when the master switch is enabled.
`REQUIRE_SESSION`	Require a valid session when enabled; `false`.
`SERVICE_NAME`	`justpen-utility-mcp`; overrides additional `service.name`.
`RESOURCE_ATTRIBUTES`	Additional fields such as `justpen.run.id`; excludes `justpen.session.id`.
`PROTOCOL`	`http/protobuf` (default) or `grpc`.
`ENDPOINT`	Collector base URL; SDK defaults to localhost:4318 for HTTP or localhost:4317 for gRPC.
`HEADERS`	Collector headers as comma-separated, percent-encoded `key=value` pairs.
`TIMEOUT`	Positive exporter timeout in seconds; SDK default 10.
`CERTIFICATE`, `CLIENT_CERTIFICATE`, `CLIENT_KEY`	CA and optional client certificate/key file paths.
`COMPRESSION`, `INSECURE`	`none`/`gzip`/`deflate`; gRPC insecure-channel boolean.
`TRACES_`, `LOGS_`, `METRICS_*`	Per-signal protocol/exporter overrides.
`TRACES_SAMPLER`, `TRACES_SAMPLER_ARG`	Sampler; `parentbased_always_on`. Ratio argument between 0 and 1.
`BSP_MAX_QUEUE_SIZE`, `BLRP_MAX_QUEUE_SIZE`	Trace/log queue capacity; SDK default 2048.
`BSP_MAX_EXPORT_BATCH_SIZE`, `BLRP_MAX_EXPORT_BATCH_SIZE`	Batch size; SDK default 512, capped at queue capacity.
`BSP_SCHEDULE_DELAY`, `BLRP_SCHEDULE_DELAY`	Batch delay in milliseconds; SDK defaults 5000/1000.
`BSP_EXPORT_TIMEOUT`, `BLRP_EXPORT_TIMEOUT`	Batch flush timeout in milliseconds; SDK default 30000.
`METRIC_EXPORT_INTERVAL`, `METRIC_EXPORT_TIMEOUT`	Milliseconds; SDK defaults 60000/30000.
`SHUTDOWN_TIMEOUT_MS`	Total cleanup budget; `5000`.

Per-signal options take precedence. An HTTP base endpoint gains /v1/traces, /v1/logs or /v1/metrics; a signal-specific endpoint is used exactly as given. Samplers accept always_on, always_off, traceidratio and their parentbased_ variants. Invalid protocols disable the affected signal. Queue, batch and interval values must be positive integers.

Raw OTEL_* variables do not configure the server. Enabled CLI startup clears them in its child process before applying validated Utility settings. Leave FastMCP telemetry mode at its default native.

Correlation and privacy¶

A valid HTTP traceparent takes priority over MCP request params._meta context; otherwise valid _meta.traceparent is used. Valid tracestate is retained. With neither, the request starts a new root trace. Concurrent requests retain distinct context.

Codex _meta.callId and Claude _meta["claudecode/toolUseId"] map to gen_ai.tool.call.id; a conflict is recorded without merging the values. Native session, thread, turn and item IDs remain separate when present.

Exported spans and events contain fixed method, transport, outcome, known tool and known error-category fields. They do not contain TOTP secrets or codes, QR paths or decoded payloads, tool arguments/results, exception messages, collector responses, credentials or arbitrary metadata. Exception events retain only the exception type. Ordinary application logs remain on stderr; operational telemetry uses fixed event names. SDK diagnostic messages are sanitized before they reach stderr.

Request metrics are justpen.mcp.requests and justpen.mcp.request.duration (seconds), labeled only by method, transport and outcome. Correlated operational logs keep active trace/span IDs even when the parent is unsampled.

Runtime behavior and client observations¶

Disabled telemetry creates no providers or exporter threads. Export uses bounded queues, so a slow or unavailable collector can lose records without failing MCP calls. Shutdown tries to flush all enabled signals within one shared budget; blocked exporters cannot keep process exit open indefinitely.

The Browser MCP telemetry research recorded dated headless observations on 2026-09-14: stdio clients did not carry W3C context in those probes, Codex HTTP continued a separate transport-worker trace, and Claude Code HTTP continued its native tool-execution trace. Utility continues the context it receives and cannot reconstruct an upstream parent that a client did not send. These observations do not establish interactive, subagent, resume or retest behavior.