Quick Start

This guide gets you from an installed Particle Horizon Collector to a running Collector that can receive OpenTelemetry telemetry.

The Particle Horizon Collector is a standalone OpenTelemetry Collector distribution. It supports standard OpenTelemetry receivers and pipelines, together with Particle Horizon components for supported products and platforms.

Audience: Customers installing, configuring, or operating the Particle Horizon Collector. This guide focuses on normal product use rather than building the Collector from source.

Before you begin

Before starting, make sure:

You have a supported Particle Horizon Collector package or archive for your operating system.
You have sufficient permissions to install and manage the Collector service.
The host can reach any systems from which telemetry will be collected.
The host can reach your required telemetry destination.
Any required firewall rules have been configured.
You have any credentials, certificates, or licence files required by the components you intend to enable.

For Linux package installations, the Collector is installed beneath:

/opt/particle_horizon/

The standard runtime layout separates the installed software from customer configuration, local data, and logs.

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

The pho-collector path points to the currently installed Collector software.

1. Install the Collector

Use the installation package supplied for your platform.

Linux releases can be distributed as:

.deb
.rpm
.tar.gz

Windows releases are distributed as .zip archives.

Debian or Ubuntu

Install the supplied .deb package:

sudo apt install ./pho-collector-<version>.deb

RHEL-compatible Linux

Install the supplied .rpm package:

sudo dnf install ./pho-collector-<version>.rpm

After a package installation, the Collector runs as the dedicated:

pho-collector

user and group.

2. Find the configuration

The main Collector configuration file is:

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

The packaged systemd service starts the Collector with this file automatically.

The configuration follows the standard OpenTelemetry Collector structure:

extensions:
  ...

receivers:
  ...

processors:
  ...

exporters:
  ...

service:
  pipelines:
    ...

A pipeline connects:

Receiver → Processor → Exporter

For example:

Application
    │
    │ OTLP
    ▼
Particle Horizon Collector
    │
    ├── Receiver
    │
    ├── Processor
    │
    └── Exporter
    │
    ▼
Observability Platform

3. Start with the default configuration

The supplied default configuration provides a simple working Collector.

It enables OTLP reception using:

3. Start with the default configuration
Protocol	Default port
OTLP/gRPC	`4317`
OTLP/HTTP	`4318`

It also exposes Collector metrics locally on port 8888.

The default configuration contains pipelines for:

traces
metrics
logs

A simplified example is:

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
      http:
        endpoint: 0.0.0.0:4318

processors:
  batch:

exporters:
  debug:
    verbosity: detailed

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [debug]

    metrics:
      receivers: [otlp]
      processors: [batch]
      exporters: [debug]

    logs:
      receivers: [otlp]
      processors: [batch]
      exporters: [debug]

The packaged default configuration uses the debug exporter, making it suitable for confirming that telemetry is reaching the Collector before you configure your production destination.

4. Check your network binding

The example configuration listens on all interfaces:

endpoint: 0.0.0.0:4317

and:

endpoint: 0.0.0.0:4318

Where remote applications must send telemetry to the Collector, these listeners must be reachable from the relevant systems.

Where remote access is not required, restrict listeners to an appropriate network interface rather than 0.0.0.0.

The default configuration itself recommends restricting listener addresses where possible to reduce unnecessary network exposure.

5. Start the Collector

On Linux:

sudo systemctl start pho-collector

To configure it to start automatically after a reboot:

sudo systemctl enable pho-collector

You can perform both actions together with:

sudo systemctl enable --now pho-collector

The packaged service is configured to start after the network becomes available and automatically restart following a failure.

6. Check that the Collector is running

Check service status:

sudo systemctl status pho-collector

A healthy service should report:

Active: active (running)

You can also check the running process:

ps -ef | grep pho-collector

The packaged systemd service runs:

/opt/particle_horizon/pho-collector

using the configuration defined in pho-collector.conf.

7. View Collector logs

For a systemd installation, view recent logs with:

sudo journalctl -u pho-collector

Follow the logs in real time with:

sudo journalctl -u pho-collector -f

When using the default configuration, successfully received telemetry is sent to the debug exporter.

You should therefore see telemetry-related output after an application starts sending data.

8. Send telemetry to the Collector

Configure your OpenTelemetry-enabled application or agent to send telemetry to the Collector host.

For OTLP/gRPC:

http://<collector-host>:4317

For OTLP/HTTP:

http://<collector-host>:4318

Replace:

<collector-host>

with the hostname or IP address of the Particle Horizon Collector.

For example:

http://phocol01.example.com:4318

The default Collector configuration accepts OTLP traces, metrics, and logs.

9. Confirm telemetry is arriving

After configuring a telemetry source, monitor the Collector:

sudo journalctl -u pho-collector -f

With the default debug exporter enabled, received telemetry should appear in the Collector output.

