otel

Documentation

Overview

Package otel emits OpenTelemetry spans and metrics from a Dive agent following the GenAI semantic conventions (`gen_ai.*`).

OTel deps live in a separate Go module so callers who don't use this package don't pay for them.

Span shape

invoke_agent {agent.name}        // wraps an entire CreateResponse call
├── chat {request.model}         // each LLM iteration
├── execute_tool {tool.name}     // each tool call
└── execute_tool {tool.name}

Wiring

tp := /* your TracerProvider, e.g. otlptracehttp + sdktrace.NewTracerProvider */
defer tp.Shutdown(ctx)
otel.SetTracerProvider(tp)

agent, _ := dive.NewAgent(dive.AgentOptions{
    Name:         "Research Assistant",
    Model:        anthropic.New(),
    SystemPrompt: "You are an enthusiastic researcher.",
    Tracer:       telemetry.NewTracer(telemetry.WithProvider("anthropic")),
})

resp, err := agent.CreateResponse(ctx, dive.WithInput("hello"))

Privacy

Verbatim conversation content is dropped by default. Opt in with WithCaptureMessages (chat input/output) and WithCaptureToolIO (tool arguments and results). Both produce attributes that may contain user data — review your destination's retention policy before enabling.

Index

• Constants
• Variables
• func NewTracer(opts ...Option) dive.Tracer
• type Option
  • func WithAttributes(a ...attribute.KeyValue) Option
  • func WithCaptureMessages(b bool) Option
  • func WithCaptureToolIO(b bool) Option
  • func WithMeter(m metric.Meter) Option
  • func WithProvider(p string) Option
  • func WithTracer(t trace.Tracer) Option
• type Options

Constants

const InstrumentationName = "github.com/deepnoodle-ai/dive/otel"

InstrumentationName is the OTel instrumentation scope name set on every span and metric emitted by this package.

Variables

var InstrumentationVersion = resolveInstrumentationVersion()

InstrumentationVersion is reported on every span and metric. Resolved from the build's module version when this package is consumed by a tagged release; falls back to instrumentationFallbackVersion for local builds.

Functions

func NewTracer

func NewTracer(opts ...Option) dive.Tracer

NewTracer constructs a dive.Tracer that emits OpenTelemetry spans and metrics following the GenAI semantic conventions. Pass it via dive.AgentOptions.Tracer.

Types

type Option

type Option func(*Options)

Option mutates Options.

func WithAttributes

func WithAttributes(a ...attribute.KeyValue) Option

WithAttributes adds attributes to every emitted span.

func WithCaptureMessages

func WithCaptureMessages(b bool) Option

WithCaptureMessages enables capture of input/output messages on chat spans. OFF by default — payloads may contain user input.

func WithCaptureToolIO

func WithCaptureToolIO(b bool) Option

WithCaptureToolIO enables capture of tool arguments and results on execute_tool spans. OFF by default — payloads may contain user input.

func WithMeter

func WithMeter(m metric.Meter) Option

WithMeter sets the OTel meter used for the gen_ai.client.* histograms.

func WithProvider

func WithProvider(p string) Option

WithProvider sets gen_ai.provider.name. Use values from genaiconv.ProviderName* where possible — "anthropic", "openai", "gcp.gemini", "aws.bedrock", etc.

func WithTracer

func WithTracer(t trace.Tracer) Option

WithTracer sets the OTel tracer.

type Options

type Options struct {
	// Tracer is the OTel tracer. Defaults to otel.GetTracerProvider().Tracer(...).
	Tracer trace.Tracer

	// Meter is the OTel meter for the gen_ai.client.* histograms. Defaults to
	// otel.GetMeterProvider().Meter(...). Pass a noop meter to disable
	// metrics emission while keeping spans.
	Meter metric.Meter

	// Provider sets gen_ai.provider.name on every span. Suggested values
	// come from genaiconv.ProviderName* — "anthropic", "openai",
	// "gcp.gemini", etc. When empty, "dive" is used.
	Provider string

	// CaptureMessages, when true, attaches gen_ai.input.messages and
	// gen_ai.output.messages on chat spans. Off by default — payloads can
	// contain user input verbatim.
	CaptureMessages bool

	// CaptureToolIO, when true, attaches gen_ai.tool.call.arguments and
	// gen_ai.tool.call.result on execute_tool spans. Off by default.
	CaptureToolIO bool

	// Attributes are added to every span this Tracer produces.
	Attributes []attribute.KeyValue
}

Options configures the Tracer.