pwobservability

Documentation

Index

• Constants
• func MetricsForced(config pwconfig.ObservabilityConfig) bool
• func MetricsPolicy(config pwconfig.ObservabilityConfig, provider *metric.Provider, exporting bool) *pwruntime.Metrics
• func ParseLevel(value string, fallback pwruntime.Level) (pwruntime.Level, error)
• func ParseQueryLevel(value string) (pwruntime.Level, error)
• func ParseTemporality(value string) (metric.Temporality, error)
• func ProcessLogger() pwruntime.Logger
• func QueryDiagnostics(config pwconfig.ObservabilityConfig, development bool) *pwruntime.QueryDiagnostics
• func RegisterRuntimeMetrics(meter *metric.Meter)
• func ReportQueryDiagnostics(diagnostics *pwruntime.QueryDiagnostics, env string, development bool, ...)
• func ResolveSampler(config pwconfig.ObservabilityConfig, env string) (trace.Sampler, error)
• func ResolveToggle(value string, auto bool) (bool, error)
• func SetProcessBackend(backend *pwruntime.LogBackend)
• func SwapProcessBackend(backend *pwruntime.LogBackend) func()
• func TraceForced(config pwconfig.ObservabilityConfig) bool
• func TracingPolicy(config pwconfig.ObservabilityConfig, exporting bool) *pwruntime.Tracing
• type Cleanup
• type Resolved
  • func Build(config pwconfig.ObservabilityConfig, env string) (*Resolved, error)
  • func (resolved *Resolved) Backend() *pwruntime.LogBackend
  • func (resolved *Resolved) Cleanups() []Cleanup
  • func (resolved *Resolved) MetricProvider() *metric.Provider
  • func (resolved *Resolved) Sampler() string
  • func (resolved *Resolved) Shutdown(ctx context.Context) error
  • func (resolved *Resolved) SinkCount() int
  • func (resolved *Resolved) Tracing() bool

Constants

const (
	TemporalityDelta      = "delta"
	TemporalityCumulative = "cumulative"
)

Metric temporality tokens.

const (
	StdoutFormatJSON      = "json"
	StdoutFormatPlaintext = "plaintext"
)

Stdout record formats.

const (
	QueryToggleAuto = "auto"
	QueryToggleOn   = "on"
	QueryToggleOff  = "off"
)

Diagnostic toggles. Auto ties the setting to something the process already knows, so a run that wants the ordinary answer configures nothing: query diagnostics read the runtime environment, and framework spans read whether anything exports them.

const (
	// The three are exported because the startup validation, which stays in the
	// runtime, states the same bounds in its refusal messages.
	DefaultSlowThreshold  = defaultQuerySlowThreshold
	DefaultMaxSQLLength   = defaultQueryMaxSQLLength
	DefaultMaxValueLength = defaultQueryMaxValueLength
)

Query diagnostics defaults.

The record level is info rather than debug because the framework does not yet build a handler from observability.minimum_level: a debug record would be dropped by the default slog handler, and a development aid that is on by default has to be visible by default.

Functions

func MetricsForced

func MetricsForced(config pwconfig.ObservabilityConfig) bool

MetricsForced reports whether configuration asked for instruments outright rather than through auto, which is what lets a project holding its own reader record without configuring an endpoint here.

func MetricsPolicy

func MetricsPolicy(config pwconfig.ObservabilityConfig, provider *metric.Provider, exporting bool) *pwruntime.Metrics

MetricsPolicy turns configuration into the runtime instrument set, or nil when the framework should record nothing.

exporting is the automatic answer, the same signal the trace policy reads: an aggregation nothing exports is pure cost. What it does not read is the trace policy itself — a process sampling one trace in a thousand still counts every request, and that independence is the reason both signals exist.

An invalid toggle resolves to nil here; validateMetricsConfig reports it before any request is served, exactly as the trace toggle does.

func ParseLevel

func ParseLevel(value string, fallback pwruntime.Level) (pwruntime.Level, error)

ParseLevel maps a configured token to a severity. An empty value keeps the caller's default rather than silently becoming the lowest severity.

func ParseQueryLevel

func ParseQueryLevel(value string) (pwruntime.Level, error)

func ParseTemporality

func ParseTemporality(value string) (metric.Temporality, error)

ParseTemporality maps the configured token to the exported temporality.

func ProcessLogger

func ProcessLogger() pwruntime.Logger

ProcessLogger returns a logger for framework output that belongs to the process rather than to a request. Before configuration is parsed it falls back to the same stderr logger an unconfigured context gets.

func QueryDiagnostics

func QueryDiagnostics(config pwconfig.ObservabilityConfig, development bool) *pwruntime.QueryDiagnostics

QueryDiagnostics turns configuration into the runtime setting, or nil when query diagnostics are off. Invalid values resolve to nil; validation reports them before requests are served. development is whether the development relaxations apply, which is narrower than the environment being "dev": a deployment that never set APP_ENV is not asking for a log of every statement with its bind values.

func RegisterRuntimeMetrics

func RegisterRuntimeMetrics(meter *metric.Meter)

RegisterRuntimeMetrics registers the go.* instruments of the runtime group.

