How to Use Grafana Loki: The Beginner's Guide

CodexFuse Team · 2026-10-31T18:30:00.000Z · 14 min read min read

Grafana Loki beginner guide: Docker install in monolithic mode, first logs via Alloy, the labels-not-content rule, first LogQL queries, a dashboard, and retention.

If you want to learn how to use Grafana Loki, this Grafana Loki tutorial walks you through the whole first run in one page: deploying the Loki stack (Loki + Alloy + Grafana) with Docker, sending your first logs, learning the one rule about labels that keeps Loki fast and cheap, running your first LogQL queries, building a dashboard, and setting retention so logs age out instead of eating your disk. If you have never run a container stack before, our Docker beginner guide gets you to that point in about twenty minutes.

What is Grafana Loki, exactly?

Grafana Loki is a log aggregation system inspired by Prometheus. It is designed to be very cost-effective and easy to operate: unlike Elasticsearch, Loki does not index the contents of your logs at all. Instead it indexes only a small set of labels attached to each log stream, and stores the log lines themselves in highly compressed chunks.

A query therefore works in two phases: it first picks streams by their labels (cheap, index-driven), then scans the compressed chunks of only those streams. That trade-off is the whole product philosophy — one Grafana Labs statement sums it up: "A small index and highly compressed chunks simplify the operation and significantly lower the cost of Loki," which is why the same design runs everywhere from a Raspberry Pi to deployments ingesting petabytes a day.

Loki was developed by Grafana Labs and announced in 2018. The current release is v3.7.9 (published October 20, 2026), and Loki's license is AGPLv3 (Loki 2.3+ moved from Apache 2.0).

How to use Grafana Loki: the 7-step beginner arc

This is the full Grafana Loki for beginners arc, in order. Do it top to bottom and you will have a working log system on your own machine in under an hour:

1. Install Docker and Docker Compose — the stack is container-first; see our Docker beginner guide if you are starting from zero.
2. Deploy the Loki stack in monolithic mode — one Loki, one Alloy (log collector), one Grafana, all from the official quick-start repo.
3. Add Loki as a Grafana data source — one URL field, nothing else to configure.
4. Send your first logs — Alloy tails your Docker containers and forwards them to Loki's port 3100.
5. Learn the labels rule — labels are the only thing Loki indexes; keep them few and low-cardinality.
6. Run your first LogQL queries — stream selector first, then line filters, then parsers.
7. Build a dashboard and set retention — visualize what you query, and decide how long logs live.

The rest of this guide expands each step with the exact commands and the traps beginners fall into.

What you need before you start

A basic Grafana Loki setup needs only a machine you control and Docker installed. A local laptop works for the first run; for anything permanent you will want a small server of your own — see what is VPS hosting if you have not rented one before. Loki's local config is deliberately forgiving: authentication is disabled (auth_enabled: false), it binds to 127.0.0.1, keeps its data under /tmp/loki, and uses a single-node replication factor of 1 with an in-memory ring.

Expect to use about half a gigabyte of RAM for the Loki container in single-binary mode — the official guidance is that Loki runs on anything from a Raspberry Pi upward, which is the point of its small-index design.

How to install Loki with Docker (monolithic mode)

Install Loki in single-binary — also called monolithic — mode, which is the recommended Loki monolithic mode for beginners. The standard Grafana Loki install Docker path is the official quick-start tutorial: beginners should ignore the distributed microservices topology entirely, because one Loki process handles writes, reads, and storage. It deploys the whole stack with Docker Compose from the grafana/loki-fundamentals repo (-b getting-started branch):

git clone https://github.com/grafana/loki-fundamentals.git -b getting-started
cd loki-fundamentals
docker compose up -d
docker compose ps

Within about thirty seconds you should see three containers: loki, alloy, and grafana. Loki listens on port 3100 (HTTP; gRPC on 9096), Grafana on port 3000, and Alloy's UI on localhost:12345/graph. The key flag to verify in cmd/loki/loki-local-config.yaml is server.http_listen_port: 3100, and the schema version beginners should see is the TSDB v13 index format — the stable, recommended index format in 2026.

How to add Loki as a Grafana data source

