> ## Documentation Index
> Fetch the complete documentation index at: https://otel.fyi/llms.txt
> Use this file to discover all available pages before exploring further.

# Chrony

> OpenTelemetry receiver for Chrony

# Chrony Receiver

![Status](https://img.shields.io/badge/status-beta-yellow)

**Available in:** `contrib`

**Maintainers:** [@MovieStoreGuy](https://github.com/MovieStoreGuy), [@jamesmoessis](https://github.com/jamesmoessis)

**Source:** [opentelemetry-collector-contrib](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/chronyreceiver)

## Supported Telemetry

![Metrics](https://img.shields.io/badge/metrics-beta-green)

## Overview

The [chrony] receiver is a pure go implementation of the command `chronyc tracking` to allow for
portability across systems and platforms. All of the data that would typically be captured by
the tracking command is made available in this receiver, see [documentation](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/chronyreceiver/documentation.md) for
more details.

## Configuration

### Default

By default, the `chrony` receiver will default to the following configuration:

```yaml theme={null}
chrony/defaults:
  endpoint: unix:///var/run/chrony/chronyd.sock # The default port by chronyd to allow cmd access
  timeout: 10s # Allowing at least 10s for chronyd to respond before giving up

chrony:
  # This will result in the same configuration as above
```

### Customised

The following options can be customised:

* endpoint (required) - the address on where to communicate to `chronyd`
  * The allowed formats are the following
    * `udp://hostname:port`
    * `unix:///path/to/chrony.sock` (Please note the triple slash)
    * `unixgram:///path/to/chrony/sock`
  * The network type `unix` will be converted to `unixgram` but both are permissible
* file\_mount\_path (optional) - the directory where the receiver creates a random Unix datagram reply socket
  * Use it only when the collector and chronyd run in separate network namespaces (for example, different containers) but share a filesystem volume
  * The directory should be dedicated to chronyd and the collector; do not share it with unrelated processes
  * Prefer an ephemeral mount because ungraceful exits can leave stale `otel-chrony-*.sock` files behind
  * When empty (default), Go's abstract socket autobind is used, which only works within the same network namespace
  * Example: `/run/chrony`
* timeout (optional) - The total amount of time allowed to read and process the data from chronyd
  * Recommendation: This value should be set above 1s to allow `chronyd` time to respond
* collection\_interval (optional) - how frequent this receiver should poll [chrony]
* `initial_delay` (default = `1s`): defines how long this receiver waits before starting.
* metrics (optional) - Which metrics should be exported, read the [documentation] for complete details

## Example

An example of the configuration is:

```yaml theme={null}
receivers:
  chrony:
    endpoint: unix:///var/run/chrony/chronyd.sock
    timeout: 10s
    collection_interval: 30s
    metrics:
      ntp.skew:
        enabled: true
      ntp.stratum:
        enabled: true
```

### Cross-Container Deployment

When the collector and chronyd run in separate containers with different Linux network namespaces
but share a filesystem volume for the Unix socket, Go's default abstract socket autobind fails
because abstract sockets are namespace-scoped. Use `file_mount_path` to place the client socket
in a shared volume.

The chronyd instance must be configured to listen on the same shared volume. In `chrony.conf`:

```
bindcmdaddress /run/chrony/chronyd.sock
```

The corresponding collector configuration:

```yaml theme={null}
receivers:
  chrony:
    endpoint: unix:///run/chrony/chronyd.sock
    file_mount_path: /run/chrony
    timeout: 10s
    collection_interval: 10s
```

Both containers must mount the `/run/chrony` directory as a shared volume. Use a directory that is
writable only by chronyd and the collector. A randomly generated socket file will be created in
`file_mount_path` and cleaned up when the collector shuts down normally. If the collector exits
ungracefully, stale `otel-chrony-*.sock` files can remain, so prefer an ephemeral shared volume.

The complete list of metrics emitted by this receiver is found in the [documentation].

[documentation]: ./documentation.md

[chrony]: https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/7/html/system_administrators_guide/ch-configuring_ntp_using_the_chrony_suite

## Metrics

| Metric Name              | Description                                                                                                            | Unit     | Type  | Attributes  |
| ------------------------ | ---------------------------------------------------------------------------------------------------------------------- | -------- | ----- | ----------- |
| ❌ `ntp.frequency.offset` | The frequency is the rate by which the system s clock would be wrong if chronyd was not correcting it.                 | ppm      | Gauge | leap.status |
| ✅ `ntp.skew`             | This is the estimated error bound on the frequency.                                                                    | ppm      | Gauge |             |
| ❌ `ntp.stratum`          | The number of hops away from the reference system keeping the reference time                                           | \{count} | Gauge |             |
| ✅ `ntp.time.correction`  | The number of seconds difference between the system's clock and the reference clock                                    | seconds  | Gauge | leap.status |
| ✅ `ntp.time.last_offset` | The estimated local offset on the last clock update                                                                    | seconds  | Gauge | leap.status |
| ❌ `ntp.time.rms_offset`  | the long term average of the offset value                                                                              | seconds  | Gauge | leap.status |
| ❌ `ntp.time.root_delay`  | This is the total of the network path delays to the stratum-1 system from which the system is ultimately synchronised. | seconds  | Gauge | leap.status |

## Attributes

| Attribute Name | Description                             | Type   | Values                                                       |
| -------------- | --------------------------------------- | ------ | ------------------------------------------------------------ |
| `leap.status`  | how the chrony is handling leap seconds | string | `normal`, `insert_second`, `delete_second`, `unsynchronised` |

## Configuration

### Example Configuration

```yaml theme={null}
chrony/custom:
  endpoint: "udp://localhost:3030"
  timeout: 10s
```

***

*Last generated: 2026-07-06*