zerologlintctx

Note

This project was written by AI (Claude Code).

A Go linter that checks zerolog logging chains for missing context propagation.

Overview

zerologlintctx detects cases where a context.Context is available in function parameters but not properly passed to zerolog logging chains via .Ctx(ctx).

Installation & Usage

Using go install

go install github.com/mpyw/zerologlintctx/cmd/zerologlintctx@latest
zerologlintctx ./...

Using go vet

Since zerologlintctx has no custom flags, it can be run via go vet:

go install github.com/mpyw/zerologlintctx/cmd/zerologlintctx@latest
go vet -vettool=$(which zerologlintctx) ./...

Using go tool (Go 1.24+)

# Add to go.mod as a tool dependency
go get -tool github.com/mpyw/zerologlintctx/cmd/zerologlintctx@latest

# Run via go tool
go tool zerologlintctx ./...

Using go run

go run github.com/mpyw/zerologlintctx/cmd/zerologlintctx@latest ./...

Caution

To prevent supply chain attacks, pin to a specific version tag instead of @latest in CI/CD pipelines (e.g., @v0.7.1).

Flags

Flag	Default	Description
-test	true	Analyze test files (*_test.go) — built-in driver flag

Generated files (containing // Code generated ... DO NOT EDIT.) are always excluded and cannot be opted in.

Examples

# Exclude test files from analysis
zerologlintctx -test=false ./...

What It Checks

Missing .Ctx(ctx) in Event Chains

Detects zerolog logging chains missing .Ctx(ctx):

func handler(ctx context.Context, log zerolog.Logger) {
    // Bad: missing .Ctx(ctx)
    log.Info().Str("key", "value").Msg("hello")

    // Good: includes .Ctx(ctx)
    log.Info().Ctx(ctx).Str("key", "value").Msg("hello")

    // Also good: context from log.Ctx() or zerolog.Ctx()
    log.Ctx(ctx).Info().Str("key", "value").Msg("hello")
}

Direct Logging Methods

Detects direct logging calls that bypass the Event chain and cannot propagate context:

func handler(ctx context.Context, log zerolog.Logger) {
    // Bad: bypasses Event chain, context cannot be set
    log.Print("hello")
    log.Printf("hello %s", name)
}

The analyzer uses SSA (Static Single Assignment) form to track Event values through variable assignments, conditionals, and closures, ensuring accurate detection even in complex code patterns.

Directives

//zerologlintctx:ignore

Suppress warnings for a specific line:

func handler(ctx context.Context, log zerolog.Logger) {
    //zerologlintctx:ignore - intentionally not passing context
    log.Info().Msg("background task")
}

The comment can be on the same line or the line above.

Design Principles

1. Zero false positives - Prefer missing issues over false alarms
2. Type-safe analysis - Uses go/types for accurate detection
3. SSA-based tracking - Uses SSA form to track Event values through assignments and closures
4. Nested function support - Correctly tracks context through closures

Documentation

• Architecture - Internal design and detection logic
• CLAUDE.md - AI assistant guidance for development

Related Tools

• goroutinectx - Goroutine context propagation linter
• ctxweaver - Code generator for context-aware instrumentation
• gormreuse - GORM instance reuse linter
• zerologlint - General zerolog linting rules
• contextcheck - Detects context.Background()/context.TODO() usage and missing context parameters

zerologlintctx is complementary to these tools:

• zerologlint provides general zerolog best practices
• contextcheck warns about creating new contexts when one should be propagated
• zerologlintctx specifically warns about not using an available context in zerolog chains

License

MIT