Skip to main content
Lantern Home

 

Splunk Lantern

Running the Splunk OpenTelemetry Collector on Darwin

  1. Last updated
  2. Save as PDF

Your company runs on Darwin (Mac OS X) and you are interested in using the Splunk Distribution of the OpenTelemetry Collector and the upstream OpenTelemetry Collector on this operating system. You need configuration guidance.

Data required

OpenTelemetry

How to use Splunk software for this use case

The full configuration of the Splunk Distribution of the OpenTelemetry Collector involves manual steps to build a custom binary for Darwin (macOS) compiled for AMD64 or for ARM64. To simplify this, you can use the automation script provided below or follow the detailed manual steps.

If you want to get started without compiling software and wrangling dependencies, you can use a pre-compiled binary of the OpenTelemetry Collector, but this solution does not include the additional functionality included in the Splunk Distribution of the OpenTelemetry Collector.

Prerequisites

  • Command Line Access with sudo privileges.
  • Git, Xcode, and Xcode Developer Tools.
  • Golang. It is strongly recommended to install Golang using the official installer rather than Homebrew to ensure correct path configuration and avoid conflicts.
  • Splunk Observability Cloud credentials. You will need your Access Token and realm.

Automated setup (recommended)

The following script automates the cloning, building, configuration, and persistence (LaunchAgent) setup for the collector on macOS.

How to use:

  1. Save the code below as install_otel.sh.
  2. Make it executable: chmod +x install_otel.sh.
  3. Run the script: ./install_otel.sh.
#!/bin/bash 

 
# Ensure the script is running on macOS 
if [[ "$OSTYPE" != "darwin"* ]]; then 
    echo "ERROR: This script is intended for macOS only." 
    exit 1 
fi 

# --- 1. CONFIGURATION VARIABLES AND PROMPTS --- 
INSTALL_DIR="$HOME/Library/Application Support/splunk-otel-collector" 
CONFIG_PATH="$INSTALL_DIR/agent_config.yaml" 
BINARY_DIR="$INSTALL_DIR/bin" 
BINARY_PATH="$BINARY_DIR/otelcol" 
REPO_NAME="splunk-otel-collector" 
SERVICE_FILE="$HOME/Library/LaunchAgents/com.splunk.otel.collector.plist" 

echo "--- Splunk Configuration Required ---" 

# Check for Splunk Access Token 
if [ -z "$SPLUNK_ACCESS_TOKEN" ]; then 
    read -p "Enter your Splunk Access Token: " SPLUNK_ACCESS_TOKEN 
fi 

# Check for Splunk Realm 
if [ -z "$SPLUNK_REALM" ]; then 
    read -p "Enter your Splunk Realm (e.g., us1, eu0): " SPLUNK_REALM 
fi 

# Check for Deployment Environment 
if [ -z "$DEPLOYMENT_ENVIRONMENT" ]; then 
    read -p "Enter your Deployment Environment (e.g., production, staging): " DEPLOYMENT_ENVIRONMENT 
fi 

# Final validation 
if [ -z "$SPLUNK_ACCESS_TOKEN" ] || [ -z "$SPLUNK_REALM" ] || [ -z "$DEPLOYMENT_ENVIRONMENT" ]; then 
    echo "ERROR: Splunk Access Token, Realm, and Environment Name are required to proceed." 
    exit 1 
fi 

# Normalize Realm to lowercase 
SPLUNK_REALM=$(echo "$SPLUNK_REALM" | tr '[:upper:]' '[:lower:]') 
echo "--- Starting Splunk OpenTelemetry Collector Setup on Darwin ---" 

# --- 2. REPOSITORY HANDLING --- 
if [ -d "$REPO_NAME" ]; then 
    echo "The directory '$REPO_NAME' already exists." 
    read -p "Choose an action: [u]pdate existing, [r]e-clone (delete & start over), [s]kip clone: " repo_action 
    case $repo_action in 
        [Rr]* )  
            echo "   Removing existing directory and re-cloning..." 
            rm -rf "$REPO_NAME" 
            git clone https://github.com/signalfx/splunk-otel-collector.git || { echo "Git clone failed. Exiting."; exit 1; } 
            ;; 
        [Uu]* )  
            echo "   Updating existing repository..." 
            cd "$REPO_NAME" && git pull || { echo "Git pull failed. Exiting."; exit 1; } 
            cd .. 
            ;; 
        [Ss]* )  
            echo "   Skipping clone, using existing files." 
            ;; 
        * )  
            echo "   Invalid selection. Proceeding with existing files..." 
            ;; 
    esac 
