Skip to main content

​
Sshcheck Receiver

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

​
Supported Telemetry

Metrics

​
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

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:
  sshcheck:
    endpoint: localhost:2222
    username: otelu
    password: $OTELP
    collection_interval: 60s
SSH check with key file authentication: 
receivers:
  sshcheck:
    endpoint: sftp.example.com:22
    username: monitoring
    key_file: /path/to/private_key
    collection_interval: 60s
SSH check with SFTP monitoring enabled: 
receivers:
  sshcheck:
    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:
  sshcheck:
    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: [sshcheck]
      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:
  sshcheck:
    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:
  1. Using the check_sftp option (enables SFTP status and duration metrics):
receivers:
  sshcheck:
    check_sftp: true
  1. By enabling SFTP metrics individually:
receivers:
  sshcheck:
    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:
  sshcheck:
    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:
  sshcheck:
    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:
  sshcheck:
    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.

​
Limitations and 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 NameTypeDescriptionUnitEnabled by Default
sshcheck.durationGaugeMeasures the duration of SSH connectionmsYes
sshcheck.statusSum1 if SSH client successfully connected, otherwise 01Yes
sshcheck.errorSumRecords errors occurring during SSH check{error}Yes
sshcheck.sftp_durationGaugeMeasures SFTP request durationmsNo
sshcheck.sftp_statusSum1 if SFTP server replied to request, otherwise 01No
sshcheck.sftp_errorSumRecords 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 NameDescriptionUnitTypeAttributes
✅ sshcheck.durationMeasures the duration of SSH connection.msGauge
✅ sshcheck.errorRecords errors occurring during SSH check.{error}UpDownCountererror.message
❌ sshcheck.sftp_durationMeasures SFTP request duration.msGauge
❌ sshcheck.sftp_errorRecords errors occurring during SFTP check.{error}UpDownCountererror.message
❌ sshcheck.sftp_status1 if the SFTP server replied to request, otherwise 0.1UpDownCounter
✅ sshcheck.status1 if the SSH client successfully connected, otherwise 0.1UpDownCounter

​
Attributes

Attribute NameDescriptionTypeValues
error.messageError message recorded during checkstring

​
Resource Attributes

Attribute NameDescriptionTypeEnabled
ssh.endpointFull SSH endpointstring❌

​
Configuration

​
Example Configuration

receivers:
  sshcheck:
    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: [sshcheck]
     processors: [nop]
     exporters: [nop]
Last generated: 2026-04-13