Prometheus metrics#

Web Manager dependency#

SFTPPlus exposes process metrics in Prometheus format through the Web Manager service at /metrics. Metrics collection by Prometheus requires the Web Manager service to be enabled and running on each SFTPPlus instance being monitored. Prometheus must be able to connect to that service. For example, a service listening on port 10020 exposes metrics at https://sftp.acme.com:10020/metrics. When using base_url_path, append /metrics to that base URL.

Authentication and permissions#

Each scrape requires HTTP Basic authentication with an administrator's username and password. In SFTPPlus, an administrator account defines the identity and permissions used to access the metrics endpoint. For Prometheus monitoring, this account represents the automated scraper. Create a dedicated administrator account for the scraper and configure Prometheus to use its username and password for each scrape.

Authentication uses the same methods and restrictions as Web Manager password login. Web Manager session cookies and session tokens do not authenticate metrics requests. The service's TLS settings also apply to metrics, including mutual TLS when configured. A client certificate does not replace the administrator's username and password.

The administrator needs read permission for /metrics. This permission grants access to all metrics exposed at the endpoint; metrics cannot be restricted by service.

New installations include a role with UUID DEFAULT-METRICS-ROLE and name Metrics role. The role grants read access to /metrics, which covers every metric exposed by the endpoint. Installations upgraded from an older version do not receive this role automatically. To create it manually, configure the role as follows:

[roles/DEFAULT-METRICS-ROLE]
name = Metrics role
permissions = /metrics, read

Associate this role with a dedicated administrator using the Web Manager's Administrators page. Roles with empty permissions retain their existing full administrative access, including metrics.

Exposition format#

SFTPPlus exports Prometheus Text Format 1.0.0, encoded as UTF-8. The response has the following HTTP header:

Content-Type: text/plain; version=1.0.0; charset=utf-8

Each metric includes # HELP and # TYPE lines followed by its sample value. The metric sections below show selected lines from one /metrics response, grouped by metric for readability. Each process-wide metric has one sample per response; component metrics can have several series in the same response. UUID labels in the examples use four characters for readability; real responses use full UUIDs. Names, counts, and system values are also illustrative. An omitted measurement is unavailable or has not yet been recorded; it is not reported as zero. A measured value of zero is still exported. Counters ending in _total are monotonic and suitable for rate() and increase(); component counters reset when the process restarts. Metrics describe the local process and contain no usernames, IP addresses, or filenames.

The endpoint does not export OpenMetrics format. It returns Prometheus text regardless of the request's Accept header, including when a client requests application/openmetrics-text. Configure clients to accept text/plain; the endpoint does not negotiate an alternative format.

Available metrics#

Metrics prefixed with process_ use well-known Prometheus process metric names. The sftpplus_reactor_delay_seconds metric measures Twisted reactor responsiveness. Metrics prefixed with sftpplus_ are specific to SFTPPlus. The following metrics are available:

Metric	Type	Description
process_start_time_seconds	Gauge	Fixed process start time in seconds since the Unix epoch.
sftpplus_info	Gauge	Application metadata with value 1 and labels version, build, python_version, os, architecture, and openssl_version. One series is exposed per running SFTPPlus instance. The version includes development, release candidate, and trial suffixes. The build is the UTC build date in YYYYMMDD format, or development when no build date has been generated.
process_open_fds	Gauge	Open file descriptors, or process handles on Windows.
process_max_fds	Gauge	OS soft limit for open file descriptors, recorded when the Web Manager starts. An unlimited limit is exported as +Inf. Omitted when unavailable, including on Windows.
process_resident_memory_bytes	Gauge	Resident process memory in bytes.
process_virtual_memory_bytes	Gauge	Virtual process memory in bytes.
process_heap_bytes	Gauge	Native allocator heap usage in bytes, including mapped allocations. Available on Linux with glibc, Windows, and macOS. Omitted on other platforms, including Linux with musl.
process_cpu_seconds_total	Counter	Total user and system CPU time consumed by the process, in seconds. Excludes child process CPU time.
process_threads	Gauge	Number of process threads.
sftpplus_reactor_delay_seconds	Gauge	Delay of the most recent reactor responsiveness check, scheduled every five seconds.
sftpplus_component_info	Gauge	Configured runnable metadata with value 1 and labels uuid, name, family, and type.
sftpplus_component_status	Gauge	Current component state with labels uuid and status and value 1.
sftpplus_connections_total	Counter	Established service or location connections.
sftpplus_connections_active	Gauge	Current service protocol connections or active location clients.
sftpplus_authentications_total	Counter	Authentication outcomes for services and client connection outcomes for locations, with purpose (server, client, or cluster) and result (success or failure) labels.
sftpplus_bytes_total	Counter	Bytes read or written by a service or location, with direction (received or sent) and result (success or failure) labels.
sftpplus_files_total	Counter	Completed service or location file operations with direction and result labels.
sftpplus_transfer_bytes_total	Counter	Source file sizes, in bytes, for files delivered by a transfer.
sftpplus_transfer_files_total	Counter	Files completed by transfer jobs, with a result label of success or failure.

