Credentials¶

synthkit reads credentials from a .env file (gitignored — never commit secrets). Each signal type uses its own credential triplet. The self-observability path uses an entirely separate Grafana Cloud stack — never GC_TOKEN.

The two stacks¶

Stack	Purpose	Token var
Synthetic-data stack	Where your fake telemetry lands (dashboards, alerts, demos)	`GC_TOKEN`
Self-obs stack	Where synthkit's own process telemetry lands (RED metrics, traces, profiles)	`GC_SELF_OTLP_PASSWORD` / `GC_PYROSCOPE_PASSWORD` — never `GC_TOKEN`

Keep these separate. Using GC_TOKEN for self-observability would intermingle the generator's own signals with the synthetic data.

Credential reference¶

Synthetic data sinks¶

A single Cloud Access Policy (CAP) token with metrics:write, logs:write, traces:write, and profiles:write scopes covers all four synthetic-data sinks.

Purpose	Env vars	Notes
Metrics (Mimir, Remote-Write v2)	`GC_TOKEN`, `GC_PROM_RW`, `GC_PROM_USER`	`GC_PROM_RW` = push URL; `GC_PROM_USER` = Mimir instance ID
Traces (Tempo, OTLP)	`GC_TOKEN`, `GC_OTLP_ENDPOINT`, `GC_OTLP_USER`	`GC_OTLP_ENDPOINT` = base OTLP gateway URL (`…/otlp`); `GC_OTLP_USER` = stack ID
Logs (Loki)	`GC_TOKEN`, `GC_LOKI`, `GC_LOKI_USER`	`GC_LOKI` = Loki push URL; `GC_LOKI_USER` = Loki instance ID
Profiles (Pyroscope)	`GC_TOKEN`, `GC_PROFILES_URL`, `GC_PROFILES_USER`	Optional; absent = profiles disabled

GC_TOKEN is the password for all four sinks. The user ID for each sink differs (Mimir ID vs stack ID vs Loki ID — they are different numbers).

RUM / Faro (optional)¶

Needed only for blueprints with rum: true on a workload, or app workload nodes with a RUM lane.

Env var	Value
`GC_FARO_COLLECTOR`	Faro collector URL, e.g. `https://faro-collector-<region>.grafana.net/collect/<app-key>`
`GC_FARO_APP_KEY`	Faro application key

Synthetic Monitoring (optional)¶

Used only by the cmd/sm-provision provisioner, not by the main emitter. The SM token is a separate bearer token — not GC_TOKEN.

Env var	Value
`GC_SM_URL`	SM API URL, e.g. `https://synthetic-monitoring-api-<region>.grafana.net`
`GC_SM_TOKEN`	SM API bearer token

See Synthetic Monitoring for the two-phase startup.

Fleet Management (optional)¶

Env var	Value
`GC_FM_URL`	FM API URL, e.g. `https://fleet-management-prod-0NN.grafana.net`
`GC_FM_STACK_ID`	FM basic-auth username = Grafana Cloud stack ID (NOT `GC_PROM_USER`)
`GC_FM_TOKEN`	CAP token with `fleet-management:write` scope

See Fleet Management.

Self-observability — OTLP (optional)¶

Sends synthkit's own RED metrics, traces, and operational logs to a separate stack.

Env var	Value
`SELFOBS_ENABLED`	`true` to enable (default `false`)
`GC_SELF_OTLP_ENDPOINT`	OTLP gateway base URL for the self-obs stack
`GC_SELF_OTLP_USER`	Self-obs stack ID
`GC_SELF_OTLP_PASSWORD`	Self-obs CAP token — never `GC_TOKEN`

Self-profiling — Pyroscope (optional)¶

Sends the synthkit process's continuous profiles to a separate stack. Follows SELFOBS_ENABLED and is suppressed under DRY_RUN.

Env var	Value
`GC_PYROSCOPE_URL`	Profiles endpoint, e.g. `https://profiles-prod-XXX.grafana.net`
`GC_PYROSCOPE_USER`	Profiles instance ID
`GC_PYROSCOPE_PASSWORD`	Profiles CAP token — never `GC_TOKEN`

Getting credentials from Grafana Cloud¶

Open your Grafana Cloud stack → Security → Access policies.
Create a policy with the scopes you need (at minimum: metrics:write, logs:write, traces:write).
Generate a token.
Find the endpoint URLs under Details for each data source (Mimir, Loki, Tempo, Profiles).

If you use gcx, gcx config get --context <your-stack> prints the endpoint URLs for the configured context.

Filling in `.env`¶

cp .env.example .env
# open .env in your editor and fill in the values

Comment placement

Docker Compose's env_file does not strip inline comments. Put comments on their own line — VALUE=foo # comment makes # comment part of the value. .env.example demonstrates the correct style throughout.

The minimum set for a live synthetic push: GC_TOKEN + GC_PROM_RW/GC_PROM_USER + GC_OTLP_ENDPOINT/GC_OTLP_USER + GC_LOKI/GC_LOKI_USER. Leave optional blocks empty to disable RUM, SM, FM, and self-obs.

See Configuration for the full environment variable reference including behaviour knobs (TICK_DEFAULT, SEND_SHARDS, queue tunables, etc.).