How to Install and Configure an OpenTelemetry Collector

OpenTelemetry is at the core of standardizing telemetry solutions and observIQ is focused on building the very best in open source telemetry software. Our relationship with OpenTelemetry began in 2021, with observIQ contributing our logging agent, Stanza, to the OpenTelemetry community. Now, we are shifting our focus to simplifying OpenTelemetry solutions to its large base of users. On that note, we launched a collector that combines the best of both worlds, with OpenTelemetry at its core, combined with observIQ’s functionalities to simplify its usage.

In this post, we are taking you through the installation of the observIQ distribution of the OpenTelemetry collector and the steps to configure the collector to fetch metrics from a MySQL server, eventually forwarding those metrics to Google Cloud Operations. Before we delve into the installation, here’s a quick look at the architecture of an OpenTelemetry Collector:

Broken image

• observIQ-Otel Collector: It collects the metrics fetched by the receiver, runs the processor, and forwards it to the exporter for distribution to the destination.
• Receiver: Scrapes the metrics from the source based on push or pull-based requests. The receiver is capable of fetching metrics from one or more data sources.
• Processor: Enrich the metrics data using processors. Metrics data are enriched after being received from the receiver and before being forwarded to the exporter. Although processors are optional, in some scenarios using processors is highly recommended.
• Exporter: Sends the metrics to the configured destination using push or pull-based requests. As in the case of receivers, exporters support having one or more data destinations for the metrics data.

Getting Started: Installation

Linux Installation:

• There are two ways to do the installation, a simple installation script or via deb/ rpm packages.

Prerequisites for Installation:

1. Root level permissions for manual installations
2. Download the latest deb and rpm packages

Installation Steps:

1. Visit the Releases page in the repo to download the latest version of the installation package or use the following installation script:

1sudo sh -c "$(curl -fsSlL https://github.com/observiq/observiq-otel-collector/releases/latest/download/install_unix.sh)" install_unix.sh

Broken image

2. After running the installation script, you can verify the service is running with the following command:

1systemctl status observiq-otel-collector

Broken image

3. View the logs from the collector that are logged to journalD.

1journalctl -u observiq-otel-collector.service

Broken image

Windows Installation:

• The collector is installed using the latest version of MSI available at the releases page in our repo. You may choose to install using the MSI or use the powershell command to install in quiet mode. This helps when replicating and mirroring the installation/ configuration using Ansible, Terraform etc.
• Post installation, you may start or stop the collector from Windows Service Manager

Prerequisites for Installation:

1. Administrator level permissions for manual installations
2. Download the MSI to the local drive

Installation Steps:

1. Visit the releases page in the repo to download the latest version of the MSI. Windows may ask you to change some security settings for package downloads.

2. Run the installation

3. At the end of the installation, the following is installed under C:\Program Files\observiq-otel-collector:

Broken image

4. use the command Get-Service observiq-otel-collector

Broken image

Alternatively, Open services to check if the collector is running.

Broken image

What’s installed?

• Plugins folder: This folder contains the configuration files for a host of logging configurations.
• Config.yaml: The default configuration file with default settings. Visit our repo to see a sample configuration.
• Observiq-otel-collector: The actual collector binary file.
• Opentelemetry-java-contrib-jmx-metrics: The jar file that must be used with the JMX receiver for scraping JMX metrics.

Broken image

Getting Started: Configuring the collector

Before we begin the configuration, here are some important points to note about the default configuration that is downloaded as part of the installation:

• For fetching metrics specific to certain sources, we use the configuration specific to those receivers. A list of available receivers is documented in OpenTelemetry’s repo.
• The advantage of using obersvIQ’s distribution of OpenTelemetry is in how the collector seamlessly ties in the receivers, processors, and exporters, all done using a single line installation.
• In the default config.yaml, the scraped metrics are not exported to any destination. After we configure the receiver, we must configure an exporter to specify the destination for the metrics export.

In this sample configuration, the steps to use the mysqlreceiver to fetch metrics from a MySQL database and export them to Google Cloud Operations are detailed. This is how it works:

• The collector scrapes metrics and logs from MySQL and exports them to a destination assigned in the configuration file.
• To export the metrics to Google Cloud Operations, use the configurations outlined in the googlecloudexporter

Prerequisites:

1. Have a MySQL database setup
2. Set up an OTel user in MySQL. This user needs to have select and process permissions enabled for all databases to be monitored. The configuration detailed below monitors all databases.
3. A Google cloud service account and JSON key file downloaded and saved to /opt/observiq-otel-collector

Configuration Steps:

1. Move the Google service account key to the observiq-collector folder, and change permissions.

1sudo cp ./otel-agent-dev.json /opt/observiq-otel-collector/otel-agent-dev.json
2sudo chgrp observiq-otel-collector /opt/observiq-otel-collector/otel-agent-dev.json
3sudo chown observiq-otel-collector /opt/observiq-otel-collector/otel-agent-dev.json
4sudo chmod 0640 /opt/observiq-otel-collector/otel-agent-dev.json

2. Modify the service using systemctl to include the service account information in environment

1sudo systemctl edit observiq-otel-collector

Paste the following, to include the environment variable to the service.

1[Service]
2Environment=GOOGLE_APPLICATION_CREDENTIALS=/opt/observiq-otel-collector/otel-agent-dev.json

3. Change the config.yaml with the configuration to use the mysqlreceiver and the googlecloudexporter

1receivers:
2 mysql:
3   username: otel
4   password: password
5   endpoint: localhost:3306
6processors:
7 batch:
8   send_batch_max_size: 200
9   send_batch_size: 200
10exporters:
11 googlecloud:
12   retry_on_failure:
13     enabled: false
14   project: otel-agent-dev
15service:
16 pipelines:
17   metrics:
18     receivers: [mysql]
19     processors: [batch]
20     exporters: [googlecloud]

4. Restart the collector

1systemctl restart observiq-otel-collector

Getting Started: Viewing the metrics in Google Cloud Operations

You should now be able to view the MySQL metrics in your Metrics explorer. Nice work! This is how simple it is to work with receivers and exporters in OpenTelemetry.

Broken image

Here’s a dashboard created using the metrics gathered:

Broken image

Metrics collected

observIQ’s distribution is a game-changer for companies looking to implement the OpenTelemetry standards. The single line installer, seamlessly integrated receivers, exporter, and processor pool make working with this collector simple. Follow this space to keep up with all our future posts and simplified configurations for various sources. For questions, requests, and suggestions, reach out to our support team at support@observIQ.com.

observIQ’s distribution is a game-changer for companies looking to implement the OpenTelemetry standards. The single line installer, seamlessly integrated receivers, exporter, and processor pool make working with this collector simple. Follow this space to keep up with all our future posts and simplified configurations for various sources. For questions, requests, and suggestions, reach out to our support team at support@observIQ.com.