macOS Installation

Install the OpenTelemetry Collector on macOS as a LaunchDaemon (system-wide) or LaunchAgent (user-level).

Prerequisites

• macOS (Intel or Apple Silicon)
• curl and tar commands
• Root/sudo access
• Coralogix Send-Your-Data API key

Quick Start

Run the following command to install the collector with a 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)" \
  -- -c /path/to/config.yaml

Environment Variables

Required Variables

Variable	Required	Description
CORALOGIX_PRIVATE_KEY	Yes	Your Coralogix Send-Your-Data API key
CORALOGIX_MACOS_USER_AGENT	No	Set to true to install as user-level LaunchAgent (default: system-wide LaunchDaemon)

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

Supervisor mode is supported as a system-wide LaunchDaemon. It does not support the user-level LaunchAgent mode.

macOS LaunchAgent (User-Level)

Install as a user-level agent that runs at login (instead of system-wide at boot):

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

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)" \
  -- -c /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)" \
  -- -c /path/to/config.yaml --version 0.140.1

Install with Custom Memory Limit

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

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

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

Script Options

Option	Description
-v, --version <version>	Install specific collector version
-c, --config <path>	Path to custom configuration file
--memory-limit <MiB>	Total memory in MiB to allocate to the collector (default: 512)
--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)
--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

Component	LaunchDaemon (system-wide)	LaunchAgent (user-level)
Binary	/usr/local/bin/otelcol-contrib	/usr/local/bin/otelcol-contrib
Configuration	/etc/otelcol-contrib/config.yaml	/etc/otelcol-contrib/config.yaml
Plist	/Library/LaunchDaemons/com.coralogix.otelcol.plist	~/Library/LaunchAgents/com.coralogix.otelcol.plist
Logs	/var/log/otel-collector/otel-collector.log	~/Library/Logs/otel-collector/otel-collector.log

Service Management

LaunchDaemon (System-Wide)

# Check status
sudo launchctl list | grep otelcol

# View logs
tail -f /var/log/otel-collector/otel-collector.log

# Restart
sudo launchctl bootout system /Library/LaunchDaemons/com.coralogix.otelcol.plist
sudo launchctl bootstrap system /Library/LaunchDaemons/com.coralogix.otelcol.plist

LaunchAgent (User-Level)

# Check status
launchctl list | grep otelcol

# View logs
tail -f ~/Library/Logs/otel-collector/otel-collector.log

# Restart
launchctl bootout gui/$(id -u) ~/Library/LaunchAgents/com.coralogix.otelcol.plist
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.coralogix.otelcol.plist

Uninstall

Remove the collector while keeping configuration and logs:

bash -c "$(curl -fsSL https://github.com/coralogix/telemetry-shippers/releases/latest/download/coralogix-otel-collector.sh)" -- --uninstall

Remove the collector and all data:

bash -c "$(curl -fsSL https://github.com/coralogix/telemetry-shippers/releases/latest/download/coralogix-otel-collector.sh)" -- --uninstall --purge

Configuration Behavior

Scenario	Action
Fresh install	Creates default empty config
Config exists	Preserves existing config
Auto-upgrade	Preserves existing config

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 plist exists: ls -la /Library/LaunchDaemons/com.coralogix.otelcol.plist
2. Check logs: tail -f /var/log/otel-collector/otel-collector.log
3. Validate config: /usr/local/bin/otelcol-contrib validate --config /etc/otelcol-contrib/config.yaml