Documentation
¶
Overview ¶
Package serverboot collects the startup boilerplate shared by the long-running substrate server binaries (ateapi, atelet, ateom-gvisor, ateom-microvm): slog wiring, OTel tracer + meter providers, a Prometheus + /readyz HTTP surface, and a couple of small helpers for startup fail-fast.
Index ¶
- Constants
- func Fatal(ctx context.Context, msg string, err error)
- func InitLogger()
- func InitLoggerWithWriter(w io.Writer)
- func InitMetrics(ctx context.Context, serviceName string) (*sdkmetric.MeterProvider, error)
- func InitMetricsPushOnly(ctx context.Context, serviceName string, producers ...sdkmetric.Producer) (*sdkmetric.MeterProvider, error)
- func InitMetricsPushOnlyVia(ctx context.Context, serviceName string, conn *grpc.ClientConn, ...) (*sdkmetric.MeterProvider, error)
- func InitTracing(ctx context.Context, opts TracingOptions) (*sdktrace.TracerProvider, error)
- func LogLevel() slog.Leveler
- func SetLogLevel(level string) error
- func ShutdownProvider(name string, shutdown func(context.Context) error)
- func StartMetricsServer(ctx context.Context, opts MetricsServerOptions)
- func StartReadinessServer(ctx context.Context, addr string, readiness *Readiness)
- type MetricsServerOptions
- type Readiness
- type TraceSampling
- type TracingOptions
Constants ¶
const ControlPlaneTraceRatio = 0.1
ControlPlaneTraceRatio is the default root sampling ratio for the control plane binaries: low volume, and their traces are what lifecycle debugging needs, so the default leans generous.
Variables ¶
This section is empty.
Functions ¶
func Fatal ¶
Fatal logs msg + err and exits with status 1. For startup-time fail-fast where there's no recovery path.
func InitLogger ¶
func InitLogger()
InitLogger sets the global slog logger to a JSON handler wrapped in contextlogging.NewHandler, writing to os.Stdout. Call once at process start.
func InitLoggerWithWriter ¶
InitLoggerWithWriter is InitLogger with an explicit destination. Use it to share one synchronized writer between the runtime logger and a separate writer (e.g. ateom's actor-log forwarder) so their lines don't interleave.
func InitMetrics ¶
InitMetrics registers a global MeterProvider with both a Prometheus reader (exposed via StartMetricsServer's /metrics handler) and an OTLP periodic reader. No Producer option, unlike InitMetricsPushOnly: a bridged registry would be served twice, here and on its own endpoint.
func InitMetricsPushOnly ¶
func InitMetricsPushOnly(ctx context.Context, serviceName string, producers ...sdkmetric.Producer) (*sdkmetric.MeterProvider, error)
InitMetricsPushOnly is InitMetrics without the Prometheus reader, for binaries that run no metrics HTTP server of their own (ateom, atecontroller): a pull reader would collect into a registry nothing serves. producers put metrics recorded outside the OTel SDK on the same push path; atecontroller bridges controller-runtime's registry that way.
func InitMetricsPushOnlyVia ¶
func InitMetricsPushOnlyVia(ctx context.Context, serviceName string, conn *grpc.ClientConn, producers ...sdkmetric.Producer) (*sdkmetric.MeterProvider, error)
InitMetricsPushOnlyVia is InitMetricsPushOnly with an explicit exporter connection: the metrics counterpart of TracingOptions.ExporterConn. ateom passes atelet's relay socket (internal/otlprelay) so the worker pod needs no network path of its own; a nil conn keeps the direct dial to OTEL_EXPORTER_OTLP_ENDPOINT.
The caller owns the connection: the meter provider's Shutdown does not close a connection it did not create.
Calling this at all marks the component relay-capable, so its metrics carry the relay attribute (see relayAttrs) either way — "relay" with a conn, "direct" without one. It is the metrics counterpart of TracingOptions.RelayCapable, implied rather than a parameter because only a caller that has a relay to pass reaches for this function in the first place.
func InitTracing ¶
func InitTracing(ctx context.Context, opts TracingOptions) (*sdktrace.TracerProvider, error)
InitTracing registers a global TracerProvider with the given options and the TraceContext text-map propagator.
func LogLevel ¶
LogLevel exposes the level behind the serverboot loggers, for binaries that build their own handler but should still honor --log-level. A Leveler (not the LevelVar) so SetLogLevel stays the only mutation path.
func SetLogLevel ¶
SetLogLevel sets the minimum level of the serverboot loggers from a flag value: "debug", "info", "warn", or "error" (case-insensitive). Empty means unset and leaves the current level unchanged, so configs that never populate the field keep the default.
func ShutdownProvider ¶
ShutdownProvider invokes the OTel provider's Shutdown and logs any error. Designed to be deferred from main():
defer serverboot.ShutdownProvider("TracerProvider", tp.Shutdown)
func StartMetricsServer ¶
func StartMetricsServer(ctx context.Context, opts MetricsServerOptions)
StartMetricsServer runs an HTTP server exposing /metrics (Prometheus) and optionally /readyz and /healthz. Blocks until http.ListenAndServe returns; designed to be `go`-launched.
func StartReadinessServer ¶
StartReadinessServer runs an HTTP server exposing only /readyz. Blocks until http.ListenAndServe returns; designed to be `go`-launched. A serve failure exits the process: a worker whose readiness endpoint cannot come up never turns Ready and never registers, so dying loudly lets the kubelet restart it instead of leaving a pod that looks alive but can never receive work.
Types ¶
type MetricsServerOptions ¶
type MetricsServerOptions struct {
// Addr is the TCP listen address (e.g. ":9090").
Addr string
// Readiness, if non-nil, enables a /readyz handler: 200 while
// Ready, 503 after MarkNotReady. A zero-value Readiness never
// flips, giving a static 200 for binaries with no drain sequence.
// Nil serves no /readyz at all.
Readiness *Readiness
// EnableHealthz adds an always-200 /healthz for liveness probes,
// which must keep succeeding while a draining server fails /readyz.
EnableHealthz bool
}
MetricsServerOptions configures StartMetricsServer.
type Readiness ¶
type Readiness struct {
// contains filtered or unexported fields
}
Readiness is a predicate for process readiness. The zero value reports ready. Calling MarkNotReady flips it permanently to not ready, which causes /readyz to start returning "Service Unavailable" (503).
func (*Readiness) MarkNotReady ¶
func (r *Readiness) MarkNotReady()
MarkNotReady makes /readyz return 503 from now on.
type TraceSampling ¶
type TraceSampling struct {
// contains filtered or unexported fields
}
TraceSampling is a resolved sampling policy. The root fraction is kept alongside the sampler because the atenet router must mirror it into Envoy's RandomSampling percent, which roots the data plane traces.
func ParentNeverSampling ¶
func ParentNeverSampling() TraceSampling
ParentNeverSampling is ParentBased(NeverSample()).
func ParentRatioSampling ¶
func ParentRatioSampling(ratio float64) TraceSampling
ParentRatioSampling is ParentBased(TraceIDRatioBased(ratio)), clamped to [0, 1].
func ResolveTraceSampling ¶
func ResolveTraceSampling(ctx context.Context, def TraceSampling) TraceSampling
ResolveTraceSampling applies OTEL_TRACES_SAMPLER / OTEL_TRACES_SAMPLER_ARG on top of the component default. serverboot resolves the env itself because an explicit WithSampler silences the SDK's env handling, and the SDK falls open to 100% sampling on invalid values where this keeps the default and logs. That includes a ratio sampler without an arg, which the spec reads as 1.0.
func (TraceSampling) RootSamplingPercent ¶
func (s TraceSampling) RootSamplingPercent() float64
RootSamplingPercent is the percentage (0 to 100) of parentless requests sampled at the root.
func (TraceSampling) Sampler ¶
func (s TraceSampling) Sampler() sdktrace.Sampler
type TracingOptions ¶
type TracingOptions struct {
// ServiceName is required; populates resource.semconv ServiceName.
ServiceName string
// Sampling is required. Build it with ResolveTraceSampling so
// OTEL_TRACES_SAMPLER / OTEL_TRACES_SAMPLER_ARG override the component
// default.
Sampling TraceSampling
// ExporterConn, when non-nil, is the connection the OTLP exporter sends
// over, instead of dialing OTEL_EXPORTER_OTLP_ENDPOINT itself. ateom passes
// the unix socket to atelet's relay (internal/otlprelay) so a worker pod
// exports without a network path of its own; nil keeps the direct dial.
//
// The caller owns the connection: the exporter's Shutdown does not close a
// connection it did not create.
ExporterConn *grpc.ClientConn
// RelayCapable marks a component that is meant to export through the relay,
// whether or not it managed to (see relayAttrs). Only the ateoms set it. It
// is separate from ExporterConn because a nil conn on its own cannot tell
// "the ateom tried and fell back" from "this component never had a relay".
RelayCapable bool
}
TracingOptions configures InitTracing.
Source Files