Traefik Log Dashboard: a Go agent that parses Traefik logs and a Vite UI that maps them

Three components with very different sizes

The project describes itself as a comprehensive real-time analytics platform for Traefik reverse proxy logs, and the component table explains the shape of it.

The agent is a lightweight Go service that parses Traefik logs and exposes metrics via a REST API, and the table records its image size on linux/amd64 as 15MB. The dashboard is a Vite web UI with real-time analytics, charts and geographic visualisation, at 151MB. The third component is a CLI, a terminal-based dashboard using Bubble Tea, which is optional and has no image size.

That size difference is the first thing to notice. The agent is a single Go binary and the dashboard is a Node.js application with a bundled frontend, and the ten to one ratio is the usual cost of shipping a web application in a container. If you are sizing a deployment or pulling images on a metered connection, that number matters.

The repository layout mirrors the split, with an agent directory, a dashboard directory, a cli directory, a charts directory, a k8s directory for Kubernetes deployment, a docker-compose.yml at the root, a QUICK_START_GUIDE.md and a docs directory.

There are also mobile apps for iOS and Android, listed in the README with their store links, and a note that all the apps support Pangolin and Basis authentication. That authentication line is the only place the README mentions those two projects, and it signals that the dashboard sits behind a reverse proxy that handles access control rather than doing it itself.

A quick start in five steps with Docker Compose

The quick start claims you can be running in under five minutes with Docker Compose, and the steps are conventional.

You create the project structure first:

mkdir -p traefik-dashboard/data/{logs,positions,dashboard}
cd traefik-dashboard

The three subdirectories under data are the mounts the two services need: logs for the agent to read, positions for the agent to write its location data, and dashboard for the UI's own state.

Then you write a docker-compose.yml with two services. The agent runs the hhftechnology/traefik-log-dashboard-agent image on port 5000, mounts the logs directory read-only and the positions directory writable, and takes its configuration from environment variables:

    environment:
      - TRAEFIK_LOG_DASHBOARD_ACCESS_PATH=/logs/access.log
      - TRAEFIK_LOG_DASHBOARD_ERROR_PATH=/logs/traefik.log
      - TRAEFIK_LOG_DASHBOARD_AUTH_TOKEN=your_secure_token_here
      - TRAEFIK_LOG_DASHBOARD_SYSTEM_MONITORING=true
      - TRAEFIK_LOG_DASHBOARD_LOG_FORMAT=json

The dashboard runs on port 3000, mounts the dashboard and positions directories, and is told where the agent is:

    environment:
      # Agent Configuration - REPLACE WITH YOUR TOKEN
      - AGENT_API_URL=http://traefik-agent:5000
      - AGENT_API_TOKEN=d41d8cd98f00b204e9800998ecf8427e
      - AGENT_NAME=Default Agent

The compose file also declares an external network named pangolin, and the dashboard depends on the agent with a condition of service_healthy, which is why the agent's healthcheck matters:

    healthcheck:
      test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://localhost:5000/api/logs/status"]
      interval: 2m
      timeout: 10s
      retries: 3
      start_period: 30s

Tokens, networks and the start sequence

Step three is generating a secure token, and the command is short:

openssl rand -hex 32

The instruction is to update both TRAEFIK_LOG_DASHBOARD_AUTH_TOKEN and AGENT_API_TOKEN with that value, which tells you the model. The agent has its own token that clients must present, and the dashboard has the token it uses to talk to the agent, and the two are set to the same value in the guide. That is convenient for a quick start and is the thing to change first in a real deployment, because the example values in the compose file are placeholders and the same placeholder appears in the repository's own docker-compose.yml.

Step four starts things:

# Create network if it doesn't exist
docker network create traefik-network 2>/dev/null || true

# Start services
docker compose up -d

The network creation is separate from the compose file, which is why the external network declaration exists. The two services need to reach each other by name, and the compose file's network is named pangolin in the quick start example while the command creates traefik-network, so the two have to agree. That inconsistency between the quick start text and the compose snippet is the kind of small friction that costs an hour the first time, so check which name your file actually uses.

Step five is opening http://localhost:3000 in a browser.

What the agent reads and how it is configured

The agent environment variable table is short and tells you what the service actually does.

TRAEFIK_LOG_DASHBOARD_ACCESS_PATH is the path to the access log file or directory, defaulting to /var/log/traefik/access.log. TRAEFIK_LOG_DASHBOARD_ERROR_PATH is the error log path, defaulting to /var/log/traefik/traefik.log. TRAEFIK_LOG_DASHBOARD_AUTH_TOKEN is the authentication token and is marked required. TRAEFIK_LOG_DASHBOARD_SYSTEM_MONITORING enables system monitoring and is true by default. TRAEFIK_LOG_DASHBOARD_LOG_FORMAT is the log format, either json or common, defaulting to json. PORT is the agent listen port, defaulting to 5000.

