Read the Chart

Platform engineers, SREs, and observability-focused developers who have completed the Beginner and Intermediate levels or are comfortable with OpenFeature evaluation context, and want to learn how flag evaluations join distributed traces and metrics, and how to use a flag flip as an operational lever for live rollbacks.

1. 1Get Started
   Open in GitHub Codespaces (opens in new tab). The devcontainer is pre-configured and starts automatically. When you push from Codespaces, GitHub forks the repository to your account automatically.

   Prefer working locally? Clone the repo and open it in any editor that supports the Dev Containers specification (VS Code, JetBrains IDEs, and others). The devcontainer config will be detected automatically.

2. 2Start Your Challenge
   The sibling containers (flagd, Grafana LGTM, k6 loadgen) start automatically as part of the devcontainer compose. Wait ~2-3 minutes for them to be ready before moving on.

3. 3Explore the UIs
   Open the Ports tab and navigate to each service:

   • Port 8080: Spring Boot lab. Add ?userId=subject-42 for a stable fractional-rollout bucketing key.
   • Port 3000: Grafana (admin / admin). Open Dashboards > Feature Flag Metrics (empty until metrics are wired). Try Explore > Tempo to see flag evaluations as span events.
   • Port 9090: Prometheus. Query metrics directly via the Prometheus UI or curl http://localhost:9090/api/v1/query.
   • Port 3200: Tempo. Tempo HTTP API used by the verify script to assert traces are flowing.

   flagd runs on the docker-internal network only. No port forwarding needed.

4. 4Start the Lab
   The sibling containers are already up. Boot the Spring Boot lab by clicking Run on Laboratory in the Spring Boot Dashboard panel (or press F5 with Laboratory.java open), or from the terminal:

   ./mvnw spring-boot:run
   

   Copy

   Spans start flowing into Tempo on the first request. The trace pipeline is already wired. The metrics pipeline is dead (task 4a), so the Grafana dashboard panels stay empty until you fix it.

5. 5Turn On the Metrics Exporter
   OTel ships two parallel pipelines: traces (already flowing into Tempo) and metrics (dead). The OTel Java Agent attached to the lab JVM has both pipelines plumbed and pointed at the LGTM stack, but otel.properties (next to pom.xml) sets otel.metrics.exporter=none, so anything the meter records goes nowhere.

   Open otel.properties and flip the exporter on. While you're there, look at the export interval. The default makes the next steps harder than they need to be.

   Once the exporter is on, MetricsHook (next step) finds the working meter provider through GlobalOpenTelemetry without any further plumbing. You will need to restart the lab to pick up the change.

6. 6Register MetricsHook
   OpenFeatureConfig.java registers TracesHook but stops there. MetricsHook needs an OpenTelemetry handle to find the meter provider. The agent installs one globally at JVM start, so GlobalOpenTelemetry.get() is the way to reach it.

   Register MetricsHook alongside TracesHook in OpenFeatureConfig. The Feature Flag Metrics dashboard stays empty until traffic drives through. That is what the loadgen step does.

7. 7Write and Register ContextSpanHook
   The two contrib hooks tell you what happened: which flag, which variant, which reason. What is missing is the why visible in Tempo. Write a ContextSpanHook that copies the merged eval context attributes onto the active OTel span as feature_flag.context.<key>:

   before(hookCtx) {
       span = active OTel span
       for each allowlisted key in merged eval context:
           span.setAttribute("feature_flag.context." + key, value)
   }
   

   Copy

   HookContext.getCtx() returns the merged evaluation context (global + transaction + invocation). Use a fixed allowlist of List.of("species", "country", "dose"). Never iterate the whole context: targetingKey joins to PII in real apps, and span attributes are retained for days in Tempo at scale.

   Register ContextSpanHook alongside TracesHook and MetricsHook in OpenFeatureConfig. The verifier searches Tempo for feature_flag.context.dose=underdose once you are done.

8. 8Turn On the Loadgen
   flags.json has two flags: loadgen_active (off by default) and the misbehaving vision_amplifier_v2. flagd watches the file and picks up changes within about a second.

   Flip loadgen_active to on. The k6 loadgen polls it every two seconds and starts five virtual users hammering the lab. Within a minute, latency p99 should climb ~200ms and the 5xx rate ~10% on the dashboard, confirming that the bad arm of vision_amplifier_v2 is active.

9. 9Roll Back the Rollout
   The dashboard's variant-distribution panel shows which variant is the culprit. Roll it back by editing flags.json to set vision_amplifier_v2 to 100% off.

   No deploy. No rebuild. No restart of the lab.

   Watch the dashboard: the 5xx rate falls back to baseline, and the next batch of subjects walks out seeing.