Class TelemetryConfig

src/google/adk/telemetry/context.py:81–213

Per-request OpenTelemetry configuration. Attached to an invocation via ``RunConfig.telemetry``. Any field left as ``None`` falls back to its corresponding env var (an ``OTEL_*`` var, plus the default-on ``ADK_CAPTURE_MESSAGE_CONTENT_IN_SPANS`` for legacy spans). ``frozen=True`` lets the sam

class TelemetryConfig(BaseModel):
  """Per-request OpenTelemetry configuration.

  Attached to an invocation via ``RunConfig.telemetry``. Any field left as
  ``None`` falls back to its corresponding env var (an ``OTEL_*`` var, plus the
  default-on ``ADK_CAPTURE_MESSAGE_CONTENT_IN_SPANS`` for legacy spans).
  ``frozen=True`` lets the same config be shared safely across concurrent
  invocations; the resolution properties read env lazily, so later
  ``os.environ`` changes are still picked up.

  Limitations:
    * When ``opentelemetry-instrumentation-google-genai`` is installed and
      wraps ``google.genai.Models.generate_content``, span creation is
      delegated to that library, which reads its own OTel env vars; per-request
      overrides are inoperative for the inference span (but still apply to
      ADK-owned spans).

  Attributes:
    genai_semconv_stability_opt_in: Override for
      ``OTEL_SEMCONV_STABILITY_OPT_IN``. ``'experimental'`` opts in to the
      experimental GenAI semconv attributes; ``'stable'`` keeps the legacy path.
      ``'stable'`` has no env-var equivalent (the env path infers stable from
      the absence of ``'gen_ai_latest_experimental'`` in the CSV).
    capture_message_content: Override for
      ``OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT``. Pass a
      :class:`ContentCapturingMode` member; the env-var path accepts the
      matching uppercase string.
  """

  model_config = ConfigDict(frozen=True, extra='forbid')

  genai_semconv_stability_opt_in: Optional[
      Literal['stable', 'experimental']
  ] = None
  capture_message_content: Optional[ContentCapturingMode] = None

  @property
  def _ignore_per_request(self) -> bool:
    """Whether the admin lock (``ADK_TELEMETRY_IGNORE_RUN_CONFIG``) is set.

    When set, the per-request fields are ignored and resolution falls back to
    the ``OTEL_*`` env vars.
    """
    lock = os.getenv(ADK_TELEMETRY_IGNORE_RUN_CONFIG, '').strip().lower()
    return lock in _TRUTHY_ENV_VALUES

  @property
  def should_use_experimental_genai_semconv(self) -> bool:
    """Whether to emit experimental GenAI semconv attributes.

    Precedence: admin lock > ``genai_semconv_stability_opt_in`` >
    ``OTEL_SEMCONV_STABILITY_OPT_IN`` env var > ``False``.
    """
    if (
        not self._ignore_per_request
        and self.genai_semconv_stability_opt_in is not None
    ):
      return self.genai_semconv_stability_opt_in == 'experimental'