Integrations

Proxima Console integrations extend the agent's monitoring capabilities beyond system-level metrics. Each integration is a collector plugin that connects to a specific service (database, message queue, web server, etc.) and reports metrics and status back to the backend.

How integrations work

1. Agent configuration — You enable a collector in the agent's YAML config under the collectors array, or let auto-discovery detect services automatically.
2. Metrics collection — The agent runs the collector on the configured interval, gathering service-specific metrics. Each metric is labeled with collector=<name> for frontend filtering.
3. Status reporting — Each collector reports its status (ok or error) in every heartbeat, which the backend stores in the host_integrations table.
4. Frontend visibility — The Integrations page shows all available integrations, how many hosts are using each, and their health status. Each integration's detail page includes a Metrics tab with dedicated dashboards.

Architecture

Agent                          Backend                    Frontend
┌──────────────┐  heartbeat   ┌──────────────────┐       ┌──────────────┐
│  Collector   │──────────────│  Heartbeat Worker │──────▶│ Integrations │
│  (PostgreSQL)│  + status    │  → upsert         │       │ Page         │
└──────┬───────┘              │    host_integrations│     └──────┬───────┘
       │ metrics              └──────────────────┘              │
       │ (collector=<name>)   ┌──────────────────┐       ┌──────▼───────┐
       └──────────────────────│  Metrics Worker   │      │ Integration  │
           NATS publish       │  → VictoriaMetrics│──────▶│ Metrics Tab │
                              └──────────────────┘       │ (filtered by │
                                                         │  collector)  │
                                                         └──────────────┘

Integration catalog

The backend maintains a catalog of known integration types in the integrations database table. Currently available:

Integration	Category	Description
PostgreSQL	Database	Connections, cache hit ratio, transactions, deadlocks, replication lag, database size, query statistics
Nginx	Web	Active connections, request rates, connection states via stub_status
Docker	Container	Container states, per-container CPU/memory/network/block I/O, daemon config, container inventory

Collector status

Each host-integration pairing tracks a status and version:

Field	Description
Status	ok (running), error (connection refused, auth failure, etc.), discovered (detected but needs manual configuration), or unknown (not yet reported)
Version	The detected server version (e.g., "PostgreSQL 18.2", "nginx/1.27.4"). Populated by collectors that implement the VersionReporter interface. Displayed as a version badge next to the collector name on both the Integration Detail Page (host rows) and the Host Detail Page (Integrations tab).

Collector labels

The agent injects a collector=<name> label into every metric produced by a plugin collector. For example, a PostgreSQL collector named pg-main adds collector=pg-main to all pg_* metrics. This label:

• Prevents series collisions — Multiple collectors of the same type (e.g., two PostgreSQL instances) produce distinct series in VictoriaMetrics.
• Enables frontend filtering — The integration Metrics tab filters series by the collector=<name> prefix to show only the selected collector's data.

Integration metrics dashboard

Each integration's detail page includes a Metrics tab that displays a dedicated dashboard for the integration's metrics. The dashboard is driven by a per-integration config (integration-metrics.ts) that defines:

• Summary cards — Key metrics displayed as stat cards at the top (e.g., active connections, cache hit ratio)
• Metric groups — Charts organized by category (e.g., connections, cache, transactions, deadlocks & replication lag, database size, query stats)
• Display names — Human-readable names for metric keys
• Chart types — Per-group and per-metric chart type overrides (area, line) with overlay support

When multiple collectors of the same type exist on a host, a collector picker lets the operator switch between instances.

Webhook Sources (External Change Events)

In addition to collector-based integrations, Proxima Console can receive change events from external tools via webhooks. These are not agent plugins — they are HTTP endpoints that external tools (GitLab, GitHub, ArgoCD) post to directly.

Webhook events appear on the Events Timeline alongside agent-detected file changes, enabling root cause correlation across the delivery pipeline (e.g., merge → deploy → config change → metric spike).

Source	Event Types
GitLab	push, tag, merge request, pipeline, job
GitHub	push, pull request, release, workflow run, check suite
ArgoCD	sync, health degraded, sync failed

See the Webhook Sources page for setup instructions and full documentation.

API endpoints

Method	Path	Description
GET	/api/v1/integrations	List all integrations with host counts
GET	/api/v1/integrations/{id}	Get a single integration
GET	/api/v1/integrations/{id}/hosts	List hosts using an integration
GET	/api/v1/clients/{id}/integrations	List integrations scoped to a client
GET	/api/v1/hosts/{id}/integrations	List integrations on a specific host