Every one is an observable: the value already exists inside the runtime, and recording it as it changed would mean instrumenting the allocator. It is also the one group with no framework seam at all, which is why a deployment already collecting it from its own agent can decline it.

The process samples of the development telemetry viewer are not these: that watches the process from outside and cannot see a heap, a goroutine, or a GC cycle. Neither is derived from the other.

func ReportQueryDiagnostics

func ReportQueryDiagnostics(diagnostics *pwruntime.QueryDiagnostics, env string, development bool, driver string)

ReportQueryDiagnostics states at startup what the query log will do, so a missing capability is reported once instead of silently per statement, and a run that did not ask for development says out loud that records may carry row values.

The warning keys off development rather than off the environment token so that the one case most in need of it — a deployment that never set APP_ENV and landed on "dev" by default — is the case that gets it. Suppressing it there would leave the only signal about row values in logs behind the very condition that produced them.

func ResolveSampler

func ResolveSampler(config pwconfig.ObservabilityConfig, env string) (trace.Sampler, error)

ResolveSampler builds the head sampler for this process.

An empty configured name takes the environment's default rather than one value everywhere: development records every trace because the loop's only view of a request is the trace it kept, and every other environment samples because the process may be exporting straight to a backend that bills per span. Parse normally fills the key before this runs, so that the startup summary can name the provenance; the resolution is repeated here for the path that never parses a configuration at all.

func ResolveToggle

func ResolveToggle(value string, auto bool) (bool, error)

ResolveToggle reads the auto/on/off vocabulary shared by every diagnostic switch. auto is what the caller passes as the resolved automatic answer, which differs per setting: the runtime environment for query diagnostics, and whether anything exports traces for framework spans.

func SetProcessBackend

func SetProcessBackend(backend *pwruntime.LogBackend)

func SwapProcessBackend

func SwapProcessBackend(backend *pwruntime.LogBackend) func()

SwapProcessBackend installs a backend and returns the restore, for a test that has to read what the framework says about itself at startup. Startup records are written before any request, so there is no context to capture one through and the process-wide backend is the only seam there is.

func TraceForced

func TraceForced(config pwconfig.ObservabilityConfig) bool

TraceForced reports whether configuration asked for framework spans outright rather than through auto.

It is what installs the request root span in a process that exports nothing. Without it, "on" would produce a render span and a statement span with no parent between them and no server span above, which is a set of disconnected roots rather than a trace. A project reaching this state is one holding its own provider, and it wants the whole tree.

func TracingPolicy

func TracingPolicy(config pwconfig.ObservabilityConfig, exporting bool) *pwruntime.Tracing

TracingPolicy turns configuration into the runtime span policy, or nil when the framework should open no span of its own.

exporting is the automatic answer: whether this process has somewhere to send a span. It is the same signal that decides whether the request root span is created, so auto keeps the two in step — a run with no collector opens no root and no children, and the dev loop, which is handed an endpoint, gets the whole tree without configuring anything.

An invalid value resolves to nil here; validateTraceConfig reports it before any request is served, exactly as query diagnostics do.

Types

type Cleanup

type Cleanup struct {
	Name  string
	Close func(context.Context) error
}

Cleanup is one release this process owes, named so a runtime keeps one per name across repeated initialization.

type Resolved

type Resolved struct {
	// contains filtered or unexported fields
}

Resolved is the resolved emission and tracing state of one process.

func Build

func Build(config pwconfig.ObservabilityConfig, env string) (*Resolved, error)

Build resolves configuration and the standard OTLP environment into one emission policy.

The environment matters as much as the file here: api:cli-dev injects OTEL_EXPORTER_OTLP_ENDPOINT into the process it starts, so a developer gets traces and correlated logs without writing configuration at all.

func (*Resolved) Backend

func (resolved *Resolved) Backend() *pwruntime.LogBackend

Backend is the emission policy every request logger is built from.

func (*Resolved) Cleanups

func (resolved *Resolved) Cleanups() []Cleanup

Cleanups are what this process opened and must release, in the order they were opened. They are returned rather than registered because the shutdown order is the runtime's: a log sink has to outlive whatever still logs.

func (*Resolved) MetricProvider

func (resolved *Resolved) MetricProvider() *metric.Provider

MetricProvider is what the runtime instrument set is created from, or nil when this process exports nothing.

func (*Resolved) Sampler

func (resolved *Resolved) Sampler() string

Sampler describes which traces this process records, or an empty string when it builds no provider and therefore samples nothing at all.

func (*Resolved) Shutdown

func (resolved *Resolved) Shutdown(ctx context.Context) error

Shutdown flushes every provider within the caller's deadline. Records still queued at that point are lost by design: shutdown is bounded.

The metric reader is shut down first, because its final collection is a complete interval that would otherwise be the one discarded, and it is the only one of the three whose loss cannot be repaired by a later export.

func (*Resolved) SinkCount

func (resolved *Resolved) SinkCount() int

SinkCount reports how many destinations a record reaches.

func (*Resolved) Tracing

func (resolved *Resolved) Tracing() bool

Tracing reports whether a request root span should be created.