Authored by @Ying Mo, @Minghong Xu, @Paras Kampasi

Introduction

OpenTelemetry has become the standard for instrumenting applications, offering a unified approach to collecting telemetry data, including traces, metrics, and logs. However, collecting data is only half the battle, making sense of it is where IBM Instana excels. With powerful analytics and real-time monitoring, IBM Instana is the ideal choice for OpenTelemetry-based observability.

If you are exploring OpenTelemetry and looking for an easy way to enhance your application observability using a sophisticated observability solution such as IBM Instana, you have come to the right place. In this blog post, we will guide you through a quick and straightforward approach to monitoring applications using OpenTelemetry and IBM Instana.

For our demonstration, we will use the OpenTelemetry Demo application, a well-known and feature-rich project from the OpenTelemetry community, as an example application that is perfect for showcasing OpenTelemetry in action. By the end of this post, you will see just how effortlessly you can connect this example application to IBM Instana and start gaining valuable insights in minutes.

About OpenTelemetry Demo

OpenTelemetry Demo is an example application developed as part of the popular CNCF project: OpenTelemetry. It simulates an astronomy-themed online store, built as a collection of microservices, each implemented in different programming languages such as Node.JS, Go, Java, Python, etc. These services communicate using gRPC and HTTP, with OpenTelemetry instrumentation seamlessly integrated across key components like the Frontend, Product Catalog, Checkout, and Payment services. This demo serves as a valuable resource for learning about observability, distributed tracing, metrics, and logs collection in a modern microservices architecture.

In this blog post, we will be working with a customized OpenTelemetry Demo forked from the upstream repository, specifically tailored for IBM Instana. Through this hands-on example, you will learn how to:

• Deploy the OpenTelemetry Demo application and connect it to your existing Instana server.
• Explore the OpenTelemetry metrics, traces, and logs generated by the application in Instana UI.

You will see how easy it is to monitor an OpenTelemetry-instrumented application using Instana, gaining valuable insights with minimal effort.

Deploy OpenTelemetry Demo

The OpenTelemetry Demo application can be deployed using either Docker or Kubernetes. In this guide, we will focus on deploying it with Docker. If you prefer to use Kubernetes, please refer to the official community documentation for detailed instructions.

Prerequisites

Before you begin, ensure your system meets the following requirements:

• Docker
• Docker Compose (v2.0.0 or later)
• Make
• At least 6 GB of RAM for the application

Step 1: Clone the Demo Repository

Run the following command to clone the OpenTelemetry Demo repository:

git clone https://github.com/instana/opentelemetry-demo.git

Navigate to the cloned directory:

cd opentelemetry-demo/

Step 2: Configure the Connection to Instana

To connect the OpenTelemetry Demo application to Instana backend, open the instana/otelcollector/otelcol-config-extras.yml file in a text editor, then make sure the following configuration are present.

processors:
  resource:
    attributes:
      - key: application.id # for filtering usage
        value: my-awesome-otel-demo # make it unique and easy to identify for filtering usage
        action: upsert

# Replace the INSTANA_ENDPOINT, more information:
# https://www.ibm.com/docs/en/instana-observability/current?topic=opentelemetry-sending-data-instana
exporters:
  otlp/instana:
    endpoint: <INSTANA_ENDPOINT>
    tls:
      insecure: false
    headers:
      x-instana-key: <YOUR_INSTANA_AGENT_KEY>

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]

Note:

• Ensure that you provide the correct value for exporters.otlp/instana.endpoint. For example, the value otlp-pink-saas.instana.rocks:4317 corresponds to an endpoint exposed by a SaaS Instana environment, designed to receive OpenTelemetry data via the gRPC protocol. For a self-hosted environment, please refer to the Instana configuration documentation for the appropriate setup.

• The x-instana-key parameter represents the agent key for Instana, which is used to direct telemetry data to the Instana backend. You can find this key from your Instana server administrator.

Step 3: Start the Demo

You can start the demo using either Docker Compose or Make:

Using Docker Compose

docker compose up --force-recreate --remove-orphans --detach

Using Make

make start

Once the deployment is complete, you can access the following services via the frontend-proxy:

• Web store: http://localhost:8080/
• Load Generator UI: http://localhost:8080/loadgen/
• Flagd configurator UI: http://localhost:8080/feature/

Explore OpenTelemetry Data in Instana UI

Now that you have successfully launched the OpenTelemetry Demo application and connected it to Instana, let’s dive into a few key monitoring capabilities that Instana provides to support OpenTelemetry-based observability. The following exercises will guide you through exploring the OpenTelemetry metrics, traces, and logs generated by OpenTelemetry Demo application, showcasing the powerful features of Instana.

