Documentation
¶
Overview ¶
Package otel initializes the OpenTelemetry trace, metric, and log pipelines. It uses autoexport for environment-driven configuration of exporters, supporting all standard OTEL_* env vars per D-07.
Index ¶
- Variables
- func InitFreshnessGauge(lastSyncFn func(ctx context.Context) (time.Time, bool)) error
- func InitMemoryGauges() error
- func InitMetrics() error
- func InitObjectCountGauges(countsFn func() map[string]int64) error
- func InitResponseHeapHistogram() error
- func NewDualLogger(stdout io.Writer, logProvider *sdklog.LoggerProvider) *slog.Logger
- type SetupInput
- type SetupOutput
Constants ¶
This section is empty.
Variables ¶
var ResponseHeapDeltaBytes metric.Int64Histogram
ResponseHeapDeltaBytes records the per-request Go heap HeapInuse delta (exit - entry) for pdbcompat list handlers, in bytes. Populated by internal/pdbcompat.recordResponseHeapDelta via defer at the top of serveList.
Attributes: endpoint (e.g. "/api/net"), entity (e.g. "net"). Low-cardinality by construction — 1 endpoint per type × 13 types = 13 label combinations.
Registered by InitResponseHeapHistogram (Phase 71 Plan 05, D-06).
var RoleTransitions metric.Int64Counter
RoleTransitions counts LiteFS role transition events (promoted/demoted).
var SyncDuration metric.Float64Histogram
SyncDuration records the duration of sync operations in seconds.
var SyncOperations metric.Int64Counter
SyncOperations counts sync operations by status (success/failed).
var SyncPeakHeapBytes atomic.Int64
SyncPeakHeapBytes holds the most-recent end-of-sync-cycle Go runtime HeapInuse in bytes. Exposed via pdbplus.sync.peak_heap ObservableGauge (Prom name: pdbplus_sync_peak_heap_bytes) for Grafana / Prometheus dashboards to plot over time. Zero means "no sync has completed yet" — the gauge suppresses observation until the first store. Bytes is the canonical Prom unit; dashboards format MiB / GiB at render time.
var SyncPeakRSSBytes atomic.Int64
SyncPeakRSSBytes holds the most-recent end-of-sync-cycle /proc/self/status VmHWM in bytes (Linux only). Zero means "not Linux" or "no sync yet" — the gauge suppresses observation when zero.
var SyncTypeDeleted metric.Int64Counter
SyncTypeDeleted counts objects deleted per type.
var SyncTypeFallback metric.Int64Counter
SyncTypeFallback counts incremental-to-full fallback events per type.
var SyncTypeFetchErrors metric.Int64Counter
SyncTypeFetchErrors counts PeeringDB API fetch errors per type per D-10.
var SyncTypeObjects metric.Int64Counter
SyncTypeObjects counts objects synced per type.
var SyncTypeOrphans metric.Int64Counter
SyncTypeOrphans counts FK-orphan rows observed per sync cycle, broken down by {type, parent_type, field, action} where action is "drop" (row excluded entirely from upsert) or "null" (FK column nulled but row kept). Provides the per-cycle aggregate that replaces the per-row WARN logs which previously blew Tempo's 7.5 MB per-trace budget.
var SyncTypeUpsertErrors metric.Int64Counter
SyncTypeUpsertErrors counts database upsert errors per type per D-10.
Functions ¶
func InitFreshnessGauge ¶ added in v1.1.0
InitFreshnessGauge registers the sync freshness observable gauge per D-09. The lastSyncFn callback returns the time of the last successful sync. Must be called after OTel Setup() and database initialization.
func InitMemoryGauges ¶ added in v1.15.0
func InitMemoryGauges() error
InitMemoryGauges registers observable gauges that report the most-recent end-of-sync-cycle peak heap and RSS (bytes) for SEED-001 dashboard watch. Values are updated by internal/sync.(*Worker).emitMemoryTelemetry via the SyncPeakHeapBytes / SyncPeakRSSBytes atomics. A zero value suppresses the observation (no sync yet, or non-Linux for RSS) so dashboards don't plot misleading zeros.
Bytes is the canonical Prom unit (post-2026-04-26 audit); dashboards format MiB / GiB at render time via Grafana's "bytes" field unit.
func InitMetrics ¶
func InitMetrics() error
InitMetrics registers custom metric instruments for sync operations per D-05. HTTP metrics are handled automatically by otelhttp middleware (Plan 03).
func InitObjectCountGauges ¶ added in v1.5.0
InitObjectCountGauges registers an observable Int64Gauge that reports the number of objects stored per PeeringDB type. Reads from a cache function that returns pre-computed counts updated at sync completion time (PERF-02). Must be called after OTel Setup().
func InitResponseHeapHistogram ¶ added in v1.16.0
func InitResponseHeapHistogram() error
InitResponseHeapHistogram registers the per-request heap-delta histogram for pdbcompat response paths (Phase 71 D-06, MEMORY-03). Called from main.go at startup after the OTel SDK is ready. Analogous to InitMemoryGauges but records a histogram (distribution over p50/p95/p99) rather than a point-in-time gauge, because per-request deltas are the thing operators want a distribution over — not a last-write-wins value.
Bucket boundaries span 512 B to 512 MiB (in bytes per the post-2026-04-26 audit unit canonicalisation): the low end catches near-zero-delta responses (cached small payloads), the high end the budget-breach neighbourhood (PDBPLUS_RESPONSE_MEMORY_LIMIT default 128 MiB; buckets step past that into 256 / 512 MiB territory so outliers still get counted).
func NewDualLogger ¶
NewDualLogger creates a slog.Logger that sends every log record to both a JSON stdout handler and the OTel log pipeline via otelslog per D-03. This ensures logs are always visible on stdout even if the OTel backend is unavailable.
Types ¶
type SetupInput ¶
SetupInput holds configuration for initializing the OTel pipeline. SampleRate controls trace sampling (0.0 to 1.0) per D-02.
type SetupOutput ¶
type SetupOutput struct {
// Shutdown flushes all providers and must be called before program exit.
Shutdown func(context.Context) error
// LogProvider is exposed so the caller can create a dual slog handler
// that bridges slog records into the OTel log pipeline.
LogProvider *sdklog.LoggerProvider
}
SetupOutput holds the OTel shutdown function and LoggerProvider for creating the dual slog handler.
func Setup ¶
func Setup(ctx context.Context, in SetupInput) (*SetupOutput, error)
Setup initializes TracerProvider, MeterProvider, and LoggerProvider using autoexport for environment-driven exporter selection per D-06, D-07. Individual signals can be disabled via OTEL_*_EXPORTER=none per D-04.
Source Files