Install using the Tarball

This guide describes how to install the Particle Horizon pho-collector on Linux using the .tar.gz archives.

pho-collector is a standalone OpenTelemetry Collector distribution.

Supported Linux architectures

Release archives are produced for:

The archive contains the following runtime layout:

particle_horizon/
├── SOFTWARE/
│   └── pho-collector-<version>-linux-<arch>/
│       ├── BUILD_INFO.txt
│       ├── THIRDPARTY_NOTICES
│       └── bin/
│           └── pho-collector
├── pho-collector --> SOFTWARE/pho-collector-<version>-linux-<arch>/bin/pho-collector
├── local_config/
│   └── pho-collector/
│       ├── config.yaml
│       └── pho-collector.conf
├── local_data/
│   └── pho-collector/
└── logs/
    └── pho-collector/

The intended installation root on Linux is:

/opt/particle_horizon

Prerequisites

This guide assumes that you have already acquired and placed the archive on the target machine.

The installation commands in this guide require:

• a supported 64-bit Linux system;
• tar;
• systemd if the collector will be installed as a system service;
• sudo or root access to install under /opt.

You can check the current system architecture with:

uname -m

Typical results are:

x86_64

or:

aarch64

1. Extract the archive

Create a temporary extraction directory:

INSTALL_TMP="$(mktemp -d)"

Extract the release:

tar -xzf "${ARCHIVE}" -C "${INSTALL_TMP}"

Inspect the contents:

find "${INSTALL_TMP}/particle_horizon" -maxdepth 4 -print

2. Create the service account

When running pho-collector as a system service, create a dedicated system account:

sudo useradd \
  --system \
  --home-dir /opt/particle_horizon \
  --shell /usr/sbin/nologin \
  pho-collector

If the account already exists, useradd will report that condition and no further action is required.

You can confirm the account with:

getent passwd pho-collector

3. Install the collector

Create the installation directory:

sudo mkdir -p /opt/particle_horizon

Copy the contents of the extracted particle_horizon directory into it:

sudo cp -a \
  "${INSTALL_TMP}/particle_horizon/." \
  /opt/particle_horizon/

The collector should now be available through the stable path:

/opt/particle_horizon/pho-collector

Check it:

/opt/particle_horizon/pho-collector --help

The stable path points at the collector binary beneath the version-specific SOFTWARE directory.

4. Set directory ownership

The collector service runs under the pho-collector user and group.

Give the service write access to its runtime data and log directories:

sudo chown -R pho-collector:pho-collector \
  /opt/particle_horizon/local_data/pho-collector \
  /opt/particle_horizon/logs/pho-collector

The configuration can remain owned by root:

sudo chown -R root:root \
  /opt/particle_horizon/local_config/pho-collector

Ensure the collector can read its configuration:

sudo chmod 0755 /opt/particle_horizon/local_config
sudo chmod 0755 /opt/particle_horizon/local_config/pho-collector
sudo chmod 0644 /opt/particle_horizon/local_config/pho-collector/config.yaml
sudo chmod 0644 /opt/particle_horizon/local_config/pho-collector/pho-collector.conf

5. Configure the collector

The default configuration is installed at:

/opt/particle_horizon/local_config/pho-collector/config.yaml

Edit it as required for the environment:

sudo vi /opt/particle_horizon/local_config/pho-collector/config.yaml

The supplied environment file is:

/opt/particle_horizon/local_config/pho-collector/pho-collector.conf

By default it contains settings equivalent to:

OTELCOL_OPTIONS="--config=/opt/particle_horizon/local_config/pho-collector/config.yaml"
GOMAXPROCS=2

Additional collector command-line options can be added to OTELCOL_OPTIONS.

For example:

OTELCOL_OPTIONS="--config=/opt/particle_horizon/local_config/pho-collector/config.yaml --set=service.telemetry.logs.level=info"

6. Test the collector manually

Before creating the service, run the collector interactively:

sudo -u pho-collector \
  /opt/particle_horizon/pho-collector \
  --config=/opt/particle_horizon/local_config/pho-collector/config.yaml

If the configuration is valid, the collector should start and begin initialising its configured receivers, processors, exporters, extensions, and pipelines.

Stop the interactive process with Ctrl+C.

7. Install the systemd service

Create:

/etc/systemd/system/pho-collector.service

with the following content:

