> For the complete documentation index, see [llms.txt](https://docs.release.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.release.com/guides-and-examples/common-setup-examples/opentelemetry-demo.md). # OpenTelemetry demo Observability is an essential part of any microservice architecture. But when services are built using many divergent technologies, consistent observability becomes a challenge. OpenTelemetry is a collection of tools that enables developers and DevOps to simplify and standardize the collection of telemetry data. To demonstrate how OpenTelemetry works for a complex microservices-based application, the OpenTelemetry developers maintain an example application called the [OpenTelemetry Astronomy Shop Demo](https://github.com/open-telemetry/opentelemetry-demo). The demo is in constant development, with contributors regularly adding more services. This may seem overengineered, but this is the point: To provide a realistic demonstration of how to improve observability of a complex distributed system. In this tutorial, we'll look at how to host a snapshot of this application on Release. ## The Release fork of the OpenTelemetry Astronomy Shop Demo We created a [fork of the OpenTelemetry Astronomy Shop Demo](https://github.com/awesome-release/opentelemetry-demo), hosted in our [Awesome Release](https://github.com/awesome-release/) GitHub organization. We modified this fork by including the following files to simplify adding the demo as a Release application: | Filename | Purpose | | ------------------------------------- | ----------------------------------------------------- | | `.release/application_template.yaml` | A complete application template, generated by Release | | `.release/environment_variables.yaml` | Default environment variables, generated by Release | | `.release.yaml` | This file indicates where to find the templates above | ## Adding the demo app using template files The simplest way to add this demo application to Release is to use the pre-generated application template and corresponding default environment variables. You'll need an existing [Release account](/getting-started/create-an-account.md) with a [cluster](/guides-and-examples/advanced-guides/create-a-cluster.md) and a [domain](/guides-and-examples/domains-and-dns/managing-your-domains.md). Follow the steps below to deploy the demo application: 1. Add a new Release application. ![Select your repo and branch](https://585411240-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M1neGLLQ0sDXeK6ooSo%2Fuploads%2Fgit-blob-923ddd6f24c9d3697d770175d20ea798e6613c52%2Fotel-demo-select-repo.png?alt=media\&token=b26e7cab-bbb7-470d-8986-41f5b1e1d772) 1. Under **Analyze your repository**, skip to the **Next Step**. ![Skip the analysis function](https://585411240-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M1neGLLQ0sDXeK6ooSo%2Fuploads%2Fgit-blob-e6e7b9639f6c654946d7c3c821d3db2380d0bf9f%2Fotel-demo-skip-analyze.png?alt=media\&token=52ebb32f-1a8f-4acd-80e7-768fe4c7e541) 1. Select `.release/application_template.yaml` from the **Select release template file** dropdown. ![Select the application template](https://585411240-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M1neGLLQ0sDXeK6ooSo%2Fuploads%2Fgit-blob-933debc8a1b35483045fc2fb8b034a2045bb7fc0%2Fotel-demo-template.png?alt=media\&token=52715234-4bee-4e3e-871b-a199ba06a2e0) 1. Double-check your `context` and `domain` values, then click **Next Step**. 2. Select `.release/environment_variables.yaml` from the **Select release env template file** dropdown, then click **Next Step**. ![Select environment variables template](https://585411240-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M1neGLLQ0sDXeK6ooSo%2Fuploads%2Fgit-blob-986872f45666c687a968a57f517162d537f547e4%2Fotel-demo-environment-vars.png?alt=media\&token=8a5bbbda-6a2a-4e5b-b316-4287859972dc) 1. Click **Next Step** again to skip over the build arguments form. 2. Click **Deploy your app!** ![Deploy your application](https://585411240-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M1neGLLQ0sDXeK6ooSo%2Fuploads%2Fgit-blob-99d45fb64c834249416913ae94495c17358e12d7%2Fotel-demo-deploy.png?alt=media\&token=0cb97042-f9ac-4324-9e31-1e17d68ef1f3) 1. Release will now build and deploy your OpenTelemetry demo. This could take up to 20 minutes the first time. 2. Visit the environment detail page. 3. Click the **frontend proxy** URL to see the demo shop. Reach the demo's public services by visiting the URLs below (substitute your frontend proxy hostname): * Webstore: `https://your-frontend-proxy-hostename.tld/` * Grafana: `https://your-frontend-proxy-hostename.tld/grafana/` * Feature Flags UI: `https://your-frontend-proxy-hostename.tld/feature/` * Load Generator UI: `https://your-frontend-proxy-hostename.tld/loadgen/` * Jaeger UI: `https://your-frontend-proxy-hostename.tld/jaeger/ui/` ## Detailed steps: How to prepare a Release Application Template from scratch We provide the steps we used to generate a new `application_template.yaml` file for this application as reference. Release can create an application based on an existing Docker Compose file. At the time of writing, Release can import the OpenTelemetry app file, requiring only a few minor changes to the resulting application template: 1. Service names should not contain underscores. 2. Service names are used by Release to create service-specific environment variables. These variables sometimes clash with expected variables from existing apps. ### Use the Docker Compose file to create an application in Release 1. In Release, create a new application. 2. Select your repository and the branch containing your new `compose.yaml` file. Click **Next Step**. ![Select your repo and branch](https://585411240-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M1neGLLQ0sDXeK6ooSo%2Fuploads%2Fgit-blob-923ddd6f24c9d3697d770175d20ea798e6613c52%2Fotel-demo-select-repo.png?alt=media\&token=b26e7cab-bbb7-470d-8986-41f5b1e1d772) 1. From the **Select files** dropdown, pick only `docker-compose.yaml`. ![Select docker-compose.yaml](https://585411240-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M1neGLLQ0sDXeK6ooSo%2Fuploads%2Fgit-blob-b57329718b6e1a1d34cdb952a3fcfeedc596b6d4%2Fotel-demo-docker-compose-yaml.png?alt=media\&token=6dbc6f12-92ca-4bcb-b1ab-22ad32bf604b) 1. Click **Start Analysis**. Release will read the `docker-compose.yaml` file and show a list of services. 2. Add `otelcol` as a dependency to the `kafka` service, then click **Next Step**. ![Select services](https://585411240-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M1neGLLQ0sDXeK6ooSo%2Fuploads%2Fgit-blob-25537fc6d064b64ca26300ef2cb8e086594f3835%2Fotel-demo-kafka-depends-otelcol.png?alt=media\&token=e33d0728-0467-4391-87de-26d4e1b40cc7) 1. Release will create a complete Application Template. Double-check the `context` and `domain` values for your account. ![Generated application template](https://585411240-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M1neGLLQ0sDXeK6ooSo%2Fuploads%2Fgit-blob-84fac8f6956d3ad04f890eab8eb25ae1577b056d%2Fotel-demo-new-app-template.png?alt=media\&token=a85df1b6-d5d6-476c-8d50-ffb84b1a4d3d) 1. Change `kafka` to `kafkaservice` for each occurrence, except the image name. 2. Change all occurrences of `ffs_postgres` to `ffspostgres`. 3. Add container port 5432 to the `ffspostgres` service: ```yaml ports: - type: container_port port: '5432' loadbalancer: false ``` 4. Add container ports 9092 and 9093 to the `kafkaservice` service: ```yaml ports: - type: container_port port: '9092' loadbalancer: false - type: container_port port: '9093' loadbalancer: false ``` 5. Fix the `kafkaservice` health check by changing `kafkaservce` hostname to `localhost`: ```yaml command: - nc - "-z" - kafka - localhost - '9092' ``` 6. Remove the extra current directory selector (`./`) from `configmap` repo paths. 7. Mount extra Grafana configuration files: ```yaml - mount_path: "/etc/grafana/provisioning/dashboards/general.yaml" repo_path: "./src/grafana/provisioning/dashboards/general.yaml" name: grafana-general-yaml - mount_path: "/etc/grafana/provisioning/dashboards/general/demo-dashboard.json" repo_path: "./src/grafana/provisioning/dashboards/general/demo-dashboard.json" name: grafana-general-demo-dashboard-json - mount_path: "/etc/grafana/provisioning/dashboards/general/opentelemetry-collector.json" repo_path: "./src/grafana/provisioning/dashboards/general/opentelemetry-collector.json" name: grafana-general-otel-collector-json - mount_path: "/etc/grafana/provisioning/datasources/default.yaml" repo_path: "./src/grafana/provisioning/datasources/default.yaml" name: grafana-datasources-default-yaml - mount_path: "/etc/grafana/provisioning/datasources/jaeger.yaml" repo_path: "./src/grafana/provisioning/datasources/jaeger.yaml" name: grafana-datasources-jaeger-yaml ``` 8. Click **Next Step**. 9. Edit the generated environment variables file, by removing `PUBLIC_OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` key and value from the `frontend` service. 10. Add a new entry for `PUBLIC_OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` under the `mapping` key: ```yaml mapping: PUBLIC_OTEL_EXPORTER_OTLP_TRACES_ENDPOINT: "${OTELCOL_INGRESS_URL}/v1/traces" ``` 11. Change the value of `FEATURE_FLAG_SERVICE_HOST` to `featureflagservice`. 12. Click **Next Step**. ![Generated environment variables](https://585411240-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M1neGLLQ0sDXeK6ooSo%2Fuploads%2Fgit-blob-2a9571bc0b2ef1cbc22003f61358e262fa490730%2Fotel-demo-new-environment-vars.png?alt=media\&token=1c44ec9d-b873-4248-9571-b61b7f13102b) 1. Skip the build arguments form by clicking **Next Step** again. 2. Click **Deploy your app!** ![Deploy your application](https://585411240-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M1neGLLQ0sDXeK6ooSo%2Fuploads%2Fgit-blob-99d45fb64c834249416913ae94495c17358e12d7%2Fotel-demo-deploy.png?alt=media\&token=0cb97042-f9ac-4324-9e31-1e17d68ef1f3) Release will now build and deploy your demo application. ### View your running application Reach the demo's public services by visiting the URLs below (substitute your frontend proxy hostname): * Webstore: `https://your-frontend-proxy-hostename.tld/` * Grafana: `https://your-frontend-proxy-hostename.tld/grafana/` * Feature Flags UI: `https://your-frontend-proxy-hostename.tld/feature/` * Load Generator UI: `https://your-frontend-proxy-hostename.tld/loadgen/` * Jaeger UI: `https://your-frontend-proxy-hostename.tld/jaeger/ui/` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.release.com/guides-and-examples/common-setup-examples/opentelemetry-demo.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.