Standard process metrics#

Metrics with the process_ prefix describe the monitored process. process_start_time_seconds and process_max_fds are available even when analytics is stopped. The maximum file descriptor limit is the operating system soft limit recorded when the Web Manager starts; an unlimited limit appears as +Inf, and this metric is omitted when the limit is unavailable, including on Windows. process_open_fds reports handles instead of file descriptors on Windows. process_heap_bytes includes mapped allocations and is available on Linux with glibc, Windows, and macOS; it is omitted on other platforms, including Linux with musl. process_cpu_seconds_total counts user and system CPU time but excludes child processes. The usage metrics require analytics to be running and are omitted until its first sample. They refresh at the analytics monitor_interval; match that setting to the Prometheus scrape_interval to get a fresh usage sample for each scrape. An example response includes:

# HELP process_start_time_seconds Start time of the process in seconds since the Unix epoch.
# TYPE process_start_time_seconds gauge
process_start_time_seconds 1790928000.0
# HELP process_open_fds Number of open file descriptors, or handles on Windows.
# TYPE process_open_fds gauge
process_open_fds 48.0
# HELP process_max_fds Maximum number of open file descriptors (soft limit).
# TYPE process_max_fds gauge
process_max_fds 1048576.0
# HELP process_resident_memory_bytes Resident memory in bytes.
# TYPE process_resident_memory_bytes gauge
process_resident_memory_bytes 268435456.0
# HELP process_virtual_memory_bytes Virtual memory in bytes.
# TYPE process_virtual_memory_bytes gauge
process_virtual_memory_bytes 805306368.0
# HELP process_heap_bytes Native allocator heap usage in bytes.
# TYPE process_heap_bytes gauge
process_heap_bytes 146800640.0
# HELP process_cpu_seconds_total Total user and system CPU time spent in seconds.
# TYPE process_cpu_seconds_total counter
process_cpu_seconds_total 125.5
# HELP process_threads Number of process threads.
# TYPE process_threads gauge
process_threads 18.0

Application metadata and reactor delay#

sftpplus_info describes the whole instance with one gauge series of value 1 per monitored endpoint. The version retains development, release candidate, and trial suffixes; the build is the UTC build date in YYYYMMDD format, or development when no build date has been generated. The Python version includes its patch number, the operating system name is lowercase, and the architecture is the runtime machine identifier. The openssl_version label contains the full OpenSSL version used through pyOpenSSL. Application metadata is available even when analytics is stopped. Use count by (version) (sftpplus_info) to count monitored instances by version.

sftpplus_reactor_delay_seconds is a gauge of the most recent Twisted reactor responsiveness check, scheduled every five seconds. It requires analytics to be running and is omitted until the first check. An example response includes:

# HELP sftpplus_info SFTPPlus application and build metadata.
# TYPE sftpplus_info gauge
sftpplus_info{version="6.1.0",build="20261002",python_version="3.14.0",os="linux",architecture="x86_64",openssl_version="OpenSSL 3.5.0 8 Apr 2025"} 1.0
# HELP sftpplus_reactor_delay_seconds Measured delay of the Twisted reactor in seconds.
# TYPE sftpplus_reactor_delay_seconds gauge
sftpplus_reactor_delay_seconds 0.003

Component identity and status#

Each configured service, location, transfer, resource, authentication, and event handler has an sftpplus_component_info series. Its value is 1, and its uuid, name, family, and type labels identify the component. The family label distinguishes service, location, and transfer identities; transfer identities use family="transfer" and type="transfer".

sftpplus_component_status emits one gauge series of value 1 for the component's current state. The status label is running, stopped, or failed, with disconnected for locations and suspended for transfers outside their scheduled window. The status series and the info series share the uuid label. Component metrics are available independently of analytics. An example response includes:

