1. Introduction

OpenTelemetry is an Observability framework designed to standardize and simplify the collection, processing, and analysis of telemetry data (metrics, traces, and logs) from distributed systems. OpenTelemetry is vendor-agnostic meaning that it can be used with a broad variety of Observability backends, including open-source tools like Jaeger and Prometheus, as well as commercial offerings (Elasticsearch). In this tutorial, you will learn how to install and configure OpenTelemetry Collector using Docker.

2. Prerequisites

• You are expected to have basic knowledge of Docker. This tutorial uses Docker Desktop for Windows, but you can use any other Docker installation depending on your Operating System. Moving forward, we will assume that you have a working installation of Docker in your workstation.

3. Directory Structure

First things first. Let’s start by creating a directory opentelemetry where we will keep the Collector configuration file and any other file related to the installation.

C:\apps\opentelemetry>tree /f
Folder PATH listing for volume Windows
Volume serial number is xxx-xxxx
C:.
└───config
        otel-collector-config.yml

• otel-collector-config.yml is the OpenTelemetry Collector configuration file. You can create an empty file for now.

4. OpenTelemetry Configuration file otel-collector-config.yml

The OpenTelemetry Collector requires a configuration file in YAML format.

Let’s create the file and save it under “C:\apps\opentelemetry\config\otel-collector-config.yml“, with the following content:

# OpenTelemetry Collector Configuration
receivers:
  otlp:
    protocols:
      grpc:
        endpoint: "0.0.0.0:4317"
      http:
        endpoint: "0.0.0.0:4318"

exporters:
  logging:
    loglevel: debug

service:
  pipelines:
    traces:
      receivers: [otlp]
      exporters: [logging]
    metrics:
      receivers: [otlp]
      exporters: [logging]
    logs:
      receivers: [otlp]
      exporters: [logging]

In OpenTelemetry terminology, there are several concepts, among which the most important are:

• Receivers: They receive telemetry data from one or multiple sources and send them to processors. You may define one or more receivers in the configuration file in the receivers section. Discover the full list of possible receivers.
• Processors: They transform data from the receivers before sending it to exporters. You may define one or more processors in the configuration file in the processors section. Processors are optional. Discover the full list of possible processors.
• Exporters: They send the data to a backend (Elasticsearch, Prometheus, Jaeger,…). You may define one or more exporters in the configuration file in the exporters section. Discover the full list of possible exporters.

Pro-tip: Declaring receivers, processors and exporters does not enable them. You need to explicitly add them to appropriate pipelines within the service section.

Our collector has the following configuration:

• One OTLP receiver. The receiver will be gathering data through the OTLP(OpenTelemetry Protocol) on ports 4317 for gRPC, and 4318 for HTTP.
• One logging exporter. This exporter is used for testing purposes only. It will log the telemetry data to the console.
• Three pipelines have been defined, each corresponding to a specific type of telemetry data (traces, metrics, and logs).

5. Pull the OpenTelemetry Collector Docker image

Now that we have created the Collector configuration file, let’s start the installation properly. You can find the list of Docker images for OpenTelemetry in the Docker Otel Registry. For this tutorial, we will be installing the version 0.107.
Open a command prompt (or a terminal) and run the following command:

docker pull otel/opentelemetry-collector:0.107.0

6. Start the Container

Once the image is pulled, use the following command to start the OpenTelemetry Collector container:

docker run --name otel -h otel -it -m 1GB -p 4317:4317 -p 4318:4318 -v C:/apps/opentelemetry/config/otel-collector-config.yml:/usr/share/opentelemetry/otel-collector-config.yml  otel/opentelemetry-collector:0.107.0 --config=/usr/share/opentelemetry/otel-collector-config.yml

• --name otel: the name we are giving to the container
• -h otel: the hostname of the docker container
• -m 1GB : to limit the memory size
• -v ... : to bind a directory in the host machine to a directory in the container. We use it to pass the configuration file from our host machine to the container.
• --config=... : to tell OpenTelemetry Collector the path to the config file

If everything goes well, OpenTelemetry will start listening for OTLP requests on ports 4317 (otlp/grpc) and 4318(otlp/http).

7. Install OpenTelemetry: Verifications

To test your setup, you can do any of the following:
Check OpenTelemetry logs in Docker

docker logs otel

Generate some data via OTLP
We have configured OpenTelemetry to listen to OTLP requests on ports 4317 and 4318 and to send the output to the console. To check if it works as expected, you can send an OTLP request to your Collector.
To achieve that, we will use Otel-cli to generate a custom OTLP request.

otel-cli span --endpoint http://localhost:4318 --name "custom-event" -a "attr1=value1,attr2=value2" --service "test-service" --verbose

The previous command will send a custom event with the given attributes and values to the collector.
Here is the output from the collector console:

8. Conclusion

In this quick tutorial, you learned how to install OpenTelemetry Collector using Docker. In the next article, you will learn how to monitor a Java Application using OpenTelemetry.