# 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---/ │ ├── 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-.deb ``` ### RHEL-compatible Linux Install the supplied `.rpm` package: ``` sudo dnf install ./pho-collector-.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
ProtocolDefault port
OTLP/gRPC4317
OTLP/HTTP4318
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://:4317 ``` For OTLP/HTTP: ``` http://:4318 ``` Replace: ``` ``` 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: - ``` 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: 1. The application is generating telemetry. 2. The application points to the correct Collector endpoint. 3. The receiver appears in the correct pipeline. 4. The pipeline contains the expected exporter. 5. The exporter destination is reachable. 6. 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 - Install the Particle Horizon Collector package. - Locate `/opt/particle_horizon/local_config/pho-collector/config.yaml`. - Confirm the required network interfaces and ports. - Start `pho-collector`. - Confirm the service reports `active (running)`. - Configure a telemetry source to use port `4317` or `4318`. - Confirm telemetry appears through the default debug exporter. - Configure your required production exporter. - Enable any required Particle Horizon receivers. - Restart the Collector after configuration changes. - Confirm telemetry reaches the required destination. * * * ## Next steps Once the basic Collector is running, continue with: 1. **What is the Collector** — understand the role of the Particle Horizon Collector. 2. **Architecture** — understand where Collectors sit within your environment. 3. **Agents vs. Gateways** — decide where your Collectors should run. 4. **Networking Requirements** — configure the required communication paths. 5. **Build Your First Configuration** — create a configuration for your environment. 6. **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 ```