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:

FilenamePurpose

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

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

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

  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.

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

  2. Click Deploy your app!

  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.

  1. From the Select files dropdown, pick only 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.

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

  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.

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

  2. Click Deploy your app!

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/

Last updated