Install the Collector

You can deploy the OpenTelemetry Collector on a wide variety of operating systems and architectures. The following instructions show how to download and install the latest stable version of the Collector.

If you aren’t familiar with the deployment models, components, and repositories applicable to the OpenTelemetry Collector, first review the Data Collection and Deployment Methods page.

Docker

The following commands pull a Docker image and run the Collector in a container. Replace 0.99.0 with the version of the Collector you want to run.

• DockerHub
• ghcr.io

docker pull otel/opentelemetry-collector-contrib:0.99.0
docker run otel/opentelemetry-collector-contrib:0.99.0

docker pull ghcr.io/open-telemetry/opentelemetry-collector-releases/opentelemetry-collector-contrib:0.99.0
docker run ghcr.io/open-telemetry/opentelemetry-collector-releases/opentelemetry-collector-contrib:0.99.0

To load a custom configuration file from your working directory, mount that file as a volume:

• DockerHub
• ghcr.io

docker run -v $(pwd)/config.yaml:/etc/otelcol-contrib/config.yaml otel/opentelemetry-collector-contrib:0.99.0

docker run -v $(pwd)/config.yaml:/etc/otelcol-contrib/config.yaml ghcr.io/open-telemetry/opentelemetry-collector-releases/opentelemetry-collector-contrib:0.99.0

Docker Compose

You can add OpenTelemetry Collector to your existing docker-compose.yaml file as in the following example:

otel-collector:
  image: otel/opentelemetry-collector-contrib
  volumes:
    - ./otel-collector-config.yaml:/etc/otelcol-contrib/config.yaml
  ports:
    - 1888:1888 # pprof extension
    - 8888:8888 # Prometheus metrics exposed by the Collector
    - 8889:8889 # Prometheus exporter metrics
    - 13133:13133 # health_check extension
    - 4317:4317 # OTLP gRPC receiver
    - 4318:4318 # OTLP http receiver
    - 55679:55679 # zpages extension

Kubernetes

The following command deploys an agent as a daemonset and a single gateway instance:

kubectl apply -f https://raw.githubusercontent.com/open-telemetry/opentelemetry-collector/v0.99.0/examples/k8s/otel-config.yaml

The previous example is meant to serve as a starting point, to be extended and customized before actual production usage. For production-ready customization and installation, see OpenTelemetry Helm Charts.

You can also use the OpenTelemetry Operator 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, and more.

For guidance on how to use the Collector with Kubernetes, see Kubernetes Getting Started.

Nomad

You can find reference job files to deploy the Collector as an agent, gateway, and as full demo in Getting Started with OpenTelemetry on HashiCorp Nomad.

Linux

Every Collector release includes APK, DEB and RPM packaging for Linux amd64/arm64/i386 systems. You can find the default configuration in /etc/otelcol/config.yaml after installation.

Note: systemd is required for automatic service configuration.

APK Installation

To get started on Alpine systems run the following commands:

• AMD64
• ARM64
• i386

apk update
apk add wget shadow
wget https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/v0.99.0/otelcol_0.99.0_linux_amd64.apk
apk add --allow-untrusted otelcol_0.99.0_linux_amd64.apk

apk update
apk add wget shadow
wget https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/v0.99.0/otelcol_0.99.0_linux_arm64.apk
apk add --allow-untrusted otelcol_0.99.0_linux_arm64.apk

apk update
apk add wget shadow
wget https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/v0.99.0/otelcol_0.99.0_linux_386.apk
apk add --allow-untrusted otelcol_0.99.0_linux_386.apk

DEB Installation

To get started on Debian systems run the following commands:

• AMD64
• ARM64
• i386

sudo apt-get update
sudo apt-get -y install wget systemctl
wget https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/v0.99.0/otelcol_0.99.0_linux_amd64.deb
sudo dpkg -i otelcol_0.99.0_linux_amd64.deb

sudo apt-get update
sudo apt-get -y install wget systemctl
wget https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/v0.99.0/otelcol_0.99.0_linux_arm64.deb
sudo dpkg -i otelcol_0.99.0_linux_arm64.deb

sudo apt-get update
sudo apt-get -y install wget systemctl
wget https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/v0.99.0/otelcol_0.99.0_linux_386.deb
sudo dpkg -i otelcol_0.99.0_linux_386.deb

RPM Installation

To get started on Red Hat systems run the following commands:

• AMD64
• ARM64
• i386

sudo yum update
sudo yum -y install wget systemctl
wget https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/v0.99.0/otelcol_0.99.0_linux_amd64.rpm
sudo rpm -ivh otelcol_0.99.0_linux_amd64.rpm

sudo yum update
sudo yum -y install wget systemctl
wget https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/v0.99.0/otelcol_0.99.0_linux_arm64.rpm
sudo rpm -ivh otelcol_0.99.0_linux_arm64.rpm

sudo yum update
sudo yum -y install wget systemctl
wget https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/v0.99.0/otelcol_0.99.0_linux_386.rpm
sudo rpm -ivh otelcol_0.99.0_linux_386.rpm

Manual Linux installation

Linux releases are available for various architectures. You can download the file containing the binary and install it on your machine manually:

• AMD64
• ARM64
• i386
• ppc64le

curl --proto '=https' --tlsv1.2 -fOL https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/v0.99.0/otelcol_0.99.0_linux_amd64.tar.gz
tar -xvf otelcol_0.99.0_linux_amd64.tar.gz

curl --proto '=https' --tlsv1.2 -fOL https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/v0.99.0/otelcol_0.99.0_linux_arm64.tar.gz
tar -xvf otelcol_0.99.0_linux_arm64.tar.gz

curl --proto '=https' --tlsv1.2 -fOL https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/v0.99.0/otelcol_0.99.0_linux_386.tar.gz
tar -xvf otelcol_0.99.0_linux_386.tar.gz

curl --proto '=https' --tlsv1.2 -fOL https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/v0.99.0/otelcol_0.99.0_linux_ppc64le.tar.gz
tar -xvf otelcol_0.99.0_linux_ppc64le.tar.gz

Automatic service configuration

By default, the otelcol systemd service starts with the --config=/etc/otelcol/config.yaml option after installation.

To use a different settings, set the OTELCOL_OPTIONS variable in the /etc/otelcol/otelcol.conf systemd environment file to the appropriate command-line options. You can run /usr/bin/otelcol --help to see all available options. You can pass additional environment variables to the otelcol service by adding them to this file.

If you modify the Collector configuration file or /etc/otelcol/otelcol.conf, restart the otelcol service to apply the changes by running:

sudo systemctl restart otelcol

To check the output from the otelcol service, run:

sudo journalctl -u otelcol

macOS

macOS releases are available for Intel and ARM systems. The releases are packaged as gzipped tarballs (.tar.gz). To unpack them, run the following commands:

• Intel
• ARM

curl --proto '=https' --tlsv1.2 -fOL https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/v0.99.0/otelcol_0.99.0_darwin_amd64.tar.gz
tar -xvf otelcol_0.99.0_darwin_amd64.tar.gz

curl --proto '=https' --tlsv1.2 -fOL https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/v0.99.0/otelcol_0.99.0_darwin_arm64.tar.gz
tar -xvf otelcol_0.99.0_darwin_arm64.tar.gz

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

Windows

Windows releases are packaged as gzipped tarballs (.tar.gz). Every Collector release includes an otelcol.exe executable that you can run after unpacking.

Build from source

You can build the latest version of the Collector based on the local operating system using the following commands:

git clone https://github.com/open-telemetry/opentelemetry-collector.git
cd opentelemetry-collector
make install-tools
make otelcorecol