Adding Loki as a Grafana data source takes one field. Open Grafana at http://localhost:3000 (default login admin/admin), go to Connections → Data Sources → Add data source, search for Loki, and set the URL to http://loki:3100/ — that is the only value you need to change. Save, then switch to the Explore view: Loki will now appear in the data-source dropdown with its LogQL query editor ready.

How to send logs to Loki: Alloy collection

Alloy collects the logs; Loki stores them. In the quick-start stack, Grafana Alloy is configured via config.alloy to tail the logs of all Docker containers on the host (using discovery.docker) and forward them to Loki at http://loki:3100/loki/api/v1/push. You do not write this config by hand on the first run — it ships with the repo — but you should know it exists, because every "where do my logs come from" question ends there.

Once the stack is up, generate some activity: restart any container, or docker run something noisy like an nginx. Within seconds the lines appear in Grafana's Explore when you query {container="..."} for that container's name. That is your first proof that the whole pipeline — collect, ship, store, query — works end to end.

Alloy vs Promtail: the Grafana Alloy vs Promtail decision for new setups

Use Grafana Alloy — Promtail is end of life. Promtail reached end of life on March 2, 2026: no future support, no updates, all feature development moved to Alloy. The official docs ship a one-command Promtail-to-Alloy config migration tool for anyone with old configs, and the quick-start stack you just deployed never used Promtail at all.

Some older third-party tutorials still show Promtail — treat those steps as legacy and follow the Alloy path from the current official docs.

The labels rule: Loki indexes labels, not log content — Loki labels best practice

Loki indexes only labels, never log content — so labels are the single most important decision in your setup. The official labels guide is blunt: labels should store low-cardinality values that describe where the logs come from (region, cluster, environment, job). Keep the set small — ten to fifteen labels at most — with long-lived, bounded values.

The expensive mistake is creating a label for something very specific, like a user ID or customer ID. Every unique label value becomes a new stream in the index, so high-cardinality labels explode the index — the official warning says this "will significantly reduce the performance and cost-effectiveness of Loki," which is the exact thing Loki was built to avoid. For those per-request values, use structured metadata instead of labels (Loki 3.x also natively ingests OTLP, and structured metadata is the recommended channel for it).

A healthy beginner label set looks like {job="nginx", env="prod", region="us-east"}. An unhealthy one looks like {job="nginx", user_id="847291", session="a9f2c..."} — the second set will quietly eat your index alive.

Your first LogQL queries: a Loki LogQL beginner crash course

Every LogQL query starts with a stream selector; everything else is optional. The selector picks the label sets to read ({job="mysql"}), line filters like |= "error" narrow inside those streams, and parsers like | json or | logfmt extract fields from each line. If you are unsure what a query does, paste it into our LogQL analyzer — it decodes selectors, filters, parsers, and range functions into plain English.

Three beginner queries from the official query examples, explained:

{job="mysql"} |= "error" | json | duration > 500

Select the mysql stream, keep only lines containing "error", parse them as JSON, and keep rows whose extracted duration field exceeds 500.

sum(count_over_time({job="mysql"}[5m])) by (level)

Count log lines over rolling five-minute windows, summed and grouped by the level label — an error-rate-over-time chart.

topk(10, sum(rate({region="us-east1"}[5m])) by (name))

The ten noisiest services in the region, by per-second log rate — the standard "what is flooding my logs" query.

Ordering guidance from the docs: stream selector first, then line filters, then label filters. Put the most selective label filter first so Loki fetches the smallest chunk set before doing expensive line-level parsing.

From Explore to your first dashboard

Graduate from Explore to a saved dashboard once a query proves useful. The official quick-start also introduces Grafana's Logs Drilldown, which lets you browse labels and volumes visually before you write any LogQL — genuinely useful while you are still learning what your labels look like. When a query earns a permanent place, add it to a dashboard panel (rate/volume queries become time-series panels; stream selectors become log panels). For the Grafana side of the stack in depth, see our Grafana beginner guide.

Retention: keeping logs for 30 days with cheap Loki retention S3 storage

Turn on the compactor and set a retention period — by default, Loki keeps logs forever. Retention in Loki is applied by the Compactor, and compactor.retention-enabled is off by default, so a fresh install never deletes anything. Enable it and set a global period in limits_config — retention_period: 744h is 31 days — or set per-stream retention with retention_stream selectors (label matchers only, minimum 24 hours).

