Metrics Plugin
Relevant source files
The following files were used as context for generating this wiki page:
The Metrics Plugin for sshpiperd is a specialized monitoring component categorized as a Metrics Plugin (marked with the 📈 icon). Its primary purpose is to provide a dedicated HTTP server that exposes Prometheus-formatted metrics regarding active SSH pipes, connection lifecycles, and authentication failures.
Sources: plugin/metrics/README.md:3-5, README.md:126
Unlike routing or challenge plugins, the metrics plugin acts as a listener that hooks into connection events via gRPC callbacks provided by the sshpiperd daemon. It tracks real-time data such as open connections partitioned by remote address and username, and can optionally collect error statistics for pipe creation and upstream authentication.
Sources: plugin/metrics/main.go:68-120, plugin/metrics/README.md:17-19
Architecture and Data Flow
The plugin is built using the libplugin framework and operates as a long-running gRPC service. When initialized, it registers several callbacks with sshpiperd. These callbacks are triggered by the daemon at specific points in an SSH session's lifecycle.
The following diagram illustrates how the Metrics Plugin interacts with the sshpiperd daemon and external Prometheus scrapers:
Callback Mechanism
The plugin utilizes the SshPiperPluginConfig structure to define its interaction points. Key callbacks include:
- PipeStartCallback: Triggered when a pipe is successfully established. It increments the gauge for open connections.
- PipeErrorCallback: Triggered when a pipe closes or encounters an error. It removes the specific label set from the open connections gauge.
- UpstreamAuthFailureCallback: Triggered if the upstream server rejects an authentication attempt.
- PipeCreateErrorCallback: Triggered if
sshpiperdfails to initiate the pipe to the upstream.
Sources: plugin/metrics/main.go:88-120, libplugin/plugin.proto:61-75
Exposed Metrics
The plugin provides one default metric and two optional metrics that must be explicitly enabled via command-line flags.
| Metric Name | Type | Labels | Description |
|---|---|---|---|
sshpiper_pipe_open_connections | Gauge | remote_addr, username | Current number of active pipes. |
sshpiper_pipe_create_errors | Counter | remote_addr | Failures during pipe initialization (Optional). |
sshpiper_upstream_auth_failures | Counter | remote_addr, user, method | Upstream authentication rejections (Optional). |
Sources: plugin/metrics/README.md:7-15, plugin/metrics/main.go:70-101
Configuration and Usage
The Metrics Plugin is executed as a child process of sshpiperd. It supports standard environment variables and CLI flags for configuration.
CLI Flags
The following flags are available for the metrics plugin:
| Flag | Env Var | Default | Description |
|---|---|---|---|
--address | SSHPIPERD_METRICS_ADDRESS | "" | Listen address for the metrics HTTP server. |
--port | SSHPIPERD_METRICS_PORT | 9000 | Listen port for the metrics HTTP server. |
--collect-pipe-create-errors | SSHPIPERD_METRICS_COLLECT_PIPE_CREATE_ERRORS | false | Enable collection of pipe creation errors. |
--collect-upstream-auth-failures | SSHPIPERD_METRICS_COLLECT_UPSTREAM_AUTH_FAILURES | false | Enable collection of upstream auth failures. |
Sources: plugin/metrics/main.go:21-46
Execution Example
The plugin must be used in conjunction with other routing or authentication plugins. The -- separator is used in the sshpiperd command line to distinguish between plugin configurations.
sshpiperd fixed --target 127.0.0.1:22 -- metrics --port 9000 --collect-pipe-create-errors
Sources: plugin/metrics/README.md:21-23
Implementation Details
The plugin utilizes a prometheusMetrics struct to manage the lifecycle of the Prometheus registry and its associated vectors.
type prometheusMetrics struct {
registry *prometheus.Registry
openConnections *prometheus.GaugeVec
pipeCreateErrors *prometheus.CounterVec
upstreamAuthFailures *prometheus.CounterVec
}
Sources: plugin/metrics/main.go:104-109
When newPrometheusMetrics is called, it initializes the registry and registers the openConnections gauge. If the optional flags are set to true, it additionally registers the counter vectors and assigns the corresponding callbacks in the libplugin.SshPiperPluginConfig.
The HTTP server is started in a separate goroutine during the CreateConfig phase, ensuring the metrics endpoint /metrics is available as soon as the plugin is loaded by sshpiperd.
Sources: plugin/metrics/main.go:48-65, plugin/metrics/main.go:111-118
Summary
The Metrics Plugin serves as a non-intrusive monitoring layer for sshpiperd clusters. By transforming internal gRPC connection events into standard Prometheus metrics, it enables administrators to visualize connection density and troubleshoot authentication or networking issues across the proxy. It is designed to be chained with other plugins, allowing for comprehensive observability without modifying routing logic.
Sources: plugin/metrics/README.md:17-19, cmd/sshpiperd/internal/plugin/chain.go:193-206