Grafana Loki in WSL: A Single-Binary Log Ingestion Lab

Grafana Loki can be useful in WSL for testing log labels, ingestion clients, LogQL queries, and dashboards without sending development logs to a shared service. The official local installation guide runs Loki as a single binary and recommends Grafana Alloy as a log collection agent. This is a local evaluation topology, not a resilient logging platform. A single process and one WSL virtual disk do not provide independent storage, replication, or service availability.

WSL adds two operational boundaries: the Linux distribution can stop independently of the Windows host, and the filesystem path can cross between Linux and Windows. Keep Loki’s mutable data and configuration on the distro filesystem unless the test specifically targets Windows-backed storage. Microsoft’s WSL filesystem documentation explains the performance and file-semantics reasons to keep Linux workloads in the Linux filesystem.

Pin a matching binary and configuration

Choose a Loki release from the official release artifacts and use the corresponding local configuration from that exact release tag. Grafana’s local installation documentation explicitly warns to match the configuration to the version being run. Do not combine a binary from one release with the moving main branch’s config and assume compatibility. Record the binary version, checksum, configuration source tag, and data directory in the lab notes.

Create a dedicated Linux-owned directory for the lab. Keep test logs and configuration out of a synced Windows folder. The configuration can define storage paths, limits, retention, and listening behavior; inspect these values before starting the process. An example launch has the form shown in the official docs:

mkdir -p "$HOME/loki-lab"
cd "$HOME/loki-lab"
./loki-linux-amd64 -config.file=./loki-local-config.yaml

Use the executable name from the release archive for your Linux architecture. Start in the foreground first so startup errors and the active configuration path are visible. If you later create a systemd unit, explicitly set the working directory, config path, Linux user, and writable data directories. systemd starts a service only while the WSL distribution is running; it does not guarantee Windows uptime.

Treat the HTTP API as a sensitive local service

Loki does not include an authentication layer. The official local installation guide says an authenticating reverse proxy must be placed in front of the services to prevent unauthorized access. For a private development lab, the simpler boundary is to keep the listener and host access intentionally local and avoid exposing the service on a LAN. Do not assume that a process inside WSL is inaccessible to other Windows software.

Inspect the effective configuration for the HTTP listen address and port. Confirm the actual socket with ss -ltnp, then test reachability from Linux and the intended Windows client. The default local guide exposes the service on a localhost endpoint, but a copied configuration can differ. If Windows cannot connect, check listener binding and WSL networking mode before widening the listener. NAT localhost forwarding and mirrored networking have different behavior; do not solve a route problem by opening an unauthenticated endpoint to every interface.

Loki ingestion and query APIs are separate from Grafana’s dashboard service. A successful page load or a 200 response from a readiness endpoint does not establish that log ingestion works. Use a test client compatible with the selected release and submit one uniquely labeled test stream. Verify that the returned request succeeds, query the same stream with LogQL, and confirm the expected line and timestamp. Delete or expire only the test data using documented mechanisms.

Model labels and storage before sending logs

Loki indexes labels rather than treating every log line like a fully indexed field. Choose a small, bounded label set such as service, environment, and host role. Avoid high-cardinality values such as request IDs, user IDs, full URLs, or arbitrary exception text as labels. Put frequently varying details in the log body and parse them at query time when appropriate. A development lab with a few hand-written streams can hide cardinality and ingestion costs that appear under real application volume.

Keep the input collection path explicit. Grafana recommends Alloy for sending logs to Loki; choose a supported Alloy pipeline and test file discovery, parsing, labels, and position/state files deliberately. A tailing agent’s checkpoint location is separate from Loki’s data directory. If either lives under /mnt/c, permissions, rename behavior, and I/O characteristics may differ from the Linux filesystem. Do not run multiple agents against the same checkpoint file unless the documented design supports it.

Retention is a storage policy, not a cleanup assumption. Verify the selected Loki configuration’s storage backend and retention behavior for the release you pinned. Check disk growth with a bounded test stream and confirm what happens after a clean restart. Do not delete active index or chunk files manually. For a disposable lab, stop the process and remove a known dedicated data directory only after verifying its canonical path.

Plan a small volume test that measures both accepted bytes and query usefulness. A burst of tiny log lines can exercise parsing overhead differently from a stream of large multiline records. Record the input rate, active labels, data directory growth, process memory, and time to query the test interval. Do not extrapolate a laptop’s single-process result into a cluster capacity estimate: storage backend, replication, schema, compaction, and network topology are different variables. Keep ingestion retries observable so a client reconnect does not silently produce duplicate application events; Loki storing log entries does not make the producer’s delivery semantics exactly-once.

Query and dashboard acceptance workflow

Begin with one log line containing a stable service label and a test marker in the body. Confirm the agent has discovered the file, sent data, and preserved the intended timestamp. Query with a bounded time range and exact label selector; then add parser stages only after the base stream is visible. Keep the query range narrow to avoid accidentally reading unrelated local data.

If Grafana is part of the exercise, add Loki as a local data source and run the same LogQL query from Grafana Explore. Do not store a production Grafana credential in WSL configuration for convenience. A dashboard panel that returns no data may reflect time-range selection, label mismatch, agent checkpoints, or clock skew rather than a Loki outage. Compare timestamps and query the API directly to isolate the failure.

Troubleshoot by layer

If Loki exits on startup, verify that the config corresponds to the binary version, storage paths are writable, and required directories have the correct ownership. If ingestion is absent, inspect Alloy’s source discovery, pipeline stages, network target, and logs. If queries return empty, compare the exact labels, timestamp range, and the line content sent. If the process is reachable from Linux but not Windows, inspect bind address, forwarding mode, and firewall rules.

If the VHDX grows, identify whether the bytes are Loki chunks/index, Alloy state, logs, or package files. Establish a bounded retention policy for the test. A WSL export or backup of a live filesystem does not itself prove that Loki’s active data is application-consistent. For a local integration test, capture test inputs and configuration so the lab can be rebuilt rather than treating its single data directory as the only durable copy.

Acceptance criteria

The lab is ready when the Loki binary and matching configuration release are recorded, the server binds only to the intended local path, a test log is ingested through the selected client, a bounded query returns that exact line, and a clean stop/restart behaves as expected. The operator should know that the endpoint has no built-in authentication and should have a clear cleanup and retention plan.

Loki in WSL is a convenient protocol and query-development environment. It is not a production security boundary, replicated log store, or proof of ingestion capacity under cluster load.

Related:

Sources: