Telemetry¶

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

Setup¶

For an HTTP/protobuf collector on the standard local port:

export JUSTPEN_INTEGRATION_OTEL_ENABLED=true
export JUSTPEN_INTEGRATION_OTEL_PROTOCOL=http/protobuf
export JUSTPEN_INTEGRATION_OTEL_ENDPOINT=http://127.0.0.1:4318
export JUSTPEN_SESSION_ID=pentest-example
export JUSTPEN_INTEGRATION_OTEL_RESOURCE_ATTRIBUTES=justpen.run.id=run-example,deployment.environment.name=local
python -m justpen_integration_mcp

JUSTPEN_INTEGRATION_OTEL_ENDPOINT is the telemetry collector address. It is separate from the MCP HTTP listener at http://127.0.0.1:8932/mcp. For stdio, put the telemetry variables in the environment that the MCP client passes to the server process.

The default HTTP listener is suitable for a trusted local client. If the MCP listener is exposed beyond loopback, place authentication, access control, and TLS in front of it because callers can use the configured Gmail integration.

Session and resource identity¶

justpen.session.id comes only from JUSTPEN_SESSION_ID. It accepts 1–128 ASCII letters, digits, periods, underscores, colons, and hyphens. Set JUSTPEN_INTEGRATION_OTEL_REQUIRE_SESSION=true to reject enabled startup when the value is missing or invalid.

Additional resource attributes use comma-separated, percent-encoded key=value entries in JUSTPEN_INTEGRATION_OTEL_RESOURCE_ATTRIBUTES. justpen.run.id may identify one run within a session. Additional attributes cannot override justpen.session.id or the installed service.version.

Export settings¶

Every setting except JUSTPEN_SESSION_ID uses the JUSTPEN_INTEGRATION_OTEL_ prefix.

Suffix	Meaning and default
`ENABLED`	Master switch; `false`.
`TRACES_ENABLED`, `LOGS_ENABLED`, `METRICS_ENABLED`	Individual signals; each `true` behind the master switch.
`PROTOCOL`	`http/protobuf` (default) or `grpc`.
`ENDPOINT`	Collector base URL; SDK defaults are localhost ports 4318/4317.
`HEADERS`, `TIMEOUT`	Collector headers and positive exporter timeout in seconds.
`SERVICE_NAME`	`justpen-integration-mcp`.
`RESOURCE_ATTRIBUTES`	Additional process resource fields; excludes `justpen.session.id`.
`REQUIRE_SESSION`	Require a valid `JUSTPEN_SESSION_ID`; `false`.
`TRACES_`, `LOGS_`, `METRICS_*`	Per-signal protocol, endpoint, header, timeout, TLS and compression keys.
`TRACES_SAMPLER`, `TRACES_SAMPLER_ARG`	SDK sampler and optional ratio; `parentbased_always_on`.
`SHUTDOWN_TIMEOUT_MS`	Total telemetry flush/shutdown budget after Gmail cleanup; `5000`.

Batch queue, batch size, schedule delay, export timeout, and metric interval settings use the standard SDK suffixes BSP_*, BLRP_*, and METRIC_* under the same service prefix. Raw OTEL_* variables do not configure the server and are cleared inside an enabled CLI child before SDK initialization. Leave FastMCP telemetry mode at its default native.

Correlation and privacy¶

A valid HTTP traceparent takes priority over MCP params._meta; otherwise a valid metadata parent is used. Missing or invalid context starts a root trace. Valid tracestate is retained and baggage is ignored. Codex callId and Claude Code claudecode/toolUseId normalize to gen_ai.tool.call.id, while native session, thread, turn, and item IDs remain separate.

Exports contain fixed request/lifecycle event names and bounded correlation attributes. They do not contain email bodies, subjects, addresses, search expressions, Gmail IDs or cursors, credentials, tool arguments/results, request URLs, authorization headers, arbitrary error text, or exception messages. A status: "error" result exports only a known error prefix such as TIMEOUT; partial status: "ok" results remain successful.

The Browser MCP's 2026-09-14 headless client observations found that client and transport combinations differed in whether they sent W3C context. Those dated measurements also apply as practical limits here: this server continues context it receives and cannot reconstruct a parent the client did not send. They do not establish interactive, subagent, resume, or retest behavior.

Operational logs remain separate from ordinary Python stderr logs. Metrics are justpen.mcp.requests and justpen.mcp.request.duration, labeled only by MCP method, transport, and outcome. A slow or unavailable collector may lose records without failing Gmail calls. Shutdown attempts every signal within one shared budget after the Gmail worker and client close.