The opentelemetry-demo project is a wonderful showcase of the powerful observability available via OpenTelemetry instrumentation. The demo project consists of a distributed eCommerce system (the Astronomy Shop) composed of services in several programming languages. These services are networked together, with their OTel SDKs configured to point to a local otel-collector running alongside. The demo project is maintained by the community and evolves along with the OTel spec and the capabilities of the represented languages. Services are added regularly. Like the rest of the OpenTelemetry project, it is freely available to download and use.

What would one do with such a demo? Examining the various implementations to get an idea of how each language sets up the OTel SDK in a working project can certainly be useful for inspiration and understanding. However, a more gratifying use case is firing it up and pointing it at your favorite OTel backend or storage provider for a while and then taking a spin through your UI of choice to view the OpenTelemetry signals. The demo does include a jaeger service out-of-the-box, but we naturally prefer our own setup, TelemetryHub, which will happily store your signal data and provide a web interface to explore them later. “Look at all those distributed traces, services all working together in glorious harmony to show me Astronomy Shop products!” you’ll say, eyes shining with wonder. It is like a holiday miracle.

What luck, then, that running the demo project yourself is a complete breeze. Two methods are prepared, one for a single instance of compute (e.g., your laptop) via Docker and docker-compose, the other for a Kubernetes cluster via Helm. Here we will focus on the Docker version for ease. The prerequisites are a working `git` executable, a text editor, and a running Docker daemon. It takes about three steps:

  • Git clone && cd opentelemetry-demo && git checkout telemetryhub-backend
  • Update src/otelcollector/otelcol-config-extras.yml with an actual TelemetryHub Ingest Key rather than $YOUR_INGEST_KEY placeholder
  • Docker compose up –no-build

The above will grab the code for the demo and switch to a branch with some TelemetryHub-specific configuration baked into the otelcol-config-extras.yml. It will stop sending demo signals to the default backends and instead point them at the TelemetryHub ingest location. All you need to do is add a valid ingest key and bring everything up.

After you start the `docker up` command, grab yourself a cup of coffee and play a hand or four of euchre. Even without building them locally, it is likely to take a spell to download all of the required images. Users running this on machines with ARM architectures (such as an Apple M* device) may actually need to bite the bullet and build the images locally; some components still appeared unhappy using the public images while we were testing this (using version 1.2.1).

And there, just like that, you have your own happy little Astronomy Shop. Once all the services have been booted and are full of vim and vigor, the front end will be available at http://localhost:8080 for exploration. In addition, the load generator service should automatically begin making requests to the front end to simulate usage. This, in turn, will cause all those delightful spans to be fired off to the collector and thence to the backend (which will be TelemetryHub if you cloned the repo linked above and put in a valid ingest key). The Astronomy Shop also presents a front end at http://localhost:8080 if you would like to browse manually and see traces generated from a user session.

Explore the workings in your account at to your heart’s content!