apiserverspanexporter.go

Overview

This file defines the APIServerSpanExporter type, a custom implementation of the sdktrace.SpanExporter interface from OpenTelemetry. Its primary purpose is to collect and store trace span data related to specific span events (call_llm, send_data, and spans prefixed with execute_tool). The stored data is maintained in-memory as a map keyed by a unique event identifier (gcp.vertex.agent.event_id). This exporter is designed mainly for debugging and analyzing individual event traces in the system.

The APIServerSpanExporter thus serves as a specialized trace exporter focused on capturing span attributes relevant to API server operations involving LLM calls, data sending, and tool execution.

Types and Functions

Type: APIServerSpanExporter

• Description: Implements the sdktrace.SpanExporter interface. Stores span attribute data in-memory keyed by event ID.

• Fields:

  • traceDict map[string]map[string]string
    A map where the keys are event IDs (gcp.vertex.agent.event_id), and the values are maps of attribute keys to their string values. This structure holds all relevant span attributes for quick lookup.

Function: NewAPIServerSpanExporter() *APIServerSpanExporter

• Description: Constructs and returns a new APIServerSpanExporter instance with an initialized empty traceDict.

• Parameters: None

• Returns: Pointer to an APIServerSpanExporter

• Usage Example:

  exporter := NewAPIServerSpanExporter()
  

Method: (s *APIServerSpanExporter) GetTraceDict() map[string]map[string]string

• Description: Provides access to the current in-memory stored trace information.

• Parameters: None

• Returns: A map of event IDs to their associated span attribute maps.

• Usage Example:

  traces := exporter.GetTraceDict()
  for eventID, attrs := range traces {
      fmt.Println("Event ID:", eventID)
      for key, value := range attrs {
          fmt.Printf("  %s: %s\n", key, value)
      }
  }
  

Method: (s *APIServerSpanExporter) ExportSpans(ctx context.Context, spans []sdktrace.ReadOnlySpan) error

• Description: Implements the ExportSpans method of the sdktrace.SpanExporter interface. Processes a batch of spans, filters relevant spans by name, extracts their attributes, and stores them in traceDict.

• Parameters:

  • ctx context.Context — Context for cancellation and deadlines.

  • spans []sdktrace.ReadOnlySpan — Slice of spans to export.

• Returns: error — Always returns nil since no error conditions are handled.

• Details:

  • Only spans with names exactly "call_llm", "send_data", or those starting with "execute_tool" are processed.

  • For each matching span, all attributes are extracted and converted into a string map.

  • The span's trace_id and span_id are added to the attributes map.

  • If an attribute with key "gcp.vertex.agent.event_id" exists, the attribute map is stored keyed by this event ID.

• Usage Example: This method is invoked automatically by OpenTelemetry when spans are ready to be exported.

Method: (s *APIServerSpanExporter) Shutdown(ctx context.Context) error

• Description: Implements the Shutdown method of the sdktrace.SpanExporter interface. This method is intended to release any resources or close connections.

• Parameters:

  • ctx context.Context — Context for cancellation or timeout.

• Returns: error — Always returns nil because no resources need explicit shutdown; the exporter only uses in-memory data.

• Usage: Called during the shutdown phase of the tracer provider lifecycle.

Implementation Details and Algorithms

• The exporter filters spans by their names to limit the scope of captured data, focusing on spans related to LLM calls and tool execution.

• Attributes are converted from their native representation (attribute.KeyValue) into simple key-string maps for ease of inspection and debugging.

• The use of the "gcp.vertex.agent.event_id" attribute as a key enables correlation of spans to specific events, facilitating debugging of individual API server operations.

• Trace and span IDs are included with the attributes to uniquely identify the tracing context.

Interactions with Other System Components

• Implements the sdktrace.SpanExporter interface from OpenTelemetry SDK (go.opentelemetry.io/otel/sdk/trace), enabling integration with the tracing pipeline.

• Used in telemetry and observability workflows to collect detailed trace data about LLM calls, data transmission, and tool execution spans, correlating to events generated within API servers.

• The stored data in traceDict can be accessed for debugging or analysis, possibly by other components responsible for trace visualization or diagnostics.

• Works closely with span creation instrumentation elsewhere in the system, where spans named "call_llm", "send_data", and "execute_tool*" are generated. This relates to the broader topic of telemetry and observability Telelemetry and Observability.

Diagram: Structure of APIServerSpanExporter

classDiagram
class APIServerSpanExporter {
-traceDict map[string]map[string]string
+NewAPIServerSpanExporter()
+GetTraceDict() map[string]map[string]string
+ExportSpans(ctx, spans) error
+Shutdown(ctx) error
}
APIServerSpanExporter ..|> sdktrace.SpanExporter

References

• sdktrace.SpanExporter interface from OpenTelemetry SDK for context on implemented interface and lifecycle.

• Relevant telemetry and tracing workflows within the system, especially for LLM and tool execution spans Telelemetry and Observability.

• OpenTelemetry Span and Attribute concepts for understanding span data extraction and storage.