Documentation
¶
Overview ¶
Package otelcore holds the OTLP/OTel export plumbing shared by GTB's analytics pipeline and its web-service observability signals: OTLP/HTTP endpoint parsing, the service resource, telemetry.* configuration resolution, and the GTB config adapter that can observe a resolved signal settings source.
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 see when a resolved settings snapshot changes without importing the GTB config container.
Index ¶
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 ObserveSettingsFromConfig ¶ added in v0.30.0
func ObserveSettingsFromConfig( cfg gtbconfig.Containable, signal string, opts ...gtbconfig.SectionBindingOption[Settings], ) (*gtbconfig.ObservedSection[Settings], error)
ObserveSettingsFromConfig binds a single telemetry signal's resolved OTLP settings to cfg and keeps the typed snapshot rehydrated after successful config reloads.
Types ¶
type Config ¶ added in v0.30.0
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 ¶
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 Resolve ¶
func Resolve(cfg gtbconfig.Containable, signal string) Settings
Resolve reads telemetry.<signal>.* overlaid on the shared telemetry.* keys, in the same shared-plus-override style as pkg/tls. A per-signal key, when set, overrides the shared value for that one field. Enabled is per-signal only.
An empty Endpoint is intentional and not an error: it lets the OTel SDK fall back to the standard OTEL_EXPORTER_OTLP_* environment variables, so operators who configure the ecosystem's env vars need set nothing in GTB config beyond telemetry.<signal>.enabled.
func ResolveSettings ¶ added in v0.30.0
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 ¶ added in v0.30.0
SettingsSource exposes the latest resolved signal settings without requiring packages to import GTB's config adapter package.
type SignalConfig ¶ added in v0.30.0
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 ¶ added in v0.30.0
SignalOverrides records which per-signal fields were explicitly supplied by an adapter and should override shared config.
Source Files