Documentation
¶
Overview ¶
Package telemetry integrates runtime events with Clue tracing and metrics.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
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 goa.design/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 goa.design/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)
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