300 lines
12 KiB
Markdown
300 lines
12 KiB
Markdown
---
|
|
title: Getting Started
|
|
spelling: cSpell:ignore dpkg GOARCH journalctl kubectl
|
|
weight: 1
|
|
---
|
|
|
|
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.
|
|
|
|
## Demo
|
|
|
|
Deploys a load generator, agent and gateway as well as Jaeger, Zipkin and
|
|
Prometheus back-ends. More information can be found on the demo [README.md][]
|
|
|
|
```sh
|
|
git clone git@github.com:open-telemetry/opentelemetry-collector-contrib.git; \
|
|
cd opentelemetry-collector-contrib/examples/demo; \
|
|
docker-compose up -d
|
|
```
|
|
|
|
## Docker
|
|
|
|
Pull a docker image and run the collector in a container. Replace
|
|
`{{% param collectorVersion %}}` with the version of the Collector you wish to
|
|
run.
|
|
|
|
<!-- prettier-ignore-start -->
|
|
{{< ot-tabs DockerHub ghcr.io >}}
|
|
{{< ot-tab lang="console">}}
|
|
$ docker pull otel/opentelemetry-collector:{{% param collectorVersion %}}
|
|
$ docker run otel/opentelemetry-collector:{{% param collectorVersion %}}
|
|
{{< /ot-tab >}}
|
|
|
|
{{< ot-tab lang="console">}}
|
|
$ docker pull ghcr.io/open-telemetry/opentelemetry-collector-releases/opentelemetry-collector-contrib:{{% param collectorVersion %}}
|
|
$ docker run ghcr.io/open-telemetry/opentelemetry-collector-releases/opentelemetry-collector-contrib:{{% param collectorVersion %}}
|
|
{{< /ot-tab >}}
|
|
{{< /ot-tabs >}}
|
|
|
|
To load your custom configuration `config.yaml` from your current working directory, mount that file as a volume:
|
|
|
|
{{< ot-tabs DockerHub ghcr.io >}}
|
|
{{< ot-tab lang="console">}}
|
|
$ docker run -v $(pwd)/config.yaml:/etc/otelcol/config.yaml otel/opentelemetry-collector:{{% param collectorVersion %}}
|
|
{{< /ot-tab >}}
|
|
|
|
{{< ot-tab lang="console">}}
|
|
$ docker run -v $(pwd)/config.yaml:/etc/otelcol-contrib/config.yaml ghcr.io/open-telemetry/opentelemetry-collector-releases/opentelemetry-collector-contrib:{{% param collectorVersion %}}
|
|
{{< /ot-tab >}}
|
|
{{< /ot-tabs >}}
|
|
<!-- prettier-ignore-end -->
|
|
|
|
## Docker Compose
|
|
|
|
You can add OpenTelemetry collector to your existing `docker-compose.yaml` like
|
|
the following:
|
|
|
|
```yaml
|
|
# Collector
|
|
otel-collector:
|
|
image: otel/opentelemetry-collector
|
|
command: [--config=/etc/otel-collector-config.yaml]
|
|
volumes:
|
|
- ./otel-collector-config.yaml:/etc/otel-collector-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
|
|
|
|
Deploys an agent as a daemonset and a single gateway instance.
|
|
|
|
```sh
|
|
kubectl apply -f https://raw.githubusercontent.com/open-telemetry/opentelemetry-collector/main/examples/k8s/otel-config.yaml
|
|
```
|
|
|
|
The example above 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][].
|
|
|
|
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.
|
|
|
|
## Nomad
|
|
|
|
Reference job files to deploy the Collector as an agent, gateway and in the full
|
|
demo can be found at [Getting Started with OpenTelemetry on HashiCorp Nomad][]
|
|
|
|
## Linux Packaging
|
|
|
|
Every Collector release includes APK, DEB and RPM packaging for Linux
|
|
amd64/arm64/i386 systems. The packaging includes a default configuration that
|
|
can be found at `/etc/otelcol/config.yaml` post-installation.
|
|
|
|
> Please note that systemd is required for automatic service configuration
|
|
|
|
### APK Installation
|
|
|
|
To get started on alpine systems run the following replacing
|
|
`v{{% param collectorVersion %}}` with the version of the Collector you wish to
|
|
run.
|
|
|
|
<!-- prettier-ignore-start -->
|
|
{{< ot-tabs AMD64 ARM64 i386 >}}
|
|
{{< ot-tab lang="console">}}
|
|
$ apk update
|
|
$ apk add wget shadow
|
|
$ wget https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/v{{% param collectorVersion %}}/otelcol_{{% param collectorVersion %}}_linux_amd64.apk
|
|
$ apk add --allow-untrusted otelcol_{{% param collectorVersion %}}_linux_amd64.apk
|
|
{{< /ot-tab >}}
|
|
|
|
{{< ot-tab lang="console">}}
|
|
$ apk update
|
|
$ apk add wget shadow
|
|
$ wget https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/v{{% param collectorVersion %}}/otelcol_{{% param collectorVersion %}}_linux_arm64.apk
|
|
$ apk add --allow-untrusted otelcol_{{% param collectorVersion %}}_linux_arm64.apk
|
|
{{< /ot-tab >}}
|
|
|
|
{{< ot-tab lang="console">}}
|
|
$ apk update
|
|
$ apk add wget shadow
|
|
$ wget https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/v{{% param collectorVersion %}}/otelcol_{{% param collectorVersion %}}_linux_386.apk
|
|
$ apk add --allow-untrusted otelcol_{{% param collectorVersion %}}_linux_386.apk
|
|
{{< /ot-tab >}}
|
|
{{< /ot-tabs >}}
|
|
<!-- prettier-ignore-end -->
|
|
|
|
### DEB Installation
|
|
|
|
To get started on Debian systems run the following replacing
|
|
`v{{% param collectorVersion %}}` with the version of the Collector you wish to
|
|
run and `amd64` with the appropriate architecture.
|
|
|
|
<!-- prettier-ignore-start -->
|
|
{{< ot-tabs AMD64 ARM64 i386 >}}
|
|
{{< ot-tab lang="console">}}
|
|
$ sudo apt-get update
|
|
$ sudo apt-get -y install wget systemctl
|
|
$ wget https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/v{{% param collectorVersion %}}/otelcol_{{% param collectorVersion %}}_linux_amd64.deb
|
|
$ sudo dpkg -i otelcol_{{% param collectorVersion %}}_linux_amd64.deb
|
|
{{< /ot-tab >}}
|
|
|
|
{{< ot-tab lang="console">}}
|
|
$ sudo apt-get update
|
|
$ sudo apt-get -y install wget systemctl
|
|
$ wget https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/v{{% param collectorVersion %}}/otelcol_{{% param collectorVersion %}}_linux_arm64.deb
|
|
$ sudo dpkg -i otelcol_{{% param collectorVersion %}}_linux_arm64.deb
|
|
{{< /ot-tab >}}
|
|
|
|
{{< ot-tab lang="console">}}
|
|
$ sudo apt-get update
|
|
$ sudo apt-get -y install wget systemctl
|
|
$ wget https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/v{{% param collectorVersion %}}/otelcol_{{% param collectorVersion %}}_linux_386.deb
|
|
$ sudo dpkg -i otelcol_{{% param collectorVersion %}}_linux_386.deb
|
|
{{< /ot-tab >}}
|
|
{{< /ot-tabs >}}
|
|
<!-- prettier-ignore-end -->
|
|
|
|
### RPM Installation
|
|
|
|
To get started on Red Hat systems run the following replacing
|
|
`v{{% param collectorVersion %}}` with the version of the Collector you wish to
|
|
run and `x86_64` with the appropriate architecture.
|
|
|
|
<!-- prettier-ignore-start -->
|
|
{{< ot-tabs AMD64 ARM64 i386 >}}
|
|
{{< ot-tab lang="console">}}
|
|
$ sudo yum update
|
|
$ sudo yum -y install wget systemctl
|
|
$ wget https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/v{{% param collectorVersion %}}/otelcol_{{% param collectorVersion %}}_linux_amd64.rpm
|
|
$ sudo rpm -ivh otelcol_{{% param collectorVersion %}}_linux_amd64.rpm
|
|
{{< /ot-tab >}}
|
|
|
|
{{< ot-tab lang="console">}}
|
|
$ sudo yum update
|
|
$ sudo yum -y install wget systemctl
|
|
$ wget https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/v{{% param collectorVersion %}}/otelcol_{{% param collectorVersion %}}_linux_arm64.rpm
|
|
$ sudo rpm -ivh otelcol_{{% param collectorVersion %}}_linux_arm64.rpm
|
|
{{< /ot-tab >}}
|
|
|
|
{{< ot-tab lang="console">}}
|
|
$ sudo yum update
|
|
$ sudo yum -y install wget systemctl
|
|
$ wget https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/v{{% param collectorVersion %}}/otelcol_{{% param collectorVersion %}}_linux_386.rpm
|
|
$ sudo rpm -ivh otelcol_{{% param collectorVersion %}}_linux_386.rpm
|
|
{{< /ot-tab >}}
|
|
{{< /ot-tabs >}}
|
|
<!-- prettier-ignore-end -->
|
|
|
|
### Automatic Service Configuration
|
|
|
|
By default, the `otelcol` systemd service will be started with the
|
|
`--config=/etc/otelcol/config.yaml` option after installation. To customize
|
|
these options, modify the `OTELCOL_OPTIONS` variable in the
|
|
`/etc/otelcol/otelcol.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 `otelcol`
|
|
service by adding them to this file.
|
|
|
|
If either the Collector configuration file or `/etc/otelcol/otelcol.conf` are
|
|
modified, restart the `otelcol` service to apply the changes by running:
|
|
|
|
```sh
|
|
sudo systemctl restart otelcol
|
|
```
|
|
|
|
To check the output from the `otelcol` service, run:
|
|
|
|
```sh
|
|
sudo journalctl -u otelcol
|
|
```
|
|
|
|
## MacOS Packaging
|
|
|
|
[MacOS releases][] are available for Intel- & ARM-based systems. They are
|
|
packaged as gzipped tarballs (`.tar.gz`) and will need to be unpacked with a
|
|
tool that supports this compression format:
|
|
|
|
{{< ot-tabs Intel ARM >}} {{< ot-tab lang="console">}} $ curl -O -L
|
|
https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/v{{%
|
|
param collectorVersion
|
|
%}}/otelcol*{{% param collectorVersion %}}\_darwin_amd64.tar.gz $ tar -xvf
|
|
otelcol*{{% param collectorVersion %}}\_darwin_amd64.tar.gz {{< /ot-tab >}}
|
|
|
|
{{< ot-tab lang="console">}} $ curl -O -L
|
|
https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/v{{%
|
|
param collectorVersion
|
|
%}}/otelcol*{{% param collectorVersion %}}\_darwin_arm64.tar.gz $ tar -xvf
|
|
otelcol*{{% param collectorVersion %}}\_darwin_arm64.tar.gz {{< /ot-tab >}}
|
|
{{< /ot-tabs >}}
|
|
|
|
Every Collector release includes an `otelcol` executable that you can run after
|
|
unpacking.
|
|
|
|
## 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.
|
|
|
|
## Local
|
|
|
|
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. The following example uses two terminal windows to
|
|
better illustrate the collector. In the first terminal window run the following:
|
|
|
|
```sh
|
|
git clone https://github.com/open-telemetry/opentelemetry-collector.git
|
|
cd opentelemetry-collector
|
|
make install-tools
|
|
make otelcorecol
|
|
./bin/otelcorecol_* --config ./examples/local/otel-config.yaml
|
|
```
|
|
|
|
In a second terminal window, you can test the newly built collector by doing the
|
|
following:
|
|
|
|
```sh
|
|
git clone https://github.com/open-telemetry/opentelemetry-collector-contrib.git
|
|
cd opentelemetry-collector-contrib/examples/demo/server
|
|
go build -o main main.go; ./main & pid1="$!"
|
|
cd ../client
|
|
go build -o main main.go; ./main
|
|
```
|
|
|
|
To stop the client, use type <kbd>Ctrl-C</kbd>. To stop the server, use the
|
|
`kill $pid1` command. To stop the collector, type <kbd>Ctrl-C</kbd> in its
|
|
terminal window as well.
|
|
|
|
**Note:** The commands shown above demonstrate the process in a bash shell.
|
|
These commands may vary slightly for other shells.
|
|
|
|
[data collection]: /docs/concepts/data-collection
|
|
[deployment methods]: ../deployment
|
|
[readme.md]:
|
|
https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/examples/demo
|
|
[opentelemetry helm charts]:
|
|
https://github.com/open-telemetry/opentelemetry-helm-charts
|
|
[opentelemetry operator]:
|
|
https://github.com/open-telemetry/opentelemetry-operator
|
|
[getting started with opentelemetry on hashicorp nomad]:
|
|
https://github.com/hashicorp/nomad-open-telemetry-getting-started
|
|
[macos releases]:
|
|
https://github.com/open-telemetry/opentelemetry-collector-releases/releases
|
|
[windows releases]:
|
|
https://github.com/open-telemetry/opentelemetry-collector-releases/releases
|