# MosaicOA PE Receiver

The MosaicOA PE Receiver monitors a MosaicOA PE status endpoint and emits OpenTelemetry metrics. It can optionally add gateway information obtained from InfluxDB v2.

<table><caption class="sr-only">MosaicOA PE Receiver</caption><thead><tr><th scope="col">Property</th><th scope="col">Value</th></tr></thead><tbody><tr><td>Component ID</td><td><code>mosaicoapereceiver</code></td></tr><tr><td>Type</td><td>Receiver</td></tr><tr><td>Signal</td><td>Metrics</td></tr><tr><td>Availability</td><td>PHO Collector distribution</td></tr></tbody></table>

## Capabilities

-   Polls the MosaicOA PE status endpoint.
-   Reports topic records and polls.
-   Reports xPath, update, Dataview, CIMP, garbage-collection, and memory information.
-   Preserves release and status context as OpenTelemetry resource attributes.
-   Optionally reports comma-containing InfluxDB column-tag values for configured gateways.
-   Supports HTTPS, private certificate authorities, and mutual TLS.

## Prerequisites

-   Network access to the MosaicOA PE status endpoint.
-   TLS trust material when HTTPS uses a private certificate authority.
-   Optional network and query access to InfluxDB v2.
-   A PHO licence containing a `mosaicoapereceiver` entitlement.

## Status endpoint configuration

<table><caption class="sr-only">Status endpoint configuration</caption><thead><tr><th scope="col">Setting</th><th scope="col">Required</th><th scope="col">Default</th><th scope="col">Description</th></tr></thead><tbody><tr><td><code>host</code></td><td>Yes</td><td>—</td><td>MosaicOA PE hostname or IP address</td></tr><tr><td><code>scheme</code></td><td>No</td><td><code>https</code></td><td><code>http</code> or <code>https</code></td></tr><tr><td><code>port</code></td><td>No</td><td><code>443</code></td><td>Status endpoint port</td></tr><tr><td><code>path</code></td><td>No</td><td><code>/status</code></td><td>Status endpoint path</td></tr><tr><td><code>timeout</code></td><td>No</td><td><code>10s</code></td><td>Request timeout</td></tr><tr><td><code>collection_interval</code></td><td>No</td><td><code>30s</code></td><td>Collection frequency</td></tr><tr><td><code>tls.ca_file</code></td><td>No</td><td>System trust</td><td>Private CA certificate</td></tr><tr><td><code>tls.cert_file</code></td><td>No</td><td>—</td><td>Client certificate</td></tr><tr><td><code>tls.key_file</code></td><td>No</td><td>—</td><td>Client private key</td></tr><tr><td><code>tls.insecure_skip_verify</code></td><td>No</td><td><code>false</code></td><td>Disables certificate verification; not recommended</td></tr></tbody></table>

The client certificate and private key must be supplied together.

## Optional InfluxDB configuration

<table><caption class="sr-only">Optional InfluxDB configuration</caption><thead><tr><th scope="col">Setting</th><th scope="col">Required when enabled</th><th scope="col">Default</th><th scope="col">Description</th></tr></thead><tbody><tr><td><code>influx.enabled</code></td><td>—</td><td><code>false</code></td><td>Enables gateway tag monitoring</td></tr><tr><td><code>influx.endpoint</code></td><td>Yes</td><td>—</td><td>Absolute InfluxDB URL</td></tr><tr><td><code>influx.org</code></td><td>Yes</td><td>—</td><td>InfluxDB organisation</td></tr><tr><td><code>influx.bucket</code></td><td>Yes</td><td>—</td><td>InfluxDB bucket</td></tr><tr><td><code>influx.gateways</code></td><td>Yes</td><td>—</td><td>Gateways to monitor</td></tr><tr><td><code>influx.token</code></td><td>No</td><td>—</td><td>InfluxDB API token</td></tr><tr><td><code>influx.lookback</code></td><td>No</td><td><code>90m</code></td><td>Query lookback period</td></tr><tr><td><code>influx.timeout</code></td><td>No</td><td><code>30s</code></td><td>Query timeout</td></tr><tr><td><code>influx.tls.*</code></td><td>No</td><td>—</td><td>TLS settings for InfluxDB</td></tr></tbody></table>

## Example

