prometheus-dcache-exporter 0.1.0__tar.gz

prometheus_dcache_exporter-0.1.0/LICENCE

@@ -0,0 +1,13 @@
+Copyright © 2026 Christoph Anton Mitterer <mail@christoph.anton.mitterer.name>
+
+
+This program is free software: you can redistribute it and/or modify it under
+the terms of the GNU General Public License as published by the Free Software
+Foundation, either version 3 of the License, or (at your option) any later
+version.
+This program is distributed in the hope that it will be useful, but WITHOUT ANY
+WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+PARTICULAR PURPOSE.
+See the GNU General Public License for more details.
+You should have received a copy of the GNU General Public License along with
+this program. If not, see <https://www.gnu.org/licenses/>.

prometheus_dcache_exporter-0.1.0/MANIFEST.in

@@ -0,0 +1,2 @@
+exclude COPYING
+prune debian

prometheus_dcache_exporter-0.1.0/PKG-INFO

@@ -0,0 +1,32 @@
+Metadata-Version: 2.4
+Name: prometheus-dcache-exporter
+Version: 0.1.0
+Summary: A Prometheus exporter for dCache.
+Author-email: Christoph Anton Mitterer <mail@christoph.anton.mitterer.name>
+Maintainer-email: Christoph Anton Mitterer <mail@christoph.anton.mitterer.name>
+Project-URL: website, https://gitlab.com/calestyo/prometheus-dcache-exporter
+Keywords: monitoring,prometheus,prometheus exporter,dcache
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Environment :: No Input/Output (Daemon)
+Classifier: Environment :: Plugins
+Classifier: Intended Audience :: Information Technology
+Classifier: Intended Audience :: System Administrators
+Classifier: Natural Language :: English
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: System :: Monitoring
+Classifier: Topic :: System :: Networking :: Monitoring
+Requires-Python: >=3.13
+License-File: LICENCE
+Requires-Dist: certifi
+Requires-Dist: httpx
+Requires-Dist: humanfriendly
+Requires-Dist: paramiko
+Requires-Dist: prometheus-client
+Requires-Dist: python-jsonpath
+Requires-Dist: python-module-utils
+Provides-Extra: extended-logging-formatter
+Requires-Dist: python-logging-extras; extra == "extended-logging-formatter"
+Provides-Extra: rich-text
+Requires-Dist: rich; extra == "rich-text"
+Dynamic: license-file

prometheus_dcache_exporter-0.1.0/pyproject.toml

@@ -0,0 +1,99 @@
+[project]
+name = "prometheus-dcache-exporter"
+
+description = "A Prometheus exporter for dCache."
+keywords = [
+            "monitoring", "prometheus", "prometheus exporter",
+            "dcache"
+           ]
+classifiers = [
+               "Development Status :: 4 - Beta",
+               "Environment :: Console",
+	       "Environment :: No Input/Output (Daemon)",
+               "Environment :: Plugins",
+               "Intended Audience :: Information Technology",
+               "Intended Audience :: System Administrators",
+               "Natural Language :: English",
+               "Programming Language :: Python :: 3",
+               "Topic :: System :: Monitoring",
+               "Topic :: System :: Networking :: Monitoring"
+              ]
+
+authors = [
+           {name = "Christoph Anton Mitterer", email = "mail@christoph.anton.mitterer.name"}
+          ]
+maintainers = [
+               {name = "Christoph Anton Mitterer", email = "mail@christoph.anton.mitterer.name"}
+              ]
+
+license-files = ["LICENCE"]
+
+requires-python = ">=3.13"
+dependencies = [
+		"certifi",
+		"httpx",
+		"humanfriendly",
+		"paramiko",
+                "prometheus-client",
+		"python-jsonpath",
+		"python-module-utils"
+               ]
+
+dynamic = ["version"]
+
+
+[project.urls]
+website = "https://gitlab.com/calestyo/prometheus-dcache-exporter"
+
+
+[project.optional-dependencies]
+extended-logging-formatter = ["python-logging-extras"]
+rich-text = ["rich"]
+
+
+[project.scripts]
+prometheus-dcache-exporter = "prometheus_dcache_exporter.__main__:main"
+
+
+
+
+[build-system]
+requires = ["setuptools>=77", "setuptools-scm>=8"]
+build-backend = "setuptools.build_meta"
+
+
+
+
+[tool.setuptools]
+
+
+[tool.setuptools_scm]
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+#Copyright © 2026 Christoph Anton Mitterer <mail@christoph.anton.mitterer.name>
+#
+#
+#This program is free software: you can redistribute it and/or modify it under
+#the terms of the GNU General Public License as published by the Free Software
+#Foundation, either version 3 of the License, or (at your option) any later
+#version.
+#This program is distributed in the hope that it will be useful, but WITHOUT ANY
+#WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+#PARTICULAR PURPOSE.
+#See the GNU General Public License for more details.
+#You should have received a copy of the GNU General Public License along with
+#this program. If not, see <https://www.gnu.org/licenses/>.

prometheus_dcache_exporter-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

prometheus_dcache_exporter-0.1.0/src/prometheus_dcache_exporter/__init__.py

