README
¶
Loki: like Prometheus, but for logs.
Loki is a horizontally-scalable, highly-available, multi-tenant log aggregation system inspired by Prometheus. It is designed to be very cost effective and easy to operate. It does not index the contents of the logs, but rather a set of labels for each log stream.
Compared to other log aggregation systems, Loki:
- does not do full text indexing on logs. By storing compressed, unstructured logs and only indexing metadata, Loki is simpler to operate and cheaper to run.
- indexes and groups log streams using the same labels you’re already using with Prometheus, enabling you to seamlessly switch between metrics and logs using the same labels that you’re already using with Prometheus.
- is an especially good fit for storing Kubernetes Pod logs. Metadata such as Pod labels is automatically scraped and indexed.
- has native support in Grafana (needs Grafana v6.0).
A Loki-based logging stack consists of 3 components:
- Alloy is agent, responsible for gathering logs and sending them to Loki.
- Loki is the main service, responsible for storing logs and processing queries.
- Grafana for querying and displaying the logs.
Note that Alloy replaced Promtail in the stack, because Promtail is considered to be feature complete, and future development for logs collection will be in Grafana Alloy.
Loki is like Prometheus, but for logs: we prefer a multidimensional label-based approach to indexing, and want a single-binary, easy to operate system with no dependencies. Loki differs from Prometheus by focusing on logs instead of metrics, and delivering logs via push, instead of pull.
Getting started
⚠️ Helm Chart Migration
Effective March 16, 2026, the Grafana Loki Helm chart will be forked to a new repository grafana-community/helm-charts. The chart in the Loki repository will continue to be maintained for GEL users only. See #20705 for details.
Upgrading
Documentation
- Latest release
- Upcoming release, at the tip of the main branch
Commonly used sections:
- API documentation for getting logs into Loki.
- Labels
- Operations
- Docker Driver Client is a Docker plugin to send logs directly to Loki from Docker containers.
- LogCLI provides a command-line interface for querying logs.
- Loki Canary monitors your Loki installation for missing logs.
- Troubleshooting presents help dealing with error messages.
- Loki in Grafana describes how to set up a Loki datasource in Grafana.
Getting Help
If you have any questions or feedback regarding Loki:
- Search existing thread in the Grafana Labs community forum for Loki: https://community.grafana.com
- Ask a question on the Loki Slack channel. To invite yourself to the Grafana Slack, visit https://slack.grafana.com/ and join the #loki channel.
- File an issue for bugs, issues and feature suggestions.
- Send an email to lokiproject@googlegroups.com, or use the web interface.
- UI issues should be filed directly in Grafana.
Your feedback is always welcome.
Further Reading
- The original design doc for Loki is a good source for discussion of the motivation and design decisions.
- Callum Styan's March 2019 DevOpsDays Vancouver talk "Grafana Loki: Log Aggregation for Incident Investigations".
- Grafana Labs blog post "How We Designed Loki to Work Easily Both as Microservices and as Monoliths".
- Tom Wilkie's early-2019 CNCF Paris/FOSDEM talk "Grafana Loki: like Prometheus, but for logs" (slides, video).
- David Kaltschmidt's KubeCon 2018 talk "On the OSS Path to Full Observability with Grafana" (slides, video) on how Loki fits into a cloud-native environment.
- Goutham Veeramachaneni's blog post "Loki: Prometheus-inspired, open source logging for cloud natives" on details of the Loki architecture.
- David Kaltschmidt's blog post "Closer look at Grafana's user interface for Loki" on the ideas that went into the logging user interface.
Contributing
Refer to CONTRIBUTING.md
Building from source
Loki can be run in a single host, no-dependencies mode using the following commands.
You need an up-to-date version of Go, we recommend using the version found in our Makefile
# Checkout source code
$ git clone https://github.com/grafana/loki
$ cd loki
# Build binary
$ go build ./cmd/loki
# Run executable
$ ./loki -config.file=./cmd/loki/loki-local-config.yaml
Alternatively, on Unix systems you can use make to build the binary, which adds additional arguments to the go build command.
# Build binary
$ make loki
# Run executable
$ ./cmd/loki/loki -config.file=./cmd/loki/loki-local-config.yaml
To run multiple Loki tenants locally, ensure that auth_enabled is set to true and provide a runtime config with any tenant specific overrides.
# Build binary
$ make loki
# Run executable
./loki -config.file=./cmd/loki/loki-local-multi-tenant-config.yaml -runtime-config.file=./cmd/loki/loki-overrides.yaml
Adopters
Please see ADOPTERS.md for some of the organizations using Loki today. If you would like to add your organization to the list, please open a PR to add it to the list.
License
Grafana Loki is distributed under AGPL-3.0-only. For Apache-2.0 exceptions, see LICENSING.md.
Directories
¶
| Path | Synopsis |
|---|---|
|
clients
|
|
|
cmd/docker-driver
command
|
|
|
cmd/fluent-bit
command
|
|
|
pkg/promtail/server/ui
Package ui provides the assets via a virtual filesystem.
|
Package ui provides the assets via a virtual filesystem. |
|
pkg/promtail/targets/windows/win_eventlog
Package win_eventlog Input plugin to collect Windows Event Log messages
|
Package win_eventlog Input plugin to collect Windows Event Log messages |
|
cmd
|
|
|
logcli
command
|
|
|
logql-analyzer
command
|
|
|
loki
command
|
|
|
loki-canary
command
|
|
|
lokitool
command
|
|
|
migrate
command
|
|
|
querytee
command
|
|
|
integration
|
|
|
pkg
|
|
|
bloomgateway
The bloom gateway is a component that can be run as a standalone microserivce target and provides capabilities for filtering ChunkRefs based on a given list of line filter expressions.
|
The bloom gateway is a component that can be run as a standalone microserivce target and provides capabilities for filtering ChunkRefs based on a given list of line filter expressions. |
|
columnar
Package columnar provides utilities for working with columnar in-memory arrays.
|
Package columnar provides utilities for working with columnar in-memory arrays. |
|
compute
Package compute implements stateless computational operations over columnar data.
|
Package compute implements stateless computational operations over columnar data. |
|
dataobj
Package dataobj holds utilities for working with data objects.
|
Package dataobj holds utilities for working with data objects. |
|
dataobj/consumer/logsobj
Package logsobj provides tooling for creating logs-oriented data objects.
|
Package logsobj provides tooling for creating logs-oriented data objects. |
|
dataobj/index/indexobj
Package indexobj provides tooling for creating index-oriented data objects.
|
Package indexobj provides tooling for creating index-oriented data objects. |
|
dataobj/internal/arrowconv
Package arrowconv provides helper utilities for converting between Arrow and dataset values.
|
Package arrowconv provides helper utilities for converting between Arrow and dataset values. |
|
dataobj/internal/dataset
Package dataset contains utilities for working with datasets.
|
Package dataset contains utilities for working with datasets. |
|
dataobj/internal/result
Package result provides utilities for dealing with iterators that can fail during iteration.
|
Package result provides utilities for dealing with iterators that can fail during iteration. |
|
dataobj/internal/streamio
Package streamio defines interfaces shared by other packages for streaming binary data.
|
Package streamio defines interfaces shared by other packages for streaming binary data. |
|
dataobj/internal/util/bitmask
Package bitmask provides an API for creating and manipulating bitmasks of arbitrary length.
|
Package bitmask provides an API for creating and manipulating bitmasks of arbitrary length. |
|
dataobj/internal/util/bufpool
Package bufpool offers a pool of *bytes.Buffer objects that are placed into exponentially sized buckets.
|
Package bufpool offers a pool of *bytes.Buffer objects that are placed into exponentially sized buckets. |
|
dataobj/internal/util/protocodec
Package protocodec provides utilities for encoding and decoding protobuf messages into files.
|
Package protocodec provides utilities for encoding and decoding protobuf messages into files. |
|
dataobj/internal/util/rangeset
Package rangeset implements a half-open interval set [start, end).
|
Package rangeset implements a half-open interval set [start, end). |
|
dataobj/internal/util/sliceclear
Package sliceclear provides a way to clear and truncate the length of a slice.
|
Package sliceclear provides a way to clear and truncate the length of a slice. |
|
dataobj/internal/util/symbolizer
Package symbolizer provides a string interning mechanism to reduce memory usage by reusing identical strings.
|
Package symbolizer provides a string interning mechanism to reduce memory usage by reusing identical strings. |
|
dataobj/sections/internal/columnar
Package columnar provides a base implementation for sections which store columnar data using github.com/grafana/loki/v3/pkg/dataobj/internal/dataset.
|
Package columnar provides a base implementation for sections which store columnar data using github.com/grafana/loki/v3/pkg/dataobj/internal/dataset. |
|
dataobj/sections/logs
Package logs defines types used for the data object logs section.
|
Package logs defines types used for the data object logs section. |
|
dataobj/sections/pointers
Package pointers defines types used for the data object pointers section.
|
Package pointers defines types used for the data object pointers section. |
|
dataobj/sections/streams
Package streams defines types used for the data object streams section.
|
Package streams defines types used for the data object streams section. |
|
dataobj/tools
TODO(grobinson): Find a way to move this file into the dataobj package.
|
TODO(grobinson): Find a way to move this file into the dataobj package. |
|
engine/internal/arrowagg
Package arrowagg provides utilities for aggregating Apache Arrow data structures.
|
Package arrowagg provides utilities for aggregating Apache Arrow data structures. |
|
engine/internal/assertions
Assertions package provides a set of runtime assertions for extra safety.
|
Assertions package provides a set of runtime assertions for extra safety. |
|
engine/internal/deletion
package deletion contains utilities for handling deletion requests in query engine.
|
package deletion contains utilities for handling deletion requests in query engine. |
|
engine/internal/executor/matchutil
Package matchutil provides optimized string matching utilities for the query engine.
|
Package matchutil provides optimized string matching utilities for the query engine. |
|
engine/internal/planner/logical
Package logical provides a logical query plan representation for data processing operations.
|
Package logical provides a logical query plan representation for data processing operations. |
|
engine/internal/proto/ulid
Package ulid provides a ULID implementation.
|
Package ulid provides a ULID implementation. |
|
engine/internal/scheduler
Package scheduler provides an implementation of workflow.Runner that works by scheduling tasks to be executed by a set of workers.
|
Package scheduler provides an implementation of workflow.Runner that works by scheduling tasks to be executed by a set of workers. |
|
engine/internal/scheduler/wire
Package wire provides the wire protocol for how peers scheduler peers communicate.
|
Package wire provides the wire protocol for how peers scheduler peers communicate. |
|
engine/internal/util/dag
Package dag provides utilities for working with directed acyclic graphs (DAGs).
|
Package dag provides utilities for working with directed acyclic graphs (DAGs). |
|
engine/internal/util/ewma
Package ewma provides an implementation of an exponentially weighted moving average (EWMA) that can be reported as a Prometheus metric.
|
Package ewma provides an implementation of an exponentially weighted moving average (EWMA) that can be reported as a Prometheus metric. |
|
engine/internal/util/objtest
Package objtest provides support for creating a data object storage directory for testing purposes.
|
Package objtest provides support for creating a data object storage directory for testing purposes. |
|
engine/internal/util/queue/fair
Package fair implements a Hierarchical Fair Queue (HFQ), providing balanced service across a hierarchy of queues.
|
Package fair implements a Hierarchical Fair Queue (HFQ), providing balanced service across a hierarchy of queues. |
|
engine/internal/worker
Package worker provides a mechanism to connect to the [scheduler] for executing tasks.
|
Package worker provides a mechanism to connect to the [scheduler] for executing tasks. |
|
engine/internal/workflow
Package workflow defines how to represent physical plans as distributed workflows.
|
Package workflow defines how to represent physical plans as distributed workflows. |
|
expr
Package expr provides utilities for evaluating expressions against a columnar.RecordBatch with a selection vector.
|
Package expr provides utilities for evaluating expressions against a columnar.RecordBatch with a selection vector. |
|
goldfish
Package goldfish provides query sampling and comparison functionality for the querytee and Goldfish UI.
|
Package goldfish provides query sampling and comparison functionality for the querytee and Goldfish UI. |
|
ingester/index
originally from https://github.com/cortexproject/cortex/blob/868898a2921c662dcd4f90683e8b95c927a8edd8/pkg/ingester/index/index.go but modified to support sharding queries.
|
originally from https://github.com/cortexproject/cortex/blob/868898a2921c662dcd4f90683e8b95c927a8edd8/pkg/ingester/index/index.go but modified to support sharding queries. |
|
kafka
Package kafka provides encoding and decoding functionality for Loki's Kafka integration.
|
Package kafka provides encoding and decoding functionality for Loki's Kafka integration. |
|
limits/client
Package client provides gRPC client implementation for limits service.
|
Package client provides gRPC client implementation for limits service. |
|
limits/frontend
Package frontend contains provides a frontend service for ingest limits.
|
Package frontend contains provides a frontend service for ingest limits. |
|
limits/frontend/client
Package client provides gRPC client implementation for limits-frontend.
|
Package client provides gRPC client implementation for limits-frontend. |
|
logql
Fork of https://raw.githubusercontent.com/cockroachdb/cockroach/065aa74206c9ec9bcd8b9ea2a6c62ddde8aab0a6/pkg/util/treeprinter/tree_printer.go
|
Fork of https://raw.githubusercontent.com/cockroachdb/cockroach/065aa74206c9ec9bcd8b9ea2a6c62ddde8aab0a6/pkg/util/treeprinter/tree_printer.go |
|
logql/bench/cmd/bench
command
|
|
|
logql/bench/cmd/generate
command
|
|
|
logql/bench/cmd/generate-k6
command
|
|
|
logql/bench/cmd/stream
command
|
|
|
logql/bench/discover/cmd
command
|
|
|
logql/log/logfmt
Adapted from https://github.com/go-logfmt/logfmt/ but []byte as parameter instead Original license is MIT.
|
Adapted from https://github.com/go-logfmt/logfmt/ but []byte as parameter instead Original license is MIT. |
|
logql/syntax
This file is taken from the golang text/scanner package so `bufLen` can be set to `maxInputSize`.
|
This file is taken from the golang text/scanner package so `bufLen` can be set to `maxInputSize`. |
|
logqlmodel/metadata
Package metadata provides primitives for recording metadata across the query path.
|
Package metadata provides primitives for recording metadata across the query path. |
|
logqlmodel/stats
Package stats provides primitives for recording metrics across the query path.
|
Package stats provides primitives for recording metrics across the query path. |
|
memory
Package memory provides support for allocating and reusing contiguous [Region]s of memory.
|
Package memory provides support for allocating and reusing contiguous [Region]s of memory. |
|
memory/internal/memalign
Package memalign provides utilities for aligning memory.
|
Package memalign provides utilities for aligning memory. |
|
memory/internal/unsafecast
Package unsafecast provides utilties for performing unsafe type casts.
|
Package unsafecast provides utilties for performing unsafe type casts. |
|
querier/queryrange
Package contains methods to marshal logqmodel types to queryrange Protobuf types.
|
Package contains methods to marshal logqmodel types to queryrange Protobuf types. |
|
querytee/goldfish
Package goldfish provides query sampling and comparison functionality for the querytee tool.
|
Package goldfish provides query sampling and comparison functionality for the querytee tool. |
|
ruler/storage/cleaner
This directory was copied and adapted from https://github.com/grafana/agent/tree/main/pkg/metrics.
|
This directory was copied and adapted from https://github.com/grafana/agent/tree/main/pkg/metrics. |
|
ruler/storage/instance
This directory was copied and adapted from https://github.com/grafana/agent/tree/main/pkg/metrics.
|
This directory was copied and adapted from https://github.com/grafana/agent/tree/main/pkg/metrics. |
|
ruler/storage/util
This directory was copied and adapted from https://github.com/grafana/agent/tree/main/pkg/metrics.
|
This directory was copied and adapted from https://github.com/grafana/agent/tree/main/pkg/metrics. |
|
ruler/storage/wal
This directory was copied and adapted from https://github.com/grafana/agent/tree/main/pkg/metrics.
|
This directory was copied and adapted from https://github.com/grafana/agent/tree/main/pkg/metrics. |
|
scratch
Package scratch provides an abstraction for scratch space.
|
Package scratch provides an abstraction for scratch space. |
|
storage/hack
command
|
|
|
storage/stores/shipper/bloomshipper/config
package bloomshipperconfig resides in its own package to prevent circular imports with storage package
|
package bloomshipperconfig resides in its own package to prevent circular imports with storage package |
|
ui
Package ui provides HTTP handlers for the Loki UI and cluster management interface.
|
Package ui provides HTTP handlers for the Loki UI and cluster management interface. |
|
util/arrowtest
Package arrowtest provides utilities for testing Arrow records.
|
Package arrowtest provides utilities for testing Arrow records. |
|
util/fakeauth
Package fakeauth provides middlewares thats injects a fake userID, so the rest of the code can continue to be multitenant.
|
Package fakeauth provides middlewares thats injects a fake userID, so the rest of the code can continue to be multitenant. |
|
util/marshal
Package marshal converts internal objects to loghttp model objects.
|
Package marshal converts internal objects to loghttp model objects. |
|
util/marshal/legacy
Package marshal converts internal objects to loghttp model objects.
|
Package marshal converts internal objects to loghttp model objects. |
|
util/rangeio
Package rangeio provides basic interfaces and utilities for reading ranges of data.
|
Package rangeio provides basic interfaces and utilities for reading ranges of data. |
|
xcap
Package xcap provides a utility to capture statistical information about the lifetime of a query.
|
Package xcap provides a utility to capture statistical information about the lifetime of a query. |
|
tools
|
|
|
bloom/inspector
command
|
|
|
dataobj-sort
command
|
|
|
deprecated-config-checker
command
|
|
|
doc-generator
command
|
|
|
querycomparator
command
|
|
|
stream-generator
command
|
|
|
stream-generator/distributor/client
Package client provides gRPC client implementation for distributor service.
|
Package client provides gRPC client implementation for distributor service. |
|
tsdb/index-analyzer
command
|
|
|
tsdb/migrate-versions
command
|
|
|
tsdb/tsdb-map
command
|
Click to show internal directories.
Click to hide internal directories.