app

func (*App) Logger ¶

func (a *App) Logger() *slog.Logger

Logger returns the structured logger. Safe to call on all goroutines for the lifetime of the App.

func (*App) Metrics ¶

func (a *App) Metrics() *metrics.Metrics

Metrics returns the Prometheus metrics registry. Use this to register application-specific collectors or to obtain a [prometheus.Registerer] for injection into sub-components. Safe to call on all goroutines for the lifetime of the App.

func (*App) ReadinessCheck ¶

func (a *App) ReadinessCheck() func(context.Context) error

ReadinessCheck returns a function that reports whether all non-critical components are currently healthy. The returned function can be passed directly to httpserver.Server.AddReadinessCheck:

srv.AddReadinessCheck("app-components", a.ReadinessCheck())

The check returns nil when all non-critical components have successfully started (or there are none). It returns an error naming every component that is still in a degraded state.

ReadinessCheck must be called after all components have been registered (i.e. after [Start] returns). Calling it concurrently with [Register] or [RegisterNonCritical] is a data race.

func (*App) Register ¶

func (a *App) Register(c Component)

Register adds a Component to the App. Components are started by [Start] in registration order and shut down by [Shutdown] in reverse registration order. Register panics if called after Start.

package main

import (
	"context"
	"log/slog"

	"gitlab.com/gitlab-org/labkit/v2/app"
)

func main() {
	ctx := context.Background()

	a, err := app.New(ctx)
	if err != nil {
		panic(err)
	}

	w := &worker{logger: a.Logger()}
	a.Register(w)

	if err := a.Start(ctx); err != nil {
		panic(err)
	}
	defer a.Shutdown(ctx)
}

// worker is a minimal app.Component used in ExampleApp_Register.
type worker struct {
	logger *slog.Logger
}

func (w *worker) Start(ctx context.Context) error {
	w.logger.InfoContext(ctx, "worker started")
	return nil
}

func (w *worker) Shutdown(ctx context.Context) error {
	w.logger.InfoContext(ctx, "worker stopped")
	return nil
}

Output:

func (*App) RegisterNonCritical ¶

func (a *App) RegisterNonCritical(c Component)

RegisterNonCritical adds a Component to the App that is allowed to fail during startup without halting the application. If the component fails to start, App.Start logs a warning and continues starting other components. A background goroutine retries the failed component with exponential backoff until it succeeds or App.Shutdown is called. The initial backoff and cap are controlled by [Config.RetryInitialBackoff] and [Config.RetryMaxBackoff].

The degraded state of non-critical components is exposed via App.ReadinessCheck, which can be registered with httpserver.AddReadinessCheck to gate Kubernetes readiness probes.

RegisterNonCritical panics if called after Start.

package main

import (
	"context"
	"time"

	"gitlab.com/gitlab-org/labkit/v2/app"
)

func main() {
	ctx := context.Background()

	a, err := app.NewWithConfig(ctx, &app.Config{
		// Optional: tune how quickly degraded components are retried.
		RetryInitialBackoff: 500 * time.Millisecond,
		RetryMaxBackoff:     30 * time.Second,
	})
	if err != nil {
		panic(err)
	}

	// critical: any start failure halts the app.
	// a.Register(db)

	// non-critical: start failure logs a warning and triggers background retry.
	// a.RegisterNonCritical(otelCollector)

	// Wire degraded-component state into the /-/readiness health endpoint.
	// srv.AddReadinessCheck("app-components", a.ReadinessCheck())

	if err := a.Run(ctx); err != nil {
		panic(err)
	}
}

Output:

func (*App) Run ¶

func (a *App) Run(ctx context.Context) error

Run starts all components, blocks until ctx is cancelled or a SIGTERM/SIGINT signal is received, then shuts down gracefully using [Config.ShutdownTimeout]. It is a convenience method that replaces the common boilerplate of calling [Start], waiting for a signal, and calling [Shutdown].

a, _ := app.New(ctx)
a.Register(srv)
if err := a.Run(ctx); err != nil {
	log.Fatal(err)
}

func (*App) Shutdown ¶

func (a *App) Shutdown(ctx context.Context) error

Shutdown calls Shutdown on each registered Component in reverse registration order, then flushes buffered trace spans. All shutdown errors are collected and returned as a combined error so that a failure in one component does not prevent others from shutting down.

Background retry goroutines for non-critical components are cancelled before any component Shutdown is called. Non-critical components that never successfully started are skipped.

defer a.Shutdown(ctx)

func (*App) Start ¶

func (a *App) Start(ctx context.Context) error

Start calls Start on each registered Component in registration order.

For critical components (registered via [Register]), any start failure triggers an immediate rollback: all previously started components are shut down in reverse order before the error is returned.

For non-critical components (registered via [RegisterNonCritical]), a start failure is logged as a warning and the component is marked degraded. A background goroutine retries with exponential backoff until the component succeeds or [Shutdown] is called.

func (*App) Tracer ¶

func (a *App) Tracer() *trace.Tracer

Tracer returns the distributed-tracing Tracer. Safe to call on all goroutines for the lifetime of the App.