Documentation
¶
Overview ¶
Package olly is a portable OpenTelemetry helper for Go services.
Boundary rules:
- No imports of product application packages.
- No product-specific service names, operation names, or metric names.
- Apps own business span names and redaction policy.
- olly owns provider lifecycle, optional OTLP export, local failure-trace dumps, HTTP middleware, CLI Run helpers, and small span error helpers.
Package layout:
- olly: Init, Config, Shutdown, Flush (env-aware OTLP)
- olly/dump: SpanProcessor that buffers by trace and writes JSON on envelope ERROR
- olly/errors: span annotation helpers (Record, EndWithStatus, IDs)
- olly/http: WrapHandler, Middleware, WrapTransport, Client
- olly/cli: AddFlags, ConfigFromEnv, Run, Lifecycle (stdlib flag; no cobra)
Index ¶
- Constants
- func BoolPtr(b bool) *bool
- func EnvelopeKind() trace.SpanKind
- func Flush(ctx context.Context) error
- func Init(cfg Config) (func(context.Context) error, error)
- func Provider() *sdktrace.TracerProvider
- func SamplerForRatio(ratio float64) sdktrace.Sampler
- func Shutdown(ctx context.Context) error
- func Tracer(instrumentationName string) trace.Tracer
- type Config
- type Protocol
Constants ¶
const DefaultOTLPEndpoint = "localhost:4319"
DefaultOTLPEndpoint is the local Polypus HyperDX OTLP/gRPC host:port. Init does not apply it automatically when OTLPEndpoint is empty (empty still means dump-only). Apps and ConfigFromEnv may use this constant.
Variables ¶
This section is empty.
Functions ¶
func EnvelopeKind ¶
EnvelopeKind is the default process envelope for failure dumps (SERVER).
func Init ¶
Init installs the global TracerProvider, W3C propagator, optional OTLP exporter, and optional failure-dump processor. Returns a shutdown function.
Environment fallbacks (when Config fields are empty) follow the OpenTelemetry spec names; see Config and Config.Resolve.
func Provider ¶
func Provider() *sdktrace.TracerProvider
Provider returns the SDK provider installed by Init, or nil.
func SamplerForRatio ¶
SamplerForRatio returns AlwaysSample for local/full capture (ratio <=0 or >=1). Otherwise ParentBased TraceIDRatioBased for partial export.
Types ¶
type Config ¶
type Config struct {
// Enabled installs a real TracerProvider. When false, Init installs noop.
Enabled bool
// ServiceName is set on the resource as service.name.
// Empty falls back to OTEL_SERVICE_NAME, then "olly".
ServiceName string
// OTLPEndpoint is host:port or URL for OTLP. Empty skips OTLP after env
// fallback (dump-only tracing still works when Dump.Dir is set).
// Env fallback: OTEL_EXPORTER_OTLP_TRACES_ENDPOINT, then OTEL_EXPORTER_OTLP_ENDPOINT.
OTLPEndpoint string
// Protocol is grpc or http/protobuf. Empty falls back to
// OTEL_EXPORTER_OTLP_TRACES_PROTOCOL, then OTEL_EXPORTER_OTLP_PROTOCOL, then grpc.
Protocol Protocol
// Headers are sent with OTLP export (e.g. authorization for HyperDX cloud).
// Env fallback: OTEL_EXPORTER_OTLP_TRACES_HEADERS, then OTEL_EXPORTER_OTLP_HEADERS
// (comma-separated k=v). Explicit Headers win over env for the same key.
Headers map[string]string
// Insecure overrides TLS. Nil derives from the endpoint: localhost, 127.0.0.1,
// or an http:// scheme uses insecure; otherwise TLS.
Insecure *bool
// OTLPTimeout bounds exporter construction. Zero uses 10s.
OTLPTimeout time.Duration
// BatchTimeout is the OTLP batch export interval. Zero uses 3s.
BatchTimeout time.Duration
// SampleRatio is 0..1. Values <=0 or >=1 use AlwaysSample.
SampleRatio float64
// AllowOTLPFailure continues with dump-only tracing when OTLP setup fails.
// When false, Init returns the exporter error.
AllowOTLPFailure bool
// Dump configures the local failure-trace processor. Empty Dir disables it.
Dump dump.Config
// ExtraProcessors are appended after the dump processor (if any).
ExtraProcessors []sdktrace.SpanProcessor
// ResourceAttributes are merged onto the default resource (service.name wins from ServiceName).
// Env OTEL_RESOURCE_ATTRIBUTES (comma-separated k=v) fill keys not set here.
ResourceAttributes map[string]string
// Diagnostics receives dump write/prune messages. Nil uses stderr.
Diagnostics dump.Diagnostics
}
Config controls provider construction.
Directories
¶
| Path | Synopsis |
|---|---|
|
Package cli provides stdlib helpers to wire OpenTelemetry into Go CLIs with minimal boilerplate.
|
Package cli provides stdlib helpers to wire OpenTelemetry into Go CLIs with minimal boilerplate. |
|
Package dump buffers OpenTelemetry spans and writes JSON when a process envelope ends with an ERROR somewhere in the trace.
|
Package dump buffers OpenTelemetry spans and writes JSON when a process envelope ends with an ERROR somewhere in the trace. |
|
Package errors annotates OpenTelemetry spans from Go errors.
|
Package errors annotates OpenTelemetry spans from Go errors. |
|
Package http wraps net/http handlers and clients with OpenTelemetry spans.
|
Package http wraps net/http handlers and clients with OpenTelemetry spans. |