observability

Documentation

Overview

Package observability provides Prometheus metrics, OpenTelemetry tracing, health/readiness probes, and the HTTP server that exposes them for the mcp-prometheus process.

The main entry points are:

• NewMetrics — creates a custom Prometheus registry with per-tool counters and duration histograms.
• NewTracerProvider — returns a no-op TracerProvider by default; switches to OTLP HTTP export when OTEL_EXPORTER_OTLP_ENDPOINT is set.
• NewInstrumentor — wraps MCP tool handlers to record spans and metrics.
• Health — tracks readiness state; exposes /healthz and /readyz handlers.
• NewServer / RunServer — build and run the observability HTTP mux.

Index

• func Listen(addr string) (net.Listener, error)
• func NewServer(metrics *Metrics, health *Health) *http.ServeMux
• func NewTracerProvider(ctx context.Context, logger *slog.Logger) (trace.TracerProvider, func(context.Context) error, error)
• func RunServer(ctx context.Context, addr string, handler http.Handler) error
• func Serve(ctx context.Context, ln net.Listener, handler http.Handler) error
• type Health
  • func (h *Health) HealthzHandler() http.HandlerFunc
  • func (h *Health) ReadyzHandler() http.HandlerFunc
  • func (h *Health) SetReady(ready bool)
• type Instrumentor
  • func NewInstrumentor(metrics *Metrics, tp trace.TracerProvider) *Instrumentor
  • func (i *Instrumentor) Wrap(toolName string, ...) func(context.Context, mcp.CallToolRequest) (*mcp.CallToolResult, error)
• type Metrics
  • func NewMetrics() *Metrics
  • func (m *Metrics) Handler() http.Handler

Functions

func Listen

func Listen(addr string) (net.Listener, error)

Listen creates a TCP listener on addr. The error is returned synchronously so the caller can fail fast before launching any goroutines.

func NewServer

func NewServer(metrics *Metrics, health *Health) *http.ServeMux

NewServer builds an HTTP mux with the following routes:

GET /metrics  — Prometheus metrics (text/OpenMetrics format)
GET /healthz  — liveness probe (always 200 OK)
GET /readyz   — readiness probe (200 OK / 503 Service Unavailable)

func NewTracerProvider

func NewTracerProvider(ctx context.Context, logger *slog.Logger) (trace.TracerProvider, func(context.Context) error, error)

NewTracerProvider initialises an OTel TracerProvider.

When OTEL_EXPORTER_OTLP_ENDPOINT is empty a no-op provider is returned and no network connections are made. When the env var is set an OTLP HTTP exporter is created and the global TracerProvider is set.

The second return value is a shutdown function that must be called on exit to flush any pending spans.

func RunServer

func RunServer(ctx context.Context, addr string, handler http.Handler) error

RunServer is a convenience wrapper around Listen and Serve. Prefer calling them separately when you need to surface bind errors before launching a goroutine.

func Serve

func Serve(ctx context.Context, ln net.Listener, handler http.Handler) error

Serve starts an HTTP server using the pre-bound listener and blocks until ctx is cancelled, at which point the server is shut down gracefully.

Callers should use Listen first to surface bind errors synchronously, then launch Serve in a goroutine:

ln, err := observability.Listen(addr)
if err != nil { return err }
go observability.Serve(ctx, ln, handler)

Types

type Health

type Health struct {
	// contains filtered or unexported fields
}

Health tracks server readiness state and exposes HTTP health-check handlers.

func (*Health) HealthzHandler

func (h *Health) HealthzHandler() http.HandlerFunc

HealthzHandler returns a handler that always responds HTTP 200 OK as long as the process is alive (Kubernetes liveness probe).

func (*Health) ReadyzHandler

func (h *Health) ReadyzHandler() http.HandlerFunc

ReadyzHandler returns a handler that responds HTTP 200 OK when the server is ready to handle traffic, or HTTP 503 Service Unavailable otherwise (Kubernetes readiness probe).

func (*Health) SetReady

func (h *Health) SetReady(ready bool)

SetReady marks the server as ready (true) or not ready (false).

type Instrumentor

type Instrumentor struct {
	// contains filtered or unexported fields
}

Instrumentor wraps MCP tool handlers to record Prometheus metrics and OpenTelemetry spans for every tool invocation.

func NewInstrumentor

func NewInstrumentor(metrics *Metrics, tp trace.TracerProvider) *Instrumentor

NewInstrumentor creates an Instrumentor backed by the given metrics registry and tracer provider.

func (*Instrumentor) Wrap

func (i *Instrumentor) Wrap(
	toolName string,
	next func(context.Context, mcp.CallToolRequest) (*mcp.CallToolResult, error),
) func(context.Context, mcp.CallToolRequest) (*mcp.CallToolResult, error)

Wrap instruments a single MCP tool handler with Prometheus metrics and an OTel span. It satisfies the ToolMiddleware signature expected by RegisterPrometheusTools.

type Metrics

type Metrics struct {
	ToolCallsTotal   *prometheus.CounterVec
	ToolCallDuration *prometheus.HistogramVec
	// contains filtered or unexported fields
}

Metrics holds Prometheus counters and histograms for MCP tool invocations.

func NewMetrics

func NewMetrics() *Metrics

NewMetrics creates a Prometheus registry and registers:

• Go runtime collector
• Process collector
• mcp_prometheus_tool_calls_total{tool,status}
• mcp_prometheus_tool_call_duration_seconds{tool}

func (*Metrics) Handler

func (m *Metrics) Handler() http.Handler

Handler returns an HTTP handler that serves the Prometheus metrics page in OpenMetrics / text format.