chronyreceiver

README

Chrony Receiver

Status
Stability	beta: metrics
Distributions	contrib
Issues
Code coverage
Code Owners	@MovieStoreGuy, @jamesmoessis

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 for more details.

Configuration

Default

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

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:

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:

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

Index

• func NewFactory() receiver.Factory
• type Config
  • func (c *Config) Validate() error

Functions

func NewFactory

func NewFactory() receiver.Factory

Types

type Config

type Config struct {
	scraperhelper.ControllerConfig `mapstructure:",squash"`
	metadata.MetricsBuilderConfig  `mapstructure:",squash"`
	// Endpoint is the published address or unix socket
	// that allows clients to connect to:
	// The allowed format is:
	//   unix:///path/to/chronyd/unix.sock
	//   udp://localhost:323
	//
	// The default value is unix:///var/run/chrony/chronyd.sock
	Endpoint string `mapstructure:"endpoint"`

	// FileMountPath is the directory where the receiver creates a random
	// unixgram reply socket.
	// Use it only when the collector and chronyd run in different network
	// namespaces but share a filesystem volume.
	// This directory should be dedicated to chronyd and the collector.
	// Prefer an ephemeral mount because ungraceful exits can leave stale socket
	// files behind.
	// When empty, Go's default abstract socket autobind is used (same-namespace only).
	// Example: /run/chrony
	FileMountPath string `mapstructure:"file_mount_path"`
	// contains filtered or unexported fields
}

func (*Config) Validate

func (c *Config) Validate() error