Skip to content

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:

labels:
    environment: "production"
    instance: "seedbox-01"

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/ready should print ready), that the url ends 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.