Sshcheck Receiver

Available in: contrib Maintainers: @ishaish103 Source: opentelemetry-collector-contrib

Supported Telemetry

Overview

Prerequisites

If ignore_host_key is not set then host key validation requires the agent either have a known_hosts file at a path specified by setting known_hosts or at default paths indicated by ssh man pages: $HOME/.ssh/known_hosts or /etc/ssh/known_hosts.

Configuration

Note: This receiver was renamed from sshcheck to ssh_check to match the snake_case naming convention. The deprecated component type sshcheck is still accepted as an alias and will log a deprecation warning.

The following settings are required:

endpoint
username
password or key_file

Either password or key_file must be set. But if both are set then password is treated as the passphrase and the key is assumed to be encrypted. The following settings are optional:

collection_interval (default = 60s): This receiver collects metrics on an interval. Valid time units are ns, us (or µs), ms, s, m, h.
known_hosts (default = ssh defaults): The path to the known_hosts file. If this isn’t set then default locations are checked at $HOME/.ssh/known_hosts and /etc/ssh/known_hosts.
ignore_host_key (default = false): Can override conventional ssh security for use cases like tests where authentication via the known_hosts file isn’t required.

Example Configuration

Basic SSH check with password authentication:

receivers:
  ssh_check:
    endpoint: localhost:2222
    username: otelu
    password: $OTELP
    collection_interval: 60s

SSH check with key file authentication:

receivers:
  ssh_check:
    endpoint: sftp.example.com:22
    username: monitoring
    key_file: /path/to/private_key
    collection_interval: 60s

SSH check with SFTP monitoring enabled:

receivers:
  ssh_check:
    endpoint: sftp.example.com:22
    username: monitoring
    key_file: /path/to/private_key
    check_sftp: true
    collection_interval: 60s

Production-ready configuration with processors and exporters:

receivers:
  ssh_check:
    endpoint: production-server.example.com:22
    username: monitoring
    key_file: /etc/otel/ssh_monitoring_key
    collection_interval: 30s
    timeout: 5s
    known_hosts: /etc/otel/known_hosts

processors:
  batch:
    timeout: 10s
    send_batch_size: 100

exporters:
  otlp_grpc:
    endpoint: otel-collector:4317

service:
  pipelines:
    metrics:
      receivers: [ssh_check]
      processors: [batch]
      exporters: [otlp_grpc]

The full list of settings exposed for this receiver are documented in config.go with detailed sample configurations in testdata/config.yaml.

Advanced Configuration

Timeout Configuration

The timeout option controls how long the receiver waits for an SSH connection to establish. The default is 10s. This timeout applies to both SSH and SFTP connection attempts.

receivers:
  ssh_check:
    endpoint: slow-server.example.com:22
    username: user
    password: pass
    timeout: 30s  # Increase timeout for slow connections

SFTP Check Configuration

SFTP checks can be enabled in two ways:

Using the check_sftp option (enables SFTP status and duration metrics):

receivers:
  ssh_check:
    check_sftp: true

By enabling SFTP metrics individually:

receivers:
  ssh_check:
    metrics:
      sshcheck.sftp_duration:
        enabled: true
      sshcheck.sftp_status:
        enabled: true

When check_sftp is enabled or SFTP metrics are individually enabled, the receiver will attempt to establish an SFTP connection after a successful SSH connection. Note that SFTP checks require a successful SSH connection first (see Limitations section).

Metric Enable/Disable Configuration

Individual metrics can be enabled or disabled using the metrics configuration section. By default, all SSH metrics are enabled and all SFTP metrics are disabled.

receivers:
  ssh_check:
    endpoint: localhost:2222
    username: user
    password: pass
    metrics:
      sshcheck.duration:
        enabled: true  # Default: true
      sshcheck.status:
        enabled: true  # Default: true
      sshcheck.error:
        enabled: true  # Default: true
      sshcheck.sftp_duration:
        enabled: false  # Default: false
      sshcheck.sftp_status:
        enabled: false  # Default: false
      sshcheck.sftp_error:
        enabled: false  # Default: false

See metadata.yaml for the complete list of available metrics and their default states.

Known Hosts Configuration

The known_hosts option specifies the path to the SSH known_hosts file for host key validation. If not specified, the receiver checks default locations:

$HOME/.ssh/known_hosts
/etc/ssh/known_hosts

