HYPHAby S33D
Documentation › Integrations

Databases, caches, queues and search engines

Each integration reads the software with a read-only monitoring account, or through the local socket when possible.

PostgreSQL

On by default if the socket /var/run/postgresql/.s.PGSQL.5432 exists. The agent connects through that socket as the system user postgres (peer authentication, no password), in a read-only session.

integrations:
  postgres:
    enabled: auto
    # or a monitoring account holding the pg_monitor role:
    # dsn: postgres://hypha:password@127.0.0.1:5432/postgres?sslmode=disable
    dbm: auto

Metrics: connections and their share of the maximum, committed and rolled-back transactions, rows read and written, database sizes, cache hit ratio, locks, waiting queries, longest query, idle-in-transaction sessions, background writer, primary or replica role, replication lag (postgresql.replication_delay, postgresql.replication.wal_lag_bytes).

Most expensive queries (DBM)

If the pg_stat_statements extension exists in the postgres database, the agent sends the 50 most expensive queries (total time) every 5 minutes, with the normalised text PostgreSQL returns. The Databases page ranks them by total time, calls or mean time, with the cache hit ratio and each query's trend.

-- postgresql.conf: shared_preload_libraries = 'pg_stat_statements' (restart needed if missing)
CREATE EXTENSION IF NOT EXISTS pg_stat_statements;

The agent checks for the extension again once an hour: after creating it, restart hypha-agent to see it at once.

MySQL and MariaDB

Without settings, the agent connects as root through the local socket /run/mysqld/mysqld.sock (socket authentication of Debian and Ubuntu packages). Otherwise, a monitoring account:

CREATE USER 'hypha'@'127.0.0.1' IDENTIFIED BY '…';
GRANT PROCESS, REPLICATION CLIENT ON *.* TO 'hypha'@'127.0.0.1';
integrations:
  mysql:
    dsn: "hypha:password@tcp(127.0.0.1:3306)/"

Metrics: connections (current, maximum, share used, refused, aborted), queries and slow queries, commands by type, running threads, on-disk temporary tables, InnoDB buffer pool, row lock waits, database sizes, replication lag and state (mysql.replication).

Redis and Valkey

The INFO command, on 127.0.0.1:6379 by default, or a Unix socket.

integrations:
  redis:
    address: 127.0.0.1:6379
    # username: hypha   # Redis 6+ ACL
    # password: "…"

Metrics: connected and blocked clients, used memory, limit, fragmentation, cache hit rate, keys, expired and evicted keys, commands, network throughput, replication and replicas, persistence to disk (redis.persistence).

Memcached

The stats command on 127.0.0.1:11211: bytes and limit, get hit rate, evictions, connections and refused connections, items, threads.

MongoDB

A connection URI, mongodb://127.0.0.1:27017 by default. With authentication on, an account with the clusterMonitor role:

integrations:
  mongodb:
    uri: "mongodb://hypha:password@127.0.0.1:27017/?authSource=admin"

Metrics: current and available connections, operations, read and write queues, WiredTiger cache, resident memory, database sizes, replica set state and lag.

RabbitMQ

The management API (http://127.0.0.1:15672), with an account holding the monitoring tag (without an account: guest, which RabbitMQ only accepts from the machine itself).

integrations:
  rabbitmq:
    url: http://127.0.0.1:15672
    username: hypha
    password: "…"

Metrics: connections, channels, consumers, queues, ready and unacknowledged messages, publish, deliver and ack rates, node alarms (memory, disk, descriptors) through the rabbitmq.node check, messages per queue.

OpenSearch and Elasticsearch

The REST API of the local node: the agent finds the address port 9200 listens on, or uses url.

integrations:
  opensearch:
    url: https://127.0.0.1:9200
    username: hypha
    password: "…"
    insecure: false     # true only for a self-signed certificate

Metrics: cluster health (opensearch.cluster_health), nodes, active, initialising and unassigned shards, pending tasks, JVM heap and garbage collection, disk usage, documents, indexing and search (rate, latency), rejected writes and searches, tripped circuit breakers.

SQL Server

On Windows, through performance counters, when SQL Server is present: mssql.buffer_cache_hit_ratio, mssql.batch_requests_per_s, mssql.user_connections.

PgBouncer

Admin console (pgbouncer database), with an account listed in stats_users of pgbouncer.ini:

integrations:
  pgbouncer:
    dsn: postgres://hypha:password@127.0.0.1:6432/pgbouncer?sslmode=disable

Metrics: active and waiting clients, active, idle, used, tested and logging-in server connections, longest wait (pgbouncer.pools.maxwait) per database and user; queries, transactions, bytes received and sent, average query and transaction times per database; connections and pool size per database. Checks pgbouncer.can_connect and pgbouncer.database (warning for a paused or disabled database).

ProxySQL

Admin interface (port 6032), with the admin-stats_credentials account (reads the stats tables only):

integrations:
  proxysql:
    dsn: "stats:password@tcp(127.0.0.1:6032)/"

Metrics: active transactions, client and server connections (open, created, aborted), queries and slow queries, processing time, buffer memory, query cache (hit rate), denied accesses; per MySQL server behind ProxySQL (hostgroup, backend tags): used and free connections, successful and failed connections, queries, bytes, latency. One proxysql.backend.status check per server: ONLINE OK, OFFLINE_SOFT warning, SHUNNED and OFFLINE_HARD critical.

ClickHouse

HTTP interface (http://127.0.0.1:8123), tables system.metrics, system.events and system.asynchronous_metrics. A read-only account is enough (readonly = 1); without an account, the default user. The identity travels in the X-ClickHouse-User and X-ClickHouse-Key headers, never in the URL.

integrations:
  clickhouse:
    username: hypha
    password: "…"

Metrics: running, counted and failed queries (SELECT and INSERT apart), average duration, rows and bytes inserted and read, delayed and rejected inserts, merges and mutations, connections per protocol, tracked and resident memory, parts per partition (clickhouse.part.max_per_partition), read-only replicas, replica delay and queue, number of databases, tables and parts, uptime.

CouchDB

Node REST API (/_node/_local/_stats, /_system, /_active_tasks). CouchDB 3 restricts these pages to a server administrator: the probe waits for that account.

integrations:
  couchdb:
    url: http://127.0.0.1:5984
    username: admin
    password: "…"

Metrics: HTTP requests (including bulk requests and view reads), responses per status class, response time (mean, p95, p99, max), document reads and writes, open databases and files, running, pending and crashed replications (couchdb.couch_replicator.jobs.crashed), active tasks per type, Erlang memory and run queue.

Couchbase

Cluster REST API (port 8091), with a "Read-Only Admin" account:

integrations:
  couchbase:
    url: http://127.0.0.1:8091
    username: hypha
    password: "…"

Metrics: cluster RAM and disk (totals, used, quotas), active nodes, balance; per node: CPU, memory, operations, items; per bucket: operations per second, items, memory, disk, RAM quota used (couchbase.by_bucket.quota_percent_used). One couchbase.node.health check per node: critical out of the cluster or unhealthy, warning while warming up.

Monitor templates

The Databases, Message queues and Search families of the catalogue: unreachable, replication stopped or lagging, connections almost saturated, Redis memory almost full, Redis persistence failing, growing RabbitMQ queue, RabbitMQ node alarm, degraded OpenSearch cluster, saturated JVM heap, disk at watermark, rejected writes; waiting PgBouncer clients and wait too long, MySQL server shunned by ProxySQL, too many ClickHouse parts, read-only ClickHouse replica, failing CouchDB replication, Couchbase node down, Couchbase bucket almost full.

Updated: 20 November 2026