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.

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, hosted in our 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 with a cluster and a domain.

Follow the steps below to deploy the demo application:

1. Add a new Release application.

Select your repo and branch

1. Under Analyze your repository, skip to the Next Step.

Skip the analysis function

1. Select .release/application_template.yaml from the Select release template file dropdown.

Select the application template

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

1. Click Next Step again to skip over the build arguments form.

2. Click Deploy your app!

Deploy your application

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

1. From the Select files dropdown, pick only docker-compose.yaml.

Select docker-compose.yaml

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

1. Release will create a complete Application Template. Double-check the context and domain values for your account.

Generated application template

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:

   ports:
   - type: container_port
     port: '5432'
     loadbalancer: false

4. Add container ports 9092 and 9093 to the kafkaservice service:

   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:

   command:
   - nc
   - "-z"
   - kafka
   - localhost
   - '9092'

6. Remove the extra current directory selector (./) from configmap repo paths.

7. Mount extra Grafana configuration files:

   - 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:

    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

1. Skip the build arguments form by clicking Next Step again.

2. Click Deploy your app!

Deploy your application

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/