Documentation
¶
Overview ¶
Package telemetry integrates runtime events with Clue tracing and metrics.
Index ¶
- Constants
- func GenAIInputMessagesAttr(messages []*model.Message) (attribute.KeyValue, bool, error)
- func GenAIOutputMessagesAttr(messages []model.Message, finishReason string) (attribute.KeyValue, bool, error)
- func GenAITemperatureOmittedAttrs(modelID string, temperature float64) []attribute.KeyValue
- func GenAIUsageAttrs(input, output, cacheRead, cacheCreation int) []attribute.KeyValue
- func MergeContext(ctx, base context.Context) context.Context
- func ShouldRecordSpanError(ctx context.Context, err error) bool
- type ClueLogger
- type ClueMetrics
- type ClueTracer
- type Logger
- type Metrics
- type NoopLogger
- type NoopMetrics
- type NoopTracer
- type Span
- type ToolTelemetry
- type Tracer
Constants ¶
const ( // AttrGenAIConversationID identifies the conversation/session for a GenAI operation. AttrGenAIConversationID = attribute.Key("gen_ai.conversation.id") // AttrGenAIAgentID identifies the logical agent for a GenAI operation. AttrGenAIAgentID = attribute.Key("gen_ai.agent.id") // AttrGenAIAgentName names the logical agent for a GenAI operation. AttrGenAIAgentName = attribute.Key("gen_ai.agent.name") // AttrGenAIOperationName identifies the GenAI operation type. AttrGenAIOperationName = attribute.Key("gen_ai.operation.name") // AttrGenAIInputMessages captures sensitive input messages when explicitly enabled. AttrGenAIInputMessages = attribute.Key("gen_ai.input.messages") // AttrGenAIOutputMessages captures sensitive output messages when explicitly enabled. AttrGenAIOutputMessages = attribute.Key("gen_ai.output.messages") // AttrGenAIRequestModel records the requested model identifier or class. AttrGenAIRequestModel = attribute.Key("gen_ai.request.model") // AttrGenAIRequestMaxTokens records the requested max output token cap. AttrGenAIRequestMaxTokens = attribute.Key("gen_ai.request.max_tokens") // AttrGenAIRequestTemperature records the requested sampling temperature. AttrGenAIRequestTemperature = attribute.Key("gen_ai.request.temperature") // AttrGenAIRequestTemperatureOmitted records that a provider rejected the requested temperature. AttrGenAIRequestTemperatureOmitted = attribute.Key("gen_ai.request.temperature_omitted") // AttrGenAIResponseModel records the provider-resolved response model. AttrGenAIResponseModel = attribute.Key("gen_ai.response.model") // AttrGenAIResponseFinishReasons records provider finish reasons. AttrGenAIResponseFinishReasons = attribute.Key("gen_ai.response.finish_reasons") // AttrGenAIResponseTTFT records seconds to first streamed output chunk. AttrGenAIResponseTTFT = attribute.Key("gen_ai.response.time_to_first_chunk") // AttrGenAIUsageInputTokens records input token usage. AttrGenAIUsageInputTokens = attribute.Key("gen_ai.usage.input_tokens") // AttrGenAIUsageOutputTokens records output token usage. AttrGenAIUsageOutputTokens = attribute.Key("gen_ai.usage.output_tokens") // AttrGenAIUsageCacheReadTokens records cached input tokens read. AttrGenAIUsageCacheReadTokens = attribute.Key("gen_ai.usage.cache_read.input_tokens") // AttrGenAIUsageCacheCreationTokens records cached input tokens written. AttrGenAIUsageCacheCreationTokens = attribute.Key("gen_ai.usage.cache_creation.input_tokens") )
const (
// GenAIOperationChat is the standard operation name for chat model calls.
GenAIOperationChat = "chat"
)
Variables ¶
This section is empty.
Functions ¶
func GenAIInputMessagesAttr ¶ added in v1.2.0
GenAIInputMessagesAttr serializes input messages into the OpenTelemetry GenAI message schema. Message content can be sensitive, so callers must explicitly opt in before attaching this attribute. Reasoning content is never captured.
func GenAIOutputMessagesAttr ¶ added in v1.2.0
func GenAIOutputMessagesAttr(messages []model.Message, finishReason string) (attribute.KeyValue, bool, error)
GenAIOutputMessagesAttr serializes output messages into the OpenTelemetry GenAI message schema. Message content can be sensitive, so callers must explicitly opt in before attaching this attribute. Reasoning content is never captured.
func GenAITemperatureOmittedAttrs ¶ added in v1.2.0
GenAITemperatureOmittedAttrs returns attributes for a requested temperature that was intentionally omitted because the resolved model does not accept it.
func GenAIUsageAttrs ¶ added in v1.2.0
GenAIUsageAttrs returns standard token usage attributes for a model call.
func MergeContext ¶
MergeContext injects logging, tracing, and baggage metadata carried by base into ctx. It is used by workflow adapters to rehydrate the caller context (Clue logger + OTEL span) inside workflow/activity handlers so downstream code inherits the same observability state even when the workflow engine creates a fresh context. When base is nil the original ctx is returned.
Types ¶
type ClueLogger ¶
type ClueLogger struct{}
ClueLogger wraps github.com/CaliLuke/loom/clue/log for runtime logging.
func (ClueLogger) Debug ¶
func (ClueLogger) Debug(ctx context.Context, msg string, keyvals ...any)
Debug emits a debug-level log message with structured key-value pairs.
func (ClueLogger) Error ¶
func (ClueLogger) Error(ctx context.Context, msg string, keyvals ...any)
Error emits an error-level log message with structured key-value pairs.
type ClueMetrics ¶
type ClueMetrics struct {
// contains filtered or unexported fields
}
ClueMetrics wraps OTEL metrics for runtime instrumentation.
func (*ClueMetrics) IncCounter ¶
func (m *ClueMetrics) IncCounter(name string, value float64, tags ...string)
IncCounter increments a counter metric by the given value.
func (*ClueMetrics) RecordGauge ¶
func (m *ClueMetrics) RecordGauge(name string, value float64, tags ...string)
RecordGauge records a gauge metric value.
func (*ClueMetrics) RecordTimer ¶
func (m *ClueMetrics) RecordTimer(name string, duration time.Duration, tags ...string)
RecordTimer records a duration histogram/timer metric.
type ClueTracer ¶
type ClueTracer struct {
// contains filtered or unexported fields
}
ClueTracer wraps OTEL tracing for runtime tracing.
type Logger ¶
type Logger interface {
Debug(ctx context.Context, msg string, keyvals ...any)
Info(ctx context.Context, msg string, keyvals ...any)
Warn(ctx context.Context, msg string, keyvals ...any)
Error(ctx context.Context, msg string, keyvals ...any)
}
Logger captures structured logging used throughout the runtime. Implementations typically delegate to Clue but the interface is intentionally small so tests can provide lightweight stubs.
func NewClueLogger ¶
func NewClueLogger() Logger
NewClueLogger constructs a Logger that delegates to github.com/CaliLuke/loom/clue/log. The logger reads formatting and debug settings from the context (set via log.Context and log.WithFormat/log.WithDebug).
func NewNoopLogger ¶
func NewNoopLogger() Logger
NewNoopLogger constructs a Logger that discards all log messages. Use this for testing or when logging is not required.
type Metrics ¶
type Metrics interface {
IncCounter(name string, value float64, tags ...string)
RecordTimer(name string, duration time.Duration, tags ...string)
RecordGauge(name string, value float64, tags ...string)
}
Metrics exposes counter and histogram helpers for runtime instrumentation.
func NewClueMetrics ¶
func NewClueMetrics() Metrics
NewClueMetrics constructs a Metrics recorder that delegates to OTEL metrics. Uses the global MeterProvider; configure it via otel.SetMeterProvider before invoking runtime methods (typically done via clue.ConfigureOpenTelemetry).
func NewNoopMetrics ¶
func NewNoopMetrics() Metrics
NewNoopMetrics constructs a Metrics recorder that discards all metrics. Use this for testing or when metrics are not required.
type NoopLogger ¶
type NoopLogger struct{}
NoopLogger is a no-op implementation of Logger that discards all log messages.
func (NoopLogger) Debug ¶
func (NoopLogger) Debug(context.Context, string, ...any)
Debug discards the log message.
func (NoopLogger) Error ¶
func (NoopLogger) Error(context.Context, string, ...any)
Error discards the log message.
type NoopMetrics ¶
type NoopMetrics struct{}
NoopMetrics is a no-op implementation of Metrics that discards all metrics.
func (NoopMetrics) IncCounter ¶
func (NoopMetrics) IncCounter(string, float64, ...string)
IncCounter discards the counter metric.
func (NoopMetrics) RecordGauge ¶
func (NoopMetrics) RecordGauge(string, float64, ...string)
RecordGauge discards the gauge metric.
func (NoopMetrics) RecordTimer ¶
func (NoopMetrics) RecordTimer(string, time.Duration, ...string)
RecordTimer discards the timer metric.
type NoopTracer ¶
type NoopTracer struct{}
NoopTracer is a no-op implementation of Tracer that creates no-op spans.
type Span ¶
type Span interface {
End(opts ...trace.SpanEndOption)
AddEvent(name string, attrs ...any)
SetAttributes(attrs ...attribute.KeyValue)
SetStatus(code codes.Code, description string)
RecordError(err error, opts ...trace.EventOption)
}
Span represents an in-flight tracing span. Uses OTEL option types for type safety.
Example usage:
ctx, span := tracer.Start(ctx, "operation", trace.WithSpanKind(trace.SpanKindClient)) defer span.End() span.SetStatus(codes.Ok, "completed successfully")
type ToolTelemetry ¶
type ToolTelemetry struct {
// DurationMs is the wall-clock execution time in milliseconds.
DurationMs int64
// TokensUsed tracks the total tokens consumed by LLM calls.
TokensUsed int
// Model identifies which LLM model was used (e.g., "gpt-4", "claude-3-opus").
Model string
// Extra holds tool-specific metadata not captured by common fields.
Extra map[string]any
}
ToolTelemetry captures observability metadata collected during tool execution. Common fields provide type safety for standard metrics. The Extra map holds tool-specific data (e.g., API response headers, cache keys, provider details).
type Tracer ¶
type Tracer interface {
Start(ctx context.Context, name string, opts ...trace.SpanStartOption) (context.Context, Span)
Span(ctx context.Context) Span
}
Tracer abstracts span creation so runtime code can remain agnostic of the underlying OpenTelemetry provider. Uses OTEL option types for type safety.
func NewClueTracer ¶
func NewClueTracer() Tracer
NewClueTracer constructs a Tracer that delegates to OTEL tracing. Uses the global TracerProvider; configure it via otel.SetTracerProvider before invoking runtime methods (typically done via clue.ConfigureOpenTelemetry or environment variables like OTEL_EXPORTER_OTLP_ENDPOINT).
func NewNoopTracer ¶
func NewNoopTracer() Tracer
NewNoopTracer constructs a Tracer that creates no-op spans. Use this for testing or when tracing is not required.
Source Files