else 
    echo "Cloning the Splunk-Otel-Collector GitHub repository..." 
    git clone https://github.com/signalfx/splunk-otel-collector.git || { echo "Git clone failed. Exiting."; exit 1; } 
fi 
 
# --- 3. BUILD PROCESS --- 
cd "$REPO_NAME" || { echo "Failed to enter directory. Exiting."; exit 1; } 

echo "Modifying Makefile to force CGO_ENABLED=1..." 
if ! grep -q "export CGO_ENABLED=1" Makefile; then 
    echo "export CGO_ENABLED=1" | cat - Makefile > Makefile.tmp && mv Makefile.tmp Makefile 
fi 
sed -i "" 's/CGO_ENABLED=0/CGO_ENABLED=1/g' Makefile 
echo "Building install-tools and otelcol..." 
make install-tools || { echo "make install-tools failed. Exiting."; exit 1; } 

# Set build environment 
export GOPATH=$HOME/go 
export GOROOT=$(go env GOROOT) 
export PATH=$PATH:$GOPATH/bin:$GOROOT/bin 
export CGO_ENABLED=1 

echo "Building the Collector binary (this may take a while)..." 
CGO_ENABLED=1 make -k || { echo "Collector build failed. Exiting."; exit 1; } 

# --- 4. INSTALLATION --- 

