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

Variable	Required	Description
CORALOGIX_PRIVATE_KEY	Yes	Your Coralogix Send-Your-Data API key
CORALOGIX_DOMAIN	Supervisor mode only	Your Coralogix domain

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

Enable Comprehensive Process Metrics

By default, the collector may not have permissions to read detailed process metrics (CPU, memory, disk I/O) for all processes. Use the --enable-process-metrics flag to grant the necessary Linux capabilities:

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

This grants CAP_SYS_PTRACE and CAP_DAC_READ_SEARCH capabilities to the collector binary, allowing it to: - Read /proc/[pid]/io for all processes (disk I/O metrics) - Access process information for all users (not just the collector user)

Security Note: This is a secure, opt-in mechanism that avoids running the collector as root. The capabilities are granted only to the collector binary using Linux capabilities.

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

Script Options

Option	Description
`-v, --version <version>`	Install specific collector version
`-c, --config <path>`	Path to custom configuration file
`-s, --supervisor`	Install with OpAMP Supervisor mode (Linux only)
`-u, --upgrade`	Upgrade existing installation (preserves config)
`--memory-limit <MiB>`	Total memory in MiB to allocate to the collector (default: 512) (ignored in supervisor mode)
`--listen-interface <ip>`	Network interface for receivers to listen on (default: 127.0.0.1). Use `0.0.0.0` for all interfaces (gateway mode)
`--enable-process-metrics`	Grant Linux capabilities for comprehensive process metrics collection
`--supervisor-version <version>`	Supervisor version (supervisor mode only)
`--collector-version <version>`	Collector version (supervisor mode only)
`--uninstall`	Remove the collector (keeps config)
`--uninstall --purge`	Remove the collector and all configuration
`-h, --help`	Show help message

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

Component	Location
Binary	`/usr/bin/otelcol-contrib`
Configuration	`/etc/otelcol-contrib/config.yaml`
Service	`otelcol-contrib.service` (systemd)
Logs	`journalctl -u otelcol-contrib`

Supervisor Mode

Component	Location
Collector Binary	`/usr/local/bin/otelcol-contrib`
Supervisor Config	`/etc/opampsupervisor/config.yaml`
Effective Config	`/var/lib/opampsupervisor/effective.yaml`
Service	`opampsupervisor.service` (systemd)
Logs	`/var/log/opampsupervisor/opampsupervisor.log`

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

Upgrade

Upgrade the collector while preserving your existing configuration:

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

To upgrade and replace the configuration:

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

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

Scenario	Action
Fresh install	Creates default empty config
Config exists	Preserves existing config
With `--config`	Uses provided config
Upgrade (`--upgrade`)	Preserves existing config
Supervisor mode	Config managed remotely via OpAMP

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

Check status: sudo systemctl status otelcol-contrib
Check logs: sudo journalctl -u otelcol-contrib -n 50
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

Previous Getting Started

Next macOS

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)