```
extensions:
  pho_license:
    file: /etc/otelcol/license.json

receivers:
  mosaicoapereceiver:
    scheme: https
    host: mosaicoa-pe.example.com
    port: 8443
    path: /status
    timeout: 10s
    collection_interval: 30s
    tls:
      ca_file: /etc/otelcol/mosaicoa-ca.pem
      insecure_skip_verify: false
    influx:
      enabled: true
      endpoint: https://influxdb.example.com:8086
      org: CJC
      bucket: EVENT/EVENT
      token: ${env:INFLUX_TOKEN}
      gateways: [GATEWAY-1, GATEWAY-2]
      lookback: 90m
      timeout: 30s

processors:
  batch: {}

exporters:
  otlp:
    endpoint: telemetry-gateway.example.com:4317

service:
  extensions: [pho_license]
  pipelines:
    metrics:
      receivers: [mosaicoapereceiver]
      processors: [batch]
      exporters: [otlp]
```

Use an environment variable or an approved secrets manager for the InfluxDB token.

## Telemetry

<table><caption class="sr-only">Telemetry</caption><thead><tr><th scope="col">Metric</th><th scope="col">Unit</th><th scope="col">Description</th></tr></thead><tbody><tr><td><code>mosaicoa.pe.topic.records</code></td><td><code>1</code></td><td>Records reported for each MosaicOA topic</td></tr><tr><td><code>mosaicoa.pe.topic.polls</code></td><td><code>1</code></td><td>Polls reported for each MosaicOA topic</td></tr><tr><td><code>mosaicoa.pe.xpaths.total</code></td><td><code>1</code></td><td>Total xPaths</td></tr><tr><td><code>mosaicoa.pe.summary_xpaths.total</code></td><td><code>1</code></td><td>Total summary xPaths</td></tr><tr><td><code>mosaicoa.pe.updates.total</code></td><td><code>1</code></td><td>Total updates</td></tr><tr><td><code>mosaicoa.pe.dataviews.total</code></td><td><code>1</code></td><td>Total Dataviews</td></tr><tr><td><code>mosaicoa.pe.mods</code></td><td><code>1</code></td><td>MODS status value</td></tr><tr><td><code>mosaicoa.pe.cimp.points_written</code></td><td><code>1</code></td><td>CIMP points written</td></tr><tr><td><code>mosaicoa.pe.gc.avg_time</code></td><td><code>ms</code></td><td>Average garbage-collection time</td></tr><tr><td><code>mosaicoa.pe.heap.memory.usage</code></td><td><code>By</code></td><td>Heap memory usage</td></tr><tr><td><code>mosaicoa.pe.non_heap.memory.usage</code></td><td><code>By</code></td><td>Non-heap memory usage</td></tr><tr><td><code>mosaicoa.pe.influx.comma_tag_values</code></td><td><code>1</code></td><td>Matching InfluxDB tag values per configured gateway</td></tr></tbody></table>

Topic metrics carry the `mosaicoa.topic` attribute. The InfluxDB metric carries `Gateway`.

The following resource attributes provide additional context:

-   `mosaicoa.pe.version`
-   `mosaicoa.pe.generation_time`
-   `mosaicoa.pe.last_reset_time`
-   `mosaicoa.pe.cimp.process_time`

## Operational behaviour

-   A status-endpoint failure affects only the current collection interval.
-   Invalid individual status rows are skipped while valid rows remain available.
-   An InfluxDB failure does not prevent status-endpoint metrics from being collected.
-   A configured gateway with no matching values reports zero.

## Troubleshooting

<table><caption class="sr-only">Troubleshooting</caption><thead><tr><th scope="col">Symptom</th><th scope="col">Recommended action</th></tr></thead><tbody><tr><td>No status metrics</td><td>Verify the host, port, path, network access, and endpoint response</td></tr><tr><td>TLS connection fails</td><td>Confirm the CA file and client-certificate settings</td></tr><tr><td>Only some metrics appear</td><td>Confirm the corresponding values are present and valid in the status response</td></tr><tr><td>InfluxDB metric is missing</td><td>Verify the endpoint, organisation, bucket, gateway names, token, and query access</td></tr><tr><td>Licence error at startup</td><td>Confirm a valid <code>mosaicoapereceiver</code> entitlement is available</td></tr></tbody></table>