telemetry

Documentation

Overview

Package telemetry provides OpenTelemetry instrumentation for ToolHive MCP server proxies.

Index

• Constants
• func CreateMiddleware(config *types.MiddlewareConfig, runner types.MiddlewareRunner) error
• func NewHTTPMiddleware(config Config, tracerProvider trace.TracerProvider, ...) types.MiddlewareFunction
• type Config
  • func DefaultConfig() Config
• type FactoryMiddleware
  • func (m *FactoryMiddleware) Close() error
  • func (m *FactoryMiddleware) Handler() types.MiddlewareFunction
  • func (m *FactoryMiddleware) PrometheusHandler() http.Handler
• type FactoryMiddlewareParams
• type HTTPMiddleware
  • func (m *HTTPMiddleware) Handler(next http.Handler) http.Handler
• type Provider
  • func NewProvider(ctx context.Context, config Config) (*Provider, error)
  • func (p *Provider) MeterProvider() metric.MeterProvider
  • func (p *Provider) Middleware(serverName, transport string) types.MiddlewareFunction
  • func (p *Provider) PrometheusHandler() http.Handler
  • func (p *Provider) Shutdown(ctx context.Context) error
  • func (p *Provider) TracerProvider() trace.TracerProvider

Constants

const (
	MiddlewareType = "telemetry"
)

Factory middleware type constant

Functions

func CreateMiddleware

func CreateMiddleware(config *types.MiddlewareConfig, runner types.MiddlewareRunner) error

CreateMiddleware factory function for telemetry middleware

func NewHTTPMiddleware

func NewHTTPMiddleware(
	config Config,
	tracerProvider trace.TracerProvider,
	meterProvider metric.MeterProvider,
	serverName, transport string,
) types.MiddlewareFunction

NewHTTPMiddleware creates a new HTTP middleware for OpenTelemetry instrumentation. serverName is the name of the MCP server (e.g., "github", "fetch") transport is the backend transport type ("stdio" or "sse")

Types

type Config

type Config struct {
	// Endpoint is the OTLP endpoint URL
	Endpoint string

	// ServiceName is the service name for telemetry
	ServiceName string

	// ServiceVersion is the service version for telemetry
	ServiceVersion string

	// SamplingRate is the trace sampling rate (0.0-1.0)
	SamplingRate float64

	// Headers contains authentication headers for the OTLP endpoint
	Headers map[string]string

	// Insecure indicates whether to use HTTP instead of HTTPS for the OTLP endpoint
	Insecure bool

	// EnablePrometheusMetricsPath controls whether to expose Prometheus-style /metrics endpoint
	// The metrics are served on the main transport port at /metrics
	// This is separate from OTLP metrics which are sent to the Endpoint
	EnablePrometheusMetricsPath bool

	// EnvironmentVariables is a list of environment variable names that should be
	// included in telemetry spans as attributes. Only variables in this list will
	// be read from the host machine and included in spans for observability.
	// Example: []string{"NODE_ENV", "DEPLOYMENT_ENV", "SERVICE_VERSION"}
	EnvironmentVariables []string
}

Config holds the configuration for OpenTelemetry instrumentation.

func DefaultConfig

func DefaultConfig() Config

DefaultConfig returns a default telemetry configuration.

type FactoryMiddleware

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

FactoryMiddleware wraps telemetry middleware functionality for factory pattern

func (*FactoryMiddleware) Close

func (m *FactoryMiddleware) Close() error

Close cleans up any resources used by the middleware.

func (*FactoryMiddleware) Handler

func (m *FactoryMiddleware) Handler() types.MiddlewareFunction

Handler returns the middleware function used by the proxy.

func (*FactoryMiddleware) PrometheusHandler

func (m *FactoryMiddleware) PrometheusHandler() http.Handler

PrometheusHandler returns the Prometheus metrics handler.

type FactoryMiddlewareParams

type FactoryMiddlewareParams struct {
	Config     *Config `json:"config"`
	ServerName string  `json:"server_name"`
	Transport  string  `json:"transport"`
}

FactoryMiddlewareParams represents the parameters for telemetry middleware

type HTTPMiddleware

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

HTTPMiddleware provides OpenTelemetry instrumentation for HTTP requests.

func (*HTTPMiddleware) Handler

func (m *HTTPMiddleware) Handler(next http.Handler) http.Handler

Handler implements the middleware function that wraps HTTP handlers. This middleware should be placed after the MCP parsing middleware in the chain to leverage the parsed MCP data.

type Provider

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

Provider encapsulates OpenTelemetry providers and configuration.

func NewProvider

func NewProvider(ctx context.Context, config Config) (*Provider, error)

NewProvider creates a new OpenTelemetry provider with the given configuration.

func (*Provider) MeterProvider

func (p *Provider) MeterProvider() metric.MeterProvider

MeterProvider returns the configured meter provider.

func (*Provider) Middleware

func (p *Provider) Middleware(serverName, transport string) types.MiddlewareFunction

Middleware returns an HTTP middleware that instruments requests with OpenTelemetry. serverName is the name of the MCP server (e.g., "github", "fetch") transport is the backend transport type ("stdio" or "sse")

func (*Provider) PrometheusHandler

func (p *Provider) PrometheusHandler() http.Handler

PrometheusHandler returns the Prometheus metrics handler if configured. Returns nil if no metrics port is configured.

func (*Provider) Shutdown

func (p *Provider) Shutdown(ctx context.Context) error

Shutdown gracefully shuts down the telemetry provider.

func (*Provider) TracerProvider

func (p *Provider) TracerProvider() trace.TracerProvider

TracerProvider returns the configured tracer provider.