Services¶

The Finch stack runs seven containers. This page describes what each one does and how it fits into the overall system.

Grafana¶

Visualization and alerting.

Grafana is the front-end for all observability data. It connects to Loki, Mimir, and Pyroscope as pre-configured data sources and ships with a set of built-in dashboards for logs, metrics, and profiles.

Access Grafana at https://finch.example.com/grafana. No Finch authentication is applied to this path. Grafana manages its own login.

Pre-built dashboards cover:

• Logs from Docker containers
• Logs from systemd journal
• Logs from files
• Infrastructure metrics
• Finch profiling data

Loki¶

Log aggregation and storage.

Loki receives log streams pushed by Alloy agents and stores them in a compressed, indexed format optimized for querying by label. It is Grafana's native log backend and is queried using LogQL.

Agents write to /loki on the stack. Traefik strips the path prefix and forwards requests to Loki. Every write request is authenticated by Finch before reaching Loki.

Log data is retained for 72 hours and then automatically deleted.

Mimir¶

Short-term metrics storage.

Mimir is a horizontally scalable, Prometheus-compatible metrics backend. Finch runs it in single-binary mode, which is well-suited to a single-server deployment. Grafana's native metrics backend, and it is queried using PromQL.

Agents push Prometheus-format metrics to /mimir. Traefik strips the path prefix and forwards requests to Mimir. Every write request is authenticated by Finch before reaching Mimir.

Metrics data is retained for 72 hours and then automatically deleted.

Pyroscope¶

Continuous profiling storage.

Pyroscope stores CPU and memory profiles sent by Alloy agents running on hosts with profiling enabled. Profiles are browseable in Grafana using the Pyroscope data source, showing flame graphs over time.

Agents write to /pyroscope. Traefik strips the path prefix and forwards to Pyroscope. Every write request is authenticated by Finch before reaching Pyroscope.

Profile data is retained for 72 hours and then automatically deleted.

Alloy¶

The collection agent.

Alloy is Grafana's OpenTelemetry-compatible collector. One Alloy instance runs on each enrolled host and is responsible for:

• Tailing log sources (journal, Docker, files, Windows Event Log)
• Scraping Prometheus metrics endpoints
• Collecting pprof profiles

Alloy is configured and deployed by finchctl agent deploy. Its configuration includes the stack endpoints and the agent's JWT, both generated by Finch at enrolment time.

The stack also runs its own internal Alloy instance (within the compose network) to collect logs, metrics and profiling data from the Finch services itself.

Traefik¶

Reverse proxy, TLS termination, and authentication gateway.

Traefik is the single entry point for all traffic to the stack. It handles:

• TLS termination on port 443 (self-signed, Let's Encrypt, or custom cert)
• HTTP to HTTPS redirect on port 80
• Path-based routing to backend services
• mTLS client certificate passthrough for finchctl gRPC connections
• JWT forwarding authentication for agent data writes (delegates to Finch auth server)

Routing summary:

Finch¶

The control plane.

Finch is the service that finchctl talks to. It runs three internal servers:

Agent records are stored in a SQLite database at /var/lib/finch/finch.db.