Documentation
¶
Overview ¶
Package obs provides Glacier's OpenTelemetry-based observability : metrics and traces. Logs stay in log/. Initialize via obs.Init, which configures a shared Provider holding a MeterProvider and TracerProvider with Glacier defaults (resource attributes from build info, configurable sampler and exporter). Typed counter, histogram, and gauge constructors use Go generics over int64 and float64 (the OTEL instrument types). Span helpers wrap go.opentelemetry.io/otel/trace with Glacier-flavored ergonomics and ctx propagation. The log/ bridge automatically appends trace_id and span_id attributes to log records when an active span is in ctx. Every other framework package gains opt-in instrumentation via WithTracing() and WithMetrics() options; when unset, overhead is zero. Full API in specs/0017-obs.md.
Index ¶
- Constants
- Variables
- func SpanIDFromContext(ctx context.Context) string
- func TraceIDFromContext(ctx context.Context) string
- func WithEndpoint(endpoint string) option.Option[initConfig]
- func WithInsecure() option.Option[initConfig]
- func WithLogger(l *slog.Logger) option.Option[initConfig]
- func WithMetricsInterval(d time.Duration) option.Option[initConfig]
- func WithResourceAttributes(attrs ...attribute.KeyValue) option.Option[initConfig]
- func WithSampler(s sdktrace.Sampler) option.Option[initConfig]
- func WithSpanAttributes(attrs ...attribute.KeyValue) option.Option[spanConfig]
- func WithSpanKind(k oteltrace.SpanKind) option.Option[spanConfig]
- type Counter
- type Gauge
- type Histogram
- type NumericType
- type Provider
- type Span
- type SpanKind
Examples ¶
Constants ¶
const ( SpanKindInternal = oteltrace.SpanKindInternal SpanKindServer = oteltrace.SpanKindServer SpanKindClient = oteltrace.SpanKindClient SpanKindProducer = oteltrace.SpanKindProducer SpanKindConsumer = oteltrace.SpanKindConsumer )
Span kind constants re-exported for convenience.
Variables ¶
var ( // HTTP attributes. AttrHTTPMethod = attribute.Key("http.method") AttrHTTPStatusCode = attribute.Key("http.status_code") AttrHTTPURL = attribute.Key("http.url") AttrHTTPRoute = attribute.Key("http.route") // CLI attributes. AttrCLICommand = attribute.Key("cli.command") AttrCLIExitCode = attribute.Key("cli.exit_code") // Conf attributes. AttrConfSection = attribute.Key("conf.section") AttrConfSource = attribute.Key("conf.source") // Common. AttrErrorType = attribute.Key("error.type") AttrServiceName = attribute.Key("service.name") )
Standard attribute keys for Glacier instrumentation.
Functions ¶
func SpanIDFromContext ¶
SpanIDFromContext returns the hex span ID from the current span in ctx, or "" if no span is active.
func TraceIDFromContext ¶
TraceIDFromContext returns the hex trace ID from the current span in ctx, or "" if no span is active.
func WithEndpoint ¶
WithEndpoint sets the OTLP gRPC endpoint (e.g., "localhost:4317").
func WithInsecure ¶
WithInsecure disables TLS for the OTLP gRPC connection (for dev/test).
func WithLogger ¶
WithLogger sets the slog.Logger for internal obs operational events.
func WithMetricsInterval ¶
WithMetricsInterval sets how often metrics are exported.
func WithResourceAttributes ¶
WithResourceAttributes adds key-value pairs to the OTEL resource description.
func WithSampler ¶
WithSampler sets the trace sampling strategy.
func WithSpanAttributes ¶
WithSpanAttributes adds attributes to a span at start time.
Types ¶
type Counter ¶
type Counter[T NumericType] struct { // contains filtered or unexported fields }
Counter[T] is a monotonically increasing counter.
func NewCounter ¶
func NewCounter[T NumericType](meterName, counterName string, opts ...otelmetric.MeterOption) (*Counter[T], error)
NewCounter creates a Counter[T] using the named meter and instrument.
type Gauge ¶
type Gauge[T NumericType] struct { // contains filtered or unexported fields }
Gauge[T] is a point-in-time measurement.
func NewGauge ¶
func NewGauge[T NumericType](meterName, gaugeName string, opts ...otelmetric.MeterOption) (*Gauge[T], error)
NewGauge creates a Gauge[T] using the named meter and instrument.
type Histogram ¶
type Histogram[T NumericType] struct { // contains filtered or unexported fields }
Histogram[T] records value distributions.
func NewHistogram ¶
func NewHistogram[T NumericType](meterName, histName string, opts ...otelmetric.MeterOption) (*Histogram[T], error)
NewHistogram creates a Histogram[T] using the named meter and instrument.
type NumericType ¶
NumericType is the constraint for metric value types.
type Provider ¶
type Provider struct {
// contains filtered or unexported fields
}
Provider wraps OTEL SDK providers and their shared lifecycle.
var Default *Provider
Default is the package-level shared provider. nil until Init is called.
func Init ¶
Init creates a Provider with an OTLP gRPC exporter and sets obs.Default. If the OTEL endpoint is not configured (env or WithEndpoint), Init returns a no-op Provider (zero overhead).
Init is idempotent: the second call is a no-op if Default is already set.
Example ¶
ExampleInit demonstrates initializing the obs package in no-op mode.
package main
import (
"context"
"github.com/nathanbrophy/glacier/obs"
)
func main() {
p, err := obs.Init(context.Background())
if err != nil {
panic(err)
}
defer p.Shutdown(context.Background()) //nolint:errcheck
}
Output:
type Span ¶
type Span struct {
// contains filtered or unexported fields
}
Span wraps an OTEL span with Glacier-flavored helpers.
func SpanFromContext ¶
SpanFromContext returns the current span from ctx, or a no-op span.
func StartSpan ¶
func StartSpan(ctx context.Context, tracerName, spanName string, opts ...option.Option[spanConfig]) (context.Context, *Span)
StartSpan begins a new span and returns a derived context and the Span.
The caller must call span.End() when done, typically via defer.
Example ¶
ExampleStartSpan demonstrates starting and ending a span.
package main
import (
"context"
"github.com/nathanbrophy/glacier/obs"
)
func main() {
ctx, span := obs.StartSpan(context.Background(), "my-service", "my-operation")
defer span.End()
_ = ctx
}
Output:
func (*Span) RecordError ¶
RecordError records err as an exception on the span.
func (*Span) SetAttribute ¶
SetAttribute sets an attribute on the span.
Source Files