olly

package module
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 6, 2026 License: Apache-2.0 Imports: 13 Imported by: 0

README

olly

Portable OpenTelemetry helper for Behavior Engineering services.

Module: github.com/behaviorengineering/olly.

Apps map their own config and logger at the boundary, then call olly.Init once at process start. olly installs the global tracer provider, optional OTLP export, and an optional local failure-trace dump processor.

What olly owns

Package Role
olly Provider lifecycle (Init, Shutdown, Flush), sampling, W3C propagation
olly/dump Buffer spans by trace_id; write JSON when SERVER envelopes end with ERROR
olly/errors Annotate spans from Go errors; expose trace/span IDs for logs

What stays in the app

  • Service names, operation taxonomies, HTTP wrappers
  • Redaction of product-specific attributes (pass dump hooks)
  • Business metrics and logger implementations
  • Pipeline execution records (strop/runreport)

Failure dumps

Default completion policy (one mode for gateway and CLI):

  1. Buffer spans by trace_id.
  2. Treat SpanKindServer as this process's envelope (not IsRoot(); inbound traceparent makes the local envelope a remote child).
  3. Write JSON when envelope in-flight hits zero and any buffered span had ERROR.
  4. On shutdown, dump leftover error buffers.

Successful traces are not written. Retention is by max age and max files.

Quick start

import (
    "context"

    "github.com/behaviorengineering/olly"
    "github.com/behaviorengineering/olly/dump"
)

shutdown, err := olly.Init(olly.Config{
    Enabled:      true,
    ServiceName:  "my-service",
    OTLPEndpoint: "localhost:4317", // empty = dump-only / no OTLP
    Dump: dump.Config{
        Dir:         "logs/failures",
        MaxAgeHours: 48,
        MaxFiles:    20,
    },
})
if err != nil {
    return err
}
defer shutdown(context.Background())

Releases (for agents)

Default bump on each releasable merge to main is patch (vX.Y.(Z+1)). Skip docs/chore/ci-only ranges and [skip release]. Consumers pin both the git checkout and go.mod to the same v* tag.

Documentation

Overview

Package olly is a portable OpenTelemetry helper for Go services.

Boundary rules:

  1. No imports of product application packages.
  2. No product-specific service names, operation names, or metric names.
  3. Apps own loggers, HTTP wrappers, and business instrumentation.
  4. olly owns provider lifecycle, optional OTLP export, local failure-trace dumps, and small span error helpers.

Package layout:

  • olly: Init, Config, Shutdown, Flush
  • olly/dump: SpanProcessor that buffers by trace and writes JSON on envelope ERROR
  • olly/errors: span annotation helpers (Record, EndWithStatus, TraceIDs)

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func EnvelopeKind

func EnvelopeKind() trace.SpanKind

EnvelopeKind is the default process envelope for failure dumps (SERVER).

func Flush

func Flush(ctx context.Context) error

Flush flushes pending spans when an SDK provider is active.

func Init

func Init(cfg Config) (func(context.Context) error, error)

Init installs the global TracerProvider, W3C propagator, optional OTLP exporter, and optional failure-dump processor. Returns a shutdown function.

func Provider

func Provider() *sdktrace.TracerProvider

Provider returns the SDK provider installed by Init, or nil.

func SamplerForRatio

func SamplerForRatio(ratio float64) sdktrace.Sampler

SamplerForRatio returns AlwaysSample for local/full capture (ratio <=0 or >=1). Otherwise ParentBased TraceIDRatioBased for partial export.

func Shutdown

func Shutdown(ctx context.Context) error

Shutdown shuts down the provider installed by Init.

func Tracer

func Tracer(instrumentationName string) trace.Tracer

Tracer returns a named tracer from the global provider.

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.
	ServiceName string
	// OTLPEndpoint is host:port for OTLP/gRPC (insecure). Empty skips OTLP;
	// dump-only tracing still works when Dump.Dir is set.
	OTLPEndpoint string
	// 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).
	ResourceAttributes map[string]string
	// Diagnostics receives dump write/prune messages. Nil uses stderr.
	Diagnostics dump.Diagnostics
}

Config controls provider construction.

func (Config) Defaults

func (c Config) Defaults() Config

Defaults fills zero-value timeouts and dump retention.

Directories

Path Synopsis
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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL