Documentation
¶
Overview ¶
Package telemetry wires OpenTelemetry traces and metrics, and log/slog.
The provider is a value. It sets no global provider, because design rule 1 forbids global mutable state. The application passes it to each subsystem that produces a span.
The default exporter is none. With every exporter off, the HTTP middleware returns the handler that it received, so a request costs no extra allocation. See the SDD, S3.
Index ¶
- Constants
- func Attr(key string, value any) attribute.KeyValue
- type Fault
- type Option
- type Provider
- func (p *Provider) DrelOption() drel.Option
- func (p *Provider) DrelTracer() drel.Tracer
- func (p *Provider) HTTPMiddleware() router.Middleware
- func (p *Provider) Logger() *slog.Logger
- func (p *Provider) Meter() metric.Meter
- func (p *Provider) MetricsEnabled() bool
- func (p *Provider) Name() string
- func (p *Provider) Start(context.Context) error
- func (p *Provider) StartClient(ctx context.Context, name string, attrs ...attribute.KeyValue) (context.Context, trace.Span)
- func (p *Provider) StartConsumer(ctx context.Context, name string, attrs ...attribute.KeyValue) (context.Context, trace.Span)
- func (p *Provider) StartInternal(ctx context.Context, name string, attrs ...attribute.KeyValue) (context.Context, trace.Span)
- func (p *Provider) StartProducer(ctx context.Context, name string, attrs ...attribute.KeyValue) (context.Context, trace.Span)
- func (p *Provider) Stop(ctx context.Context) error
- func (p *Provider) Tracer() trace.Tracer
- func (p *Provider) TracesEnabled() bool
Constants ¶
const ( // ExporterNone produces no telemetry. It is the default. ExporterNone = "none" // ExporterOTLP sends to a collector over OTLP. ExporterOTLP = "otlp" )
The exporter names that OTEL_TRACES_EXPORTER and OTEL_METRICS_EXPORTER take.
const ProtocolHTTP = "http/protobuf"
ProtocolHTTP is the only OTLP protocol that Avero ships.
The gRPC exporter is a module that the SDD does not name, so Avero does not import it. google.golang.org/grpc still reaches the build through go.opentelemetry.io/proto/otlp, which the OTLP HTTP exporters use for their message types. Avero opens no gRPC connection.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Fault ¶
type Fault struct {
// Variable is the environment variable at fault.
Variable string `json:"variable"`
// Message states the fault.
Message string `json:"message"`
// Repair states what to do. It is one sentence.
Repair string `json:"repair"`
// Err is the cause. It can be nil.
Err error `json:"-"`
}
Fault is one telemetry fault. It names the environment variable, states what went wrong, and states the repair in one sentence. See DX-7.
type Option ¶
type Option func(*options)
Option configures a provider.
func WithLogWriter ¶
WithLogWriter sends the log to w. The default is standard error.
func WithMeterProvider ¶
func WithMeterProvider(mp metric.MeterProvider) Option
WithMeterProvider supplies the meter provider. It replaces the exporter that the configuration names.
func WithTracerProvider ¶
func WithTracerProvider(tp trace.TracerProvider) Option
WithTracerProvider supplies the tracer provider. A test passes one that keeps every span in memory. It replaces the exporter that the configuration names.
type Provider ¶
type Provider struct {
// contains filtered or unexported fields
}
Provider holds the tracer, the meter and the logger of one application. Build it with New and register it as a component, so that Stop flushes the exporters inside SHUTDOWN_GRACE.
func New ¶
func New(cfg config.BaseConfig, opts ...Option) (*Provider, error)
New builds a provider from the OTEL_* variables of the configuration.
func (*Provider) DrelOption ¶
DrelOption returns the engine option that installs the tracer.
engine, err := drel.NewEngine(cfg.DatabaseURL, telemetry.DrelOption())
func (*Provider) DrelTracer ¶
DrelTracer returns the tracer that drel uses. It returns nil when the exporter is off, and drel then produces no span.
func (*Provider) HTTPMiddleware ¶
func (p *Provider) HTTPMiddleware() router.Middleware
HTTPMiddleware fills the trace slot of the middleware chain. It starts one server span for each request and records the duration.
With every exporter off it returns the handler that it received. The chain then holds no wrapper, so a request costs no extra call and no extra allocation. See the SDD, S3.
The span carries the route pattern and never the raw path, the query, a header or a cookie. A secret in a URL or in a header therefore never reaches an exporter.
func (*Provider) Logger ¶
Logger returns the logger. Every record inside a request carries the trace ID, the span ID and the request ID.
func (*Provider) MetricsEnabled ¶
MetricsEnabled reports whether a measurement reaches an exporter.
func (*Provider) Start ¶
Start does nothing. New builds the exporters, so a fault appears before the process starts. See DX-8.
func (*Provider) StartClient ¶
func (p *Provider) StartClient(ctx context.Context, name string, attrs ...attribute.KeyValue, ) (context.Context, trace.Span)
StartClient begins a span for a call to another service. A generated client calls it. See the SDD, S13.
func (*Provider) StartConsumer ¶
func (p *Provider) StartConsumer(ctx context.Context, name string, attrs ...attribute.KeyValue, ) (context.Context, trace.Span)
StartConsumer begins a span for a message that the application handles. The inbox consumer calls it. See the SDD, S8.
func (*Provider) StartInternal ¶
func (p *Provider) StartInternal(ctx context.Context, name string, attrs ...attribute.KeyValue, ) (context.Context, trace.Span)
StartInternal begins a span for work inside the application, such as a projection.
func (*Provider) StartProducer ¶
func (p *Provider) StartProducer(ctx context.Context, name string, attrs ...attribute.KeyValue, ) (context.Context, trace.Span)
StartProducer begins a span for a message that the application publishes. The outbox relay calls it. See the SDD, S7.
func (*Provider) Stop ¶
Stop flushes the exporters. The context carries the SHUTDOWN_GRACE deadline. It is safe to call more than one time.
func (*Provider) Tracer ¶
Tracer returns the tracer. It is a no-op tracer when the exporter is none.
func (*Provider) TracesEnabled ¶
TracesEnabled reports whether a span reaches an exporter.