telemetry

type Attr ¶

type Attr struct {
	Key   string
	Value any
}

Attr is a span attribute.

type EventSpan ¶

type EventSpan interface {
	Span
	AddEvent(name string, attrs ...Attr)
}

EventSpan is a Span that records events. Spans that do not implement it drop the events of this package, such as the retries of a model call.

type Float64Histogram ¶

type Float64Histogram interface {
	Record(ctx context.Context, v float64, attrs ...Attr)
}

Float64Histogram records a distribution of floats.

type Instrument ¶

type Instrument struct {
	Name        string
	Description string
	// Unit is a UCUM unit, such as "s" or "{token}".
	Unit string
	// Buckets are the explicit bucket boundaries the conventions advise for
	// a histogram. Adapters may ignore them.
	Buckets []float64
}

Instrument describes a metric instrument.

type Int64Counter ¶

type Int64Counter interface {
	Add(ctx context.Context, n int64, attrs ...Attr)
}

Int64Counter adds to a monotonic sum.

type Int64Histogram ¶

type Int64Histogram interface {
	Record(ctx context.Context, v int64, attrs ...Attr)
}

Int64Histogram records a distribution of integers.

type Meter ¶

type Meter interface {
	Int64Counter(Instrument) Int64Counter
	Int64Histogram(Instrument) Int64Histogram
	Float64Histogram(Instrument) Float64Histogram
}

Meter creates metric instruments. Adapt OpenTelemetry or another metrics library to it; agentx itself has no metrics dependency. Implementations and their instruments must be safe for concurrent use. The context of a measurement holds the span of the measured operation, for exemplars.

middleware.Metrics and middleware.MeterModel record these instruments of the OpenTelemetry GenAI semantic conventions (https://github.com/open-telemetry/semantic-conventions-genai):

• gen_ai.client.inference.duration (s), and for streaming calls gen_ai.client.inference.time_to_first_chunk and gen_ai.client.inference.time_per_output_chunk;
• the gen_ai.client.inference.usage.input_tokens, .output_tokens, .cache_read.input_tokens, .cache_write.input_tokens and .reasoning.output_tokens counters, with gen_ai.token.modality "unknown", as providers do not break usage down by modality;
• the gen_ai.client.inference.operation.input_tokens and .output_tokens histograms;
• gen_ai.execute_tool.duration (s), whose count is the number of tool calls;
• gen_ai.invoke_agent.duration (s), with agentx.run.status, and the gen_ai.invoke_agent.inference_calls and .tool_calls histograms, which count only a run's own calls, not those of its sub-agents.

Model metrics carry gen_ai.operation.name, gen_ai.provider.name, gen_ai.request.model, gen_ai.response.model and server.address and server.port; run and tool metrics carry gen_ai.agent.name. Failed operations add error.type as spans do.

type NoopMeter ¶

type NoopMeter struct{}

NoopMeter discards measurements.

func (NoopMeter) Float64Histogram(Instrument) Float64Histogram

func (NoopMeter) Int64Counter(Instrument) Int64Counter

func (NoopMeter) Int64Histogram(Instrument) Int64Histogram

type NoopTracer ¶

type NoopTracer struct{}

NoopTracer discards spans.

func (NoopTracer) Start(ctx context.Context, _ string, _ SpanKind, _ ...Attr) (context.Context, Span)

type Span ¶

type Span interface {
	SetAttributes(attrs ...Attr)
	// RecordError records err and marks the span as failed: adapters should
	// set the span status to error.
	RecordError(err error)
	End()
}

Span is an in-progress trace span.

func SpanFromContext(ctx context.Context) Span

func StartSpan(ctx context.Context, name string, kind SpanKind, attrs ...Attr) (context.Context, Span)

type SpanKind ¶

type SpanKind int

SpanKind is the kind of a span, as in OpenTelemetry.

const (
	// SpanKindInternal marks work done in the process, such as agent runs
	// and tool calls.
	SpanKindInternal SpanKind = iota
	// SpanKindClient marks calls to a remote service, such as model calls.
	SpanKindClient
)

type Tracer ¶

type Tracer interface {
	Start(ctx context.Context, name string, kind SpanKind, attrs ...Attr) (context.Context, Span)
}

Tracer starts spans. Adapt OpenTelemetry or another tracing library to it; agentx itself has no tracing dependency.

Spans follow the OpenTelemetry GenAI semantic conventions (https://github.com/open-telemetry/semantic-conventions-genai):

• "invoke_agent {agent}" (internal) covers a run of the agent loop;
• "{operation} {model}" (client), such as "chat gpt-6-astra", covers a model call;
• "execute_tool {tool}" (internal) covers a tool call. A sub-agent run by agent.AsTool is a child of its execute_tool span.

The middleware package records these spans; see middleware.Tracing.

Work the conventions do not cover gets agentx spans: "hook {event}" for the hooks of a lifecycle event and "compact_context" for an automatic compaction. Retries of a model call are "agentx.retry" events.

Attributes use the gen_ai.* names of the conventions, plus agentx.run_id, agentx.turn and agentx.run.status. The span of an agent a run was handed off to has agentx.handoff.from, the agent that handed it off; a run that a guardrail blocked has agentx.guardrail.name and agentx.guardrail.kind and an "agentx.guardrail" event, which also holds the guardrail's message when content is recorded. A failed operation sets error.type to the provider's error code, "timeout", "canceled", "panic", "tool_error" for a tool that returned an error result, or "_OTHER".