HYPHAby S33D
Documentation › Integrations

Generic collection: Prometheus, Nagios plugins and syslog

Three engines to monitor what has no dedicated integration: any software that publishes its metrics in Prometheus format, the thousands of existing Nagios and Centreon plugins, and logs sent over syslog.

OpenMetrics and Prometheus reader

The agent reads /metrics pages in the Prometheus exposition format (text 0.0.4) or OpenMetrics 1.0 (text). One entry per target, under integrations.openmetrics:

integrations:
  openmetrics:
    - profile: node_exporter              # http://127.0.0.1:9100/metrics by default
    - name: myapp
      url: https://app.example:8443/metrics
      interval: 30s                       # 30 s by default, at least 10 s
      timeout: 10s
      namespace: myapp                    # prefix of the HYPHA metrics
      metrics: [http_requests_total, "job_*", "re:queue_(depth|age)_.*"]
      exclude_metrics: ["go_*"]
      rename: {http_requests_total: http.requests}
      labels: [code, method]              # labels kept as tags; "*" = all
      tags: {team: payments}
      bearer_token_file: /etc/hypha/myapp.token   # read again at every scrape
      ca_file: /etc/hypha/internal-ca.pem # also cert_file, key_file, insecure
      max_series: 2000

Lists from several conf.d files add up: one file per application. Other headers go in headers; username and password give basic authentication. Header values and passwords are never shown by hypha-agent check-config.

How metrics are translated

Prometheus typeWhat HYPHA receives
gauge, unknownthe value as is
countera per-second rate (byte_per_second for _bytes), nothing on the first read or after a reset
histogram<name>.count and <name>.sum (rates), <name>.avg, percentiles <name>.p50, .p95, .p99 estimated like histogram_quantile; buckets with histogram_buckets: true
summary<name>.count, <name>.sum, <name>.avg and every published quantile (0.5 → p50, 0.999 → p99_9)

HYPHA name: <namespace>.<name> (a counter loses its _total suffix), or <namespace>.<rename>. Prometheus labels outside labels are dropped, and series that only differ by them are added up (for example node_cpu_seconds_total without the cpu label gives the time of all cores). Every series carries instance_name and endpoint.

Cardinality guard

Beyond max_series series for a target (2,000 by default), the agent keeps the first ones in alphabetical order, drops the rest, says so in the agent status and log, and publishes openmetrics.series.dropped. The "OpenMetrics series cap reached" monitor template warns when it lasts.

Built-in profiles

A profile brings the port, path, selected metrics, their names and the useful labels. What the entry adds (metrics, rename, labels, tags) completes the profile.

ProfilePortMetrics (namespace)
node_exporter9100node.load.1, node.cpu.seconds by mode, node.memory.*, node.filesystem.* by mount point, node.network.* and node.disk.* by device, node.procs.*, node.filefd.*, node.hwmon.temperature, node.time.offset
prometheus9090prometheus.tsdb.head_series, .tsdb.samples_appended, .http.requests by code, .http.request_duration.p95, .target.interval_length.p99, .rule.evaluation_failures, .notifications.dropped, .config.last_reload_successful, .process.resident_memory

Twenty-nine more profiles (Consul, Vault, etcd, Traefik, Kafka through the JMX exporter, GitLab, Argo CD…) are described in Software exposing Prometheus.

Agent check and metrics

Nagios, Monitoring Plugins and Centreon plugins

The agent runs Nagios-format plugins and turns them into a check and metrics:

integrations:
  nagios:
    - name: root-disk
      command: check_disk -w 20% -c 10% -p /
      interval: 60s                        # at least 10 s
      timeout: 30s                         # at most the interval
    - name: local-http
      command: [check_http, -H, 127.0.0.1, -u, /health]
      user: nagios                         # account running the plugin (Linux)
    - name: centreon-load
      command: [/usr/bin/perl, /usr/lib/centreon/plugins/centreon_plugins.pl,
                --plugin=os::linux::local::plugin, --mode=load]
      tags: {role: web}

Security

Usual packages: monitoring-plugins (Debian, Ubuntu), nagios-plugins-all (EPEL); Centreon plugins: the open centreon-plugins repository (Perl, with libjson-xs-perl).

Syslog reception

The agent can receive logs from your devices (firewalls, switches, routers, NAS, printers) and servers. Off by default.

syslog:
  enabled: true
  udp: 0.0.0.0:514                 # empty = no UDP
  tcp: 0.0.0.0:514                 # empty = no TCP
  allowed_sources: [192.0.2.0/24]  # empty = any source
  max_connections: 64
  rate_limit: 2000                 # lines per second, beyond that dropped and counted
  parsers:
    - {match: 192.0.2.10, parser: kv}
  tags: {site: hq}

Received logs are searched like the others: source:syslog @syslog.hostname:fw01, source:syslog status:error.

Models for firewalls and routers (Fortinet, Stormshield, pfSense, OPNsense, Palo Alto, Cisco ASA, SonicWall, WatchGuard, Check Point, MikroTik, Ubiquiti): see Network and security devices (syslog).

Monitor templates and dashboards

Collecte générique family of the monitor catalogue: OpenMetrics target unreachable, series cap reached, Nagios plugin alerting, syslog reception failing, silent syslog device, dropped syslog lines, severe errors received by syslog.

The dashboard catalogue offers "Cibles OpenMetrics et Prometheus", "node_exporter (Prometheus)", "Serveur Prometheus", "Plugins Nagios et Centreon" and "Journaux reçus par syslog".

Updated: 20 November 2026