# HELP sftpplus_component_info Configured component metadata.
# TYPE sftpplus_component_info gauge
sftpplus_component_info{uuid="1111",name="SFTP service",family="service",type="sftp"} 1.0
sftpplus_component_info{uuid="2222",name="Local storage",family="location",type="filesystem"} 1.0
sftpplus_component_info{uuid="6666",name="Archive storage",family="location",type="sftp"} 1.0
sftpplus_component_info{uuid="3333",name="Daily archive",family="transfer",type="transfer"} 1.0
sftpplus_component_info{uuid="4444",name="Partner upload",family="transfer",type="transfer"} 1.0
sftpplus_component_info{uuid="5555",name="Weekly export",family="transfer",type="transfer"} 1.0
# HELP sftpplus_component_status Current component state.
# TYPE sftpplus_component_status gauge
sftpplus_component_status{uuid="1111",status="running"} 1.0
sftpplus_component_status{uuid="2222",status="running"} 1.0
sftpplus_component_status{uuid="6666",status="disconnected"} 1.0
sftpplus_component_status{uuid="3333",status="running"} 1.0
sftpplus_component_status{uuid="4444",status="stopped"} 1.0
sftpplus_component_status{uuid="5555",status="suspended"} 1.0

Connections and authentications#

sftpplus_connections_total counts established service connections or ready location clients. sftpplus_connections_active reports current service protocol connections or active location clients. A location tracks its high-level client rather than each TCP socket; some backends detect a broken connection only on the next operation. Services and locations have a protocol label on activity metrics, such as sftp-server or sftp-client. Transfers have no connection or authentication series.

sftpplus_authentications_total records result="success" or result="failure" for a credential check or client connection outcome. Its purpose label distinguishes server-side checks (server), client-side location connections (client), and cluster-node logins (cluster). A location counts success when its high-level client is ready to use, including filesystem and SMTP locations that do not authenticate separately. It counts failures to initiate a connection, such as an unreachable remote server. Cluster-node logins require a node instance name. Prometheus scrape authentications are not metered, so they do not increase this counter. Successful and failed scrapes still appear in the activity log with purpose="metrics" when credentials reach the checker; missing or malformed authorization headers are rejected before that check. The Web Manager's manager and _manager_unsecured services expose connection and authentication metrics, but no byte or file metrics because they do not transfer files. An example response includes:

# HELP sftpplus_connections_total Connections established.
# TYPE sftpplus_connections_total counter
sftpplus_connections_total{uuid="1111",protocol="sftp-server"} 24.0
sftpplus_connections_total{uuid="2222",protocol="filesystem-client"} 12.0
sftpplus_connections_total{uuid="6666",protocol="sftp-client"} 5.0
# HELP sftpplus_connections_active Current connections for the component.
# TYPE sftpplus_connections_active gauge
sftpplus_connections_active{uuid="1111",protocol="sftp-server"} 2.0
sftpplus_connections_active{uuid="2222",protocol="filesystem-client"} 1.0
sftpplus_connections_active{uuid="6666",protocol="sftp-client"} 0.0
# HELP sftpplus_authentications_total Authentications by the component and outcome.
# TYPE sftpplus_authentications_total counter
sftpplus_authentications_total{uuid="1111",protocol="sftp-server",purpose="server",result="success"} 22.0
sftpplus_authentications_total{uuid="1111",protocol="sftp-server",purpose="server",result="failure"} 2.0
sftpplus_authentications_total{uuid="2222",protocol="filesystem-client",purpose="client",result="success"} 12.0
sftpplus_authentications_total{uuid="2222",protocol="filesystem-client",purpose="client",result="failure"} 0.0
sftpplus_authentications_total{uuid="6666",protocol="sftp-client",purpose="client",result="success"} 4.0
sftpplus_authentications_total{uuid="6666",protocol="sftp-client",purpose="client",result="failure"} 1.0

Service and location file activity#

sftpplus_bytes_total and sftpplus_files_total describe service and location operations from SFTPPlus's perspective. direction="received" means data enters SFTPPlus through that component; direction="sent" means data leaves SFTPPlus through it. Both counters have result="success" or result="failure" for a finished operation. Failed byte series include bytes transferred before the file failed. Bytes are assigned to a result when the file operation finishes; sum across result to recover the total for one direction. For example, sum without (result) (sftpplus_bytes_total) combines successful and failed bytes while retaining each component and direction. These counters include local filesystem reads and writes.

HTTP, SFTP, and FTP services count client uploads as received bytes and files, and client downloads as sent bytes and files. File handlers record outcomes and transferred bytes directly, including partial data reported on failures.

Failed file counts include only files that were successfully opened and then failed during transfer or close. An unsuccessful open, including a missing file or permission error, does not increase the failed file count.

Locations count files and bytes read from a location as received, and files and bytes written to a location as sent. Closing a read stream increments received files; closing a write or append stream increments sent files. A read, write, or close failure makes the finished file operation a failure even if the final close succeeded. A location aggregates operations from every transfer that uses it.

