Getting Started

Please be sure to review the Data Collection documentation in order to understand the deployment models, components, and repositories applicable to the OpenTelemetry Collector.


The OpenTelemetry Collector consists of a single binary and two primary deployment methods:

  • Agent: A Collector instance running with the application or on the same host as the application (e.g. binary, sidecar, or daemonset).
  • Gateway: One or more Collector instances running as a standalone service (e.g. container or deployment) typically per cluster, data center or region.


It is recommended to deploy the Agent on every host within an environment. In doing so, the Agent is capable of receiving telemetry data (push and pull based) as well as enhancing telemetry data with metadata such as custom tags or infrastructure information. In addition, the Agent can offload responsibilities that client instrumentation would otherwise need to handle including batching, retry, encryption, compression and more. OpenTelemetry instrumentation libraries by default export their data assuming a locally running Collector is available.


Additionally, a Gateway cluster can be deployed in every cluster, data center, or region. A Gateway cluster runs as a standalone service and can offer advanced capabilities over the Agent including tail-based sampling. In addition, a Gateway cluster can limit the number of egress points required to send data as well as consolidate API token management. Each Collector instance in a Gateway cluster operates independently so it is easy to scale the architecture based on performance needs with a simple load balancer. If a gateway cluster is deployed, it usually receives data from Agents deployed within an environment.

Getting Started


Deploys a load generator, agent and gateway as well as Jaeger, Zipkin and Prometheus back-ends. More information can be found on the demo

$ git clone; \
    cd opentelemetry-collector-contrib/examples/demo; \
    docker-compose up -d


Every release of the Collector is published to Docker Hub and comes with a default configuration file.

$ docker run otel/opentelemetry-collector

In addition, you can use the local example provided. This example starts a Docker container of the core version of the Collector with all receivers enabled and exports all the data it receives locally to a file. Data is sent to the container and the container scrapes its own Prometheus metrics.

$ git clone; \
    cd opentelemetry-collector/examples; \
    go build main.go; ./main & pid1="$!";
    docker run --rm -p 13133:13133 -p 14250:14250 -p 14268:14268 \
      -p 55678-55679:55678-55679 -p 4317:4317 -p 8888:8888 -p 9411:9411 \
      -v "${PWD}/local/otel-config.yaml":/otel-local-config.yaml \
      --name otelcol otel/opentelemetry-collector \
      --config otel-local-config.yaml; \
    kill $pid1; docker stop otelcol


Deploys an agent as a daemonset and a single gateway instance.

$ kubectl apply -f

The example above is meant to serve as a starting point, to be extended and customized before actual production usage.

The OpenTelemetry Operator can also be used to provision and maintain an OpenTelemetry Collector instance, with features such as automatic upgrade handling, Service configuration based on the OpenTelemetry configuration, automatic sidecar injection into deployments, among others.


Reference job files to deploy the Collector as an agent, gateway and in the full demo can be found at

Linux Packaging

Every Collector release includes DEB and RPM packaging for Linux amd64/arm64 systems. The packaging includes a default configuration that can be found at /etc/otel-collector/config.yaml post-installation.

Please note that systemd is require for automatic service configuration

To get started on Debian systems run the following replacing v0.39.0 with the version of the Collector you wish to run and amd64 with the appropriate architecture.

$ sudo apt-get update
$ sudo apt-get -y install wget systemctl
$ wget
$ dpkg -i otelcol_0.39.0_linux_amd64.deb

To get started on Red Hat systems run the following replacing v0.39.0 with the version of the Collector you wish to run and x86_64 with the appropriate architecture.

$ sudo yum update
$ sudo yum -y install wget systemctl
$ wget
$ rpm -ivh otelcol_0.39.0_linux_amd64.rpm

By default, the otel-collector systemd service will be started with the --config=/etc/otel-collector/config.yaml option after installation. To customize these options, modify the OTELCOL_OPTIONS variable in the /etc/otel-collector/otel-collector.conf systemd environment file with the appropriate command-line options (run /usr/bin/otelcol --help to see all available options). Additional environment variables can also be passed to the otel-collector service by adding them to this file.

If either the Collector configuration file or /etc/otel-collector/otel-collector.conf are modified, restart the otel-collector service to apply the changes by running:

$ sudo systemctl restart otel-collector

To check the output from the otel-collector service, run:

$ sudo journalctl -u otel-collector

Windows Packaging

Windows releases are packaged as gzipped tarballs (.tar.gz) and will need to be unpacked with a tool that supports this compression format.

Every Collector release includes an otelcol.exe executable that you can run after unpacking.


Builds the latest version of the collector based on the local operating system, runs the binary with all receivers enabled and exports all the data it receives locally to a file. Data is sent to the container and the container scrapes its own Prometheus metrics.

$ git clone; \
    cd opentelemetry-collector-contrib/examples/demo; \
    go build client/main.go; ./client/main & pid1="$!"; \
    go build server/main.go; ./server/main & pid2="$!"; \

$ git clone; \
    cd opentelemetry-collector; make install-tools; make build-binary-cmd-otelcol; \
    ./bin/cmd-otelcol --config ./examples/local/otel-config.yaml; kill $pid1; kill $pid2