[Unit]
Description=Particle Horizon Collector
After=network.target

[Service]
EnvironmentFile=/opt/particle_horizon/local_config/pho-collector/pho-collector.conf
ExecStart=/opt/particle_horizon/pho-collector $OTELCOL_OPTIONS
ExecReload=/bin/kill -HUP $MAINPID
KillMode=mixed
Restart=on-failure
Type=simple
User=pho-collector
Group=pho-collector
WorkingDirectory=/opt/particle_horizon

[Install]
WantedBy=multi-user.target

For example:

sudo tee /etc/systemd/system/pho-collector.service >/dev/null <<'EOF'
[Unit]
Description=Particle Horizon Collector
After=network.target

[Service]
EnvironmentFile=/opt/particle_horizon/local_config/pho-collector/pho-collector.conf
ExecStart=/opt/particle_horizon/pho-collector $OTELCOL_OPTIONS
ExecReload=/bin/kill -HUP $MAINPID
KillMode=mixed
Restart=on-failure
Type=simple
User=pho-collector
Group=pho-collector
WorkingDirectory=/opt/particle_horizon

[Install]
WantedBy=multi-user.target
EOF

Reload systemd:

sudo systemctl daemon-reload

Enable the collector at boot:

sudo systemctl enable pho-collector

Start it:

sudo systemctl start pho-collector

8. Verify the service

Check the service state:

sudo systemctl status pho-collector

A healthy installation should show:

Active: active (running)

Follow the systemd journal with:

sudo journalctl -u pho-collector -f

You can also inspect the installed binary:

readlink -f /opt/particle_horizon/pho-collector

This should resolve to a version-specific path similar to:

/opt/particle_horizon/SOFTWARE/pho-collector-1.2.3-linux-amd64/bin/pho-collector

Upgrading

The archive layout keeps the executable beneath a version-specific directory while exposing a stable path at:

/opt/particle_horizon/pho-collector

This makes upgrades possible without replacing the existing version directory.

Before upgrading to v0.4.0

Collector v0.4.0 no longer includes the JMX receiver. Check the active configuration for jmx receiver instances before stopping the existing service:

grep -nE '^[[:space:]]*jmx(/[^:]+)?:' \
  /opt/particle_horizon/local_config/pho-collector/config.yaml

If the command returns a receiver, remove that receiver and every pipeline reference to it, or arrange an alternative JMX collection method. The v0.4.0 Collector cannot start while its configuration references the removed component.

Validate the complete configuration with the new binary before switching the stable executable path or starting the system service.

1. Download and extract the new version

Follow the procedure above for the new release.

2. Stop the collector

sudo systemctl stop pho-collector

3. Back up the current configuration

Because the archive contains a default config.yaml, preserve the site’s existing configuration before copying the new archive:

sudo cp \
  /opt/particle_horizon/local_config/pho-collector/config.yaml \
  /opt/particle_horizon/local_config/pho-collector/config.yaml.bak

If pho-collector.conf has been customised, back that up as well:

sudo cp \
  /opt/particle_horizon/local_config/pho-collector/pho-collector.conf \
  /opt/particle_horizon/local_config/pho-collector/pho-collector.conf.bak

4. Install the new archive

Copy the new particle_horizon tree into /opt:

sudo cp -a \
  "${INSTALL_TMP}/particle_horizon/." \
  /opt/particle_horizon/

5. Restore or merge configuration

Restore the site’s configuration if required:

sudo cp \
  /opt/particle_horizon/local_config/pho-collector/config.yaml.bak \
  /opt/particle_horizon/local_config/pho-collector/config.yaml

Where a release introduces configuration changes, merge the previous site configuration into the newly supplied configuration instead of restoring it blindly.

6. Start the new version

sudo systemctl start pho-collector

Verify it:

sudo systemctl status pho-collector

and:

readlink -f /opt/particle_horizon/pho-collector

Once the new release has been validated, older directories beneath:

/opt/particle_horizon/SOFTWARE/

can be removed if they are no longer required for rollback.

Uninstalling

Stop and disable the service:

sudo systemctl disable --now pho-collector

Remove the service definition:

sudo rm -f /etc/systemd/system/pho-collector.service
sudo systemctl daemon-reload

Remove the application:

sudo rm -rf /opt/particle_horizon

Optionally remove the service account:

sudo userdel pho-collector

File locations