# Build your first configuration This guide walks you through creating your first Particle Horizon Collector configuration. By the end of this guide, you will have a working configuration that: - starts the Particle Horizon Collector; - receives OpenTelemetry data; - processes telemetry in batches; - writes telemetry to the Collector log for initial testing; and - can be extended with Particle Horizon receivers such as DACS and VisualEdge. The Particle Horizon Collector is built on the OpenTelemetry Collector. Its configuration therefore follows the standard OpenTelemetry model of **receivers**, **processors**, **exporters**, **extensions**, and **pipelines**. ## Before you begin You should already have the Particle Horizon Collector installed on the server where you want to run it. On a packaged Linux installation, the runtime configuration is stored beneath: ``` /opt/particle_horizon/local_config/pho-collector/config.yaml ``` The standard release layout also provides dedicated locations for the application binaries, local data and logs. > **Note** > > The exact location may differ if your organisation has deployed the Collector using a customised installation method. * * * ## Understanding a Collector configuration A typical configuration contains five main sections: ``` extensions: receivers: processors: exporters: service: ``` Each section has a different purpose.
Understanding a Collector configuration
SectionPurpose
receiversDefines where telemetry enters the Collector.
processorsDefines what happens to telemetry before it leaves the Collector.
exportersDefines where the Collector sends telemetry.
extensionsEnables additional Collector capabilities that do not form part of a telemetry pipeline.
serviceConnects the configured components together into pipelines.
A component does not become active simply because it appears elsewhere in the configuration. Receivers, processors and exporters must be referenced by a pipeline under `service.pipelines`. * * * # 1\. Create a basic configuration Start with the following configuration: ``` extensions: health_check: 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] extensions: [health_check] ``` Save the file as: ``` config.yaml ``` This is a useful first configuration because it does not require an external monitoring platform. Applications can send telemetry to the Collector using OTLP, and the Collector writes the received information to its own log using the `debug` exporter. * * * # 2\. Configure the receiver The first part of the configuration defines an OTLP receiver: ``` receivers: otlp: protocols: grpc: endpoint: 0.0.0.0:4317 http: endpoint: 0.0.0.0:4318 ``` OTLP is the standard OpenTelemetry protocol. This configuration allows applications to send telemetry using either:
2. Configure the receiver
ProtocolDefault port
OTLP/gRPC4317
OTLP/HTTP4318
For example, an OpenTelemetry-enabled application using OTLP/gRPC could send telemetry to: ``` collector.example.com:4317 ``` An application using OTLP/HTTP could use: ``` http://collector.example.com:4318 ``` ## Binding to network interfaces The example listens on: ``` 0.0.0.0 ``` This means that the receiver is available on all network interfaces. For production environments, consider binding the Collector to a specific interface or IP address where appropriate. For example: ``` receivers: otlp: protocols: grpc: endpoint: 10.10.20.15:4317 http: endpoint: 10.10.20.15:4318 ``` Restricting the listening interface can reduce unnecessary network exposure. * * * # 3\. Add a processor Processors operate on telemetry between a receiver and an exporter. For your first configuration, use the `batch` processor: ``` processors: batch: ``` The batch processor groups telemetry together before passing it to the exporter. This reduces the number of individual export operations and is suitable for most Collector deployments. Processors only operate when they are added to a pipeline. For example: ``` processors: [batch] ``` * * * # 4\. Add an exporter An exporter defines the destination for telemetry. For your first configuration, use the debug exporter: ``` exporters: debug: verbosity: detailed ``` Instead of forwarding the telemetry to another monitoring platform, this exporter writes received telemetry to the Collector log. This makes it useful while building and testing your first configuration. > **Important** > > The debug exporter is intended primarily for testing and troubleshooting. A production configuration would normally export telemetry to your organisation’s observability platform instead. * * * # 5\. Build your pipelines The `service` section connects your receivers, processors and exporters. Particle Horizon supports the standard OpenTelemetry signal types: - metrics; - logs; and - traces. Our example creates a pipeline for each: ``` service: pipelines: traces: receivers: [otlp] processors: [batch] exporters: [debug] metrics: receivers: [otlp] processors: [batch] exporters: [debug] logs: receivers: [otlp] processors: [batch] exporters: [debug] ``` You can read each pipeline from left to right. For example: ``` OTLP receiver | v Batch processor | v Debug exporter ``` For the metrics pipeline, this means: ``` metrics: receivers: [otlp] processors: [batch] exporters: [debug] ``` Telemetry enters through `otlp`, is processed by `batch`, and is then sent to `debug`. * * * # 6\. Enable the health check Extensions provide additional Collector functionality outside the normal telemetry pipeline. A useful extension for a first deployment is: ``` extensions: health_check: ``` It must also be enabled under the service: ``` service: extensions: [health_check] ``` Extensions that are configured but not listed under `service.extensions` are not started. * * * # 7\. Your completed basic configuration Your complete configuration should now look like this: ``` extensions: health_check: 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] extensions: [health_check] ``` At this point you have a complete OpenTelemetry configuration. * * * # 8\. Start the Collector Start or restart the Particle Horizon Collector using the method appropriate to your installation. For a service-managed Linux installation, this will normally involve restarting the installed `pho-collector` service. After starting the Collector, check its service status and logs. A successful startup should not contain configuration validation errors. If an application sends telemetry to ports `4317` or `4318`, the debug exporter should produce corresponding telemetry entries in the Collector logs. * * * # 9\. Add Particle Horizon components Once the basic configuration is working, you can begin replacing or supplementing the generic OTLP receiver with Particle Horizon receivers. Particle Horizon currently includes proprietary components such as: - `dacsreceiver`; - `visualedgereceiver`; and - the `pho_license` extension. Licensed Particle Horizon receivers require a valid Particle Horizon licence and the `pho_license` extension to be enabled. A licence extension configuration looks similar to: ``` extensions: pho_license: file: /etc/otelcol/license.json reporting_interval: 1h warning_thresholds_days: [30, 14, 7] ``` Then enable it: ``` service: extensions: [pho_license] ``` If you already use another extension, list both: ``` service: extensions: - health_check - pho_license ``` > **Important** > > Your licence must contain sufficient entitlement for each licensed receiver you enable. * * * # 10\. Example: collect DACS metrics The `dacsreceiver` can collect DACS operational metrics from supported sources. One supported source is PostgreSQL. A minimal PostgreSQL example is: ``` extensions: pho_license: file: /etc/otelcol/license.json receivers: dacsreceiver: postgres: enabled: true endpoint: "postgresql://dacs-db.example.com:5432/dacs" username: "${env:DACS_DB_USER}" password: "${env:DACS_DB_PASSWORD}" collection_interval: 30s timeout: 10s soap: enabled: false processors: batch: exporters: debug: verbosity: detailed service: extensions: - pho_license pipelines: metrics: receivers: - dacsreceiver processors: - batch exporters: - debug ``` Replace: ``` dacs-db.example.com ``` with the hostname or IP address of your DACS PostgreSQL server. ## Store credentials outside the configuration The example deliberately uses environment variables: ``` username: "${env:DACS_DB_USER}" password: "${env:DACS_DB_PASSWORD}" ``` Configure those values in the service environment rather than placing passwords directly into `config.yaml`. Avoid configurations such as: ``` password: "MyDatabasePassword123" ``` Keeping credentials outside the Collector configuration makes the configuration easier to manage securely and reduces the chance of credentials being exposed in configuration backups, repositories or support bundles. * * * # 11\. Example: collect local DACS server metrics Particle Horizon can also collect metrics directly from DACS processes by running the DACS `set_debug` utility. For example: ``` receivers: dacsreceiver: postgres: enabled: false soap: enabled: false dacs_svr: enabled: true tool_path: /reuters/dacs/tools/set_debug collection_interval: 60s timeout: 15s ``` This type of collection requires the Collector to run on the relevant DACS server. The executable must be: ``` set_debug ``` The default path is: ``` /reuters/dacs/tools/set_debug ``` The Collector service account must also have permission to execute the tool. Several DACS processes can be monitored independently, including:
11. Example: collect local DACS server metrics
Configuration blockDACS process
dacs_svrdacs_svr
dacs_stndacs.stnd
dacs_espdacs.esp
dacs_scp_mainscp_main
dacs_snkddacs.snkd
dacs_wanldacs.wanl
dacs_wanrdacs.wanr
Only enable the components that exist on the server where the Collector is installed. * * * # 12\. Choose additional DACS metric groups The host-local DACS receivers deliberately enable only a subset of metrics by default. Additional metric groups can be enabled when required. For example: ``` receivers: dacsreceiver: postgres: enabled: false soap: enabled: false dacs_svr: enabled: true tool_path: /reuters/dacs/tools/set_debug collection_interval: 60s timeout: 15s groups: ping_status: enabled: true ``` This enables the `ping_status` metric group in addition to the receiver’s default DACS server metrics. Do not copy group names between different DACS component blocks unless that group is documented as being supported by both. Unknown group names are rejected when the Collector validates its configuration. * * * # 13\. Example: collect VisualEdge metrics If Particle Horizon is installed on a VisualEdge server, you can configure the VisualEdge receiver. For example: ``` extensions: pho_license: file: /etc/otelcol/license.json receivers: visualedgereceiver: collection_interval: 30s timeout: 10s ui_dir: /opt/VisualEdge/server/webapps/ROOT/VisualEdgeUI gui_version_file: /opt/VisualEdge/server/webapps/ROOT/VisualEdgeUI/VisualEdgeGUIVersion.txt servlet_lib_dir: /opt/VisualEdge/server/webapps/ROOT/VisualEdgeServlet/WEB-INF/lib mosaicoapi_jar: /opt/VisualEdge/server/webapps/ROOT/VisualEdgeServlet/WEB-INF/lib/MosaicOAPI-jar-with-dependencies.jar license_file: /opt/VisualEdge/licence.txt processors: batch: exporters: debug: service: extensions: - pho_license pipelines: metrics: receivers: - visualedgereceiver processors: - batch exporters: - debug ``` The paths must match your VisualEdge installation. The receiver can report information including: ``` visualedge.installation.available visualedge.release.info visualedge.licence.info visualedge.licence.days_remaining ``` * * * # 14\. Combine multiple receivers A pipeline can contain more than one receiver. For example, the following metrics pipeline accepts application OTLP metrics and collects DACS and VisualEdge metrics: ``` service: pipelines: metrics: receivers: - otlp - dacsreceiver - visualedgereceiver processors: - batch exporters: - debug ``` All three sources feed the same processing and export pipeline: ``` OTLP -----------------\ \ DACS -------------------> batch ---> debug / VisualEdge ------------/ ``` This is one of the advantages of the Collector model: different telemetry sources can use a common processing and export path. * * * # 15\. Validate configuration changes safely When changing a configuration, make one logical change at a time. A recommended workflow is: 1. Save a copy of the known-working configuration. 2. Add or modify one receiver, processor or exporter. 3. Check YAML indentation. 4. Restart the Collector. 5. Check the Collector service status. 6. Review the Collector logs for configuration or connection errors. 7. Confirm that the expected telemetry is being produced. 8. Continue with the next change. This makes troubleshooting considerably easier than introducing several new components simultaneously. * * * # 16\. Common configuration problems ## Collector does not start after editing YAML YAML uses indentation to represent structure. For example, this is valid: ``` receivers: otlp: protocols: grpc: ``` Incorrect indentation can prevent the Collector from loading its configuration. Use spaces rather than tabs. * * * ## Receiver is configured but nothing is collected Check that the receiver is actually referenced by a pipeline. For example, configuring: ``` receivers: dacsreceiver: ``` is not sufficient. It must also appear in a pipeline: ``` service: pipelines: metrics: receivers: - dacsreceiver ``` * * * ## DACS PostgreSQL receiver fails during startup When PostgreSQL collection is enabled, Particle Horizon validates database connectivity when the receiver starts. Check: - the PostgreSQL hostname; - port `5432`, if using the default PostgreSQL port; - database name; - username and password; - DNS resolution; - firewall rules; and - routing between the Collector and database. The endpoint must also be configured whenever PostgreSQL collection is enabled. * * * ## DACS local metrics do not appear For host-local DACS collection, check: ``` /reuters/dacs/tools/set_debug ``` or the custom path specified in `tool_path`. Also confirm that: - the Collector is running on the appropriate DACS server; - the expected DACS process is running; - the Collector service account can execute `set_debug`; and - the command completes before the configured timeout. If a host-local scrape fails, Particle Horizon does not publish a synthetic healthy value. Metrics from that source become absent until the source recovers. Monitoring rules should therefore consider missing data when checking the availability of these components. * * * ## Receiver reports that it is not licensed Confirm that the `pho_license` extension is configured: ``` extensions: pho_license: file: /etc/otelcol/license.json ``` and enabled: ``` service: extensions: - pho_license ``` Your Particle Horizon licence must also provide entitlement for the receiver you are attempting to start. * * * ## VisualEdge reports missing files Verify all configured VisualEdge paths: ``` ui_dir: gui_version_file: servlet_lib_dir: mosaicoapi_jar: license_file: ``` The VisualEdge receiver reports bounded status values such as: ``` ok missing_path missing_file parse_error ``` These can help identify which part of the local installation could not be read. * * * # 17\. Moving beyond the debug exporter Once you have confirmed that telemetry is being collected successfully, the next step is normally to replace the `debug` exporter with the exporter used by your monitoring platform. Your current pipeline: ``` metrics: receivers: - dacsreceiver processors: - batch exporters: - debug ``` might eventually become: ``` Receiver | v Processors | v Production observability platform ``` Particle Horizon includes a broad selection of standard OpenTelemetry Collector exporters, allowing the same receiver configuration to be integrated with different observability platforms. Your Particle Horizon deployment documentation or implementation team should provide the exporter configuration appropriate for your environment. * * * # Configuration checklist Before considering your first configuration complete, verify the following: - The Collector starts without configuration errors. - Every configured receiver is referenced by the appropriate pipeline. - The `batch` processor is enabled in the required pipelines. - The debug exporter receives telemetry during initial testing. - Network listeners are restricted appropriately for your environment. - Credentials are supplied using environment variables or another approved secret-management mechanism. - The `pho_license` extension is enabled when using licensed Particle Horizon components. - Your licence includes entitlement for each proprietary receiver being used. - DACS database connectivity has been tested where PostgreSQL collection is enabled. - The Collector can execute `set_debug` where host-local DACS monitoring is enabled. - VisualEdge file paths match the local installation where VisualEdge monitoring is enabled. - Collector logs have been reviewed after the final restart. * * * # Next steps Once your first configuration is working, you can extend it gradually. Typical next steps include: 1. enabling additional Particle Horizon receivers; 2. selecting additional DACS metric groups; 3. adding resource or attribute processors; 4. configuring memory limits and batching for production workloads; 5. replacing the debug exporter with your production telemetry destination; 6. enabling authentication or transport encryption where required; and 7. adding monitoring for the Particle Horizon Collector itself. Start with the smallest configuration that solves your immediate monitoring requirement and add components as your deployment grows.