Two things beginners get wrong: deletion happens asynchronously with a configurable delay (retention-delete-delay), so space is not freed the instant the period passes; and retention is not retroactive — chunks already past the period at the moment you enable it follow the new rules going forward. Because Loki stores chunks in cheap object storage, month-long retention on S3, GCS, or Azure costs roughly nothing compared to Elasticsearch-grade hot storage.

Loki vs Elasticsearch: which should you choose?

Choose Loki when your queries can be answered label-first; choose Elasticsearch when you need true full-text search over log content. The indexing strategy is the whole difference:

For teams already running Prometheus and Grafana, Loki is the natural ELK alternative: one unified observability UI, no JVM, no mapping migrations.

Loki vs Prometheus: logs vs metrics, the draw-the-line

Loki and Prometheus are siblings, not rivals: Prometheus scrapes metrics, Loki aggregates logs. Prometheus samples numbers over time (CPU, request rates, up values); Loki stores the actual log lines those numbers summarize. In practice you run both behind the same Grafana, and you query Prometheus with PromQL and Loki with LogQL — two languages with deliberately similar syntax. Our Prometheus beginner guide covers the metrics side; traces are the third signal, where Tempo is the matching sibling.

7 beginner mistakes (and the fix for each)

Sources

• Grafana Loki releases — v3.7.9 published October 20, 2026 (GitHub API, grafana/loki)
• Grafana licensing — Loki 2.3+ moved to AGPLv3 (grafana.com/licensing)
• Loki quick-start tutorial — single-binary mode, Docker Compose, loki-fundamentals repo (grafana.com/docs/loki/latest/get-started/quick-start/tutorial/)
• cmd/loki/loki-local-config.yaml — auth_enabled, 127.0.0.1, 3100, /tmp/loki, TSDB v13 (grafana/loki on GitHub)
• Promtail end of life — March 2, 2026, migration to Alloy (grafana.com/docs/loki/latest/send-data/promtail/)
• LogQL query examples — topk/rate, count_over_time (grafana.com/docs/loki/latest/query/query_examples/)
• Labels best practices — ≤10–15 labels, no user IDs, structured metadata (grafana.com/docs/loki/latest/get-started/labels/)
• Loki overview — cost-effective, compressed chunks, Raspberry Pi to petabytes (grafana.com/docs/loki/latest/get-started/overview/)
• Signoz, June 2026 — Loki vs Elasticsearch comparison (signoz.io/blog/loki-vs-elasticsearch/)
• Loki retention — compactor, retention_period, retention_stream, 24h minimum (grafana.com/docs/loki/latest/operations/storage/retention/)
• Loki 3.0 release notes — native OTLP ingestion, structured metadata (grafana.com/docs/loki/latest/release-notes/v3-0/)

Frequently Asked Questions

Is Grafana Loki free to use?

Yes — Loki is open source under the AGPLv3 license, so you can self-host it for free, including in production. Grafana Cloud also offers a managed Loki tier if you would rather not run it yourself.

Can Grafana Loki replace Elasticsearch?

For most operational log use cases, yes: Loki's labels-first design is cheaper and simpler, and it integrates with the Grafana you already use. It is not a drop-in replacement if you depend on true full-text search across every field of every log line — that is Elasticsearch's home turf.

Should I learn Promtail or Alloy for Loki?

Alloy. Promtail reached end of life on March 2, 2026 and receives no updates; every new Loki setup in the official docs uses Grafana Alloy, which also handles metrics, traces, and profiles.

Why are my logs not showing up in Grafana?

Check the pipeline in order: is Alloy running and tailing (check localhost:12345/graph), is Loki reachable at :3100/metrics, does your query's stream selector match your actual labels ({job="..."} is case-sensitive), and is your time range wide enough? Nine times out of ten it is the label spelling or the time range.

How many labels should I use in Loki?

Ten to fifteen at most, all low-cardinality and describing where logs come from (job, env, region). Never put user IDs, session tokens, or request IDs in labels — use structured metadata for those, or your index will explode.