labkit

labkit/v2

LabKit v2 is GitLab's standard platform library for Go services. It provides production-ready building blocks for observability, HTTP serving, database connectivity, and secret management — all wired into a common lifecycle so teams can focus on business logic rather than infrastructure boilerplate.

Packages at a glance

Typical service wiring

The app package is the entry point. All other components plug into it:

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

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

    // Postgres client — Start opens the pool and pings, Shutdown drains it.
    db, err := postgres.NewWithConfig(&postgres.Config{
        DSN:    os.Getenv("DATABASE_URL"),
        Tracer: a.Tracer(),
    })
    if err != nil {
        log.Fatal(err)
    }

    // HTTP server — built-in tracing and access logging on every route.
    srv := httpserver.NewWithConfig(&httpserver.Config{
        Addr:   ":8080",
        Logger: a.Logger(),
        Tracer: a.Tracer(),
    })
    srv.Router().Get("/api/projects/{id}", handleGetProject(db))
    srv.Router().Get("/-/metrics", a.Metrics().Handler())
    srv.AddReadinessCheck("database", func(ctx context.Context) error {
        return db.DB().PingContext(ctx)
    })

    // Register in dependency order: db starts first, shuts down last.
    a.Register(db)
    a.Register(srv)

    // Run starts all components, waits for SIGTERM/SIGINT, then shuts down.
    if err := a.Run(ctx); err != nil {
        log.Fatal(err)
    }
}

How the packages relate

graph TD
    App["<b>app.App</b><br/>lifecycle orchestrator"]

    App -->|creates| Log["<b>log</b><br/>slog structured logger"]
    App -->|creates| Trace["<b>trace</b><br/>OpenTelemetry tracer"]
    App -->|creates| Metrics["<b>metrics</b><br/>Prometheus registry"]

    Log -->|injected into| Components
    Trace -->|injected into| Components
    Metrics -->|injected into| Components

    subgraph Components["app.Component implementations"]
        HTTP["<b>httpserver.Server</b><br/>HTTP · routing · health checks"]
        PG["<b>postgres.Client</b><br/>connection pool · query tracing"]
        Custom["your own components"]
    end

    App -->|no lifecycle| Secret["<b>secret.Client</b><br/>provider-agnostic secret retrieval"]
    App -->|no lifecycle| HTTPClient["<b>httpclient.Client</b><br/>instrumented outbound HTTP"]
    App -->|no lifecycle| Fields["<b>fields</b><br/>canonical log field name constants"]

    subgraph Testing["testing/ (in-memory replacements)"]
        AppTest["apptest — App fixture"]
        LogTest["logtest — log recorder"]
        TraceTest["tracetest — span recorder"]
        MetricsTest["metricstest — metrics gatherer"]
    end

secret.Client and httpclient.Client are not app.Component implementations — they have no start/shutdown lifecycle. Construct them once and inject them into the handlers or components that need them.

Observability

app.New initialises the logger and tracer from environment variables so services work out of the box with zero configuration:

Pass explicit configuration via app.NewWithConfig to override any of these.

Testing

The testing/ sub-packages provide in-memory replacements for every I/O dependency so unit tests need no live infrastructure:

func TestMyHandler(t *testing.T) {
    a, logRec, spanRec := apptest.New()

    srv := httpserver.NewWithConfig(&httpserver.Config{
        Logger: a.Logger(),
        Tracer: a.Tracer(),
    })
    srv.Router().Get("/api/projects/{id}", handleGetProject(mockDB))

    req := httptest.NewRequest(http.MethodGet, "/api/projects/42", nil)
    rec := httptest.NewRecorder()
    srv.ServeHTTP(rec, req)

    assert.Equal(t, http.StatusOK, rec.Code)

    // Assert structured log output.
    records := logRec.Records()
    require.Len(t, records, 1)

    // Assert trace spans.
    spans := spanRec.Ended()
    require.Len(t, spans, 1)
    assert.Equal(t, "GET /api/projects/{id}", spans[0].Name)
}

Module path

gitlab.com/gitlab-org/labkit/v2

v2 is a separate Go module from the root gitlab.com/gitlab-org/labkit (v1). The two modules are independent: v2 uses log/slog and OpenTelemetry; v1 uses Logrus and OpenTracing. Services should adopt v2 for all new development.