Frequently Asked Questions¶

Short answers to common questions. Each answer links to the authoritative page for the full detail — treat those linked pages as the source of truth.

Getting started¶

Does synthkit send data to my real production Grafana Cloud stack?¶

Only if you configure it to and only synthetic data — it never reads from or writes to your production systems. DRY_RUN defaults to true, so a fresh checkout produces no network traffic at all until you explicitly set DRY_RUN=false and fill in credentials. See Getting Started and Credentials.

Do I need a Kubernetes cluster or cloud account to try synthkit?¶

No. synthkit doesn't touch real infrastructure — it generates telemetry that looks like it came from an EKS cluster, RDS database, or Cloudflare account, entirely from a YAML blueprint. Run DRY_RUN=true ./synthkit -once -dump to see the full series inventory with no credentials and no cloud account at all. See Quick Start.

What's the smallest thing I need to get real data into Grafana Cloud?¶

GC_TOKEN plus the GC_PROM_RW/GC_PROM_USER, GC_OTLP_ENDPOINT/GC_OTLP_USER, and GC_LOKI/GC_LOKI_USER pairs, then DRY_RUN=false. RUM, profiles, Synthetic Monitoring, and Fleet Management are all optional add-ons layered on top. See Credentials.

Blueprints¶

Can I edit a blueprint while synthkit is running?¶

Bundled and staged blueprints only take effect on restart — there's no hot-reload for blueprint files themselves. What does apply live, without a restart, is scenario activation, volume scaling, and ad-hoc failure injection through the control plane. See Control Plane.

If I delete a blueprint file, does anything else break?¶

No. Constructs and workloads know nothing about which blueprint they belong to — deleting a blueprint file removes exactly that blueprint's telemetry and leaves every other blueprint untouched. This is a deliberate architectural invariant, not an incidental property. See Architecture.

Why did my blueprint fail to load with no telemetry at all?¶

Blueprint decoding is strict: an unknown top-level key, an unknown construct kind, or an unknown field inside a construct's config is a loud load error, not a silently-ignored one. Check GET /control/diagnostics for the exact cause. See Blueprints Overview.

Do I have to hand-write the YAML myself?¶

Not necessarily. The /create-blueprint skill walks through an interactive authoring session in Claude Code, and skcapture + skforge can generate a draft blueprint from a real Kubernetes environment's inventory (with the option to encrypt the capture and strip Secret/ConfigMap data values). See Capture & Tooling.

Metrics and signal accuracy¶

Are the metric names and labels made up, or copied from a real exporter?¶

Copied, deliberately. Every metric name, label key, and label value is sourced from the signals/ catalogue, which is lifted from production-validated stacks with provenance citations — synthkit never invents a name. See Reading the Catalogue.

Why do my dashboard's rate() queries look wrong right after a restart?¶

Container restart resets synthkit's counters to zero, which produces one clean rate() window after the restart rather than a spike or a gap — this is intentional, not a bug. Use increase() with a long lookback across a restart boundary, or plan maintenance windows around it. See Deployment.

Operations¶

Is the control plane authenticated?¶

GET routes are always open. POST/DELETE mutation routes require HTTP Basic auth (username control) only if you set CONTROL_TOKEN — leaving it unset means anyone who can reach the port can inject failures, scale workloads to zero, or disable blueprints. The default bind is loopback only, which is the safe default. See Control Plane and Security.

My control-plane changes aren't surviving a restart — why?¶

Almost always a /data volume problem: either it's a single-file bind mount (which breaks the atomic write-then-rename save) or the directory isn't owned by uid 65532, the distroless container's nonroot user. Check persist.last_error in GET /control/status. See Troubleshooting.

Some constructs have data and others don't, even though DRY_RUN is false — why?¶

Check SERIES_CAP. When set, it silently truncates how many series synthkit pushes per tick across all sinks — a global kill switch for runaway cardinality, not a per-blueprint limit. See Troubleshooting.

Security¶

Where do I put my Grafana Cloud credentials?¶

In a gitignored .env file, never in the committed docker-compose.yml or a blueprint. The compose file and blueprints are meant to be shared or committed; .env is not. See Security and Credentials.

If someone compromised my synthkit instance, could they see real customer data?¶

No — there isn't any. synthkit reads blueprint YAML and emits synthetic telemetry; it has no inbound integration with a real production system to steal data from. The real risk is credential misuse (pushing synthetic data as if it were legitimate, or exhausting the GC_TOKEN's write quota) and control-plane abuse if left unauthenticated on a reachable network. See Security.