Skip to main content

CodeXray Database Agent

The CodeXray Database Agent connects directly to your databases and polls their internal statistics — giving you engine-level visibility that no amount of application-side instrumentation can reproduce: active connections, locks, replication lag, cache hit ratios, top queries by engine-reported cost, and more.

It's the engine that powers the Databases module and enriches the Database Insights tab with engine telemetry alongside application spans.

Two lenses, one picture

Application-side tracing tells you which queries your service is calling. The Database Agent tells you how the engine is serving them. Together, they tell you whether a slow query is an application bug, a schema problem, or the engine running out of headroom.

Supported Engines​

EngineType CodeNotes
PostgreSQLPGIncludes query stats, locks, replication, and bloat metrics
MySQLMYUses performance_schema — ensure it's enabled
MSSQLMSSQL Server DMVs
MongoDB—Supports connection URI or traditional host/port
OracleORAWR-style views
Cassandra—JMX + system tables
CouchbaseCBREST API polling

Each engine has its own sample configuration in the agent's sampleConfig/ directory — start from the one that matches your engine.

How It Works​

The agent is a long-running process that, on a configurable cycle, connects to each configured database using a read-only monitoring user, runs a well-defined set of diagnostic queries, and ships the resulting metrics and slow-query data to the CodeXray backend.

Each database you monitor is described by its own YAML config entry. A single agent process can monitor many databases — one config file per database, or one directory with many configs.

Not on the hot path

The Database Agent polls the engine's existing stats views — it does not sit in the query path, add latency to user queries, or modify anything. Worst case, a misconfigured monitoring user sees a few extra reads on system views.

Requirements​

Host​

  • Linux (recommended) — Ubuntu 20.04+, RHEL/Rocky 8+, Debian 11+. Docker-compatible.
  • Windows — supported, ships as a cross-compiled binary.
  • Architecture: amd64 (default) or arm64.

Network​

  • The agent must be able to reach each monitored database (direct TCP, or via bastion/proxy you configure).
  • Outbound connectivity to the CodeXray collector endpoint.

Database permissions​

The agent needs a read-only monitoring user on each database. Exact privileges vary by engine:

EngineMinimum privileges
PostgreSQLpg_monitor role (covers pg_stat_*, pg_stat_statements). Install the pg_stat_statements extension for slow-query analysis.
MySQLREPLICATION CLIENT, PROCESS, SELECT on performance_schema.*.
MSSQLVIEW SERVER STATE, VIEW ANY DEFINITION.
MongoDBclusterMonitor role.
OracleSELECT ANY DICTIONARY (or granular grants on V$ views).
CassandraRead access to system keyspaces.
Couchbasero_admin role.

Credentials​

  • A project API key from the CodeXray UI (used to authenticate the agent to the backend).

Installation​

Run the agent as a container, mounting your config directory:

docker run -d \
  --name codexray-db-agent \
  -v $(pwd)/configs:/home/configs \
  -e DB_USER=monitor_user \
  -e DB_PASSWORD=secure_password \
  ghcr.io/codifinary/codexray-db-agent:latest \
  --config /home/configs/pg.yaml \
  --db-user "$DB_USER" \
  --db-password "$DB_PASSWORD"

Point the container at a single config file or an entire config directory (it'll load every .yaml inside).

Standalone binary​

Cross-platform binaries are available for Linux (amd64/arm64) and Windows (amd64). Drop the binary on a host that can reach your databases and run:

./codexray-db-agent --config ./configs/pg.yaml \
  --db-user monitor_user --db-password "$DB_PASSWORD"

For long-running use, wrap it in a systemd unit (Linux) or a Windows Service.

Configuration​

Each database is described by a YAML file. A minimal PostgreSQL example:

codexray:
  service_name: orders-db-prod
  X-API-Key: eyJhbGciOi...your-project-api-key
  codexray_backend: https://your-codexray.example.com
  secure: true
  type: PG
  cronCycle: 30            # poll every 30 seconds
  hostname: orders-db.internal
  port: 5432
  user: monitor_user       # optional if using --db-user flag
  password: ""             # optional if using --db-password flag
  database: orders
  postgres:
    sslmode: require
    isExtension: true      # pg_stat_statements installed
    isQueryExtension: true
  queryLimit: 10           # number of top queries to report
  queryThresholdTime: 1    # milliseconds — filter out trivial queries
  queryTimeOut: 10         # seconds — per-poll timeout
  logPath: logs/postgres.log

Key fields​

FieldMeaning
service_nameName shown in the CodeXray Databases view. Keep it unique and descriptive.
X-API-KeyProject API key from the CodeXray UI.
codexray_backendBase URL of your CodeXray collector.
typeEngine type code (see Supported Engines table).
cronCyclePolling interval in seconds. 30s is typical; use 10s only for high-scrutiny production DBs.
hostname, port, databaseConnection target.
user, passwordCredentials — prefer passing via --db-user / --db-password CLI flags and leaving these blank.
queryLimitHow many top queries to send per cycle. 10 is a sensible default.
queryThresholdTimeExclude queries faster than this from slow-query analysis (in milliseconds).
queryTimeOutPer-poll connection/query timeout in seconds.

Credentials best practices​

Never commit credentials in YAML

The safest pattern: leave user and password blank in the YAML, and pass them via --db-user and --db-password flags — backed by a secrets manager or environment variables at runtime.

Multiple databases in one run:

./codexray-db-agent --config ./configs/ \
  --db-user "user1|user2|user3" \
  --db-password "pass1|pass2|pass3"

Use a pipe (|) separator — the agent matches them to configs in load order.

MongoDB URIs: pass the full URI with --mongo-uri:

--mongo-uri "mongodb://admin:secret@cluster.example.com:27017"

Verifying It's Working​

  1. Agent logs — the agent logs every poll cycle with the service name and status. Look for "successfully sent batch" or engine-specific confirmations.
  2. CodeXray UI — your database appears in the Databases view within a cycle or two. Top Queries, Metrics, and Active Connections views populate after a few polls of data have accumulated.
  3. Connection test — on the agent host, make sure the monitoring user can connect and read the relevant stats views (psql, mysql, mongosh, etc.).
Troubleshooting "no data in Databases view"

Most failures are authentication or permission issues. Check the agent's log file (logPath) — connection failures and permission errors are logged explicitly with the exact SQL that failed. Fix the monitoring user's grants and the agent will pick up on its next cycle.

Next Steps​