OpenTelemetry Demo: trace a failed checkout in Astronomy Shop
Run OpenTelemetry Demo 3.1.0 with Docker Compose, compare a normal checkout and a failed payment in Jaeger, and send a copy of the traces to Guance.
A failed checkout gives you a useful first exercise in the OpenTelemetry Demo. The browser tells you the order did not go through. A trace lets you see whether checkout reached the payment service and what happened inside the charge call. Astronomy Shop, the upstream sample application, lets you examine that path without instrumenting an application of your own.
This guide uses the Demo 3.1.0 release. The Compose files, route definitions, and payment behavior were checked against the pinned source. The full container stack and external DataKit ingestion were not run for this guide.
Start the Demo with its observability layer
Astronomy Shop has a storefront, product catalog, cart, checkout, payment, and other services written in several languages. The full Compose deployment adds Kafka and its consumers, including fraud detection and accounting. Collector, Jaeger, Prometheus, OpenSearch, and Grafana provide places to examine the signals. Coverage varies by service and signal. Check the generated telemetry documentation to see what a given component emits. Demo architecture · Telemetry coverage
Run this on a dedicated test machine with Docker and Compose v2. The official Docker guide lists 6 GB of application memory for the full mode and 14 GB of disk. The upstream Compose setup mounts host paths and the Docker socket and publishes ports. Keep the demo in an isolated environment and use its sample data. Docker deployment requirements · Demo 3.1.0 release
git clone --branch 3.1.0 --depth 1 https://github.com/open-telemetry/opentelemetry-demo.git
cd opentelemetry-demo
export DEMO_VERSION=3.1.0
docker compose --env-file .env --env-file .env.override \
-f compose.yaml -f compose.full.yaml \
-f compose.observability.yaml -f compose.extras.yaml up -d
A bare docker compose up loads the core file. The four files above add Kafka, the local observability backends, and the final customization layer. Wait until the services needed by the storefront and observability tools are ready.
| Local URL | What you can check |
|---|---|
http://localhost:8080/ |
Open the storefront and place a test order. |
http://localhost:8080/jaeger/ui/ |
Find the trace for that order. |
http://localhost:8080/grafana/ |
Open the provisioned dashboards and data sources. |
http://localhost:8080/loadgen/ |
Inspect the Demo’s synthetic traffic. |
http://localhost:8080/feature/ |
Change the scenario's flag in the local flagd UI. |
http://localhost:8080/telemetry/ |
Check the telemetry documented for each service. |
Compare a normal checkout with a failed payment
Start with paymentFailure set to off. Place one order using the Demo’s sample payment details and note its time. In Jaeger, select the checkout service and look for the request in that window. Follow the trace to the payment service and find the charge span. If background traffic obscures the request, narrow the search window or pause the load generator for the comparison.
In the flagd UI, set the default variant of paymentFailure to 100% and save it. Place another sample order. For the pinned code, that variant gives the Payment handler a failure probability of one. The handler raises a synthetic error and marks its charge span as an error. Compare the two traces and look for where the error first appears. Restore the flag to off after the exercise. Feature flags · Payment handler at 3.1.0
Use the failed span to explain the difference between the requests. Metrics put the failure in the context of traffic over time. Logs can add detail when the relevant service emits them and their trace IDs are available. If those logs are missing, check the service’s coverage and the logs pipeline before drawing a conclusion about the request.
Follow the data through the Collector
The application sends OTLP to the Demo’s Collector. Its base config defines receivers and processing. The observability layer sends traces to Jaeger, metrics to Prometheus, and logs to OpenSearch. The span_metrics connector also turns spans into metrics. The optional final config layer can add another destination without changing the application. Pinned Collector base · Pinned observability layer
For another exercise, follow an order into a Kafka consumer in the full mode. Check the trace context and any links between spans. Look at the actual parent or link relationship before treating async work as a direct child. If you experiment with sampling, change the tracing policy deliberately and watch what happens to the traces you can find. To reduce all the synthetic traffic the lab generates, adjust the load generator. Trace sampling does not reduce all metric and log traffic.
Send a copy of the traces to Guance
If you have a DataKit receiver reachable from the Collector container over a private route, start with traces. In src/otel-collector/otelcol-config-extras.yml, add a new OTLP/HTTP Protobuf exporter and wire it into the existing traces pipeline. Replace the example endpoint with your reachable DataKit endpoint. DataKit's documented default HTTP port is 9529 and its default trace path is /otel/v1/traces. Configure TLS and authentication for your deployment. DataKit OpenTelemetry input
exporters:
otlp_http/datakit:
traces_endpoint: https://datakit.example.com/otel/v1/traces
service:
pipelines:
traces:
exporters: [debug, otlp_grpc/jaeger, span_metrics, otlp_http/datakit]
The example uses the exact list for the four-layer deployment above. Collector replaces arrays when it merges the files, so keep Jaeger, the debug exporter, and the span_metrics connector in the list. Apply the change and restart the Collector with the same Compose layers. Once the new destination works, use the same two test orders to check service identity and span hierarchy in Guance. To send metrics or logs too, configure their signal-specific endpoints and pipelines separately. This trace example leaves the existing metrics and logs destinations in place.
Questions that come up in a lab
What if the full Demo is too large? The official minimal mode keeps the observability stack and omits Kafka and its dependent services. It needs about 3 GB of application memory according to the Docker guide. Use the supported mode so dependencies remain consistent.
Can I copy the application instrumentation into production? Start with the SDK examples relevant to your language, then set resource identity, sampling, and sensitive-data controls for your environment. Use sample checkout data in the lab and leave raw sensitive-data flags disabled.
Can I deploy the Demo with Kubernetes? The upstream Helm chart is a separate deployment route. Use a test cluster and its documented values, resource requirements, and port forwarding. Kubernetes deployment
Related reading
Contact us
Join the community
to join the community
Try Guance
Start online and pay only for what you use.
Get startedChoose a Guance plan
