logs/LLM.md

Hanzo Logs

Fork of Grafana Loki (upstream: github.com/grafana/loki). Log aggregation system for Hanzo infrastructure.

Repo: github.com/hanzoai/logs Go module: github.com/grafana/loki/v3 (not yet rebranded) Go version: 1.25.5

Binaries

Built from cmd/:

Binary	Purpose
loki	Log aggregation server
logcli	CLI for querying logs
loki-canary	End-to-end logging pipeline test tool
lokitool	Operational tooling (migration, inspection)
querytee	Query comparison proxy
chunks-inspect	Chunk data inspector
dataobj-inspect	Data object inspector
logql-analyzer	LogQL query analyzer

Commands

make all              # Build all binaries
make loki             # Build loki only
make logcli           # Build logcli only
make test             # Unit tests
make test-integration # Integration tests
make lint             # All linters
make format           # gofmt + goimports
go test ./...         # Go tests directly
go test -v ./pkg/logql/...  # Single package

Frontend (pkg/ui/frontend)

Vite-based UI, separate from the query-frontend service.

cd pkg/ui/frontend
make build   # Build
make dev     # Dev server
make lint    # Lint
make test    # Tests

Key Directories

cmd/           # Binary entry points
pkg/           # All library code
  logql/       # LogQL query engine
  ingester/    # Log ingestion
  distributor/ # Write path distribution
  compactor/   # Index compaction
  querier/     # Read path
  storage/     # Storage backends
  chunkenc/    # Chunk encoding
  kafka/       # Kafka integration
  bloomgateway/ # Bloom filter gateway
  engine/      # Query engine
clients/       # Log shipping clients (promtail)
production/    # Deployment configs (Docker, Helm, Nomad, Ksonnet)
docs/          # Documentation source

Architecture

• Write path: distributor -> ingester -> storage
• Read path: query-frontend -> querier -> storage
• Storage backends: S3, GCS, Azure Blob, filesystem, Bigtable
• Index: BoltDB, TSDB
• Query language: LogQL (Prometheus-inspired)

Style

• Standard Go formatting (gofmt/goimports)
• Import order: stdlib, external, then loki packages
• Structured logging via go-kit/log
• Table-driven tests preferred
• Conventional commits: <type>: message
• Frontend: TypeScript, functional components, dash-case dirs

Deployment

Production configs in production/:

• Docker Compose
• Helm charts
• Ksonnet/jsonnet manifests
• Nomad jobs