Grafana Loki logging¶
upPollo can ship its logs to a Grafana Loki instance for centralized analysis — useful on remote machines where reading local log files is inconvenient. Works in both CLI and API mode.
Log entries are queued and sent in the background (batched up to 100 entries or once per second), so shipping never blocks an upload. Remaining entries are flushed on shutdown. If Loki is unreachable, the buffer holds up to 1000 entries and then drops silently to protect memory.
Configuration¶
logging:
level: "info"
directory: "./logs"
loki:
enabled: true
url: "http://localhost:3100/loki/api/v1/push"
user: "" # optional: HTTP basic auth username
password: "" # optional: password or API token
labels: {} # optional: extra labels for all entries
json_format: false # emit structured JSON instead of plain text
| Field | Description |
|---|---|
enabled |
Turn Loki shipping on |
url |
Full push endpoint — must end with /loki/api/v1/push |
user, password |
HTTP basic auth, e.g. for Grafana Cloud or a reverse proxy |
labels |
Additional key-value labels attached to every entry |
json_format |
Emit log lines as JSON objects for structured LogQL queries |
For Grafana Cloud, set user to your numeric Grafana Cloud user ID and password to
an API token (found under Connections → Hosted Logs in the Grafana Cloud portal).
Labels¶
Every entry is automatically labeled with app=upPollo, host=<hostname>, and
level=<debug|info|warn|error>. Custom labels help filter across instances:
JSON format¶
With json_format: true, each line is a JSON object (custom labels included as
fields):
{"timestamp":"2026-03-13T12:00:00Z","level":"INFO","msg":"Upload finished: movie.mkv","app":"upPollo","host":"seedbox-01"}
This enables structured LogQL queries:
{app="upPollo"} | json | level="INFO"
{app="upPollo"} | json | msg =~ "Upload.*"
sum(rate({app="upPollo"} | json | level="ERROR" [5m]))
Without it, log lines are plain text and can only be filtered by stream labels or regex.
Grafana dashboard¶
A pre-built dashboard ships at grafana/dashboard.json.
Import it via Dashboards → Import → Upload JSON file, then select your Loki
datasource.
It includes stat panels (errors/warnings/info/total), a log-rate chart by level, dedicated error and warning panels, a filterable full log stream, and an errors-by-host breakdown for multi-instance setups — with dropdown variables for level and a regex search field.
Troubleshooting¶
- No logs in Grafana — check that Loki is reachable from the upPollo machine
(
curl -s http://localhost:3100/readyshould printready), that theurlends with/loki/api/v1/push, and look for[LOKI]errors on upPollo's stderr. - 401/403 — wrong
user/password; for Grafana Cloud the user is the numeric ID, the password an API token. - Missing entries — if Loki was unreachable, buffered entries beyond 1000 are dropped; check connectivity.
- Verify delivery — query
{app="upPollo"}in Grafana Explore.