Linux Installation

Install the OpenTelemetry Collector as a systemd service on Linux.

Prerequisites

• Linux (Debian, Ubuntu, RHEL, CentOS, Amazon Linux, SUSE)
• curl and tar commands
• Root/sudo access
• Coralogix Send-Your-Data API key

Quick Start

Run the following command to install the collector with default configuration:

CORALOGIX_PRIVATE_KEY="<your-private-key>" \
  bash -c "$(curl -sSL https://github.com/coralogix/telemetry-shippers/releases/latest/download/coralogix-otel-collector.sh)"

Environment Variables

Required Variables

Automatically Set Variables

The installer automatically sets these environment variables for the collector service:

Variable	Default	Description
OTEL_MEMORY_LIMIT_MIB	512	Memory limit in MiB (set via --memory-limit flag)
OTEL_LISTEN_INTERFACE	127.0.0.1	Network interface for receivers (set via --listen-interface flag)

To use these in your configuration file:

processors:
  memory_limiter:
    limit_mib: ${env:OTEL_MEMORY_LIMIT_MIB:-512}

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: ${env:OTEL_LISTEN_INTERFACE:-127.0.0.1}:4317

Supported Platforms

Linux Distributions

• Debian, Ubuntu
• RHEL, CentOS, Fedora
• Amazon Linux, Amazon Linux 2023
• Rocky Linux, AlmaLinux, Oracle Linux
• SUSE Linux Enterprise Server, openSUSE

Architectures

• x86_64 (amd64)
• ARM64 (aarch64)

Install with Custom Configuration

To install with your own configuration file:

CORALOGIX_PRIVATE_KEY="<your-private-key>" \
  bash -c "$(curl -sSL https://github.com/coralogix/telemetry-shippers/releases/latest/download/coralogix-otel-collector.sh)" \
  -- --config /path/to/config.yaml

Install Specific Version

CORALOGIX_PRIVATE_KEY="<your-private-key>" \
  bash -c "$(curl -sSL https://github.com/coralogix/telemetry-shippers/releases/latest/download/coralogix-otel-collector.sh)" \
  -- --version 0.140.1

Install with Custom Memory Limit

Allocate more memory to the collector (useful for high-volume environments):

CORALOGIX_PRIVATE_KEY="<your-private-key>" \
  bash -c "$(curl -sSL https://github.com/coralogix/telemetry-shippers/releases/latest/download/coralogix-otel-collector.sh)" \
  -- --memory-limit 2048

Note: Your configuration must reference ${env:OTEL_MEMORY_LIMIT_MIB} for this to take effect.

Install as Gateway (Listen on All Interfaces)

By default, the collector listens only on 127.0.0.1 (localhost). To accept connections from other hosts (gateway mode):

CORALOGIX_PRIVATE_KEY="<your-private-key>" \
  bash -c "$(curl -sSL https://github.com/coralogix/telemetry-shippers/releases/latest/download/coralogix-otel-collector.sh)" \
  -- --listen-interface 0.0.0.0

Note: Your configuration must reference ${env:OTEL_LISTEN_INTERFACE} for this to take effect.

Install with Custom Memory and Network Settings

CORALOGIX_PRIVATE_KEY="<your-private-key>" \
  bash -c "$(curl -sSL https://github.com/coralogix/telemetry-shippers/releases/latest/download/coralogix-otel-collector.sh)" \
  -- --memory-limit 2048 --listen-interface 0.0.0.0

Service Discovery

The installer supports automatic service discovery for databases and services (PostgreSQL, MySQL, Redis, MongoDB, NGINX, Apache, RabbitMQ, Memcached, Elasticsearch, Kafka, and Cassandra).

When discovery is enabled in your configuration, the installer will: - Create a credentials file template (/etc/otelcol-contrib/discovery.env) - Automatically enable Linux capabilities (required for discovery to work)

Configure Discovery Credentials

After installation, edit the credentials file:

sudo nano /etc/otelcol-contrib/discovery.env

Uncomment and set your credentials:

# PostgreSQL
POSTGRES_USER=postgres
POSTGRES_PASSWORD=your_password
POSTGRES_DB=postgres

# MySQL
MYSQL_USER=root
MYSQL_PASSWORD=your_password

# Redis
REDIS_PASSWORD=your_password

Then restart the service:

sudo systemctl restart otelcol-contrib

Alternatively, set environment variables before installation:

