The relay
The relay lets Guidely query a Grafana, Prometheus, Tempo or Loki on a private network. It's a small open-source program (@guidelytech/relay on npm, ghcr.io/guidelytech/guidely-relay on Docker) that you run next to your stack, in your own AWS, GCP or Kubernetes.
How it works
- The relay connects out to Guidely over HTTPS and asks for work (a long poll that Guidely holds open for up to 25 seconds).
- When a page in Guidely needs a panel, Guidely hands the relay a query job: a target name, a path such as
/api/v1/query_rangeand its query parameters. - The relay checks the job against its own copy of the read-only allowlist, sends the
GETto the target with that target's credentials, and posts the answer back. - Guidely passes the answer to the page that's waiting for it. Nothing is stored on either side.
So:
- Nothing connects to the relay. It needs outbound HTTPS (443) to Guidely and access to your targets' ports, and no inbound rules, load balancer or public address.
- Credentials stay with you. Upstream tokens and passwords live in the relay's environment. Guidely only knows each target's name and kind.
- The relay enforces the allowlist itself, so even a compromised Guidely couldn't make it write, delete or call an admin API.
- Each query has 10 seconds; answers over 5 MB are cut off; redirects aren't followed. The relay keeps nothing on disk and runs with a read-only root filesystem.
1. Create a relay in Guidely
A workspace admin opens Integrations → Grafana, Prometheus, Tempo, Loki → Add relay, names it (for example prod-eu) and copies the token (gly_rly_…). It's shown once; Guidely keeps only a hash.
2. Run it
Anywhere with Docker, on a network that can reach your stack:
docker run -d --name guidely-relay --restart unless-stopped --read-only \
-e GUIDELY_RELAY_TOKEN=gly_rly_... \
-e GUIDELY_TARGETS="prom=prometheus=http://prometheus:9090,logs=loki=http://loki:3100,traces=tempo=http://tempo:3200" \
ghcr.io/guidelytech/guidely-relay:latest
Or with Node.js 20 or later: npx @guidelytech/relay with the same variables.
For production, use one of the ready-made deployments:
- Kubernetes (Helm): EKS, GKE, AKS or any cluster.
- AWS ECS Fargate (Terraform).
- Google Cloud Run (Terraform).
- Docker Compose:
deploy/relay/docker-compose.yml.
3. Check the targets
check sends one harmless request to each target from where the relay runs, and prints a table:
docker run --rm -e GUIDELY_TARGETS="prom=prometheus=http://prometheus:9090" -e TARGET_PROM_BEARER=... \
ghcr.io/guidelytech/guidely-relay check
TARGET KIND URL RESULT
prom prometheus http://prometheus:9090 OK (12 ms)
logs loki http://loki:3100 FAILED: /loki/api/v1/labels answered 401 (check the credentials)
It asks Prometheus for /api/v1/status/buildinfo, Loki for /loki/api/v1/labels, Tempo for /api/echo, and Grafana for /api/health and /api/frontend/settings (which needs a working token). It needs no relay token and exits non-zero if any target fails.
4. Add connections through it
Once the relay has connected, Integrations → Grafana, Prometheus, Tempo, Loki shows it as connected, with its version, host name and targets. Add a connection, choose Through a relay, pick the relay and one of its targets. The kind must match the target's kind. See Connect Grafana or Connect Prometheus, Tempo or Loki for the rest; authentication is left empty, because the relay sends it.
Configuration
| Variable | Default | Meaning |
|---|---|---|
GUIDELY_RELAY_TOKEN | (required) | The relay token, gly_rly_…. |
GUIDELY_URL | https://guidelytech.com | Guidely's address. Must be https. |
GUIDELY_TARGETS | name=kind=url, comma-separated. kind is prometheus, loki, tempo or grafana. The URL may have a path. | |
TARGET_<NAME>_BEARER | Bearer token for that target. | |
TARGET_<NAME>_USERNAME, TARGET_<NAME>_PASSWORD | Basic auth. | |
TARGET_<NAME>_HEADER, TARGET_<NAME>_HEADER_VALUE | One custom header. | |
TARGET_<NAME>_ORG_ID | Sent as X-Scope-OrgID (multi-tenant Mimir, Loki, Tempo). Combines with the others. | |
TARGET_<NAME>_CA_FILE | PEM file of CA certificates to trust for an https target. | |
TARGET_<NAME>_INSECURE_SKIP_TLS_VERIFY | false | Skip certificate checks. Testing only. |
CONCURRENCY | 8 | Queries run at once (1 to 20). |
HEALTH_PORT | 8080 | Port of GET /healthz; 0 turns it off. |
GUIDELY_RELAY_CONFIG | A JSON file with the same settings; environment variables win. |
<NAME> is the target name upper-cased, with anything but letters and digits as _: target eu-prom reads TARGET_EU_PROM_BEARER. Names are 1 to 100 letters, digits, _ or -, unique ignoring case, and they're what connections point at, so keep them stable. The JSON file format is in the package README.
Running it
- Health.
GET /healthzanswers200when the relay reached Guidely in the last 2 minutes and503otherwise. Guidely shows a relay as connected when it polled in the last 90 seconds. - Logs are one JSON object per line: start-up, each query's target, path, status and duration, and connection problems. Query strings, answers and credentials are never logged.
- Outages. Network errors and
5xxor429answers are retried with backoff (1 second, growing to 30 seconds, with jitter). Panels show the relay isn't connected meanwhile. - Revoked token. If Guidely refuses the token (the relay was deleted in Guidely, or the token is wrong), the relay logs it and exits with code 1, so Docker, Kubernetes or ECS show the failure. Create a new relay, update the token and restart.
- Shutdown.
SIGTERMstops polling, finishes queries in flight (up to 10 seconds) and exits. - Several replicas with the same token are fine: each query goes to one of them. Use a separate relay (and token) per network or region, so each shows separately in Guidely.
- Updating is replacing the image; the relay is stateless.
Revoking a relay
Revoke it in Integrations → Grafana, Prometheus, Tempo, Loki (the bin next to the relay). Its token stops working at once, the relay exits on its next poll, and connections through it stop answering until you point them at another relay.