receivers:
  ssh_check:
    endpoint: server.example.com:22
    username: user
    key_file: /path/to/key
    known_hosts: /custom/path/to/known_hosts

Security Considerations

The ignore_host_key option disables host key validation. This should only be used in test environments as it makes the connection vulnerable to man-in-the-middle attacks.

receivers:
  ssh_check:
    ignore_host_key: true  # ⚠️ Only for testing!

For production use, always configure proper host key validation using known_hosts or ensure the host key is in the default known_hosts locations.

Warnings

Security

Authentication: Passwords in configuration files should be stored securely. Consider using environment variables or secret management systems. Key file authentication is recommended for production use.

Performance

Connection Overhead: Each check creates a new SSH connection. The collection_interval should be configured based on your monitoring needs and the impact on the SSH server. More frequent checks (e.g., every 10 seconds) will create more connections.
Timeout Behavior: If a connection times out, it will be retried on the next collection interval. Ensure your timeout value is appropriate for your network conditions.

Feature Gates

This receiver does not currently use any feature gates. All functionality is available through configuration options.

Metrics

This receiver produces the following metrics:

Metric Name	Type	Description	Unit	Enabled by Default
`sshcheck.duration`	Gauge	Measures the duration of SSH connection	ms	Yes
`sshcheck.status`	Sum	1 if SSH client successfully connected, otherwise 0	1	Yes
`sshcheck.error`	Sum	Records errors occurring during SSH check	{error}	Yes
`sshcheck.sftp_duration`	Gauge	Measures SFTP request duration	ms	No
`sshcheck.sftp_status`	Sum	1 if SFTP server replied to request, otherwise 0	1	No
`sshcheck.sftp_error`	Sum	Records errors occurring during SFTP check	{error}	No

Resource Attributes

The receiver adds the following resource attribute:

ssh.endpoint: The full SSH endpoint being monitored (disabled by default, can be enabled in metadata.yaml)

Detailed Metric Documentation

Complete details about the metrics produced by this receiver, including attributes, types, and units, can be found in documentation.md and metadata.yaml.

Metrics

Metric Name	Description	Unit	Type	Attributes
✅ `sshcheck.duration`	Measures the duration of SSH connection.	ms	Gauge
✅ `sshcheck.error`	Records errors occurring during SSH check.	{error}	UpDownCounter	error.message
❌ `sshcheck.sftp_duration`	Measures SFTP request duration.	ms	Gauge
❌ `sshcheck.sftp_error`	Records errors occurring during SFTP check.	{error}	UpDownCounter	error.message
❌ `sshcheck.sftp_status`	1 if the SFTP server replied to request, otherwise 0.	1	UpDownCounter
✅ `sshcheck.status`	1 if the SSH client successfully connected, otherwise 0.	1	UpDownCounter

Attributes

Attribute Name	Description	Type	Values
`error.message`	Error message recorded during check	string

Resource Attributes

Attribute Name	Description	Type	Enabled
`ssh.endpoint`	Full SSH endpoint	string	❌

Configuration

Example Configuration

receivers:
  ssh_check:
    endpoint: notdefault:1313
    username: notdefault_username
    password: notdefault_password
    key_file: notdefault/path/keyfile
    collection_interval: 10s
    known_hosts: path/to/collector_known_hosts
    ignore_host_key: false

processors:
  nop:

exporters:
  nop:

service:
  pipelines:
    metrics:
     receivers: [ssh_check]
     processors: [nop]
     exporters: [nop]

Last generated: 2026-08-24

​Sshcheck Receiver

​Supported Telemetry

​Overview

​Prerequisites

​Configuration

​Example Configuration

​Advanced Configuration

​Timeout Configuration

​SFTP Check Configuration

​Metric Enable/Disable Configuration

​Known Hosts Configuration

​Security Considerations

​Warnings

​Security

​Performance

​Feature Gates

​Metrics

​Resource Attributes

​Detailed Metric Documentation

​Metrics

​Attributes

​Resource Attributes

​Configuration

​Example Configuration

Sshcheck Receiver

Supported Telemetry

Overview

Prerequisites

Configuration

Example Configuration

Advanced Configuration

Timeout Configuration

SFTP Check Configuration

Metric Enable/Disable Configuration

Known Hosts Configuration

Security Considerations

Warnings

Security

Performance

Feature Gates

Metrics

Resource Attributes

Detailed Metric Documentation

Metrics

Attributes

Resource Attributes

Configuration

Example Configuration