How Loki stores and finds logs
Grafana Loki indexes a small set of labels for each log stream and stores the log lines themselves as compressed chunks in object storage. Queries written in LogQL select streams by label, then filter and parse the matching lines. Because the full text is not indexed, storage and indexing cost less than in a full-text search engine, and label design decides how much data each query has to read.
Loki fits teams that already use Grafana for metrics and want logs beside them, platform teams collecting Kubernetes and infrastructure logs, and estates with large volumes and modest search needs. Free-text search across every field over long periods may suit a search engine better, so decide which questions people ask of logs before choosing labels.
Loki is licensed under AGPL-3.0, with some directories, such as the client libraries and production tooling, under Apache 2.0. Grafana Labs relicensed Loki from Apache 2.0 in 2021. Running unmodified Loki internally is the common case; review the license with counsel if you plan to modify Loki and offer it to others as a service.
Components behind a Loki cluster
In every deployment mode the same components run; the modes differ in how they are grouped into processes.
Distributor
Receives pushed logs, applies tenant rate and stream limits and forwards each stream to the ingesters responsible for it.
Ingester
Builds chunks in memory, keeps a write-ahead log on local disk and flushes chunks and index files to object storage.
Query path
The query frontend splits and caches queries; queriers read recent data from ingesters and older data from object storage, with index gateways in larger clusters.
Compactor and ruler
The compactor merges index files and applies retention and delete requests; it runs as a single instance. The ruler evaluates LogQL alerting and recording rules.
Pick a deployment mode
Scale figures come from the Loki documentation and are guidance, so test with your own volumes.
| Mode | Documented fit | Status and notes |
|---|---|---|
| Monolithic | All components in one process. Suited to getting started and small workloads, up to about 20 GB of logs per day. | Supported. An HA monolithic deployment is one of the documented migration targets for simple scalable users. |
| Simple scalable | Splits work into read, write and backend targets and can scale close to a terabyte of logs per day. | Deprecated and due for removal in Loki 4.0. New deployments should avoid it, and existing ones should plan a move. |
| Microservices | Each component runs as its own process. Recommended for very large clusters and designed for Kubernetes. | Most efficient at scale and the most complex to operate. Plan autoscaling, caches and per-component monitoring. |
Design labels before you ingest
Use labels for stable, bounded attributes such as cluster, namespace, application, environment and region. People select these first, and they keep the stream count manageable.
Every unique label combination creates a stream. The Loki docs suggest keeping dynamic labels to single digits or tens of values. Request IDs, user IDs and trace IDs as labels create many small chunks and a large index.
When a high-cardinality value is needed in queries, attach it as structured metadata at the agent. It stays queryable without splitting streams. Otherwise use a line filter or parser at query time.
Set per-tenant limits for ingestion rate, streams and query size so one noisy source cannot degrade the cluster. Review active streams with logcli after onboarding each source.
Object storage, retention and deletion
Loki stores chunks and its TSDB index in object storage. The documentation recommends the TSDB index for Loki 2.8 and newer and lists Amazon S3, Google Cloud Storage, Azure Blob Storage and other object stores for chunks. On-premises deployments can use an S3-compatible store; check its performance and support before relying on it for production logs.
Logs live forever unless retention is enabled on the compactor. Retention needs retention_enabled, a delete_request_store and a 24-hour index period. Set a global retention_period, override it per tenant, and use retention_stream rules with label selectors for streams that need a longer or shorter period; each stream rule must be at least 24 hours. Chunks are removed from the index first and deleted later, after a configurable delay.
Bucket lifecycle rules should never delete objects sooner than the longest Loki retention, or the index will point at missing chunks. For backup, rely on object storage versioning or replication for chunks and index files, and keep Loki configuration and runtime overrides in version control. Ingester write-ahead logs cover short gaps between flushes.
Tenancy, authentication and access
With auth_enabled set, Loki isolates data per tenant and every request must carry an X-Scope-OrgID header. Requests without it fail. Loki does not include an authentication layer, so an authenticating reverse proxy or gateway in front of it must verify the caller and set the tenant header. Agents that push logs and Grafana data sources that query them should each have their own credentials at that gateway.
Map tenants to the boundaries that matter for access and retention, such as business unit, environment or regulated workload. Querying across tenants is off by default and can be enabled for specific queriers when a central team needs it. Grafana data source permissions then decide which users reach which tenant.
Logs often contain personal data, tokens and internal hostnames. Filter or redact at the agent before data is stored, protect object storage credentials, encrypt traffic between agents, gateway and Loki, and restrict who can submit delete requests.
Collection agents and migration
Promtail reached end of life on March 2, 2026, and Grafana directs users to Grafana Alloy, which includes a tool to convert Promtail configuration. Loki also accepts logs over OTLP, so OpenTelemetry collectors can send directly. Standardize on one agent per platform and keep its configuration in version control, since labels are set at collection time.
When moving from an Elasticsearch, OpenSearch or Graylog stack, inventory sources, retention rules, saved searches, dashboards and alerts. Decide which fields become labels, which become structured metadata and which are parsed at query time. Rewrite saved searches and alerts in LogQL and run both systems in parallel for an agreed period before retiring the old one.
The open-source Loki Helm chart moved to the grafana-community repository in March 2026. Pin a chart version and read its upgrade notes before moving between major chart versions.
Loki operating ownership
Loki cost and performance depend on the sources sending to it, so ownership covers both the platform and its tenants.
Platform team
- Runs Loki, caches, gateway and object storage.
- Watches ingestion errors, flush failures and query latency.
- Plans the move off simple scalable mode before Loki 4.0.
Tenant owners
- Agree labels, retention and limits for their sources.
- Fix high-cardinality labels.
- Own their dashboards and alert rules.
Security and privacy
- Define redaction rules for agents.
- Approve tenant boundaries and cross-tenant access.
- Review delete requests for regulated logs.
Change record
- Keep Loki and agent configuration in version control.
- Record chart and Loki versions per change.
- Log retention changes with approver and date.
Loki deployment questions
Why are our queries slow?
Usually because a query selects too many streams or too long a time range, so Loki reads a lot of chunks. Narrow the label selector, add line filters early in the query, and check whether caching and query splitting are configured.
Can we keep using simple scalable mode?
For now it runs, but it is deprecated and will be removed in Loki 4.0. Plan a move to microservices mode or an HA monolithic deployment, and test it with production-like volumes.
How do we delete specific logs?
Enable deletion through the compactor and submit delete requests for a tenant, a label selector and a time range. Deletion runs during compaction, so it is not instant. Record who requested it and why.
Scope and handover
Effort depends on daily log volume, the number of sources and tenants, retention requirements, the object storage platform, the deployment mode, migration from an existing log stack and redaction needs. Label design and source onboarding usually take more time than installing Loki.
DeployOpen sizes and deploys Loki in your environment, configures object storage, retention and tenant limits, puts an authenticating gateway and Grafana SSO in front, rolls out Alloy or OpenTelemetry agents, migrates saved searches and alerts, and documents upgrades. Handover includes label conventions, the tenant and retention map, agent configurations, restore test record and the Loki 4.0 upgrade plan.
