Documentation
¶
Overview ¶
Package tracing provides distributed tracing for the gridctl MCP gateway. It initializes the OpenTelemetry SDK, propagates W3C trace context, stores completed traces in an in-memory ring buffer, and optionally exports to OTLP.
Index ¶
- type Buffer
- func (b *Buffer) Count() int
- func (b *Buffer) ExportSpans(_ context.Context, spans []sdktrace.ReadOnlySpan) error
- func (b *Buffer) Filter(opts FilterOpts) []TraceRecord
- func (b *Buffer) GetByID(traceID string) *TraceRecord
- func (b *Buffer) GetRecent(n int) []TraceRecord
- func (b *Buffer) Shutdown(_ context.Context) error
- type Config
- type FilterOpts
- type MetaCarrier
- type Provider
- type SpanRecord
- type TraceRecord
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Buffer ¶
type Buffer struct {
// contains filtered or unexported fields
}
Buffer stores completed traces in a thread-safe ring buffer and implements sdktrace.SpanExporter so it can be registered with the OTel TracerProvider.
func (*Buffer) ExportSpans ¶
ExportSpans implements sdktrace.SpanExporter. Spans are accumulated by trace ID. When the local-root span is exported, all accumulated spans are finalised into a TraceRecord.
func (*Buffer) Filter ¶
func (b *Buffer) Filter(opts FilterOpts) []TraceRecord
Filter returns traces matching the given options, newest first.
func (*Buffer) GetByID ¶
func (b *Buffer) GetByID(traceID string) *TraceRecord
GetByID returns the trace with the given ID, or nil if not found.
func (*Buffer) GetRecent ¶
func (b *Buffer) GetRecent(n int) []TraceRecord
GetRecent returns up to n most-recent traces, newest first.
type Config ¶
type Config struct {
// Enabled controls whether tracing is active. Default: true.
Enabled bool `yaml:"enabled"`
// Sampling is the head-based sampling rate [0.0, 1.0]. Default: 1.0 (sample all).
Sampling float64 `yaml:"sampling"`
// Retention is how long completed traces are kept in the in-memory buffer.
// Parsed as a Go duration string (e.g. "24h", "1h"). Default: "24h".
Retention string `yaml:"retention"`
// Export selects an exporter: "otlp" or "" (none). Default: "".
Export string `yaml:"export,omitempty"`
// Endpoint is the OTLP endpoint URL (e.g. "http://localhost:4318").
// Required when Export is "otlp".
Endpoint string `yaml:"endpoint,omitempty"`
// MaxTraces is the ring buffer capacity. Default: 1000.
MaxTraces int `yaml:"max_traces,omitempty"`
}
Config holds tracing configuration for the gateway.
func DefaultConfig ¶
func DefaultConfig() *Config
DefaultConfig returns a Config with sensible defaults.
func (*Config) RetentionDuration ¶
RetentionDuration parses Retention as a time.Duration, returning the default (24h) on error.
type FilterOpts ¶
FilterOpts configures trace list filtering.
type MetaCarrier ¶
type MetaCarrier struct {
// contains filtered or unexported fields
}
MetaCarrier implements propagation.TextMapCarrier for MCP _meta maps. It enables standard OTel Extract()/Inject() calls on the JSON-RPC params._meta field, following MCP spec PR #414.
func NewMetaCarrier ¶
func NewMetaCarrier(meta map[string]any) *MetaCarrier
NewMetaCarrier wraps an existing _meta map (or creates one if nil).
func (*MetaCarrier) Get ¶
func (c *MetaCarrier) Get(key string) string
Get returns the value for a key, normalising to lowercase.
func (*MetaCarrier) Keys ¶
func (c *MetaCarrier) Keys() []string
Keys returns all keys present in the _meta map.
func (*MetaCarrier) Map ¶
func (c *MetaCarrier) Map() map[string]any
Map returns the underlying _meta map (e.g. to re-marshal into JSON).
func (*MetaCarrier) Set ¶
func (c *MetaCarrier) Set(key, value string)
Set stores a key-value pair in the _meta map.
type Provider ¶
type Provider struct {
Buffer *Buffer
// contains filtered or unexported fields
}
Provider wraps the OTel TracerProvider and the in-memory trace buffer. Call Init to configure and register the global OTel provider. Call Shutdown to flush and shut down cleanly.
func NewProvider ¶
NewProvider creates a Provider from config. Call Init to activate it.
func (*Provider) Init ¶
Init initialises the OTel SDK, registers the global TracerProvider and propagator, and sets up the in-memory buffer (+ optional OTLP exporter).
type SpanRecord ¶
type SpanRecord struct {
TraceID string `json:"trace_id"`
SpanID string `json:"span_id"`
ParentID string `json:"parent_id,omitempty"`
Name string `json:"name"`
StartTime time.Time `json:"start_time"`
EndTime time.Time `json:"end_time"`
DurationMs int64 `json:"duration_ms"`
Status string `json:"status"`
IsError bool `json:"is_error"`
Attrs map[string]string `json:"attrs,omitempty"`
}
SpanRecord is a completed OTel span stored in the trace buffer.
type TraceRecord ¶
type TraceRecord struct {
TraceID string `json:"trace_id"`
Operation string `json:"operation"` // root span name
ServerName string `json:"server_name,omitempty"`
MethodName string `json:"method_name,omitempty"`
StartTime time.Time `json:"start_time"`
EndTime time.Time `json:"end_time"`
DurationMs int64 `json:"duration_ms"`
SpanCount int `json:"span_count"`
IsError bool `json:"is_error"`
Spans []SpanRecord `json:"spans"`
}
TraceRecord groups all spans belonging to a single trace.
Source Files