telemetry.go

Overview

The telemetry.go file in the telemetry package provides a simple but crucial integration point for registering custom telemetry span processors into the local OpenTelemetry trace provider within the AI Agent Development Kit (ADK). This setup enables the emission of tracing data for ADK events such as LLM calls and tool executions, allowing external systems or monitoring backends to collect and analyze telemetry data.

Its primary responsibility is to expose an API for adding span processors before any telemetry events occur, ensuring that custom processors are attached to the tracer provider that handles span lifecycle management and export.

Package Functionality

Package Declaration

package telemetry

The package comment clarifies that the purpose of telemetry is to allow setting up custom telemetry processors that receive ADK events as OpenTelemetry spans.

Imports

• sdktrace "go.opentelemetry.io/otel/sdk/trace": Imports the OpenTelemetry SDK tracing package, specifically for managing span processors and tracers.

• internaltelemetry "google.golang.org/adk/internal/telemetry": Imports an internal package that holds the underlying implementation details for managing span processors and the local trace provider instance.

Functions

RegisterSpanProcessor

func RegisterSpanProcessor(processor sdktrace.SpanProcessor)

Purpose

Registers a custom span processor to the local trace provider instance which handles the creation and export of telemetry spans. Span processors are components that process spans as they are ended, e.g., exporting them to telemetry backends such as Jaeger or Zipkin.

Parameters

• processor sdktrace.SpanProcessor
  An instance of an OpenTelemetry SpanProcessor interface. This processor controls how spans are processed and exported.

Behavior

• The registration must happen before any ADK telemetry events are emitted; otherwise, the processor will be ignored.

• It delegates the actual addition to the internal telemetry package's AddSpanProcessor function, which manages the local tracer configuration.

• Global trace provider configurations (from OpenTelemetry global tracer) are also respected, meaning this registration complements but does not override global settings.

Usage Example

import (
    "go.opentelemetry.io/otel/sdk/trace"
    "google.golang.org/adk/telemetry"
)

func setupTelemetry() {
    // Create a new span processor (e.g., a batch processor exporting to a backend).
    processor := trace.NewBatchSpanProcessor(exporter)

    // Register the span processor before any tracing starts.
    telemetry.RegisterSpanProcessor(processor)
}

This ensures that all spans emitted by ADK events will be processed by the registered processor.

Important Implementation Details

• The file itself does not contain complex logic but acts as a public facade for span processor registration.

• It relies on the internal telemetry package (internaltelemetry.AddSpanProcessor) for thread-safe management of span processors and tracer initialization.

• Registration must occur at initialization time to ensure correct instrumentation of subsequent telemetry events.

• This design pattern cleanly separates public API from internal implementation, promoting modularity and encapsulation.

Interaction with Other Parts of the System

• Internal Telemetry Package: Delegates registration to the internal telemetry system that manages the local trace provider and span processors.

• OpenTelemetry SDK: Uses OpenTelemetry's SpanProcessor interface from the SDK to integrate with tracing pipelines.

• ADK Event Emitters: Once processors are registered, the ADK runtime components emit spans for LLM calls, tool executions, and agent events that these processors handle.

• Global Trace Provider Configurations: This mechanism coexists with global OpenTelemetry tracer settings, ensuring compatibility with external telemetry setups.

• Agent and Tool Packages: These components emit telemetry spans internally which get processed by span processors registered here.

This file acts as the entry point for telemetry customization, linking the ADK's internal event tracing to external observability platforms.

Diagram: Function Relationship and Workflow

flowchart TD
A[External Code] -->|RegisterSpanProcessor(processor)| B[telemetry.RegisterSpanProcessor]
B --> C[internaltelemetry.AddSpanProcessor]
C --> D[Local Trace Provider Config]
D --> E[Span Processor List]
E --> F[Span Processing & Exporting]
subgraph Telemetry Emission Pipeline
G[ADK Events Emitted] --> H[Spans Created]
H --> F
end

• External code calls RegisterSpanProcessor to add a span processor.

• The call delegates to the internal telemetry package, which stores the processor in the local trace provider config.

• When ADK events occur, spans are created and processed by the registered span processors.

• Span processors handle export to telemetry backends.

References to Related Topics

• See Telemetry and Observability for a detailed explanation of the telemetry system architecture, span lifecycle, and tracing of LLM and tool calls.

• For the mechanism of span processor registration and OpenTelemetry integration, refer to OpenTelemetry Integration.

• For how agents and tools emit telemetry spans that these processors handle, consult LLM Integration and Agents and Tooling System.

This file is a fundamental building block enabling external telemetry systems to hook into the ADK's internal event tracing by registering span processors early in the application lifecycle.