Exercise 1: Explore Metrics

Description

In this exercise, you will learn how to explore OpenTelemetry metrics across various services using the Instana Analytics → Infrastructure view. By the end of this exercise, you will be familiar with how the Analytics → Infrastructure view helps monitor OpenTelemetry metrics effectively.

Objective

• Identify microservices instrumented with OpenTelemetry.
• Filter services by application ID (e.g.: my-awesome-otel-demo) and programming language (e.g.: nodejs).
• View metrics (e.g.: CPU, memory, request latency) for each service.

Steps

1. Open Instana UI and navigate to Analytics using the left-side menu. This will take you to the Instana Analytics view.

2. In the Analytics view, use the dropdown menu at the top to select Infrastructure. This will open the Analytics → Infrastructure view.

3. In the Analytics → Infrastructure view:

   • Select OpenTelemetry from the Entity types list.
   • Alternatively, use the search bar above the Entity types list to search for OpenTelemetry, then select it from the search results.

   This will direct you to the OpenTelemetry entities view.

4. In the OpenTelemetry entities view:

   • Click Add filter, enter otel.attribute.application.id to filter the entities by defined 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 otel.attribute.telemetry.sdk.language to filter entities by programming language. In the input field after the equals sign, select or manually enter the desired programming language (e.g.: nodejs).

   This will display all available services in the OpenTelemetry Demo application that are filtered with defined application ID and selected programming language.

5. Click on a specific service (e.g.: frontend) to view its detailed information with a dashboard that displays all available OpenTelemetry metrics associated with this service.

Example Output

Figure 1: The OpenTelemetry Metrics for the frontend Service

Exercise 2: Inspect Traces

Description

In this exercise, you will learn how to inspect OpenTelemetry distributed traces using the Instana Analytics → Traces view. By the end of this exercise, you will be familiar with how the Analytics → Traces view helps diagnose calls in distributed application effectively.

Objective

• Visualize end-to-end request flows across microservices.
• Filter traces by application ID (e.g.: my-awesome-otel-demo) and programming language (e.g.: nodejs).
• Organize and group traces by service name for clearer and more structured analysis.
• Identify latency bottlenecks and detect errors in transactions.

Steps

1. Open Instana UI and navigate to Analytics using the left-side menu. This will take you to the Instana Analytics view.

2. In the Analytics view, use the dropdown menu at the top to select Application/Traces. This will open the Analytics → Applications/Traces view.

3. In the Analytics → Applications/Traces view:

   • Click Add filter, enter OpenTelemetry Resource Tags to filter traces by OpenTelemetry resource attributes. From the list of available resource attributes, select or manually enter application.id to filter traces 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 OpenTelemetry Resource Tags to filter traces by OpenTelemetry resource attributes. From the list of available resource attributes, select or manually enter telemetry.sdk.language to filter traces by programming language. In the input field after the equals sign, select or manually enter the desired programming language (e.g.: nodejs).

   • Click Add group, select Trace Service Name to organize the filtered traces by service.

   This will display all grouped traces generated by service names in the OpenTelemetry Demo application that are filtered with defined application ID and selected programming language.

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

These information will help you identify latency bottlenecks and detect errors in transactions.

Example Output

Figure 2: The OpenTelemetry Traces Grouped by Service Name

Figure 3: The OpenTelemetry Trace Detailed View

Exercise 3: Access Logs

Description

In this exercise, you will learn how to access OpenTelemetry log data using the Instana Analytics → Logs view. By the end of this exercise, you will be familiar with how to leverage the Analytics → Logs view to troubleshoot errors effectively with contextual logs.

Objective

• Perform centralized log analysis for OpenTelemetry-instrumented services.
• Filter services by application ID (e.g.: my-awesome-otel-demo) and programming language (e.g.: java).
• Organize and group logs by service name for clearer and more structured analysis.
• Correlate logs with traces and metrics for comprehensive debugging.

Steps

1. Open Instana UI and navigate to Analytics using the left-side menu. This will take you to the Instana Analytics view.

2. In the Analytics view, use the dropdown menu at the top to select Logs. This will open the Analytics → Logs view.

3. 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 defined application ID and selected programming language.

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

Figure 4: The OpenTelemetry Demo Application Logs

Conclusion

In this guide, we explored how to monitor the OpenTelemetry Demo using IBM Instana, providing a simple and practical way to get started with observability. By leveraging Instana, you can gain valuable insights into your telemetry data, track key metrics, traces, and logs, to enhance visibility into your distributed system. We hope this guide has helped you get started. Happy monitoring!

#OpenTelemetry
#General
#Demo
#Tutorial