The log format setting is the one with a real consequence. Traefik can emit its access log as JSON, which is machine readable, or in the common log format, which is not. A parser written for one will not read the other, so setting this wrong means an agent that starts cleanly and reports nothing, which is a confusing failure rather than an obvious one.

The system monitoring flag is separate from the log parsing, and it is what powers the host metrics views in the dashboard. Turning it off gives an agent that only deals with Traefik traffic.

The dashboard side has its own variables, and they are more numerous. AGENT_1_URL is the first environment agent URL and is required, unless DASHBOARD_AGENTS_JSON is used instead. AGENT_1_TOKEN is the token for that agent and is optional, and AGENT_1_NAME names it, defaulting to Agent 1. The pattern continues with AGENT_2_URL and AGENT_3_URL for more agents.

Two settings govern behaviour rather than connection. DASHBOARD_AGENTS_ENV_ONLY disables mutations made through the UI and API, defaulting to false, which means by default you can add or change agents from the interface and the environment is not the only source of truth. And DASHBOARD_REFRESH_INTERVAL_MS sets the refresh interval at 5000 milliseconds, with DASHBOARD_MAX_LOGS_DISPLAY setting how many logs are retained in dashboard state, defaulting to 1000, while NEXT_PUBLIC_MAX_LOGS_DISPLAY appears in the quick start set to 500 as the number shown.

The feature list and the parts that are not obvious

The feature list names seven capabilities, and a few of them need unpacking.

The multi-agent architecture lets you manage multiple Traefik instances from a single dashboard, which is the answer to running the same reverse proxy in several environments. The interactive 3D globe gives geographic visualisation with smooth map transitions, and the automatic GeoIP feature resolves IP geolocation with no setup required, though the compose file in the repository shows an optional mount for a local GeoIP MMDB for the highest lookup reliability, which is the escape hatch for a deployment where outbound lookups are blocked.

Advanced filtering includes include and exclude modes, geographic filters and custom filters. Background alerting covers Discord webhooks, daily summaries and threshold alerts, so the tool can notify you rather than only be looked at. High performance is attributed to the Go-based agent, optimised log parsing and position tracking, and the terminal dashboard is a Bubble Tea CLI that is optional.

The position tracking deserves a note, because it explains the separate positions directory. The agent keeps some state about where it is and what it has seen, and it writes that to the positions mount rather than keeping it in memory, so the state survives a restart of the container.

The mobile apps are the fourth surface. The README lists them for iOS and Android with their store links, and states that all apps support Pangolin and Basis auth, which suggests the mobile clients authenticate through the same reverse proxy as the web UI rather than holding their own credentials.

Where Traefik Log Dashboard is the wrong choice

The first limitation is retention. This is a real-time analytics tool over log files, not a log store. The dashboard keeps a bounded number of logs in its own state, 1000 by default with a public setting of 500 in the example, and everything older is whatever the log files on disk still hold. If you want to answer what happened last Tuesday, you need the Traefik logs to still be there, and if you want a searchable history, you want Loki, Elasticsearch or a similar system instead.

The second is the shared token model. The agent authenticates with a single token, and the dashboard holds a token per agent. That is a reasonable design for one operator with a handful of instances, and it is not a multi-user design. There is no per-user identity, no roles and no audit of who looked at what, and the DASHBOARD_AGENTS_ENV_ONLY switch exists to lock the configuration down, which is the mitigation for a shared deployment rather than a user model.

The third is the coupling to Traefik. The agent parses Traefik's access and error logs specifically, and it parses them either as JSON or in the common format. If your reverse proxy is nginx, Envoy, Caddy or HAProxy, none of this applies, and the closest alternative is a general log shipper with a dashboard, which is more work to set up and much less tailored.

There is also the practical cost of the two-image architecture. You run a Go service and a Node.js service, they talk over REST, and they must share a network and a token. That is more moving parts than a single binary reading a log file would be, and for a small deployment the whole stack is more infrastructure than the problem deserves. The comparison to running a log shipper into a hosted dashboard is the honest one, and for a team that already has one of those, the case for this project is the Traefik-specific parsing and the globe.

Editorial conclusion

Traefik Log Dashboard fits an operator who wants to see who is hitting a Traefik deployment, where from, and which routes are failing, without wiring up a general log platform. It does not fit a team that needs long-term log storage, since the design is real-time analytics over log files, and it does not fit a multi-tenant environment without thinking about the shared token model. Before deploying, generate a real token rather than shipping the example value, decide whether the logs are in json or common format, and note that the dashboard image is roughly ten times the size of the agent image.

Frequently asked questions

Official sources

1. hhftechnology/traefik-log-dashboard on GitHub
2. License: AGPL-3.0
3. Project website
4. README
5. Releases