For example, an HTTP download from the default local filesystem location increases that location's received counters and the HTTP service's sent counters. An HTTP upload increases the HTTP service's received counters and the default local filesystem location's sent counters.

A WebDAV COPY counts a read and a write on the filesystem location, even though the copied bytes do not move over the network. It also counts as both a download and an upload on the HTTP service.

A client upload or download can appear in both service and location counters, with a different direction for each component. Filter to the component family you want before calculating an overall total. An example response includes:

# HELP sftpplus_bytes_total Bytes transferred by the component, direction, and outcome.
# TYPE sftpplus_bytes_total counter
sftpplus_bytes_total{uuid="1111",protocol="sftp-server",direction="received",result="success"} 11000.0
sftpplus_bytes_total{uuid="1111",protocol="sftp-server",direction="received",result="failure"} 1000.0
sftpplus_bytes_total{uuid="1111",protocol="sftp-server",direction="sent",result="success"} 6000.0
sftpplus_bytes_total{uuid="2222",protocol="filesystem-client",direction="received",result="success"} 6000.0
sftpplus_bytes_total{uuid="2222",protocol="filesystem-client",direction="sent",result="success"} 12000.0
sftpplus_bytes_total{uuid="6666",protocol="sftp-client",direction="received",result="failure"} 3000.0
# HELP sftpplus_files_total File operations by the component, direction, and outcome.
# TYPE sftpplus_files_total counter
sftpplus_files_total{uuid="1111",protocol="sftp-server",direction="received",result="success"} 8.0
sftpplus_files_total{uuid="1111",protocol="sftp-server",direction="received",result="failure"} 1.0
sftpplus_files_total{uuid="1111",protocol="sftp-server",direction="sent",result="success"} 4.0
sftpplus_files_total{uuid="2222",protocol="filesystem-client",direction="received",result="success"} 4.0
sftpplus_files_total{uuid="2222",protocol="filesystem-client",direction="sent",result="success"} 8.0
sftpplus_files_total{uuid="6666",protocol="sftp-client",direction="received",result="failure"} 1.0

Transfer job activity#

sftpplus_transfer_bytes_total adds the source file's reported size after it reaches its final destination, for every transfer type, including pulls and transfers between remote locations. It does not measure bytes actually written, can differ from the destination size after a content action, and excludes failed files. sftpplus_transfer_files_total counts successful and failed files completed by a transfer job. Both counters use the transfer's uuid; neither has a protocol or direction label because the job sends files to a final destination.

For example, transferring a file from Azure Blob to a local filesystem increments received counters on the Azure Blob location and sent counters on the filesystem location. The transfer byte counter adds the source file size only if the file reaches its final destination; its file counter also records a failed job outcome under result="failure". The byte totals can differ when a transfer transforms content, fails partway through, or retries. Do not sum transfer counters with location or service counters: they describe different stages of the same work. An example response includes:

# HELP sftpplus_transfer_bytes_total Sum of source file sizes for files delivered by the transfer.
# TYPE sftpplus_transfer_bytes_total counter
sftpplus_transfer_bytes_total{uuid="3333"} 9000.0
sftpplus_transfer_bytes_total{uuid="4444"} 3000.0
sftpplus_transfer_bytes_total{uuid="5555"} 0.0
# HELP sftpplus_transfer_files_total Files completed by the transfer and outcome.
# TYPE sftpplus_transfer_files_total counter
sftpplus_transfer_files_total{uuid="3333",result="success"} 3.0
sftpplus_transfer_files_total{uuid="3333",result="failure"} 1.0
sftpplus_transfer_files_total{uuid="4444",result="success"} 2.0
sftpplus_transfer_files_total{uuid="4444",result="failure"} 0.0
sftpplus_transfer_files_total{uuid="5555",result="success"} 0.0
sftpplus_transfer_files_total{uuid="5555",result="failure"} 4.0

Scrape configuration#

For a manual check, use an administrator with the monitoring role:

curl --cacert /path/to/ca.pem --user monitoring \
    https://sftpplus.example.com:10020/metrics

The command prompts for the administrator's password. Successful requests return HTTP 200 and Prometheus text. Missing or invalid credentials return HTTP 401; insufficient permissions return HTTP 403.

An example Prometheus scrape configuration is:

scrape_configs:
  - job_name: sftpplus
    scheme: https
    metrics_path: /metrics
    scrape_interval: 60s
    basic_auth:
      username: monitoring
      password_file: /etc/prometheus/secrets/sftpplus-password
    tls_config:
      ca_file: /etc/prometheus/certs/sftpplus-ca.pem
    static_configs:
      - targets: ['sftpplus.example.com:10020']

For mutual TLS, add cert_file and key_file to tls_config with the paths to the client's certificate and private key.