echo "Installing binaries to $BINARY_DIR..." 
mkdir -p "$BINARY_DIR" 
cp -R bin/* "$BINARY_DIR/" 

# --- 5. CREATE YAML CONFIGURATION --- 
echo "Creating agent_config.yaml in $INSTALL_DIR..." 
mkdir -p "$INSTALL_DIR" 

cat <<EOF > "$CONFIG_PATH" 
receivers: 
  otlp: 
    protocols: 
      grpc: 
      http: 
  hostmetrics: 
    collection_interval: 10s 
    scrapers: 
      cpu: 
      memory: 
      disk: 
      filesystem: 
      network: 
      load: 
      paging:  
      process: 
        mute_process_exe_error: true  
        mute_process_io_error: true 

processors: 
  resourcedetection: 
    detectors: [system] 
    override: false 
  resourcedetection/internal: 
    detectors: [system] 
    override: true 
  resource/add_environment: 
    attributes: 
      - action: insert 
        key: deployment.environment 
        value: ${DEPLOYMENT_ENVIRONMENT} 
  batch: 
    send_batch_size: 1000 
    timeout: 10s 

exporters: 
  signalfx: 
    access_token: ${SPLUNK_ACCESS_TOKEN} 
    realm: ${SPLUNK_REALM} 
  otlp/splunk_traces: 
    endpoint: ingest.${SPLUNK_REALM}.signalfx.com:443 
    headers: 
      "X-SF-TOKEN": ${SPLUNK_ACCESS_TOKEN} 

service: 
  pipelines: 
    traces: 
      receivers: [otlp] 
      processors: [resourcedetection, resourcedetection/internal, resource/add_environment, batch] 
      exporters: [otlp/splunk_traces] 
    metrics: 
      receivers: [hostmetrics] 
      processors: [resourcedetection, resourcedetection/internal, resource/add_environment, batch] 
      exporters: [signalfx] 
EOF 

# --- 6. MACOS SERVICE CREATION AND ACTIVATION --- 
echo "Setting up macOS LaunchAgent for persistence..." 
mkdir -p "$HOME/Library/LaunchAgents" 

cat <<EOF > "$SERVICE_FILE" 
<?xml version="1.0" encoding="UTF-8"?> 
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"> 
<plist version="1.0"> 
<dict> 
    <key>Label</key> 
    <string>com.splunk.otel.collector</string> 
    <key>ProgramArguments</key> 
    <array> 
        <string>$BINARY_PATH</string> 
        <string>--config</string> 
        <string>$CONFIG_PATH</string> 
    </array> 
    <key>RunAtLoad</key> 
    <true/> 
    <key>KeepAlive</key> 
    <true/> 
    <key>StandardOutPath</key> 
    <string>/tmp/otelcol.log</string> 
    <key>StandardErrorPath</key> 
    <string>/tmp/otelcol.log</string> 
</dict> 
</plist> 
EOF 

# Unload if already existing to apply changes 
launchctl unload "$SERVICE_FILE" 2>/dev/null 
launchctl load -w "$SERVICE_FILE" 

echo "--- Splunk OpenTelemetry Collector Setup Complete ---" 
echo "SUCCESS: macOS Service started as a LaunchAgent." 
echo "INFO: Configuration: $CONFIG_PATH" 
echo "INFO: Logs: /tmp/otelcol.log"

Manual steps

  1. Clone the Splunk-Otel-Collector GitHub repository. 
    git clone https://github.com/signalfx/splunk-otel-collector.git
  2. Change to the Splunk-Otel-Collector directory. 
    cd splunk-otel-collector
  3. Open the makefile using a text editor. Locate the otelcol section and modify to ensure CGO_ENABLED=1 is present. 
  4. Build the Darwin package. 
    make install-tools
make otelcol
  5. Validate your Go installation paths.
    which go
# Expected: /usr/local/go/bin/go
  6. Set environment variables for Golang. Add these to your ~/.zshrc for persistence.
    export GOPATH=$HOME/go
export GOROOT=$(go env GOROOT)
export PATH=$PATH:$GOPATH/bin:$GOROOT/bin
  7. Apply the environment changes.
    source ~/.zshrc
  8. Install the addlicense Golang package.
    go install github.com/google/addlicense@latest
  9. Run make addlicence.
    make addlicense
  10. Build the collector.
    make -k
  11. Install the binary by creating the directory and copying the built binary.
    mkdir -p "$HOME/Library/Application Support/splunk-otel-collector/bin"
cp -R bin/* "$HOME/Library/Application Support/splunk-otel-collector/bin/"
  12. Set the required environment variables. Export these in your terminal or add them to your ~/.zshrc:
    • SPLUNK_ACCESS_TOKEN: Your Splunk Observability Cloud ingest token.
    • SPLUNK_REALM: Your Splunk realm (for example, us1).
    • DEPLOYMENT_ENVIRONMENT: Your environment tag (for example, prod).
  13. Create the agent_config.yaml file. Create the file in ~/Library/Application Support/splunk-otel-collector/ using the following configuration:
    receivers: 
  otlp: 
    protocols: 
      grpc: 
      http: 
  hostmetrics: 
    collection_interval: 10s 
    scrapers: 
      cpu: 
      memory: 
      disk: 
      filesystem: 
      network: 
      load: 
      paging:  
      process: 
        mute_process_exe_error: true 
        mute_process_io_error: true 

processors: 
  resourcedetection: 
    detectors: [system] 
    override: false 
  resourcedetection/internal: 
    detectors: [system] 
    override: true 
  resource/add_environment: 
    attributes: 
      - action: insert 
        key: deployment.environment 
        value: ${DEPLOYMENT_ENVIRONMENT} 
  batch: 
    send_batch_size: 1000 
    timeout: 10s 

exporters: 
  signalfx: 
    access_token: ${SPLUNK_ACCESS_TOKEN} 
    realm: ${SPLUNK_REALM} 
  otlp/splunk_traces: 
    endpoint: ingest.${SPLUNK_REALM}.signalfx.com:443 
    headers: 
      "X-SF-TOKEN": ${SPLUNK_ACCESS_TOKEN} 

service: 
  pipelines: 
    traces: 
      receivers: [otlp] 
      processors: [resourcedetection, resourcedetection/internal, resource/add_environment, batch] 
      exporters: [otlp/splunk_traces] 
    metrics: 
      receivers: [hostmetrics] 
      processors: [resourcedetection, resourcedetection/internal, resource/add_environment, batch] 
      exporters: [signalfx]
  14. Start the collector.
    cd "$HOME/Library/Application Support/splunk-otel-collector/bin" 
./otelcol --config="../agent_config.yaml"
  15. Set network permissions. Click Allow on the macOS network prompt.
  16. Validate the data. Check Infrastructure > My Data Center > Hosts in Splunk Observability Cloud.

Additional resources

  • Splunk GitHub: Official agent_config.yaml reference
  • Endpoints: Note that endpoints are migrating to observability.splunkcloud.com at sometime in the future.
  • Log path examples:
    • /Library/Logs
    • /var/log/system.log