Coding standards

This document describes coding conventions for the Loki codebase. Most of these rules are enforced automatically by make lint (golangci-lint). Run it before submitting a pull request.

Table of contents

• Go imports
• Error handling
• Naming
• Testing
• Logging
• Forbidden packages

Go imports

Imports must be grouped into three sections, separated by blank lines:

1. Standard library
2. External packages
3. Internal packages (github.com/grafana/loki/...)

import (
    "context"
    "fmt"

    "github.com/go-kit/log"
    "github.com/prometheus/common/model"

    "github.com/grafana/loki/v3/pkg/logproto"
    "github.com/grafana/loki/v3/pkg/logql"
)

Use goimports (called by make lint) to sort and group imports automatically.

Error handling

• Always check returned errors. The linter (errcheck) flags unchecked errors.
• Wrap errors with context using fmt.Errorf("doing X: %w", err) so callers can inspect them with errors.Is / errors.As.
• Do not swallow errors silently; if an error is intentionally ignored, document why.

Naming

Follow standard Go naming conventions:

• Use MixedCaps for exported names, mixedCaps for unexported.
• Acronyms are consistently cased: HTTPServer, not HttpServer; userID, not userId.
• Interface names describing a single method typically end in -er: Reader, Writer, Flusher.
• Test helper functions that call t.Fatal accept testing.TB, not *testing.T, so they can be reused in benchmarks.

Testing

• Prefer table-driven tests to reduce boilerplate and make adding cases easy.
• Place tests in a _test package (e.g., package logql_test) to test the public API by default. Use the same package only when testing unexported internals.
• Use require (not assert) for checks where a failure should stop the test immediately — this avoids misleading failures cascading from an initial error.
• Integration tests must be gated with the integration build tag and live under ./integration/. Run them with make test-integration.

Logging

Use github.com/go-kit/log (not github.com/go-kit/kit/log, which is deprecated). The depguard linter enforces this.

Structured log lines use key-value pairs:

level.Info(logger).Log("msg", "starting ingester", "addr", addr, "component", "ingester")

• Use "msg" as the first key to describe the event.
• Keep values scalar where possible; avoid embedding structured data in a single string value.
• Error log lines include "err", err.

Forbidden packages

The linter enforces the following import restrictions:

Forbidden	Use instead
github.com/go-kit/kit/log	github.com/go-kit/log