Hanzo Logs

Hanzo Logs is a horizontally-scalable, multi-tenant log aggregation system for Hanzo infrastructure. Fork of Grafana Loki. Written in Go. Indexes labels (not full text) for cost-effective log stora...

Overview

Hanzo Logs is a horizontally-scalable, multi-tenant log aggregation system for Hanzo infrastructure. Fork of Grafana Loki. Written in Go. Indexes labels (not full text) for cost-effective log storage and querying via LogQL (Prometheus-inspired query language). Integrates natively with Grafana.

Why Hanzo Logs?

Label-based indexing: Stores compressed unstructured logs, indexes only metadata labels -- cheaper to run than full-text indexing systems

Prometheus-native: Uses the same labels as Prometheus metrics for seamless correlation between metrics and logs

Kubernetes-native: Automatically scrapes and indexes Pod labels

Multi-tenant: Isolated log streams per tenant

Grafana integration: Native datasource in Grafana v6.0+

Tech Stack

Language: Go (1.25.5)

Go module: github.com/grafana/loki/v3 (upstream module path, not yet rebranded)

Query language: LogQL

Storage backends: S3, GCS, Azure Blob, filesystem, Bigtable

Index backends: BoltDB, TSDB

Streaming: Kafka integration

License: AGPL-3.0-only (Apache-2.0 exceptions in LICENSING.md)

OSS Base

Fork of github.com/grafana/loki. Repo: hanzoai/logs.

When to use

Aggregating logs from K8s workloads across Hanzo infrastructure

Correlating log events with Prometheus/Hanzo Metrics time-series data

Querying structured and unstructured logs via LogQL

Running a cost-effective alternative to Elasticsearch/Splunk for log storage

Operating a Loki-compatible stack for Grafana dashboards

Hard requirements

Go 1.25.5+ for building from source

Object storage (S3, GCS, Azure Blob, or local filesystem) for log chunk storage

Grafana v6.0+ for native log querying UI

Alloy or Promtail agent for shipping logs to the server

Quick reference

Item	Value
Repo	`github.com/hanzoai/logs`
Language	Go
Go Module	`github.com/grafana/loki/v3`
Default branch	`main`
License	AGPL-3.0-only
Default port	3100 (HTTP), 9096 (gRPC)

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

Build commands

# Build all binaries
make all

# Build individual binaries
make loki
make logcli

# Run tests
make test
go test ./...

# Single package test
go test -v ./pkg/logql/...

# Integration tests
make test-integration

# Linting
make lint

# Formatting
make format

Architecture

Write path:   distributor -> ingester -> storage
Read path:    query-frontend -> querier -> storage

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
  ui/frontend/      # Vite-based UI (TypeScript)
clients/            # Log shipping clients (Promtail)
  cmd/              # Client binaries
  pkg/              # Client libraries
operator/           # Kubernetes operator (separate Go module)
production/         # Deployment configs
  docker/           # Docker configs
  helm/             # Helm charts
  ksonnet/          # Ksonnet/jsonnet manifests
  nomad/            # Nomad jobs
  terraform/        # Terraform configs
docs/               # Documentation source
integration/        # Integration tests

Kubernetes Operator

The operator/ directory contains a separate Go module with a full K8s operator for managing Loki deployments, including CRDs, controllers, and OLM bundle.

Frontend UI

Vite-based TypeScript UI in pkg/ui/frontend/:

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

Deployment

Production configs in production/:

Docker Compose (production/docker-compose.yaml)

Helm charts (production/helm/)

Ksonnet/jsonnet manifests

Nomad jobs

Terraform configs

Quick local run

# Build and run with local config
go build ./cmd/loki
./loki -config.file=./cmd/loki/loki-local-config.yaml

Multi-tenant local run

make loki
./loki -config.file=./cmd/loki/loki-local-multi-tenant-config.yaml \
       -runtime-config.file=./cmd/loki/loki-overrides.yaml

Code 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 directories

hanzo/hanzo-metrics.md - Time-series metrics (VictoriaMetrics fork)

hanzo/hanzo-o11y.md - Observability overview

hanzo/hanzo-universe.md - Production K8s infrastructure

On this page