otelcore

Documentation

Overview

Package otelcore holds the transport-neutral OTLP/OTel export plumbing shared by the observability signals: OTLP/HTTP endpoint parsing, the service Resource, the typed per-signal Settings, and the shared-plus-per-signal ResolveSettings merge. Callers materialise Settings from wherever their configuration lives and hand them to the logs, metrics, and tracing packages.

It deliberately imports no signal exporters. Traces, metrics and logs each build their own typed exporter (otlptracehttp, otlpmetrichttp, otlploghttp) from a resolved Settings and Endpoint, so this package stays free of any single signal's dependencies and can be shared by all of them. Long-lived callers can depend on SettingsSource to observe when a resolved settings snapshot changes without coupling to a particular configuration container.

Index

• Constants
• Variables
• func Resource(name, version string) *resource.Resource
• type Config
• type Endpoint
  • func ParseEndpoint(rawURL string, insecure bool, headers map[string]string) (Endpoint, error)
• type Settings
  • func ResolveSettings(shared Config, signal SignalConfig, overrides SignalOverrides) Settings
• type SettingsSource
• type SignalConfig
• type SignalOverrides

Constants

const (
	SignalTracing = "tracing"
	SignalMetrics = "metrics"
	SignalLogs    = "logs"
)

Signal names, used both as the per-signal config sub-key (telemetry.<signal>.*) and as the OTLP URL path suffix.

const MaxEndpointLength = 2048

MaxEndpointLength caps the length, in bytes, of an OTLP endpoint URL. Legitimate collector endpoints are well under 200 bytes; 2 KiB is generous for proxy configurations and far short of any pathological input.

const Root = "telemetry"

Root is the config key prefix shared by the analytics pipeline and the observability signals.

Variables

var ErrInvalidEndpoint = errors.New("invalid OTLP endpoint")

ErrInvalidEndpoint is returned when an OTLP endpoint fails validation. Callers can distinguish validation failures from other errors via errors.Is.

Functions

func Resource

func Resource(name, version string) *resource.Resource

Resource builds the OTel resource that identifies the emitting service. name and version populate the service.name and service.version semantic-convention attributes that appear as labels on every signal in the backend.

Types

type Config

type Config struct {
	Endpoint string            `mapstructure:"endpoint" yaml:"endpoint" json:"endpoint"`
	Headers  map[string]string `mapstructure:"headers" yaml:"headers" json:"headers"`
	Insecure bool              `mapstructure:"insecure" yaml:"insecure" json:"insecure"`
}

Config holds shared OTLP settings that can be overlaid by each signal.

type Endpoint

type Endpoint struct {
	Host     string            // host:port, e.g. "collector:4318"
	BasePath string            // path prefix the per-signal suffix is appended to
	Insecure bool              // plaintext OTLP (http scheme, or an explicit insecure flag)
	Headers  map[string]string // exporter headers, e.g. an auth token
}

Endpoint is a parsed OTLP/HTTP base URL, split into the components every signal exporter needs. Each signal appends its own suffix to BasePath: "/v1/traces", "/v1/metrics" or "/v1/logs".

func ParseEndpoint

func ParseEndpoint(rawURL string, insecure bool, headers map[string]string) (Endpoint, error)

ParseEndpoint splits an OTLP/HTTP base URL into exporter components. An http scheme, or insecure being true, marks the endpoint as plaintext — use that only for a local collector.

The endpoint is validated fail-fast, mirroring chat.ValidateBaseURL: an empty, over-long, control-character-bearing, unparseable, schemeless or hostless URL is rejected with an error wrapping ErrInvalidEndpoint, as is any URL carrying userinfo (`http://user:pass@host`) — credentials belong in headers, never the URL. Only http and https schemes are accepted (OTLP/HTTP commonly allows both; http is plaintext and marks the endpoint insecure). A malformed endpoint thus surfaces immediately rather than failing later or silently at export time.

type Settings

type Settings struct {
	Enabled  bool
	Endpoint string // OTLP/HTTP base URL; empty means "let the SDK read OTEL_* env vars"
	Headers  map[string]string
	Insecure bool
}

Settings is the resolved OTLP target for a single signal.

func ResolveSettings

func ResolveSettings(shared Config, signal SignalConfig, overrides SignalOverrides) Settings

ResolveSettings overlays per-signal settings on shared telemetry settings. Enabled is always per-signal only.

type SettingsSource

type SettingsSource interface {
	Current() *Settings
	Version() uint64
}

SettingsSource exposes the latest resolved signal settings without coupling callers to a particular configuration container or adapter.

type SignalConfig

type SignalConfig struct {
	Enabled  bool              `mapstructure:"enabled" yaml:"enabled" json:"enabled"`
	Endpoint string            `mapstructure:"endpoint" yaml:"endpoint" json:"endpoint"`
	Headers  map[string]string `mapstructure:"headers" yaml:"headers" json:"headers"`
	Insecure bool              `mapstructure:"insecure" yaml:"insecure" json:"insecure"`
}

SignalConfig holds per-signal OTLP settings.

type SignalOverrides

type SignalOverrides struct {
	Endpoint bool
	Headers  bool
	Insecure bool
}

SignalOverrides records which per-signal fields were explicitly supplied by an adapter and should override shared config.