OpenTelemetry is the industry-standard open-source framework for processing, and exporting telemetry data: traces, metrics, and logs. Instana’s observability offering is an industry leading method for making sense of that data.
Today we will demonstrate how Instana smoothly integrates with OpenTelemetry (OTel), featuring a full walk through of how to set up OTel on Instana through the Astronomy Shop Demo and the fundamental capabilities of Instana with OpenTelemetry.
Pre-requisites:
- Download Docker
- Docker Compose (v2.0.0 or later)
- Make
- At least 6 GB of RAM for the application
Step 1: Clone the Demo Repository
Navigate to a folder where you would like to store the demo locally. Run the following command to clone the OpenTelemetry Demo repository:
git clone https://github.com/instana/opentelemetry-demo.git
Enter the following command to navigate into the demo folder:
cd opentelemetry-demo/
Step 2: Find your Instana Endpoint and Agent Key
After you have received at least a trial version of Instana you will be able to access your Instana endpoint and agent key (x-instana-key). For a self-hosted environment, please refer to the Instana configuration documentation for appropriate setup. To find the Instana Endpoint and Agent Key, first navigate to the Instana home page.gr
Click into “Data sources” which can be found on the left hand panel.
Click into “Install agents”.
Click into “Docker”
Note both the environment name (e.g. blue, red, green, pumpkin, etc.) and agent key for the next step.
Step 3: Configure the Connection to Instana
Let’s now connect the OpenTelemetry Demo application to the Instana backend. Open the /src/otel-collector/otelcol-config-extras.yml file in a text editor (e.g. Visual Studio Code). Paste the code block below then please add your endpoint with the proper port and agent key (x-instana-key) in the appropriate lines. To find the proper endpoint and port number please refer to the table at the bottom of this page. (Your endpoint may be different from what you observed in the Agent Download section of Instana). Example: otlp-red-saas-instana.io:4317 (Note: both the gplRPC and HTTP ports are supported for this demo. Here we used gRPC.)
# Copyright The OpenTelemetry Authors
# SPDX-License-Identifier: Apache-2.0
# extra settings to be merged into OpenTelemetry Collector configuration
# do not delete this file
## Example configuration for sending data to your own OTLP HTTP backend
## Note: the spanmetrics exporter must be included in the exporters array
## if overriding the traces pipeline.
##
# exporters:
# otlphttp/example:
# endpoint: endpointFromTable:portNumberfromTable
#
# service:
# pipelines:
# traces:
# exporters: [spanmetrics, otlphttp/example]
processors:
resource:
attributes:
- key: application.id
value: insertMyName-otel-demo
action: upsert
exporters:
otlp/instana:
endpoint: endpoint: otlp-red-saas.instana.io:4318 # envNameAndFullEndpointFromTable:portNumberfromTable
tls:
insecure: false
headers:
x-instana-key: yourAgentKey
service:
pipelines:
traces:
receivers: [otlp]
processors: [batch, resource]
exporters: [debug, spanmetrics, otlp/instana]
metrics:
receivers: [otlp, spanmetrics]
processors: [batch, resource]
exporters: [debug, otlp/instana]
logs:
receivers: [otlp]
processors: [batch, resource]
exporters: [debug, otlp/instana] # remove the comma and otlp/instana here if you are on the standard 14-day free trial. Logs not yet supported for trial
Step 4: Start Astronomy Shop Demo
Using Docker Compose
docker compose up --force-recreate --remove-orphans --detach
# if ever need to stop demo run 'docker compose down'
Using Make
make start
# if ever need to stop demo run 'make stop'
Once the deployment is complete (approximately one minute), you can access the following services via the frontend-proxy:
Explore OpenTelemetry Data in Instana UI
Explore Metrics:
Click into “Analytics” on the left-hand side. At the top left part of the screen, click “Infrastructure” so that the menu reads "Analytics → Infrastructure". Now, scroll until you see OpenTelemetry in the list of services and click into “OpenTelemetry”.
On this page we have access to filters. Click the “Add Filter” and type in otel.attribute.application.id. Search the name you inserted for “otel.attribute.application.id” in your otel-config-extras.yml file (e.g. insertMyName-otel-demo). Click into the service that displays.
To observe a specific service, return to the previous screen where you added filters. Click “Add Filter” again and search one of the known services in the Astronomy Shop Demo (e.g. “ad”, “frontend”, “cart”, “payment”). Click into the service that displays to monitor the metrics.
Example Filters:
Click into “Analytics” on the left-hand side panel. At the top of the page, switch the menu to Analytics → Traces.
Click “Add Filter”. Search opentelemetry.resource.tag and select the option that displays. In the Key field, include application.id and set the Value to the application.id you included in your otel-config-extras.yml file.
Click into “Add group” and click Service Name.
Click on a service group from the results list to expand it, then select a specific trace. This will take you to the Analytics → Traces view, where you can inspect the detailed information about the selected trace, including:
- The basic metadata such as the number of sub-calls, erroneous calls, and total duration
- A detailed call stack visualization
- A list of service endpoints involved in the trace and so on.
Example output after groupings:
Example output after clicking into trace:
Explore Logs:
Click into “Logs” on the left-hand side panel. Click “Analyze Logs”
In the Analytics view, use the dropdown menu at the top to select Logs. This will open the Analytics → Logs view.
In the Analytics → Logs view:
- Click “Add filter”, enter
Logs Custom Tags to filter logs by OpenTelemetry resource attributes. From the list of available resource attributes, select or manually enter application.id to filter logs by application ID. In the input field after the equals sign, select or manually enter my-awesome-otel-demo as we defined in confuguration file.
- Click “Add filter”, enter
Logs Custom Tags to filter logs by OpenTelemetry resource attributes. From the list of available resource attributes, select or manually enter telemetry.sdk.language to filter logs by programming language. In the input field after the equals sign, select or manually enter the desired programming language (e.g.: java).
This will display all available log entries generated from OpenTelemetry Demo application that are filtered with the defined application ID and selected programming language.
Now you have the ability to review log entries, including errors, warnings, and informational messages. Click on any log entry to expand it and view detailed information, including the full log line and its associated attributes.
Example output of logs:
Conclusion:
You’ve now completed the OpenTelemetry + Instana demo and seen firsthand how simple and powerful it is to integrate telemetry data into Instana’s observability platform. From deploying the demo with Docker to exploring traces, metrics, and logs through Instana’s intuitive UI, you now have a foundational understanding of how to monitor distributed systems using open standards and enterprise-grade tools.
For any further questions about configuring this demo or learning more about what Instana with OpenTelemetry can offer, feel free to reach out to John.Michaels@ibm.com or Paras.Kampasi@ibm.com.