Grafana Loki

Grafana Loki is an open source log aggregation system from Grafana Labs, built for sysadmins and SRE teams who want to collect logs from servers, containers and Windows machines and query them in Grafana next to their Prometheus metrics. Unlike full-text search engines, Loki indexes only a small set of labels per log stream and keeps the log lines themselves as compressed chunks on disk or in object storage, which makes it cheaper to run at scale.

Loki is a server component: you deploy it with Docker, Helm on Kubernetes, Linux packages or a single binary, and ship logs to it with Grafana Alloy. Promtail, the old agent, reached end of life on 2 March 2026, so new setups should start with Alloy.

Grafana Loki at a glance

What it does

• Receives log streams over HTTP (/loki/api/v1/push) from Grafana Alloy, Docker drivers, OpenTelemetry collectors and other clients.
• Indexes only labels such as job, host or namespace, and stores log lines as compressed chunks on local disk or in S3, GCS or Azure Blob storage.
• Queries logs with LogQL: label selectors, line filters, parsers for JSON and logfmt, and metric queries such as error rates.
• Evaluates alerting and recording rules on logs through its ruler, sending alerts to Alertmanager.
• Runs as a single binary for small setups or as separately scaled components (distributor, ingester, querier, compactor) for large ones.
• Applies retention per tenant or per stream through the compactor.
• Supports multi-tenancy with the X-Scope-OrgID header when authentication is enabled.

How sysadmins use it

Single-node Loki for a small environment

1. Start Loki in Docker with its built-in local configuration:

docker run -d --name loki -p 3100:3100 grafana/loki:3.7.8
curl http://localhost:3100/ready

2. For a package install, use a config like this with local storage and 31-day retention:

auth_enabled: false
server:
  http_listen_port: 3100
common:
  path_prefix: /var/lib/loki
  replication_factor: 1
  ring:
    kvstore:
      store: inmemory
  storage:
    filesystem:
      chunks_directory: /var/lib/loki/chunks
      rules_directory: /var/lib/loki/rules
schema_config:
  configs:
    - from: 2024-01-01
      store: tsdb
      object_store: filesystem
      schema: v13
      index:
        prefix: index_
        period: 24h
limits_config:
  retention_period: 744h
compactor:
  working_directory: /var/lib/loki/compactor
  retention_enabled: true
  delete_request_store: filesystem

3. In Grafana, add a Loki data source with the URL http://loki-host:3100 and open Explore to query.

Ship Linux and Windows logs with Grafana Alloy

On a Linux host, tail files under /var/log:

local.file_match "varlogs" {
  path_targets = [{"__path__" = "/var/log/*.log", "job" = "varlogs", "host" = "web01"}]
}
loki.source.file "varlogs" {
  targets    = local.file_match.varlogs.targets
  forward_to = [loki.write.default.receiver]
}
loki.write "default" {
  endpoint {
    url = "http://loki-host:3100/loki/api/v1/push"
  }
}

On a Windows server, read an event log with the same loki.write block:

loki.source.windowsevent "system" {
  eventlog_name = "System"
  labels        = {job = "windows-events", host = "dc01"}
  forward_to    = [loki.write.default.receiver]
}

Useful LogQL queries

{job="varlogs", host="web01"} |= "error"
sum by (host) (count_over_time({job="varlogs"} |= "Failed password" [5m]))
{job="nginx"} | json | status >= 500

The first finds error lines on one host, the second counts failed SSH logins per host in 5-minute windows (good for an alert rule), and the third parses JSON access logs and keeps server errors.

Install and first run

• Kubernetes: Helm is the recommended method. Note that the official Helm chart is moving to the grafana-community Helm charts repository, so check the chart source when you upgrade.
• Docker / Compose: the quickest way to try Loki together with Grafana and Alloy on one machine.
• Linux packages: DEB and RPM packages from Grafana’s repository install a systemd service; edit the config file and restart the service.
• Binaries: each GitHub release ships static binaries (for example loki-linux-amd64.zip and a Windows amd64 build) for tests or hosts without containers. Run them with -config.file= pointing to your YAML.
• Ports: HTTP 3100 for push and queries, gRPC 9095 between components. Open 3100 only to your agents and Grafana.
• Security: Loki has no built-in authentication layer. Put it behind a reverse proxy with authentication or keep it on a private network.
• Labels: keep label values low-cardinality (host, job, environment). Putting user IDs or request IDs in labels creates huge numbers of streams and hurts performance.

Limitations

• No full-text index: searches filter the chunks selected by labels, so broad queries over long periods can be slow compared with Elasticsearch or OpenSearch.
• Needs Grafana (or LogCLI) for a UI; Loki itself has no web interface.
• Scaling out means running several components and object storage, which is real operational work.
• No built-in authentication, which surprises teams moving from commercial log platforms.
• Windows is supported as a place to collect logs (through Alloy) more than as a place to run Loki in production.

Grafana Loki vs alternatives

The ELK or OpenSearch stack indexes every word, which makes free-text search fast but needs far more storage and memory. Graylog offers a full web UI with streams and alerting built in, at the cost of running OpenSearch and MongoDB behind it. Loki is the lightest option if you already use Grafana and Prometheus, because the same labels connect metrics and logs. For a desktop log viewer on a single admin workstation rather than a central platform, LogFusion is a simpler tool.

FAQ

Is Grafana Loki free?

Yes. Loki is free and open source under the AGPL-3.0, and you can self-host it without limits. Grafana Cloud Logs is a separate paid hosted service.

Is Grafana Loki open source?

Yes. The code is developed publicly on GitHub by Grafana Labs, mostly under the AGPL-3.0 with some parts under Apache-2.0.

Is Promtail deprecated?

Yes. Promtail reached end of life on 2 March 2026 and all new development happens in Grafana Alloy. A conversion tool can translate Promtail configs into Alloy configs.

Can Grafana Loki run on Windows?

A Windows amd64 binary is published with each release, useful for tests. For Windows servers, the common pattern is to run Alloy on them to ship event logs to Loki hosted on Linux or Kubernetes.

Grafana Loki vs Prometheus: what is the difference?

Prometheus stores numeric metrics; Loki stores log lines. They share the label model, so in Grafana you can jump from a metric spike to the logs of the same host or pod.

Grafana Loki vs ELK: which should I choose?

Choose ELK or OpenSearch when you need fast full-text search across everything. Choose Loki when cost and simplicity matter and you mostly search within known services and hosts.

Can Loki be used as a syslog server?

Not directly: Loki accepts pushes over HTTP. Receive syslog with Grafana Alloy’s syslog listener and forward it to Loki.

How do I install Grafana Loki with Docker Compose?

Define services for Loki (port 3100), Grafana and Alloy in one compose file, point Alloy’s loki.write at http://loki:3100/loki/api/v1/push and add Loki as a data source in Grafana.

Last checked against official sources: 30 September 2026 (developer website: grafana.com). Versions and licence terms change — confirm on the developer's site before deploying in production.