POSTGRES_PASSWORD="your_password" \
CORALOGIX_PRIVATE_KEY="<your-private-key>" \
  bash -c "$(curl -sSL https://github.com/coralogix/telemetry-shippers/releases/latest/download/coralogix-otel-collector.sh)"

Linux Capabilities

Linux capabilities (CAP_SYS_PTRACE, CAP_DAC_READ_SEARCH) are required for: - Service discovery: To identify processes on listening ports - Process metrics: To read detailed process information (CPU, memory, disk I/O)

Automatic Enablement

Capabilities are automatically enabled based on your installation mode:

Regular Mode: - Capabilities are automatically enabled when: - Service discovery is detected in your configuration - Process metrics are detected in your configuration

Supervisor Mode: - Capabilities are enabled by default - Use --disable-capabilities flag to opt-out:

CORALOGIX_DOMAIN="<your-domain>" CORALOGIX_PRIVATE_KEY="<your-private-key>" \
  bash -c "$(curl -sSL https://github.com/coralogix/telemetry-shippers/releases/latest/download/coralogix-otel-collector.sh)" \
  -- --supervisor --disable-capabilities

Security Note: Capabilities are granted only to the collector binary using Linux capabilities, avoiding the need to run as root. This is a secure, opt-in mechanism.

Supervisor Mode

Supervisor mode enables remote configuration management through Coralogix Fleet Management:

CORALOGIX_DOMAIN="<your-domain>" CORALOGIX_PRIVATE_KEY="<your-private-key>" \
  bash -c "$(curl -sSL https://github.com/coralogix/telemetry-shippers/releases/latest/download/coralogix-otel-collector.sh)" \
  -- --supervisor

Supervisor Mode Features

• Automatic capabilities: Linux capabilities are enabled by default to support service discovery and process metrics when added via Fleet Manager (use --disable-capabilities to opt-out)
• Discovery credentials: Configure credentials in /etc/opampsupervisor/opampsupervisor.conf for discovered services
• Installation summary: View installation details and useful commands in /etc/opampsupervisor/INSTALLATION_SUMMARY.txt

Script Options

Note: --memory-limit sets the OTEL_MEMORY_LIMIT_MIB environment variable. Your configuration must reference ${env:OTEL_MEMORY_LIMIT_MIB} for this to take effect.

Note: --listen-interface sets the OTEL_LISTEN_INTERFACE environment variable. Your configuration must reference ${env:OTEL_LISTEN_INTERFACE} for this to take effect.

Installation Locations

Regular Mode

Supervisor Mode

Service Management

Regular Mode

# Check status
sudo systemctl status otelcol-contrib

# View logs
sudo journalctl -u otelcol-contrib -f

# Restart
sudo systemctl restart otelcol-contrib

# Validate config
/usr/bin/otelcol-contrib validate --config /etc/otelcol-contrib/config.yaml

Supervisor Mode

# Check status
sudo systemctl status opampsupervisor

# View logs
sudo journalctl -u opampsupervisor -f
tail -f /var/log/opampsupervisor/opampsupervisor.log

# Restart
sudo systemctl restart opampsupervisor

Uninstall

Remove the collector while keeping configuration and logs:

bash coralogix-otel-collector.sh --uninstall

Remove the collector and all data:

bash coralogix-otel-collector.sh --uninstall --purge

Configuration Behavior

Environment Variables in Configuration

The installer automatically sets OTEL_MEMORY_LIMIT_MIB and OTEL_LISTEN_INTERFACE environment variables for the collector service. To use them in your custom configuration:

• Memory Limiter: limit_mib: ${env:OTEL_MEMORY_LIMIT_MIB:-512}
• Receiver Endpoint: endpoint: ${env:OTEL_LISTEN_INTERFACE:-127.0.0.1}:4317

The installer will warn you if you specify --memory-limit or --listen-interface but your configuration doesn't reference these variables.

Troubleshooting

Service fails to start

1. Check status: sudo systemctl status otelcol-contrib
2. Check logs: sudo journalctl -u otelcol-contrib -n 50
3. Validate config: /usr/bin/otelcol-contrib validate --config /etc/otelcol-contrib/config.yaml

Switching between modes

Uninstall before switching between regular and supervisor modes:

bash coralogix-otel-collector.sh --uninstall --purge
CORALOGIX_DOMAIN="<your-domain>" CORALOGIX_PRIVATE_KEY="<your-private-key>" bash coralogix-otel-collector.sh --supervisor