gemini-cli - 💡(How to fix) Fix OpenTelemetry: TRACEPARENT env var is ignored, breaking distributed tracing across process boundaries [1 participants]

What happened?

Summary

When a parent process spawns gemini as a subprocess and injects a W3C TRACEPARENT (and TRACESTATE) into its environment — the standard way to propagate OTel context across process boundaries — the Gemini CLI ignores it and starts a brand-new root trace. This breaks distributed tracing for any system that embeds the CLI as a subprocess.

Related work

This is related to but distinct from #23057, which proposed wrapping non-interactive execution in a UserPrompt root span to unify the CLI's own internal spans (intra-process correlation). That PR was auto-closed unmerged on 2026-04-03.

This issue is one level up: even with a local root span in place, that root has no upstream parent because nothing reads TRACEPARENT from the environment. The two fixes are complementary — local correlation + cross-process propagation together would give a fully connected trace.

Why this matters

I'm building an agent harness that spawns gemini in ACP mode per user session. The orchestrator emits its own OTel spans (job lifecycle, orchestration, Slack I/O). Without cross-process parenting, operators have to filter traces manually by a shared attribute (we use thread.ts) and open two separate traces in the Phoenix UI to debug one user interaction. A one-line extract at startup would give us a single coherent trace.

What did you expect to happen?

Expected behavior

On startup, if process.env.TRACEPARENT is set, the CLI should parse it and use the resulting SpanContext as the parent of its root span (e.g. agent_call, or the UserPrompt root proposed in #23057). This is the convention used by OTel SDKs in other languages (Python's opentelemetry.propagate.inject writes TRACEPARENT into env; the child is expected to pick it up).

Actual behavior

Every gemini invocation generates a fresh random trace ID regardless of TRACEPARENT. The CLI's internal span tree (agent_call → llm_call → schedule_tool_calls → tool_call) is correctly nested in-process, but it's detached from any upstream trace.

Reproduction

Parent process (Python):

import os, subprocess
from opentelemetry import trace
from opentelemetry.propagate import inject
from opentelemetry.sdk.trace import TracerProvider

trace.set_tracer_provider(TracerProvider())
tracer = trace.get_tracer("repro")

with tracer.start_as_current_span("parent_job") as span:
    env = os.environ.copy()
    inject(env)  # writes "traceparent" key
    env["TRACEPARENT"] = env.pop("traceparent")  # uppercase for env-var convention
    subprocess.run(["gemini", "-p", "hello"], env=env)

With a Phoenix/OTel collector receiving spans from both processes, you'll observe two separate traces with different trace IDs — the parent's parent_job and the CLI's agent_call — instead of one nested trace.

Evidence from the bundle

I grepped the installed @google/gemini-cli bundle (installed globally via npm). The W3CTraceContextPropagator is present as part of @opentelemetry/core, but no application code reads process.env.TRACEPARENT or calls propagation.extract against it during telemetry initialization. The propagator is only wired for cross-request HTTP propagation — not process-boundary propagation.

Client information

Environment

@google/gemini-cli installed via npm install -g Node v24.14.1 / v18.20.8 (reproduced on both) OTel collector: otelcol-contrib, OTLP/gRPC receiver Backend: Arize Phoenix

Gemini

│ About Gemini CLI │ │ │ │ CLI Version 0.37.0 │ │ Git Commit 352bbe149 │ │ Model Auto (Gemini 3) │ │ Sandbox no sandbox │ │ OS linux │ │ Auth Method vertex-ai │ │ IDE Client VS Code

Login information

Vertex AI

Anything else we need to know?

Suggested fix

In the telemetry bootstrap, before creating the root span:

import { context, propagation, trace } from "@opentelemetry/api";

const traceparent = process.env.TRACEPARENT;
if (traceparent) {
  const carrier = {
    traceparent,
    tracestate: process.env.TRACESTATE,
  };
  const extractedCtx = propagation.extract(context.active(), carrier);
  // Use extractedCtx as the parent when starting the root span:
  await context.with(extractedCtx, async () => {
    // ...existing root span creation (e.g. the UserPrompt root from #23057)...
  });
}

Both TRACEPARENT (uppercase env-var convention) and traceparent (lowercase header convention) should be accepted for robustness.