ssh exporter

CHANGELOG.md

@@ -20,6 +20,8 @@ Main (unreleased)
 
 - Add `otelcol.receiver.solace` component to receive traces from a Solace broker. (@wildum)
 
+- Added `prometheus.exporter.ssh` custom metrics via ssh for remote hosts. (@EHSchmitt4395)
+
 ### Enhancements
 
 - Add second metrics sample to the support bundle to provide delta information (@dehaansa)
@@ -33,7 +35,7 @@ Main (unreleased)
 
 - Fixed an issue in the `otelcol.processor.attribute` component where the actions `delete` and `hash` could not be used with the `pattern` argument. (@wildum)
 
-- Fixed a race condition that could lead to a deadlock when using `import` statements, which could lead to a memory leak on `/metrics` endpoint of an Alloy instance. (@thampiotr) 
+- Fixed a race condition that could lead to a deadlock when using `import` statements, which could lead to a memory leak on `/metrics` endpoint of an Alloy instance. (@thampiotr)
 
 ### Other changes
 
@@ -86,7 +88,7 @@ v1.5.0
 - Add support for relative paths to `import.file`. This new functionality allows users to use `import.file` blocks in modules
   imported via `import.git` and other `import.file`. (@wildum)
 
-- `prometheus.exporter.cloudwatch`: The `discovery` block now has a `recently_active_only` configuration attribute 
+- `prometheus.exporter.cloudwatch`: The `discovery` block now has a `recently_active_only` configuration attribute
   to return only metrics which have been active in the last 3 hours.
 
 - Add Prometheus bearer authentication to a `prometheus.write.queue` component (@freak12techno)
@@ -99,9 +101,9 @@ v1.5.0
 
 - Fixed a bug in `import.git` which caused a `"non-fast-forward update"` error message. (@ptodev)
 
-- Do not log error on clean shutdown of `loki.source.journal`. (@thampiotr) 
+- Do not log error on clean shutdown of `loki.source.journal`. (@thampiotr)
 
-- `prometheus.operator.*` components: Fixed a bug which would sometimes cause a 
+- `prometheus.operator.*` components: Fixed a bug which would sometimes cause a
   "failed to create service discovery refresh metrics" error after a config reload. (@ptodev)
 
 ### Other changes
@@ -140,7 +142,7 @@ v1.4.3
 
 - `pyroscope.scrape` no longer tries to scrape endpoints which are not active targets anymore. (@wildum @mattdurham @dehaansa @ptodev)
 
-- Fixed a bug with `loki.source.podlogs` not starting in large clusters due to short informer sync timeout. (@elburnetto-intapp) 
+- Fixed a bug with `loki.source.podlogs` not starting in large clusters due to short informer sync timeout. (@elburnetto-intapp)
 
 - `prometheus.exporter.windows`: Fixed bug with `exclude` regular expression config arguments which caused missing metrics. (@ptodev)
 
@@ -159,7 +161,7 @@ v1.4.2
   - Fix parsing of the Level configuration attribute in debug_metrics config block
   - Ensure "optional" debug_metrics config block really is optional
 
-- Fixed an issue with `loki.process` where `stage.luhn` and `stage.timestamp` would not apply 
+- Fixed an issue with `loki.process` where `stage.luhn` and `stage.timestamp` would not apply
   default configuration settings correctly (@thampiotr)
 
 - Fixed an issue with `loki.process` where configuration could be reloaded even if there

docs/sources/reference/compatibility/_index.md

@@ -106,6 +106,7 @@ The following components, grouped by namespace, _export_ Targets.
 - [prometheus.exporter.snmp](../components/prometheus/prometheus.exporter.snmp)
 - [prometheus.exporter.snowflake](../components/prometheus/prometheus.exporter.snowflake)
 - [prometheus.exporter.squid](../components/prometheus/prometheus.exporter.squid)
+- [prometheus.exporter.ssh](../components/prometheus/prometheus.exporter.ssh)
 - [prometheus.exporter.statsd](../components/prometheus/prometheus.exporter.statsd)
 - [prometheus.exporter.unix](../components/prometheus/prometheus.exporter.unix)
 - [prometheus.exporter.windows](../components/prometheus/prometheus.exporter.windows)

docs/sources/reference/components/prometheus/prometheus.exporter.ssh.md

