# PHO Licence Extension

The PHO Licence Extension validates the licence used by PHO Collector components and reports licence health through Collector self-telemetry.

<table><caption class="sr-only">PHO Licence Extension</caption><thead><tr><th scope="col">Property</th><th scope="col">Value</th></tr></thead><tbody><tr><td>Component ID</td><td><code>pho_license</code></td></tr><tr><td>Type</td><td>Extension</td></tr><tr><td>Availability</td><td>PHO Collector distribution</td></tr></tbody></table>

## Capabilities

-   Loads a PHO-provided licence from a file or environment-supplied value.
-   Confirms that the licence applies to the current host.
-   Checks component entitlements and configured capacity.
-   Revalidates the licence periodically.
-   Reports licence validity and expiry telemetry.
-   Logs licence state changes and expiry warnings.

## Prerequisites

-   A PHO Collector distribution containing `pho_license`.
-   A valid PHO-provided licence for the current host.
-   Sufficient licensed capacity for every configured PHO receiver instance.
-   Read permission for the Collector service account when a licence file is used.

## Configuration

Exactly one licence source must be configured:

-   `file`: path to a PHO-provided licence file.
-   `inline`: base64-encoded licence content, normally supplied through an environment variable or secrets manager.

<table><caption class="sr-only">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>file</code></td><td>One source required</td><td>—</td><td>Licence-file path</td></tr><tr><td><code>inline</code></td><td>One source required</td><td>—</td><td>Base64-encoded licence content</td></tr><tr><td><code>reporting_interval</code></td><td>No</td><td><code>1h</code></td><td>Reload and validation frequency</td></tr><tr><td><code>warning_thresholds_days</code></td><td>No</td><td><code>[30, 14, 7]</code></td><td>Expiry-warning thresholds</td></tr></tbody></table>

Warning thresholds must be positive, unique, and in descending order. Use an empty list to disable expiry warnings.

### File-based example

```
extensions:
  pho_license:
    file: /etc/otelcol/license.json
    reporting_interval: 1h
    warning_thresholds_days: [30, 14, 7]

service:
  extensions: [pho_license]
```

### Environment-based example

```
extensions:
  pho_license:
    inline: ${env:PHO_LICENSE_B64}
    reporting_interval: 1h
    warning_thresholds_days: [30, 14, 7]

service:
  extensions: [pho_license]
```

Defining the extension does not enable it. It must also appear under `service.extensions`.

## Licence telemetry

Licence metrics are exposed through the Collector’s self-telemetry configuration.

<table><caption class="sr-only">Licence telemetry</caption><thead><tr><th scope="col">Metric</th><th scope="col">Type</th><th scope="col">Description</th></tr></thead><tbody><tr><td><code>pho.license.valid</code></td><td>Gauge</td><td><code>1</code> when the licence is valid; otherwise <code>0</code></td></tr><tr><td><code>pho.license.days_remaining</code></td><td>Gauge</td><td>Whole days remaining before expiry</td></tr><tr><td><code>pho.license.expiry_timestamp</code></td><td>Gauge</td><td>Licence expiry as a Unix timestamp</td></tr><tr><td><code>pho.license.check.success</code></td><td>Counter</td><td>Successful licence checks</td></tr><tr><td><code>pho.license.check.failure</code></td><td>Counter</td><td>Failed or expired licence checks</td></tr></tbody></table>

Prometheus exporters typically expose dotted metric names with underscores, for example `pho_license_valid`.

Licence telemetry excludes customer identifiers, licence identifiers, host identity, licence contents, signatures, fingerprints, source paths, and raw validation errors.

## Recommended alerts

```
groups:
  - name: pho-license
    rules:
      - alert: PHOLicenseInvalid
        expr: pho_license_valid == 0
        for: 5m
        labels:
          severity: critical
        annotations:
          summary: PHO licence is invalid or expired

      - alert: PHOLicenseExpiringSoon
        expr: pho_license_days_remaining <= 30 and pho_license_days_remaining > 0
        for: 15m
        labels:
          severity: warning
        annotations:
          summary: PHO licence expires within 30 days
```

## Operational behaviour

-   The licence is checked during Collector startup.
-   Licence status is refreshed at the configured reporting interval.
-   Expiry warnings are logged when a configured threshold is entered.
-   Repeated checks within the same threshold do not generate duplicate warnings.
-   A missing, invalid, expired, or host-mismatched licence prevents licensed receivers from starting.
-   Each configured receiver instance uses one entitlement from the relevant component capacity.

## 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>Licence-source configuration is rejected</td><td>Configure exactly one of <code>file</code> or <code>inline</code></td></tr><tr><td>Licence file is missing</td><td>Confirm the path, mount, and Collector service-account permissions</td></tr><tr><td>Licence is reported as invalid</td><td>Confirm the file has not been altered and was issued for the current host</td></tr><tr><td>Licence is expired</td><td>Contact PHO for a renewed licence</td></tr><tr><td>Receiver reports insufficient capacity</td><td>Confirm the licence includes enough capacity for all configured instances</td></tr><tr><td>Licence telemetry is absent</td><td>Confirm Collector self-telemetry metrics are enabled and exported</td></tr></tbody></table>