Documentation
¶
Overview ¶
Package tracing provides OpenTelemetry OTLP trace export for the MCP Gateway. This file defines gen_ai semantic convention attribute keys per https://opentelemetry.io/docs/specs/semconv/registry/attributes/gen-ai/
Package tracing provides OpenTelemetry OTLP trace export for the MCP Gateway. This file provides HTTP handler wrapping helpers.
Package tracing provides OpenTelemetry OTLP trace export for the MCP Gateway.
When an OTLP endpoint is configured (via config or OTEL_EXPORTER_OTLP_ENDPOINT), this package initializes a real tracer provider that exports spans over HTTP. When no endpoint is configured, a noop tracer provider is used, adding zero overhead.
Usage:
tp, err := tracing.InitProvider(ctx, cfg.Gateway.Tracing)
if err != nil {
return err
}
defer tp.Shutdown(ctx)
Once initialized, obtain a tracer with:
tracer := otel.Tracer("github.com/github/gh-aw-mcpg")
Package tracing provides OpenTelemetry OTLP trace export for the MCP Gateway. This file provides span error recording helpers and span start constructors.
Index ¶
- Constants
- func GetCachedOrGlobal(cached trace.Tracer) trace.Tracer
- func ParentContext(ctx context.Context, cfg *config.TracingConfig) context.Context
- func RecordSpanError(span oteltrace.Span, err error, msg string)
- func RecordSpanErrorOnAll(err error, msg string, spans ...oteltrace.Span)
- func StartBackendExecuteSpan(ctx context.Context, tracer oteltrace.Tracer, serverID, toolName string) (context.Context, oteltrace.Span)
- func StartDIFCPipelineSpan(ctx context.Context, tracer oteltrace.Tracer, toolName, urlPath string) (context.Context, oteltrace.Span)
- func StartProxyForwardSpan(ctx context.Context, tracer oteltrace.Tracer, toolName, urlPath string) (context.Context, oteltrace.Span)
- func StartToolCallSpan(ctx context.Context, tracer oteltrace.Tracer, serverID, toolName string) (context.Context, oteltrace.Span)
- func Tracer() trace.Tracer
- func WrapHTTPHandler(next http.Handler, spanName string, extraAttrs ...attribute.KeyValue) http.Handler
- type CachedTracer
- type Provider
Constants ¶
const ( // GenAIToolName is the name of the tool utilized by the agent. GenAIToolName = semconv.GenAIToolNameKey // GenAIOperationName is the name of the operation being performed. GenAIOperationName = semconv.GenAIOperationNameKey // GenAIConversationID is the unique identifier for a conversation (session). GenAIConversationID = semconv.GenAIConversationIDKey // GenAIAgentName is the human-readable name of the GenAI agent. GenAIAgentName = semconv.GenAIAgentNameKey // GenAIAgentID is the unique identifier of the GenAI agent (server ID). GenAIAgentID = semconv.GenAIAgentIDKey )
GenAI semantic convention attribute keys. These are aliases for the official OpenTelemetry gen_ai semconv constants (semconv/v1.34.0), re-exported here for convenience.
const ( // MCPMethod is the JSON-RPC method name (e.g. "tools/call"). MCPMethod = attribute.Key("mcp.method") // MCPResponseStatus is the conceptual HTTP status of the proxied MCP response. // Used on internal MCP spans (e.g. mcp.tool_call) instead of the HTTP-specific // semconv.HTTPResponseStatusCodeKey, which is semantically reserved for HTTP spans. MCPResponseStatus = attribute.Key("mcp.response.status") // RateLimitHit indicates a rate limit was triggered. RateLimitHit = attribute.Key("rate_limit.hit") // GatewayTag is the routing mode tag (unified/routed). GatewayTag = attribute.Key("gateway.tag") )
MCP-specific attribute keys (no gen_ai equivalent in the spec).
Variables ¶
This section is empty.
Functions ¶
func GetCachedOrGlobal ¶ added in v0.2.26
GetCachedOrGlobal returns cached if non-nil, otherwise falls back to the global tracer.
func ParentContext ¶ added in v0.2.14
ParentContext returns a context carrying the W3C remote parent span context from the configured traceId and spanId (spec §4.1.3.6). Exported for use at startup to build the root span's parent context.
func RecordSpanError ¶ added in v0.3.21
RecordSpanError records err on span with a stack trace and sets the span status to Error. Use this instead of calling RecordError + SetStatus individually to ensure consistent behavior (stack traces enabled, status always set) across all error paths.
func RecordSpanErrorOnAll ¶ added in v0.3.21
RecordSpanErrorOnAll records err on all provided spans with a stack trace and sets their status to Error. Useful when both a parent and child span must reflect the same failure.
func StartBackendExecuteSpan ¶ added in v0.3.21
func StartBackendExecuteSpan(ctx context.Context, tracer oteltrace.Tracer, serverID, toolName string) (context.Context, oteltrace.Span)
StartBackendExecuteSpan starts the backend execution child span for the unified server. It is a client-kind span that covers the actual RPC to the backend MCP server.
func StartDIFCPipelineSpan ¶ added in v0.3.21
func StartDIFCPipelineSpan(ctx context.Context, tracer oteltrace.Tracer, toolName, urlPath string) (context.Context, oteltrace.Span)
StartDIFCPipelineSpan starts the DIFC pipeline OTEL span for the proxy handler. It covers all phases of the DIFC pipeline for a single proxied request.
func StartProxyForwardSpan ¶ added in v0.3.21
func StartProxyForwardSpan(ctx context.Context, tracer oteltrace.Tracer, toolName, urlPath string) (context.Context, oteltrace.Span)
StartProxyForwardSpan starts the backend forward child span for the proxy handler. It is a client-kind span that covers the HTTP request forwarded to the upstream API.
func StartToolCallSpan ¶ added in v0.3.21
func StartToolCallSpan(ctx context.Context, tracer oteltrace.Tracer, serverID, toolName string) (context.Context, oteltrace.Span)
StartToolCallSpan starts the outer tool-call OTEL span with standard gen_ai attributes. It covers the full tool call lifecycle (all DIFC pipeline phases) in unified server mode.
func Tracer ¶
Tracer returns the global MCP gateway tracer. This is a convenience wrapper around otel.Tracer for packages that don't hold a reference to the Provider.
func WrapHTTPHandler ¶
func WrapHTTPHandler(next http.Handler, spanName string, extraAttrs ...attribute.KeyValue) http.Handler
WrapHTTPHandler wraps an http.Handler with an OpenTelemetry server span. A span named spanName is created for every request, with http.request.method and http.route set automatically. Extra attrs are merged in.
Incoming W3C traceparent/tracestate headers are extracted so that an agent-originated trace is continued; if no such headers are present a fresh root span (and new trace ID) is created automatically.
This is a low-level helper used by both the MCP gateway middleware and the GitHub API proxy. Callers that need session-level attributes (e.g. session.id) should add them as extra attrs or extend the context themselves.
Types ¶
type CachedTracer ¶ added in v0.3.14
CachedTracer holds an optional pre-initialized tracer and falls back to the global tracer when the cached tracer is nil.
func (CachedTracer) GetTracer ¶ added in v0.3.14
func (ct CachedTracer) GetTracer() trace.Tracer
GetTracer returns the cached tracer when set, otherwise the global tracer.
type Provider ¶
type Provider struct {
// contains filtered or unexported fields
}
Provider wraps an OpenTelemetry TracerProvider and provides a Shutdown method.
func InitProvider ¶
InitProvider initializes the global OpenTelemetry tracer provider. When endpoint is empty, a noop provider is installed (zero overhead). When endpoint is configured, an OTLP/HTTP exporter is created and the SDK tracer provider is registered as the global provider.
In both cases a W3C TraceContext propagator is registered globally so that incoming traceparent/tracestate headers are honoured by all HTTP middleware.
The returned Provider must be shut down on application exit to flush buffered spans.
Source Files