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.

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:

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:

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.