@@ -0,0 +1,205 @@
+---
+canonical: https://grafana.com/docs/alloy/latest/reference/components/prometheus/prometheus.exporter.ssh/
+aliases:
+  - ../prometheus.exporter.ssh/ # /docs/alloy/latest/reference/components/prometheus.exporter.ssh/
+description: Learn about prometheus.exporter.ssh
+title: prometheus.exporter.ssh
+---
+
+# prometheus.exporter.ssh
+
+The `prometheus.exporter.ssh` component embeds an SSH exporter for collecting metrics from remote servers over SSH and exporting them as Prometheus metrics.
+
+## Usage
+
+```
+prometheus.exporter.ssh "LABEL" {
+  // Configuration options
+}
+```
+
+## Arguments
+
+The following arguments can be used to configure the exporter's behavior.
+All arguments are optional unless specified. Omitted fields take their default values.
+
+| Name              | Type     | Description                                        | Default | Required |
+| ----------------- | -------- | -------------------------------------------------- | ------- | -------- |
+| `verbose_logging` | `bool`   | Enable verbose logging for debugging purposes.     | `false` | no       |
+| `targets`         | `block`  | One or more target configurations for SSH metrics. |         | yes      |
+
+## Blocks
+
+The following blocks are supported inside the definition of `prometheus.exporter.ssh`:
+
+| Block          | Description                                                 | Required |
+| -------------- | ----------------------------------------------------------- | -------- |
+| `targets`      | Configures an SSH target to collect metrics from.           | yes      |
+| `custom_metrics` | Defines custom metrics to collect from the target server. | yes      |
+
+### targets block
+
+The `targets` block defines the remote servers to connect to and the metrics to collect. It supports the following arguments:
+
+| Name              | Type                  | Description                                                            | Default | Required |
+| ----------------- | --------------------- | ---------------------------------------------------------------------- | ------- | -------- |
+| `address`         | `string`              | The IP address or hostname of the target server.                       |         | yes      |
+| `port`            | `int`                 | SSH port number.                                                       | `22`    | no       |
+| `username`        | `string`              | SSH username for authentication.                                       |         | yes      |
+| `password`        | `secret`              | Password for password-based SSH authentication.                        |         | Required if `key_file` is not provided |
+| `key_file`        | `string`              | Path to the private key file for key-based SSH authentication.         |         | Required if `password` is not provided |
+| `command_timeout` | `int`                 | Timeout in seconds for each command execution over SSH.                | `30`    | no       |
+| `custom_metrics`  | `block`               | One or more custom metrics to collect from the target server.          |         | yes      |
+
+#### Authentication
+
+You must provide either `password` or `key_file` for SSH authentication. If both are provided, `key_file` will be used.
+
+### custom_metrics block
+
+The `custom_metrics` block defines the metrics to collect from the target server. It supports the following arguments:
+
+| Name           | Type                  | Description                                                                  | Default | Required |
+| -------------- | --------------------- | ---------------------------------------------------------------------------- | ------- | -------- |
+| `name`         | `string`              | The name of the metric.                                                      |         | yes      |
+| `command`      | `string`              | The command to execute over SSH to collect the metric.                       |         | yes      |
+| `type`         | `string`              | The type of the metric (`gauge` or `counter`).                               |         | yes      |
+| `help`         | `string`              | Help text for the metric.                                                    |         | no       |
+| `labels`       | `map(string, string)` | Key-value pairs of labels to associate with the metric.                      | `{}`    | no       |
+| `parse_regex`  | `string`              | Regular expression to parse the command output and extract the metric value. |         | no       |
+
+#### Metric Types
+
+- `gauge`: Represents a numerical value that can go up or down.
+- `counter`: Represents a cumulative value that only increases.
+
+#### parse_regex
+
+If the command output is not a simple numeric value, use `parse_regex` to extract the numeric value from the output.
+
+---
+
+## Secure Known Hosts Setup
+
+### How It Works
+
+The `prometheus.exporter.ssh` component uses the `known_hosts` file to validate host keys and protect against man-in-the-middle (MITM) attacks. Here's how it handles this:
+
+1. **First-Time Setup**:
+   - If the `known_hosts` file does not exist, the component creates it and fetches the host key using `ssh-keyscan`.
+   - The fetched key is securely stored in the `known_hosts` file.
+
+2. **Subsequent Runs**:
+   - The component validates the server's host key against the stored key in `known_hosts`.
+   - If the keys match, the connection proceeds.
+   - If there is a mismatch, the component raises an error, requiring **manual intervention** to verify the legitimacy of the key change.
+
+3. **Adding or Modifying Targets**:
+   - When a new target is added, or its address changes, the component automatically scans and stores the host key.
+   - If the target's key already exists but has changed, the connection is blocked until the discrepancy is resolved manually.
+
+### Manual Resolution
+
+If a host key mismatch occurs due to a legitimate key update:
+- Manually update the `known_hosts` file with the new key using `ssh-keyscan` or other secure methods.
+
+---
+
+## Exported fields
+
+{{< docs/shared lookup="reference/components/exporter-component-exports.md" source="alloy" version="<ALLOY_VERSION>" >}}
+
+## Component health
+
+`prometheus.exporter.ssh` is only reported as unhealthy if given an invalid configuration. In those cases, exported fields retain their last healthy values.
+
+## Debug information
+
+`prometheus.exporter.ssh` doesn't expose any component-specific debug information.
+
+## Debug metrics
+
+`prometheus.exporter.ssh` doesn't expose any component-specific debug metrics.
+
+---
+
+## Example
+
+This example uses a [`prometheus.scrape` component][scrape] to collect metrics from `prometheus.exporter.ssh`:
+
+```
+prometheus.exporter.ssh "example" {
+  verbose_logging = true
+
+  targets {
+    address         = "192.168.1.10"
+    port            = 22
+    username        = "admin"
+    password        = "password"
+    command_timeout = 10
+
+    custom_metrics {
+      name    = "load_average"
+      command = "cat /proc/loadavg | awk '{print $1}'"
+      type    = "gauge"
+      help    = "Load average over 1 minute"
+    }
+  }
+
+  targets {
+    address         = "192.168.1.11"
+    port            = 22
+    username        = "monitor"
+    key_file        = "/path/to/private.key"
+    command_timeout = 15
+
+    custom_metrics {
+      name        = "disk_usage"
+      command     = "df / | tail -1 | awk '{print $5}'"
+      type        = "gauge"
+      help        = "Disk usage percentage"
+      parse_regex = "(\\d+)%"
+    }
+  }
+}
+
+// Configure a prometheus.scrape component to collect SSH metrics.
+prometheus.scrape "demo" {
+  targets    = prometheus.exporter.ssh.example.targets
+  forward_to = [prometheus.remote_write.demo.receiver]
+}
+
+prometheus.remote_write "demo" {
+  endpoint {
+    url = PROMETHEUS_REMOTE_WRITE_URL
+
+    basic_auth {
+      username = USERNAME
+      password = PASSWORD
+    }
+  }
+}
+```
+
+Replace the following:
+
+- `PROMETHEUS_REMOTE_WRITE_URL`: The URL of the Prometheus remote_write-compatible server to send metrics to.
+- `USERNAME`: The username to use for authentication to the `remote_write` API.
+- `PASSWORD`: The password to use for authentication to the `remote_write` API.
+
+[scrape]: ../prometheus.scrape/
+
+<!-- START GENERATED COMPATIBLE COMPONENTS -->
+
+## Compatible components
+
+`prometheus.exporter.ssh` has exports that can be consumed by the following components:
+
+- Components that consume [Targets](../../../compatibility/#targets-consumers)
+
+{{< admonition type="note" >}}
+Connecting some components may not be sensible or components may require further configuration to make the connection work correctly.
+Refer to the linked documentation for more details.
+{{< /admonition >}}
+
+<!-- END GENERATED COMPATIBLE COMPONENTS -->

internal/component/all/all.go

@@ -128,6 +128,7 @@ import (
 	_ "github.com/grafana/alloy/internal/component/prometheus/exporter/snmp"                 // Import prometheus.exporter.snmp
 	_ "github.com/grafana/alloy/internal/component/prometheus/exporter/snowflake"            // Import prometheus.exporter.snowflake
 	_ "github.com/grafana/alloy/internal/component/prometheus/exporter/squid"                // Import prometheus.exporter.squid
+	_ "github.com/grafana/alloy/internal/component/prometheus/exporter/ssh"                  // Import prometheus.exporter.ssh
 	_ "github.com/grafana/alloy/internal/component/prometheus/exporter/statsd"               // Import prometheus.exporter.statsd
 	_ "github.com/grafana/alloy/internal/component/prometheus/exporter/unix"                 // Import prometheus.exporter.unix
 	_ "github.com/grafana/alloy/internal/component/prometheus/exporter/windows"              // Import prometheus.exporter.windows