Operations and readiness

Structured logs

The application emits lifecycle and request logs by default. See Server output and logging for configuration, startup URLs and request IDs. Trace propagation and metrics below are independently opt-in.

Health and readiness

/healthz reports that HTTP is serving. /readyz returns 200 only while the application is running and its managed readiness resources and named checks succeed; otherwise it returns a redacted 503. Registrar.Check(name, func(context.Context) error) registers an application-specific check. Checks share a one-second budget and must honor context. The GORM resource pings its pool; the gRPC server checks its transport lifecycle. Check downstream RPC availability explicitly with Clients.Ready, rather than assuming a constructed client is connected.

Propagate trace context

observability.HTTP(metrics) is optional Gin middleware installed through config.Config.Middleware. It accepts valid version-00 traceparent headers, preserves the trace ID and creates a new span ID. Invalid/duplicate headers start a fresh trace. observability.Traceparent(ctx) reads the current value. Optional observability/grpc.Client and Server unary interceptors propagate it across services; credentials and arbitrary incoming metadata are not forwarded. Streaming trace propagation and an OTLP exporter are not implemented.

Collect metrics

observability.NewMetrics() is a managed resource. Counters track completed requests, errors, in-flight work and cumulative elapsed nanoseconds by fixed route/RPC name. Unknown HTTP URLs share an unmatched label; raw URLs, user IDs and secrets are excluded. SnapshotContext copies measurements for a caller-owned exporter. Call SetReadiness(application.Ready) to include dependency readiness; without that callback, readiness represents the metrics resource's lifecycle only. Snapshots now include bounded cumulative duration histograms; opt-in Prometheus exporting and trace correlation are described in Metrics and tracing. No external backend is required.

Expose example metrics

The basic example enables tracing/counters and exposes its JSON metrics route only with GONEX_EXPOSE_METRICS=1. Protect that route at your deployment boundary if enabled. There is no exporter endpoint by default in framework applications.

Drain and stop services

Shutdown first stops accepting HTTP traffic and drains active requests within the shutdown budget, then closes managed resources in reverse order. gRPC uses graceful stop with a forced stop when its context expires. Signal handling belongs to the executable. HTTP deadline middleware cancels request contexts; handlers and dependency calls must honor them. A handler that ignores context cannot be forcibly interrupted safely.

Verify your application

Run go tool gonex check from your generated project and test your public endpoints. Probe /healthz and /readyz separately, verify dependency-failure behavior, and allow shutdown time in your process manager. Framework regression tests belong in Contribute: testing.