Documentation
¶
Overview ¶
Package otel provides OpenTelemetry integration for the gaz framework.
This package implements distributed tracing using OpenTelemetry with OTLP export. It provides a TracerProvider that can be used to instrument gRPC and HTTP servers for request tracing and observability.
Auto-Enable Behavior ¶
OpenTelemetry tracing is automatically enabled when an OTLP endpoint is configured. If no endpoint is set, the package gracefully degrades and returns a nil TracerProvider. This allows applications to run without a collector in development environments.
Configuration ¶
The package can be configured via:
- Module options (WithEndpoint, WithServiceName, WithSampleRatio)
- Environment variables (OTEL_EXPORTER_OTLP_ENDPOINT as fallback)
Usage ¶
Use NewModule to register the TracerProvider with the DI container:
app := gaz.New()
app.Use(otel.NewModule(
otel.WithEndpoint("localhost:4317"),
otel.WithServiceName("my-service"),
))
The TracerProvider is automatically shut down when the application stops.
Instrumentation ¶
Once the TracerProvider is registered, other server packages (grpc, vanguard) will automatically detect and use it for request tracing. Traces propagate across service boundaries using W3C Trace Context headers.
Graceful Degradation ¶
If the OTLP collector is unreachable at startup, the package logs a warning and continues without tracing. This ensures applications start gracefully even when observability infrastructure is temporarily unavailable.
Index ¶
Constants ¶
const (
// DefaultSampleRatio is the default sampling ratio for root spans (10%).
DefaultSampleRatio = 0.1
)
Variables ¶
This section is empty.
Functions ¶
func InitTracer ¶
func InitTracer(ctx context.Context, cfg Config, logger *slog.Logger) (*sdktrace.TracerProvider, error)
InitTracer initializes the OpenTelemetry TracerProvider.
If cfg.Endpoint is empty, returns nil (OTEL disabled). If the exporter fails to connect, logs a warning and returns nil (graceful degradation).
The function sets the global TracerProvider and TextMapPropagator.
func NewModule ¶
NewModule creates an OTEL module. Returns a gaz.Module that registers TracerProvider components.
If no endpoint is configured (via flags or OTEL_EXPORTER_OTLP_ENDPOINT env var), tracing is disabled and a nil TracerProvider is registered.
Components registered:
- otel.Config
- *sdktrace.TracerProvider (may be nil if disabled)
Example:
app := gaz.New() app.Use(otel.NewModule())
func ShutdownTracer ¶
func ShutdownTracer(ctx context.Context, tp *sdktrace.TracerProvider) error
ShutdownTracer gracefully shuts down the TracerProvider. It flushes pending spans with a 5-second timeout. Returns nil if tp is nil.
Types ¶
type Config ¶
type Config struct {
// Endpoint is the OTLP endpoint (e.g., "localhost:4317").
// If empty, tracing is disabled.
Endpoint string `json:"endpoint" yaml:"endpoint" mapstructure:"endpoint"`
// ServiceName is the service name for traces.
// Default: "gaz".
ServiceName string `json:"service_name" yaml:"service_name" mapstructure:"service_name"`
// SampleRatio is the sampling ratio for root spans (0.0-1.0).
// Only applies to spans without incoming trace context.
// Default: 0.1 (10%).
SampleRatio float64 `json:"sample_ratio" yaml:"sample_ratio" mapstructure:"sample_ratio"`
// Insecure uses insecure connection to the collector.
// Default: true for development.
Insecure bool `json:"insecure" yaml:"insecure" mapstructure:"insecure"`
}
Config holds OpenTelemetry configuration.
func DefaultConfig ¶
func DefaultConfig() Config
DefaultConfig returns the default OTEL configuration.
func (*Config) SetDefaults ¶
func (c *Config) SetDefaults()
SetDefaults applies default values to zero-value fields. Implements the config.Defaulter interface.
Source Files