@@ -0,0 +1,13 @@
+#Copyright © 2026 Christoph Anton Mitterer <mail@christoph.anton.mitterer.name>
+#
+#
+#This program is free software: you can redistribute it and/or modify it under
+#the terms of the GNU General Public License as published by the Free Software
+#Foundation, either version 3 of the License, or (at your option) any later
+#version.
+#This program is distributed in the hope that it will be useful, but WITHOUT ANY
+#WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+#PARTICULAR PURPOSE.
+#See the GNU General Public License for more details.
+#You should have received a copy of the GNU General Public License along with
+#this program. If not, see <https://www.gnu.org/licenses/>.

prometheus_dcache_exporter-0.1.0/src/prometheus_dcache_exporter/__main__.py

@@ -0,0 +1,437 @@
+from module_utils import optional_import, optional_from_import
+
+
+import sys
+import os
+import argparse
+import enum
+import signal
+import locale
+import logging
+import contextlib
+from warnings import warn
+
+import prometheus_client
+(rich, HAVE_RICH_CONSOLE) = optional_import("rich.console", get_top_level_modules=True)
+(rich.logging, HAVE_RICH_LOGGING) = optional_import("rich.logging")
+(ExtendedLoggingFormatter, HAVE_EXTENDEDLOGGINGFORMATTER) = optional_from_import("logging_extras.formatters", "ExtendedLoggingFormatter")
+
+
+from ._config import *
+from ._util import sequence_to_separated_str
+from . import _collector as collector
+from . import _dcache as dcache
+
+
+
+
+
+
+
+
+#*******************************************************************************
+#* Enums                                                                       *
+#*******************************************************************************
+class ExportMode(enum.StrEnum):
+    http = enum.auto()
+    stdout = enum.auto()
+    file = enum.auto()
+
+
+
+
+#*******************************************************************************
+#* Global Variables                                                            *
+#*******************************************************************************
+log = logging.getLogger(__name__)
+
+
+
+
+#*******************************************************************************
+#* Signal Handlers                                                             *
+#*******************************************************************************
+def exiting_signal_handler(signalnum, frame):
+    #prevent exiting while already exiting
+    for s in EXITING_SIGNALS:
+        signal.signal(s, signal.SIG_IGN)
+    
+    sys.exit(128 + signalnum)
+
+
+
+
+#*******************************************************************************
+#* Miscellaneous                                                               *
+#*******************************************************************************
+class PositiveInt(int):
+    def __new__(cls, number):
+        integer = int(number)
+        
+        if isinstance(number, str):
+            if str(integer) != number:
+                raise ValueError(f"`{number}` contains invalid characters (which includes signs, whitespace, redundant leading zeros and non-Latin digits).")
+        else:
+            if integer != number:
+                raise ValueError(f"`{number}` is not an integer.")
+        if integer <= 0:
+            raise ValueError(f"The integer `{number}` is not positive.")
+        
+        return integer
+
+
+
+
+class IntOrStr:
+    def __new__(cls, obj):
+        string = str(obj)
+        
+        try:
+            integer = int(obj)
+        except ValueError:
+            return string
+        
+        if str(integer) == string:
+            return integer
+        else:
+            return string
+
+
+
+
+class FromResourceOrBytesOrStr:
+    def __new__(cls, obj):
+        if isinstance(obj, str):
+            match obj[:1]:
+                case "=":
+                    return obj[1:]
+                case "$":
+                    return os.environb[ obj[1:].encode() ]
+                case "<":
+                    with open(obj[1:], mode="rb") as f:
+                        return f.read()
+                case _:
+                    return obj
+        elif isinstance(obj, bytes):
+            return obj
+        else:
+            return str(obj)
+
+
+
+
+class AddMetricsExtraLabel(argparse.Action):
+    def __call__(self, parser, namespace, values, option_string=None):
+        metric_name_regular_expression = values[0]
+        extra_label_name = values[1]
+        
+        
+        #if necessary, initialise the attribute specified via `argparse.ArgumentParser.add_argument`’s `dest`-parameter
+        if not hasattr(namespace, self.dest)  or  getattr(namespace, self.dest) is None:
+            setattr(namespace, self.dest, {})
+        
+        #get the attribute specified via `argparse.ArgumentParser.add_argument`’s `dest`-parameter
+        metrics_extra_labels = getattr(namespace, self.dest)
+        
+        #if necessary, initialise the set for the extra label names for the given metric name regular expression
+        if metric_name_regular_expression not in metrics_extra_labels:
+            metrics_extra_labels[metric_name_regular_expression] = set()
+        
+        
+        #add the given extra label name for the given metric name regular expression
+        metrics_extra_labels[metric_name_regular_expression].add(extra_label_name)
+
+
+
+
+def warn_about_unmatched_metric_name_regular_expressions(*, unmatched_metric_name_regular_expressions):
+    if len(unmatched_metric_name_regular_expressions) == 1:
+        if len(cfg.metrics_extra_labels[ unmatched_metric_name_regular_expressions[0] ]) == 1:
+            log.warning(f"The `--metrics.extra-label`-option with the `REGULAR-EXPRESSION`-argument having the value `{unmatched_metric_name_regular_expressions[0]}` is ignored.")
+        else:
+            log.warning(f"The `--metrics.extra-label`-options with the `REGULAR-EXPRESSION`-argument having the value `{unmatched_metric_name_regular_expressions[0]}` is ignored.")
+    else:
+        log.warning(f"The `--metrics.extra-label`-options with the `REGULAR-EXPRESSION`-argument having any of the values {sequence_to_separated_str(unmatched_metric_name_regular_expressions, ", ", " and ", element_delimiters="`")} is ignored.")
+
+
+
+
+#*******************************************************************************
+#* Main                                                                        *
+#*******************************************************************************
+def main():
+    global cfg
+    
+    
+    #set locale
+    locale.setlocale(locale.LC_ALL, "")
+    
+    
+    #set up logging
+    logging_root_logger = logging.getLogger()
+    
+    if os.isatty(sys.stderr.fileno())  and  HAVE_RICH_LOGGING  and  HAVE_RICH_CONSOLE:
+        logging_handler = rich.logging.RichHandler(console=rich.console.Console(stderr=True), rich_tracebacks=True, tracebacks_code_width=None, keywords=())
+        logging.basicConfig(handlers=(logging_handler, ), format="{name}: {message}", datefmt="%c", style="{")
+    else:
+        if HAVE_EXTENDEDLOGGINGFORMATTER:
+            # Beware that this `logging` handler must not be associated with more than a
+            # single `logging` logger (which is `logging_root_logger`).
+            # See the `dedicated_handler`-parameter of the
+            # `ExtendedLoggingFormatter.callbacks.add_logging_handler_to_hook_state,`-
+            # callback-function.
+            logging_handler = logging.StreamHandler()
+            
+            # Beware that this `logging` formatter must not be associated with more than a
+            # single `logging` handler (which is `logging_handler`).
+            # See the `dedicated_handler`-parameter of the
+            # `ExtendedLoggingFormatter.callbacks.add_logging_handler_to_hook_state,`-
+            # callback-function.
+            logging_formatter = ExtendedLoggingFormatter(fmt="{asctime}: {levelname}: {name}: {message_lineno}{message}",
+                                                         exc_fmt="{asctime}: DEBUG: {name}: {exc_lineno}{exc}",
+                                                         stack_fmt="{asctime}: DEBUG: {name}: {stack_lineno}{stack}",
+                                                         datefmt="%c", style="{")
+            logging_formatter.registerCallback(ExtendedLoggingFormatter.Hook.format_begin, ExtendedLoggingFormatter.callbacks.add_logging_logger_to_hook_state)
+            logging_formatter.registerCallback(ExtendedLoggingFormatter.Hook.format_begin, ExtendedLoggingFormatter.callbacks.add_logging_handler_to_hook_state, dedicated_handler=logging_handler)
+            logging_formatter.registerCallback(ExtendedLoggingFormatter.Hook.format_begin, ExtendedLoggingFormatter.callbacks.clear_record_parts_by_extra_level, exc_level=logging.DEBUG, stack_level=logging.DEBUG)
+            
+            logging_handler.setFormatter(logging_formatter)
+            logging_root_logger.addHandler(logging_handler)
+        else:
+            logging.basicConfig(format="{asctime}: {levelname}: {name}: {message}", datefmt="%c", style="{")
+    
+    logging_root_logger.setLevel(logging.NOTSET)
+    
+    
+    #parse command arguments
+    parser = argparse.ArgumentParser(allow_abbrev=False)
+    parser.add_argument("--dcache-frontend-rest.base-url", type=str, default=DEFAULT_DCACHE_FRONTEND_REST_BASE_URL, dest="dcache_frontend_rest_base_url", help=f"The base URL under which the REST interface of dCache’s `frontend` service can be reached. Defaults to `{DEFAULT_DCACHE_FRONTEND_REST_BASE_URL}` if this option isn’t given.", metavar="URL")
+    parser.add_argument("--dcache-frontend-rest.http-auth-type", type=dcache.frontend.HTTPAuthType, choices=[e.value  for e in dcache.frontend.HTTPAuthType], default=dcache.frontend.HTTPAuthType.none, dest="dcache_frontend_rest_http_auth_type", help=f"The type of HTTP authentication to be performed. `{dcache.frontend.HTTPAuthType.none}` (which is the default if this option isn’t given) causes no HTTP authentication to be performed. `{dcache.frontend.HTTPAuthType.basic_auth}` causes basic authentication to be used and requires the `--dcache-frontend-rest.http-auth-user`- and `--dcache-frontend-rest.http-auth-passphrase`-options to be given.")
+    parser.add_argument("--dcache-frontend-rest.http-auth-user", type=str, dest="dcache_frontend_rest_http_auth_user", help="The user used for HTTP authentication when connecting to the REST interface of dCache’s `frontend` service.", metavar="USERNAME")
+    parser.add_argument("--dcache-frontend-rest.http-auth-passphrase", type=FromResourceOrBytesOrStr, dest="dcache_frontend_rest_http_auth_passphrase", help="The passphrase used for HTTP authentication when connecting to the REST interface of dCache’s `frontend` service. If STRING starts with `$`, the passphrase is binarily read from an environment variable with the remainder of STRING as the name. If it starts with `<`, the passphrase is binarily read from a file with the remainder of it as the pathname. If it starts with `=`, the passphrase is the remainder of it.", metavar="STRING")
+    parser.add_argument("--dcache-frontend-rest.allow-http-auth-without-tls", action="store_true", dest="dcache_frontend_rest_allow_http_auth_without_tls", help="Allow HTTP authentication when connecting to the REST interface of dCache’s `frontend` service without TLS.")
+    parser.add_argument("--dcache-frontend-rest.tls-ca-certificates", type=str, dest="dcache_frontend_rest_tls_ca_certificates", help="The CA certificates that are trusted when connecting to the REST interface of dCache’s `frontend` service via TLS. If this option isn’t given, the system’s default CA certificates are used. If a regular file (or symbolic link to such), it must consist of concatenated CA certificates in PEM format; if a directory (or symbolic link to such), it must follow the well-known layout by OpenSSL. CRLs are ignored and OCSP isn’t performed.", metavar="PATHNAME")
+    parser.add_argument("--dcache-frontend-rest.tls-client-auth-certificate", type=str, dest="dcache_frontend_rest_tls_client_auth_certificate", help="The certificate and, unless the `--dcache-frontend-rest.tls-client-auth-private-key`-option is given, private key used for client authentication when connecting to the REST interface of dCache’s `frontend` service via TLS. It must be a regular file (or symbolic link to such) that consists of the certificate, depending on the aforementioned, concatenated with the private key in PEM format.", metavar="PATHNAME")
+    parser.add_argument("--dcache-frontend-rest.tls-client-auth-private-key", type=str, dest="dcache_frontend_rest_tls_client_auth_private_key", help="The private key used for client authentication when connecting to the REST interface of dCache’s `frontend` service via TLS. It must be a regular file (or symbolic link to such) that consists of the private key in PEM format.", metavar="PATHNAME")
+    parser.add_argument("--dcache-frontend-rest.tls-client-auth-private-key-passphrase", type=FromResourceOrBytesOrStr, dest="dcache_frontend_rest_tls_client_auth_private_key_passphrase", help="The passphrase used for decrypting the private key specified via the `--dcache-frontend-rest.tls-client-auth-certificate`- or `--dcache-frontend-rest.tls-client-auth-private-key`-options. If STRING starts with `$`, the passphrase is binarily read from an environment variable with the remainder of STRING as the name. If it starts with `<`, the passphrase is binarily read from a file with the remainder of it as the pathname. If it starts with `=`, the passphrase is the remainder of it.", metavar="STRING")
+    parser.add_argument("--dcache-frontend-rest.connect-timeout", type=float, default=DEFAULT_DCACHE_FRONTEND_REST_CONNECT_TIMEOUT, dest="dcache_frontend_rest_connect_timeout", help=f"The timeout in seconds for establishing the connection to the REST interface of dCache’s `frontend` service, with non-positive decimals disabling it. Defaults to `{DEFAULT_DCACHE_FRONTEND_REST_CONNECT_TIMEOUT}` if this option isn’t given.", metavar="DECIMAL")
+    parser.add_argument("--dcache-frontend-rest.read-timeout", type=float, default=DEFAULT_DCACHE_FRONTEND_REST_READ_TIMEOUT, dest="dcache_frontend_rest_read_timeout", help=f"The timeout in seconds for reading a chunk of data from the REST interface of dCache’s `frontend` service, with non-positive decimals disabling it. Defaults to `{DEFAULT_DCACHE_FRONTEND_REST_READ_TIMEOUT}` if this option isn’t given.", metavar="DECIMAL")
+    parser.add_argument("--dcache-frontend-rest.pool-timeout", type=float, default=DEFAULT_DCACHE_FRONTEND_REST_POOL_TIMEOUT, dest="dcache_frontend_rest_pool_timeout", help=f"The timeout in seconds for getting a connection from the pool of connections to the REST interface of dCache’s `frontend` service, with non-positive decimals disabling it. Defaults to `{DEFAULT_DCACHE_FRONTEND_REST_POOL_TIMEOUT}` if this option isn’t given.", metavar="DECIMAL")
+    parser.add_argument("--dcache-frontend-rest.connection-pool-max-size", type=float, dest="dcache_frontend_rest_connection_pool_max_size", help="The maximum number of connections to the REST interface of dCache’s `frontend` service in the connection pool, with non-positive decimals meaning unlimited. Defaults to the value of the `--dcache-frontend-rest.max-concurrent-requests`-option if this option isn’t given. The maximum number of requests that are actually made concurrently is specified via the `--dcache-frontend-rest.max-concurrent-requests`-option.", metavar="INTEGER")
+    parser.add_argument("--dcache-frontend-rest.connection-pool-max-idle-size", type=float, dest="dcache_frontend_rest_connection_pool_max_idle_size", help="The maximum number of idle connections to the REST interface of dCache’s `frontend` service in the connection pool, with negative decimals meaning unlimited and zero meaning none. Defaults to the value of the `--dcache-frontend-rest.connection-pool-max-size`-option if this option isn’t given.", metavar="INTEGER")
+    parser.add_argument("--dcache-frontend-rest.connection-pool-max-idle-time", type=float, default=DEFAULT_DCACHE_FRONTEND_REST_CONNECTION_POOL_MAX_IDLE_TIME, dest="dcache_frontend_rest_connection_pool_max_idle_time", help=f"The maximum time in seconds for which an idle connection to the REST interface of dCache’s `frontend` service may be kept open in the connection pool, with negative decimals meaning unlimited and zero meaning instant closure. Defaults to `{DEFAULT_DCACHE_FRONTEND_REST_CONNECTION_POOL_MAX_IDLE_TIME}` if this option isn’t given.", metavar="DECIMAL")
+    parser.add_argument("--dcache-frontend-rest.max-concurrent-requests", type=PositiveInt, default=DEFAULT_DCACHE_FRONTEND_REST_MAX_CONCURRENT_REQUESTS, dest="dcache_frontend_rest_max_concurrent_requests", help=f"The maximum number of requests that are concurrently made to the REST interface of dCache’s `frontend` service. Defaults to `{DEFAULT_DCACHE_FRONTEND_REST_MAX_CONCURRENT_REQUESTS}` if this option isn’t given.", metavar="POSITIVE-INTEGER")
+    parser.add_argument("--dcache-admin-ssh.host", type=str, default=DEFAULT_DCACHE_ADMIN_SSH_HOST, dest="dcache_admin_ssh_host", help=f"The host under which the SSH interface of dCache’s `admin` service can be reached. Defaults to `{DEFAULT_DCACHE_ADMIN_SSH_HOST}` if this option isn’t given.", metavar="HOSTNAME-OR-ADDRESS")
+    parser.add_argument("--dcache-admin-ssh.port", type=int, default=DEFAULT_DCACHE_ADMIN_SSH_PORT, dest="dcache_admin_ssh_port", help=f"The port under which the SSH interface of dCache’s `admin` service can be reached. Defaults to `{DEFAULT_DCACHE_ADMIN_SSH_PORT}` if this option isn’t given.", metavar="PORTNUMBER")
+    parser.add_argument("--dcache-admin-ssh.user", type=str, dest="dcache_admin_ssh_user", help="The user used for connecting to the SSH interface of dCache’s `admin` service. Defaults to the name of the user that executes the program.", metavar="USERNAME")
+    parser.add_argument("--dcache-admin-ssh.known-hosts", type=str, action="append", default=[], dest="dcache_admin_ssh_known_hosts", help=f"Adds the known hosts file (using OpenSSH’s `ssh_known_hosts` format) to the list of those from which trusted SSH host keys are read. The list is processed after that of any existing system known hosts files ({sequence_to_separated_str(OPENSSH_GLOBAL_KNOWN_HOSTS_FILES + OPENSSH_USER_KNOWN_HOSTS_FILES, ", ", " and ", element_delimiters="`")}) and in the order as given, with all but the first entry for a given being ignored.", metavar="PATHNAME")
+    parser.add_argument("--dcache-admin-ssh.private-key", type=str, dest="dcache_admin_ssh_private_key", help="The file with the private key used for connecting to the SSH interface of dCache’s `admin` service via the authentication method `publickey`.", metavar="PATHNAME")
+    parser.add_argument("--dcache-admin-ssh.private-key-passphrase", type=FromResourceOrBytesOrStr, dest="dcache_admin_ssh_private_key_passphrase", help="The passphrase used for decrypting the private key specified via the `--dcache-admin-ssh.private-key`-option. If STRING starts with `$`, the passphrase is binarily read from an environment variable with the remainder of STRING as the name. If it starts with `<`, the passphrase is binarily read from a file with the remainder of it as the pathname. If it starts with `=`, the passphrase is the remainder of it.", metavar="STRING")
+    parser.add_argument("--dcache-admin-ssh.passphrase", type=FromResourceOrBytesOrStr, dest="dcache_admin_ssh_passphrase", help="The passphrase used for connecting to the SSH interface of dCache’s `admin` service via the authentication methods `password` and `keyboard-interactive`. If STRING starts with `$`, the passphrase is binarily read from an environment variable with the remainder of STRING as the name. If it starts with `<`, the passphrase is binarily read from a file with the remainder of it as the pathname. If it starts with `=`, the passphrase is the remainder of it.", metavar="STRING")
+    parser.add_argument("--dcache-admin-ssh.no-system-known-hosts", action="store_true", dest="dcache_admin_ssh_no_system_known_hosts", help=f"Don’t add any system known hosts files ({sequence_to_separated_str(OPENSSH_GLOBAL_KNOWN_HOSTS_FILES + OPENSSH_USER_KNOWN_HOSTS_FILES, ", ", " and ", element_delimiters="`")}) to the list of those from which trusted SSH host keys are read.")
+    parser.add_argument("--dcache-admin-ssh.no-default-private-key-locations", action="store_true", dest="dcache_admin_ssh_no_default_private_key_locations", help="Don’t use any private keys from default locations (which are the default of OpenSSH’s `IdentityFile`-option).")
+    parser.add_argument("--dcache-admin-ssh.no-agent", action="store_true", dest="dcache_admin_ssh_no_agent", help="Don’t use any SSH agent.")
+    parser.add_argument("--dcache-admin-ssh.tcp-timeout", type=float, default=DEFAULT_DCACHE_ADMIN_SSH_TCP_TIMEOUT, dest="dcache_admin_ssh_tcp_timeout", help=f"The timeout in seconds for establishing the TCP connection to the SSH interface of dCache’s `admin` service, with non-positive decimals disabling it. Defaults to `{DEFAULT_DCACHE_ADMIN_SSH_TCP_TIMEOUT}` if this option isn’t given.", metavar="DECIMAL")
+    parser.add_argument("--dcache-admin-ssh.banner-timeout", type=float, default=DEFAULT_DCACHE_ADMIN_SSH_BANNER_TIMEOUT, dest="dcache_admin_ssh_banner_timeout", help=f"The timeout in seconds for receiving any banner from the SSH interface of dCache’s `admin` service, with non-positive decimals disabling it. Defaults to `{DEFAULT_DCACHE_ADMIN_SSH_BANNER_TIMEOUT}` if this option isn’t given.", metavar="DECIMAL")
+    parser.add_argument("--dcache-admin-ssh.authentication-timeout", type=float, default=DEFAULT_DCACHE_ADMIN_SSH_AUTHENTICATION_TIMEOUT, dest="dcache_admin_ssh_authentication_timeout", help=f"The timeout in seconds for authenticating to the SSH interface of dCache’s `admin` service, with non-positive decimals disabling it. Defaults to `{DEFAULT_DCACHE_ADMIN_SSH_AUTHENTICATION_TIMEOUT}` if this option isn’t given.", metavar="DECIMAL")
+    parser.add_argument("--dcache-admin-ssh.channel-open-timeout", type=float, default=DEFAULT_DCACHE_ADMIN_SSH_CHANNEL_OPEN_TIMEOUT, dest="dcache_admin_ssh_channel_open_timeout", help=f"The timeout in seconds for opening a (SSH) channel to the SSH interface of dCache’s `admin` service, with non-positive decimals disabling it. Defaults to `{DEFAULT_DCACHE_ADMIN_SSH_CHANNEL_OPEN_TIMEOUT}` if this option isn’t given.", metavar="DECIMAL")
+    parser.add_argument("--dcache-admin-ssh.command-channel-timeout", type=float, default=DEFAULT_DCACHE_ADMIN_SSH_COMMAND_CHANNEL_TIMEOUT, dest="dcache_admin_ssh_command_channel_timeout", help=f"The timeout in seconds for read/write operations on the (SSH) channel of an executed command in the SSH interface of dCache’s `admin` service, with non-positive decimals disabling it. Defaults to `{DEFAULT_DCACHE_ADMIN_SSH_COMMAND_CHANNEL_TIMEOUT}` if this option isn’t given.", metavar="DECIMAL")
+    parser.add_argument("--dcache-admin-ssh.keepalive-interval", type=int, default=DEFAULT_DCACHE_ADMIN_SSH_KEEPALIVE_INTERVAL, dest="dcache_admin_ssh_keepalive_interval", help=f"The interval in seconds at which (client-initiated) SSH keepalive packets are sent to the SSH interface of dCache’s `admin` service, with non-positive integers disabling it. Defaults to `{DEFAULT_DCACHE_ADMIN_SSH_KEEPALIVE_INTERVAL}` if this option isn’t given.", metavar="INTEGER")
+    parser.add_argument("--dcache-admin-ssh.max-concurrent-commands", type=PositiveInt, default=DEFAULT_DCACHE_ADMIN_SSH_MAX_CONCURRENT_COMMANDS, dest="dcache_admin_ssh_max_concurrent_commands", help=f"The maximum number of commands that are concurrently executed via the SSH interface of dCache’s `admin` service. Defaults to `{DEFAULT_DCACHE_ADMIN_SSH_MAX_CONCURRENT_COMMANDS}` if this option isn’t given.", metavar="POSITIVE-INTEGER")
+    parser.add_argument("--metrics.name-prefix", type=str, default=DEFAULT_METRICS_NAME_PREFIX, dest="metrics_name_prefix", help="The prefix for all metric names. Defaults to `{DEFAULT_METRICS_NAME_PREFIX}` if this option isn’t given.", metavar="STRING")
+    parser.add_argument("--metrics.extra-label", type=str, nargs=2, default={}, action=AddMetricsExtraLabel, dest="metrics_extra_labels", help="Adds the extra label `EXTRA-LABEL-NAME` (of each matching metric respectively) to metrics whose name (without the metrics prefix specified via the `--metrics.name-prefix`-option and without any `_`-separator after that) matches the (implicitly fully anchored) Python `re` regular expression `REGULAR-EXPRESSION`.", metavar=("REGULAR-EXPRESSION", "EXTRA-LABEL-NAME"))
+    parser.add_argument("--export-mode", type=ExportMode, choices=[e.value  for e in ExportMode], default=ExportMode.http, help=f"The mode in which the metrics are exported. `{ExportMode.http.value}` (which is the default if this option isn’t given) provides them via a HTTP server (that runs until the program is terminated by a signal or an error), with metrics being (freshly) collected on every scrape. `{ExportMode.stdout.value}` writes them to standard output (once, after which the program terminates). `{ExportMode.file.value}` writes them atomically (via moving a newly created temporary file) to the file specified via the `--output-file`-option (once, after which the program terminates), with the output file being overwritten if it exists already.")
+    parser.add_argument("--http-port", type=int, help=f"The port on which the HTTP server listens when the export mode is `http` (ignored otherwise). Defaults to `{DEFAULT_HTTP_PORT}` if this option isn’t given.", metavar="PORTNUMBER")
+    parser.add_argument("--output-file", type=str, help="The file to which the metrics are written when the export mode is `file` (ignored otherwise).", metavar="PATHNAME")
+    parser.add_argument("--log.level", type=IntOrStr, choices=[ level  for name, number in logging.getLevelNamesMapping().items()  if name != "NOTSET"  for level in (name, number) ], default=DEFAULT_LOG_LEVELNAME, dest="log_level", help=f"The minimum level (name or number) of log messages to be logged. Defaults to `{DEFAULT_LOG_LEVELNAME}` (`{logging.getLevelName(DEFAULT_LOG_LEVELNAME)}`) if this option isn’t given.")
+    
+    cfg = parser.parse_args(namespace=cfg)
+    
+    
+    #configure logging
+    logging_root_logger.setLevel(cfg.log_level)
+    
+    
+    #check whether options that are required depending on other options are given
+    match cfg.dcache_frontend_rest_http_auth_type:
+        case dcache.frontend.HTTPAuthType.none:
+            pass
+        case dcache.frontend.HTTPAuthType.basic_auth:
+            if cfg.dcache_frontend_rest_http_auth_user is None  and  cfg.dcache_frontend_rest_http_auth_passphrase is None:
+                parser.error("the following arguments are required: --dcache-frontend-rest.http-auth-user, --dcache-frontend-rest.http-auth-passphrase")
+            elif cfg.dcache_frontend_rest_http_auth_user is None:
+                parser.error("the following arguments are required: --dcache-frontend-rest.http-auth-user")
+            elif cfg.dcache_frontend_rest_http_auth_passphrase is None:
+                parser.error("the following arguments are required: --dcache-frontend-rest.http-auth-passphrase")
+        case _:
+            raise NotImplementedError(f"Unknown HTTP authentication type `{cfg.dcache_frontend_rest_http_auth_type.name}`.")
+    if cfg.dcache_frontend_rest_tls_client_auth_private_key is not None  and  cfg.dcache_frontend_rest_tls_client_auth_certificate is None:
+        parser.error("the following arguments are required: --dcache-frontend-rest.tls-client-auth-certificate")
+    if cfg.export_mode == ExportMode.file  and  cfg.output_file is None:
+        parser.error("the following arguments are required: --output-file")
+    
+    
+    #warn about ignored options
+    match cfg.dcache_frontend_rest_http_auth_type:
+        case dcache.frontend.HTTPAuthType.none:
+            if cfg.dcache_frontend_rest_http_auth_user is not None:
+                log.warning("The `--dcache-frontend-rest.http-auth-user`-option is ignored.")
+            if cfg.dcache_frontend_rest_http_auth_passphrase is not None:
+                log.warning("The `--dcache-frontend-rest.http-auth-passphrase`-option is ignored.")
+        case dcache.frontend.HTTPAuthType.basic_auth:
+            pass
+        case _:
+            raise NotImplementedError(f"Unknown HTTP authentication type `{cfg.dcache_frontend_rest_http_auth_type.name}`.")
+    if cfg.dcache_frontend_rest_tls_client_auth_private_key_passphrase is not None   and   (cfg.dcache_frontend_rest_tls_client_auth_certificate is None  and  cfg.dcache_frontend_rest_tls_client_auth_private_key is None):
+        log.warning("The `--dcache-frontend-rest.tls-client-auth-private-key-passphrase`-option is ignored.")
+    if cfg.http_port is not None  and  cfg.export_mode in (ExportMode.stdout, ExportMode.file):
+        log.warning("The `--http-port`-option is ignored.")
+    if cfg.output_file is not None    and    ( cfg.export_mode == ExportMode.http   or   (cfg.export_mode == ExportMode.stdout  and  cfg.output_file != "-") ):
+        log.warning("The `--output-file`-option is ignored.")
+    
+    
+    #set option default values (late)
+    if cfg.dcache_frontend_rest_connection_pool_max_size is None:
+        cfg.dcache_frontend_rest_connection_pool_max_size = cfg.dcache_frontend_rest_max_concurrent_requests
+    if cfg.dcache_frontend_rest_connection_pool_max_idle_size is None:
+        cfg.dcache_frontend_rest_connection_pool_max_idle_size = cfg.dcache_frontend_rest_connection_pool_max_size
+    if cfg.http_port is None:
+        cfg.http_port = DEFAULT_HTTP_PORT
+    
+    
+    #if the export mode is `file` and the `--output-file`-option has the special value `-`, change the former to `stdout`
+    if cfg.export_mode == ExportMode.file  and  cfg.output_file == "-":
+        cfg.export_mode = ExportMode.stdout
+    
+    #disable intervals/limits that are set to a non-positive value
+    for a in ("dcache_frontend_rest_connect_timeout", "dcache_frontend_rest_read_timeout", "dcache_frontend_rest_pool_timeout", "dcache_frontend_rest_connection_pool_max_size", "dcache_admin_ssh_tcp_timeout", "dcache_admin_ssh_banner_timeout", "dcache_admin_ssh_authentication_timeout", "dcache_admin_ssh_channel_open_timeout", "dcache_admin_ssh_command_channel_timeout", "dcache_admin_ssh_keepalive_interval"):
+        if getattr(cfg, a) <= 0:
+            setattr(cfg, a, None)
+    
+    #disable limits that are set to a negative value
+    for a in ("dcache_frontend_rest_connection_pool_max_idle_size", "dcache_frontend_rest_connection_pool_max_idle_time"):
+        if getattr(cfg, a) < 0:
+            setattr(cfg, a, None)
+    
+    
+    #warn about suboptimal option values
+    if cfg.dcache_frontend_rest_connection_pool_max_size is not None  and  cfg.dcache_frontend_rest_connection_pool_max_size < cfg.dcache_frontend_rest_max_concurrent_requests:
+        log.warning("The value of the `--dcache-frontend-rest.connection-pool-max-size`-option is less than that of the `--dcache-frontend-rest.max-concurrent-requests`-option, which means that some of the concurrent requests will block until others have finished.")
+    if cfg.dcache_frontend_rest_connection_pool_max_idle_size is not None:
+        if cfg.dcache_frontend_rest_connection_pool_max_size is None:
+            log.warning("The value of the `--dcache-frontend-rest.connection-pool-max-idle-size`-option causes a limit while that of the `--dcache-frontend-rest.connection-pool-max-size`-option does not, which means that some connections might not be re-used.")
+        elif cfg.dcache_frontend_rest_connection_pool_max_idle_size < cfg.dcache_frontend_rest_connection_pool_max_size:
+            log.warning("The value of the `--dcache-frontend-rest.connection-pool-max-idle-size`-option is less than that of the `--dcache-frontend-rest.connection-pool-max-size`-option, which means that some connections might not be re-used.")
+    
+    
+    #manually apply option values
+    collector.MetricName.prefix = cfg.metrics_name_prefix
+    
+    
+    #exit regularly on various exiting signals
+    for s in EXITING_SIGNALS:
+        signal.signal(s, exiting_signal_handler)
+    
+    
+    #determine the system SSH known hosts files
+    if not cfg.dcache_admin_ssh_no_system_known_hosts:
+        cfg.dcache_admin_ssh_system_known_hosts = list(OPENSSH_GLOBAL_KNOWN_HOSTS_FILES)
+        for p in OPENSSH_USER_KNOWN_HOSTS_FILES:
+            cfg.dcache_admin_ssh_system_known_hosts.append(os.path.expanduser(p))
+    
+    
+    #unregister `prometheus_client`’s default collectors
+    # TODO: Keep this aligned with `prometheus_client`’s default collectors.
+    prometheus_client.REGISTRY.unregister(prometheus_client.GC_COLLECTOR)
+    prometheus_client.REGISTRY.unregister(prometheus_client.PLATFORM_COLLECTOR)
+    prometheus_client.REGISTRY.unregister(prometheus_client.PROCESS_COLLECTOR)
+    
+    #create collector registry
+    registry = prometheus_client.CollectorRegistry()
+    
+    
+    with contextlib.ExitStack() as resource_manager:
+        #create collector
+        try:
+            resource_manager.enter_context( collector.DcacheCollector(registry=registry, unmatched_metric_name_regular_expressions_callback=warn_about_unmatched_metric_name_regular_expressions) )
+        except collector.DcacheCollector.exceptions.ConfigurationError as e1:
+            e2 = e1.__cause__
+            match type(e2):
+                case collector.DcacheCollector.exceptions.InvalidMetricNameRegularExpressionError:
+                    parser.error(f"argument --metrics.extra-label: invalid REGULAR-EXPRESSION value: '{e2.__cause__.pattern}'")
+                case collector.DcacheCollector.exceptions.ExtraLabelValueCallablesNotFoundError:
+                    if len(e2.extra_labels) == 1:
+                        parser.error(f"argument --metrics.extra-label: invalid EXTRA-LABEL-NAME value in effect for the '{e2.metric_name}'-metric: '{e2.extra_labels[0]}'")
+                    else:
+                        parser.error(f"argument --metrics.extra-label: invalid EXTRA-LABEL-NAME values in effect for the '{e2.metric_name}'-metric: {sequence_to_separated_str(e2.extra_labels, ", ", " and ", element_delimiters="'")}")
+                case _:
+                    warn(f"Unexpected type `{e2.__class__.__module__}.{e2.__class__.__qualname__}` of the `__cause__`-attribute of a `{e1.__class__.__module__}.{e1.__class__.__qualname__}`-exception.")
+                    raise
+        
+        
+        #export metrics
+        match cfg.export_mode:
+            case ExportMode.http:
+                tmp = prometheus_client.start_http_server(cfg.http_port, registry=registry)
+                
+                #wait for the program to be terminated by a signal or an error
+                # TODO: Remove this handling (including the `tmp`-variable) for
+                #       `prometheus_client` versions < 0.20.0 once newer versions are
+                #       sufficiently widespread.
+                if tmp is None:
+                    #`prometheus_client` versions < 0.20.0:
+                    
+                    import time
+                    while True:
+                        time.sleep(2**16)
+                else:
+                    #`prometheus_client` versions ≧ 0.20.0:
+                    
+                    thread = tmp[1]
+                    thread.join()
+            case ExportMode.stdout:
+                # TODO: Keep the encoding aligned to that used by `prometheus_client`’s
+                #       `generate_latest`-function.
+                print( prometheus_client.generate_latest(registry=registry).decode(encoding="utf-8"), end="" )
+            case ExportMode.file:
+                prometheus_client.write_to_textfile(cfg.output_file, registry=registry)
+            case _:
+                raise NotImplementedError(f"Unknown export mode `{cfg.export_mode.name}`.")
+    
+    
+    return os.EX_OK
+
+
+
+
+if __name__ == "__main__":
+    sys.exit( main() )
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+#Copyright © 2026 Christoph Anton Mitterer <mail@christoph.anton.mitterer.name>
+#
+#
+#This program is free software: you can redistribute it and/or modify it under
+#the terms of the GNU General Public License as published by the Free Software
+#Foundation, either version 3 of the License, or (at your option) any later
+#version.
+#This program is distributed in the hope that it will be useful, but WITHOUT ANY
+#WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+#PARTICULAR PURPOSE.
+#See the GNU General Public License for more details.
+#You should have received a copy of the GNU General Public License along with
+#this program. If not, see <https://www.gnu.org/licenses/>.