This gives you a simple first test:

Application
    │
    │ OTLP :4317 / :4318
    ▼
Particle Horizon Collector
    │
    ▼
Debug output

If telemetry appears, the basic Collector installation and receiver configuration are working.

10. Configure your production exporter

The default debug exporter is intended for initial validation.

For normal operation, configure the exporter required by your environment.

A typical production pipeline becomes:

Application
    │
    ▼
Receiver
    │
    ▼
Processor
    │
    ▼
Exporter
    │
    ▼
Observability Platform

For example:

service:
  pipelines:
    metrics:
      receivers:
        - otlp
      processors:
        - batch
      exporters:
        - <your_exporter>

Refer to the documentation for your telemetry destination for its required endpoint, authentication, and TLS settings.

Do not place passwords, tokens, or other secrets directly into configuration files where avoidable. Use your organisation’s approved secret-management mechanism.

11. Using Particle Horizon receivers

Particle Horizon distributions can include custom components for supported technologies.

For example, the Particle Horizon component repository contains receivers for environments including:

DACS
VisualEdge

The DACS receiver can collect supported metrics from PostgreSQL and local DACS sources, while the VisualEdge receiver collects installation, version, availability, and licence information from a local VisualEdge installation.

An example DACS configuration uses:

receivers:
  dacsreceiver:
    postgres:
      enabled: true
      endpoint: "postgresql://dacs-db.internal:5432/dacs"
      username: "${env:DACS_DB_USER}"
      password: "${env:DACS_DB_PASSWORD}"
      collection_interval: 30s
      timeout: 10s

The component example deliberately stores the username and password in environment variables rather than directly in the YAML configuration.

Some Particle Horizon components also require a valid Particle Horizon licence before they will start. The component repository currently documents licence enforcement for the DACS and VisualEdge receivers.

For component-specific configuration, use the relevant product or receiver guide rather than enabling every available receiver.

12. Restart after configuration changes

After modifying:

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

restart the Collector:

sudo systemctl restart pho-collector

Then confirm its status:

sudo systemctl status pho-collector

And review the startup logs:

sudo journalctl -u pho-collector -n 100

Configuration errors normally appear during startup.

Basic troubleshooting

Collector does not start

Check:

sudo systemctl status pho-collector

Then inspect the logs:

sudo journalctl -u pho-collector -n 100

Common causes include:

invalid YAML
incorrectly named components
a receiver referenced in a pipeline but not configured
an exporter referenced in a pipeline but not configured
invalid credentials
inaccessible source systems
missing licence files
a network port already being used

Applications cannot connect to the Collector

Confirm the OTLP ports are listening:

ss -lntp | grep -E '4317|4318'

Then verify:

the Collector service is running
the correct Collector hostname is being used
the required receiver is enabled
host and network firewalls permit the traffic
routing between the application and Collector is available

No telemetry appears

Check the complete path:

Telemetry source
      │
      ▼
Receiver
      │
      ▼
Pipeline
      │
      ▼
Exporter

Verify that:

The application is generating telemetry.
The application points to the correct Collector endpoint.
The receiver appears in the correct pipeline.
The pipeline contains the expected exporter.
The exporter destination is reachable.
Required credentials and licences are valid.

A DACS receiver will not start

When using PostgreSQL-backed DACS collection, the receiver validates database connectivity during startup.

If startup fails, check:

database hostname
database port
database name
username
password
firewall rules
routing
required licence entitlement

The component documentation notes that PostgreSQL connection failures are treated as startup failures rather than allowing the receiver to continue without connectivity.

Quick Start checklist

Next steps

Once the basic Collector is running, continue with:

What is the Collector — understand the role of the Particle Horizon Collector.
Architecture — understand where Collectors sit within your environment.
Agents vs. Gateways — decide where your Collectors should run.
Networking Requirements — configure the required communication paths.
Build Your First Configuration — create a configuration for your environment.
Receiver Guides — enable collection from specific supported technologies.

A successful Quick Start should leave you with the following working path:

Telemetry Source
       │
       │ OTLP
       ▼
Particle Horizon Collector
       │
       │ configured pipeline
       ▼
Telemetry Destination

Services

Documentation

Technical support

Collector

Quick Start

Before you begin

1. Install the Collector

Debian or Ubuntu

RHEL-compatible Linux

2. Find the configuration

3. Start with the default configuration

4. Check your network binding

5. Start the Collector

6. Check that the Collector is running

7. View Collector logs

8. Send telemetry to the Collector

9. Confirm telemetry is arriving

10. Configure your production exporter

11. Using Particle Horizon receivers

12. Restart after configuration changes

Basic troubleshooting

Collector does not start

Applications cannot connect to the Collector

No telemetry appears

A DACS receiver will not start

Quick Start checklist

Next steps