README
¶
Telemetry Module
The Telemetry Module provides functionality for distributed tracing and metrics in applications. It is designed to be used with OpenTelemetry and Prometheus.
Features
- Distributed tracing with OpenTelemetry
- Metrics collection with OpenTelemetry and Prometheus
- HTTP instrumentation for tracing requests and responses
- Unified interface for tracing and metrics
Installation
go get github.com/abitofhelp/servicelib/telemetry
Quick Start
See the Initialization example for a complete, runnable example of how to use the Telemetry module.
API Documentation
Initialization
The NewTelemetryProvider function creates a new telemetry provider that can be used for tracing and metrics.
Creating a Telemetry Provider
See the Initialization example for a complete, runnable example of how to create and configure a telemetry provider.
Tracing
The telemetry package provides functions for distributed tracing, including starting spans, adding attributes, and recording errors.
Using Tracing
See the Tracing example for a complete, runnable example of how to use the tracing functionality.
HTTP Instrumentation
The telemetry package provides functions for instrumenting HTTP handlers and clients with tracing.
Instrumenting HTTP Components
See the HTTP Instrumentation example for a complete, runnable example of how to instrument HTTP handlers and clients.
Metrics
The telemetry package provides functions for recording various types of metrics, including HTTP requests, database operations, and errors.
Recording Metrics
See the Metrics example for a complete, runnable example of how to record different types of metrics.
Prometheus Integration
The telemetry package provides functions for integrating with Prometheus for metrics collection and visualization.
Integrating with Prometheus
See the Prometheus Integration example for a complete, runnable example of how to integrate with Prometheus.
Configuration
The telemetry package can be configured using the following configuration structure:
# Example configuration for the telemetry module
telemetry:
enabled: true
service_name: "my-service"
environment: "development"
version: "1.0.0"
shutdown_timeout: 5
otlp:
endpoint: "localhost:4317"
insecure: true
timeout_seconds: 5
tracing:
enabled: true
sampling_ratio: 1.0
propagation_keys:
- "traceparent"
- "tracestate"
- "baggage"
metrics:
enabled: true
reporting_frequency_seconds: 15
prometheus:
enabled: true
listen: "0.0.0.0:8089"
path: "/metrics"
http:
tracing_enabled: true
Best Practices
- Service Name: Use a consistent service name across all your services
- Sampling Ratio: In production, consider using a sampling ratio less than 1.0 to reduce overhead
- Span Naming: Use descriptive names for spans that include the operation being performed
- Attributes: Add relevant attributes to spans to provide context for debugging
- Error Handling: Always record errors on spans to make debugging easier
- Metrics Naming: Use consistent naming conventions for metrics
- Cardinality: Be careful with high-cardinality labels in metrics
Documentation
¶
Overview ¶
Package telemetry provides functionality for monitoring and tracing application behavior. It offers a unified interface for both metrics collection and distributed tracing using OpenTelemetry and Prometheus.
Package telemetry provides functionality for monitoring and tracing application behavior.
Package telemetry provides functionality for monitoring and tracing application behavior.
Package telemetry provides functionality for monitoring and tracing application behavior. It offers a unified interface for both metrics collection and distributed tracing using OpenTelemetry and Prometheus.
Package telemetry provides functionality for monitoring and tracing application behavior.
Index ¶
- func AddSpanAttributes(ctx context.Context, attrs ...attribute.KeyValue)
- func CreatePrometheusHandler() http.Handler
- func DecrementRequestsInFlight(ctx context.Context, method, path string)
- func GetSpanFromContext(ctx context.Context) trace.Span
- func GetTelemetryDefaults(serviceName ...string) map[string]interface{}
- func IncrementRequestsInFlight(ctx context.Context, method, path string)
- func InitCommonMetrics(mp *MetricsProvider) error
- func InstrumentClient(client *http.Client, opts ...otelhttp.Option) *http.Client
- func InstrumentHandler(handler http.Handler, operation string, opts ...otelhttp.Option) http.Handler
- func IsMetricsEnabled(k *koanf.Koanf) bool
- func NewHTTPMiddleware(logger *logging.ContextLogger) func(http.Handler) http.Handler
- func RecordDBOperation(ctx context.Context, operation, database, collection string, ...)
- func RecordErrorMetric(ctx context.Context, errorType, operation string)
- func RecordErrorSpan(ctx context.Context, err error, opts ...trace.EventOption)
- func RecordHTTPRequest(ctx context.Context, method, path string, statusCode int, ...)
- func StartSpan(ctx context.Context, name string) (context.Context, trace.Span)
- func UpdateDBConnections(ctx context.Context, database string, delta int64)
- func WithSpan(ctx context.Context, name string, fn func(context.Context) error) error
- func WithSpanTimed(ctx context.Context, name string, fn func(context.Context) error) (time.Duration, error)
- type Config
- type HTTPConfig
- type MetricsConfig
- type MetricsProvider
- type OTLPConfig
- type PrometheusConfig
- type TelemetryProvider
- func (tp *TelemetryProvider) CreatePrometheusHandler() http.Handler
- func (tp *TelemetryProvider) InstrumentHandler(handler http.Handler, operation string) http.Handler
- func (tp *TelemetryProvider) Meter() metric.Meter
- func (tp *TelemetryProvider) NewHTTPMiddleware() func(http.Handler) http.Handler
- func (tp *TelemetryProvider) Shutdown(ctx context.Context) error
- func (tp *TelemetryProvider) Tracer() trace.Tracer
- type TracingConfig
- type TracingProvider
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func AddSpanAttributes ¶
AddSpanAttributes adds attributes to the current span in context. This is useful for adding additional information to a span.
Parameters:
- ctx: The context containing the span
- attrs: The attributes to add to the span
func CreatePrometheusHandler ¶
CreatePrometheusHandler creates a handler for the /metrics endpoint
Returns:
- http.Handler: The Prometheus metrics handler
func DecrementRequestsInFlight ¶
DecrementRequestsInFlight decrements the in-flight requests counter
Parameters:
- ctx: The context for the operation
- method: The HTTP method
- path: The HTTP path
func GetSpanFromContext ¶
GetSpanFromContext retrieves the current span from the context. This is a helper function for testing and debugging.
Parameters:
- ctx: The context containing the span
Returns:
- trace.Span: The span from the context, or nil if no span is present
func GetTelemetryDefaults ¶
GetTelemetryDefaults returns default values for telemetry configuration
Parameters:
- serviceName: The name of the service (optional, defaults to "service")
Returns:
- map[string]interface{}: Default values for telemetry configuration
func IncrementRequestsInFlight ¶
IncrementRequestsInFlight increments the in-flight requests counter
Parameters:
- ctx: The context for the operation
- method: The HTTP method
- path: The HTTP path
func InitCommonMetrics ¶
func InitCommonMetrics(mp *MetricsProvider) error
InitCommonMetrics initializes common metrics
Parameters:
- mp: The metrics provider
Returns:
- error: An error if the metrics initialization fails
func InstrumentClient ¶
InstrumentClient wraps an http.Client with OpenTelemetry instrumentation. This adds tracing to all HTTP requests made by the provided client.
Parameters:
- client: The HTTP client to instrument
- opts: Additional options for the instrumentation
Returns:
- *http.Client: The instrumented HTTP client
func InstrumentHandler ¶
func InstrumentHandler(handler http.Handler, operation string, opts ...otelhttp.Option) http.Handler
InstrumentHandler wraps an http.Handler with OpenTelemetry instrumentation. This adds tracing to all HTTP requests handled by the provided handler.
Parameters:
- handler: The HTTP handler to instrument
- operation: The name of the operation for tracing
- opts: Additional options for the instrumentation
Returns:
- http.Handler: The instrumented HTTP handler
func IsMetricsEnabled ¶
IsMetricsEnabled returns whether metrics are enabled
Parameters:
- k: The koanf instance to load configuration from
Returns:
- bool: Whether metrics are enabled
func NewHTTPMiddleware ¶
NewHTTPMiddleware creates a new middleware for HTTP request tracing. This middleware adds tracing to all HTTP requests and logs request information.
Parameters:
- logger: The logger to use for logging request information
Returns:
- func(http.Handler) http.Handler: The middleware function
func RecordDBOperation ¶
func RecordDBOperation(ctx context.Context, operation, database, collection string, duration time.Duration, err error)
RecordDBOperation records metrics for a database operation
Parameters:
- ctx: The context for the operation
- operation: The database operation
- database: The database name
- collection: The collection or table name
- duration: The operation duration
- err: The error if the operation failed
func RecordErrorMetric ¶
RecordErrorMetric records an application error in metrics
Parameters:
- ctx: The context for the operation
- errorType: The type of error
- operation: The operation that failed
func RecordErrorSpan ¶
func RecordErrorSpan(ctx context.Context, err error, opts ...trace.EventOption)
RecordErrorSpan records an error on the current span in context. This is useful for recording errors that occur during a traced operation.
Parameters:
- ctx: The context containing the span
- err: The error to record
- opts: Additional options for the error event
func RecordHTTPRequest ¶
func RecordHTTPRequest(ctx context.Context, method, path string, statusCode int, duration time.Duration, responseSize int64)
RecordHTTPRequest records metrics for an HTTP request
Parameters:
- ctx: The context for the operation
- method: The HTTP method
- path: The HTTP path
- statusCode: The HTTP status code
- duration: The request duration
- responseSize: The response size in bytes
func StartSpan ¶
StartSpan is a helper function to start a new span from a context. This is useful for tracing operations within a request.
Parameters:
- ctx: The context to start the span from
- name: The name of the span
Returns:
- context.Context: The context with the span
- trace.Span: The span
func UpdateDBConnections ¶
UpdateDBConnections updates the open database connections counter
Parameters:
- ctx: The context for the operation
- database: The database name
- delta: The change in the number of connections
func WithSpan ¶
WithSpan wraps a function with a span. This is useful for tracing functions.
Parameters:
- ctx: The context to start the span from
- name: The name of the span
- fn: The function to wrap
Returns:
- error: The error returned by the function
func WithSpanTimed ¶
func WithSpanTimed(ctx context.Context, name string, fn func(context.Context) error) (time.Duration, error)
WithSpanTimed wraps a function with a span and records the execution time. This is useful for tracing functions and measuring their execution time.
Parameters:
- ctx: The context to start the span from
- name: The name of the span
- fn: The function to wrap
Returns:
- time.Duration: The execution time of the function
- error: The error returned by the function
Types ¶
type Config ¶
type Config struct {
// Enabled indicates whether telemetry is enabled
Enabled bool `mapstructure:"enabled"`
// ServiceName is the name of the service
ServiceName string `mapstructure:"service_name"`
// Environment is the environment the service is running in
Environment string `mapstructure:"environment"`
// Version is the version of the service
Version string `mapstructure:"version"`
// ShutdownTimeout is the timeout for shutting down telemetry in seconds
ShutdownTimeout int `mapstructure:"shutdown_timeout"`
// OTLP is the configuration for the OTLP exporter
OTLP OTLPConfig `mapstructure:"otlp"`
// Tracing is the configuration for tracing
Tracing TracingConfig `mapstructure:"tracing"`
// Metrics is the configuration for metrics
Metrics MetricsConfig `mapstructure:"metrics"`
// HTTP is the configuration for HTTP telemetry
HTTP HTTPConfig `mapstructure:"http"`
}
Config holds all telemetry configuration
func LoadConfig ¶
LoadConfig loads telemetry configuration from koanf
Parameters:
- k: The koanf instance to load configuration from
Returns:
- Config: The loaded telemetry configuration
type HTTPConfig ¶
type HTTPConfig struct {
// TracingEnabled indicates whether HTTP tracing is enabled
TracingEnabled bool `mapstructure:"tracing_enabled"`
}
HTTPConfig holds configuration for HTTP telemetry
type MetricsConfig ¶
type MetricsConfig struct {
// Enabled indicates whether metrics are enabled
Enabled bool `mapstructure:"enabled"`
// ReportingFreq is the frequency of metrics reporting in seconds
ReportingFreq int `mapstructure:"reporting_frequency_seconds"`
// Prometheus is the configuration for Prometheus metrics
Prometheus PrometheusConfig `mapstructure:"prometheus"`
}
MetricsConfig holds configuration for metrics
type MetricsProvider ¶
type MetricsProvider struct {
// contains filtered or unexported fields
}
MetricsProvider holds the metrics provider and meters
func NewMetricsProvider ¶
func NewMetricsProvider(ctx context.Context, logger *logging.ContextLogger, k *koanf.Koanf) (*MetricsProvider, error)
NewMetricsProvider creates a new metrics provider
Parameters:
- ctx: The context for the operation
- logger: The logger to use for logging metrics events
- k: The koanf instance to load configuration from
Returns:
- *MetricsProvider: The metrics provider
- error: An error if the metrics provider creation fails
func (*MetricsProvider) Meter ¶
func (mp *MetricsProvider) Meter() metric.Meter
Meter returns the meter
Returns:
- metric.Meter: The OpenTelemetry meter
type OTLPConfig ¶
type OTLPConfig struct {
// Endpoint is the OTLP endpoint
Endpoint string `mapstructure:"endpoint"`
// Insecure indicates whether to use insecure connections
Insecure bool `mapstructure:"insecure"`
// Timeout is the timeout for OTLP operations in seconds
Timeout int `mapstructure:"timeout_seconds"`
}
OTLPConfig holds configuration for OTLP exporter
type PrometheusConfig ¶
type PrometheusConfig struct {
// Enabled indicates whether Prometheus metrics are enabled
Enabled bool `mapstructure:"enabled"`
// Listen is the address to listen on for Prometheus metrics
Listen string `mapstructure:"listen"`
// Path is the path to expose Prometheus metrics on
Path string `mapstructure:"path"`
}
PrometheusConfig holds configuration for Prometheus metrics
type TelemetryProvider ¶
type TelemetryProvider struct {
// contains filtered or unexported fields
}
TelemetryProvider is a unified provider for tracing and metrics
func NewTelemetryProvider ¶
func NewTelemetryProvider(ctx context.Context, logger *logging.ContextLogger, k *koanf.Koanf) (*TelemetryProvider, error)
NewTelemetryProvider creates a new telemetry provider
Parameters:
- ctx: The context for the operation
- logger: The logger to use for logging telemetry events
- k: The koanf instance to load configuration from
Returns:
- *TelemetryProvider: The telemetry provider
- error: An error if the telemetry provider creation fails
func (*TelemetryProvider) CreatePrometheusHandler ¶
func (tp *TelemetryProvider) CreatePrometheusHandler() http.Handler
CreatePrometheusHandler creates a handler for the Prometheus metrics endpoint
Returns:
- http.Handler: The Prometheus metrics handler
func (*TelemetryProvider) InstrumentHandler ¶
InstrumentHandler wraps an http.Handler with OpenTelemetry instrumentation
Parameters:
- handler: The HTTP handler to instrument
- operation: The name of the operation for tracing
Returns:
- http.Handler: The instrumented HTTP handler
func (*TelemetryProvider) Meter ¶
func (tp *TelemetryProvider) Meter() metric.Meter
Meter returns the meter
Returns:
- metric.Meter: The OpenTelemetry meter
func (*TelemetryProvider) NewHTTPMiddleware ¶
func (tp *TelemetryProvider) NewHTTPMiddleware() func(http.Handler) http.Handler
NewHTTPMiddleware creates a new middleware for HTTP request tracing
Returns:
- func(http.Handler) http.Handler: The middleware function
func (*TelemetryProvider) Shutdown ¶
func (tp *TelemetryProvider) Shutdown(ctx context.Context) error
Shutdown shuts down the telemetry provider
Parameters:
- ctx: The context for the operation
Returns:
- error: An error if the shutdown fails
func (*TelemetryProvider) Tracer ¶
func (tp *TelemetryProvider) Tracer() trace.Tracer
Tracer returns the tracer
Returns:
- trace.Tracer: The OpenTelemetry tracer
type TracingConfig ¶
type TracingConfig struct {
// Enabled indicates whether tracing is enabled
Enabled bool `mapstructure:"enabled"`
// SamplingRatio is the ratio of traces to sample
SamplingRatio float64 `mapstructure:"sampling_ratio"`
// PropagationKeys are the keys to propagate in trace context
PropagationKeys []string `mapstructure:"propagation_keys"`
}
TracingConfig holds configuration for tracing
type TracingProvider ¶
type TracingProvider struct {
// contains filtered or unexported fields
}
TracingProvider holds the tracing provider and tracer
Source Files
Directories