Database Health reporting

Release pending. These interfaces are part of the Database Health release being verified. Confirm availability in your deployment before integrating.

Authentication and privacy

Create an ingest-scoped API key for the status page. Send Authorization: Bearer <ingest key> over HTTPS. The page needs Database Health access. Ingest keys can submit measurements; they cannot read the private dashboard. Keep keys in server-side secret configuration and rotate them if exposed.

Use safe service, environment, target and pool aliases. Never send database passwords, connection strings, query text or document contents. A server observation and an application pool interval describe different measurements and are not added together.

POST /api/v1/database-health/observations

Send one version 1 observation per request. The example is illustrative: replace its UUID, timestamp and measurements with your collector's values. Leave unmeasured fields as null.

{
  "version": 1,
  "observationId": "f1e648c2-3094-4e99-8bbf-c3c9a60e676a",
  "sourceId": "orders-primary",
  "environment": "production",
  "target": "orders",
  "connectionId": null,
  "sample": {
    "result": {
      "engine": "postgresql",
      "outcome": "connected",
      "checkedAt": "2026-09-07T12:00:00.000Z",
      "latencyMs": 2,
      "capabilities": []
    },
    "measurements": {
      "connections": 12,
      "connectionLimit": 100,
      "activeSessions": null,
      "blockedSessions": null
    }
  }
}

Valid engines are mongodb, postgresql and mysql. Each observation is limited to 16 KiB. A page accepts at most 12 requests per minute and retains at most 20 server source identities. Samples must be within the last 15 minutes, with at most 30 seconds of future clock skew. Observation history expires after 24 hours.

Reuse the observationId and identical body for retries. A duplicate is acknowledged without storing it twice; reusing the UUID with different data returns 409. A source's engine, environment, target and connection association are fixed: create a new sourceId when any changes.

Set connectionId to a saved direct connection's reporting ID to associate the sources. The connection must belong to the same page and engine. Association preserves separate measurements; it does not merge their counts.

POST /api/v1/database-health/reports

This endpoint accepts versioned application pool intervals rather than server observations. The reporter package supplies the runtime-validated contract. A report identifies its session, sequence, service, environment, revision, session start and interval bounds, then supplies pool measurements and exporter failures/drops. Preserve session identity and interval sequencing when retrying.

The following complete request is illustrative, not live telemetry. Replace every identity, timestamp and measurement with values from your application. Save the JSON as database-report.json. Any language can produce this contract; using the Node.js SDK is optional.

{
  "version": 1,
  "session": "72945570-fd17-43e2-8e70-e773a8a4d8d2",
  "sequence": 1,
  "service": "orders-api",
  "environment": "production",
  "revision": "release-42",
  "startedAt": "2026-09-08T12:00:00.000Z",
  "from": "2026-09-08T12:00:00.000Z",
  "to": "2026-09-08T12:01:00.000Z",
  "pools": [
    {
      "system": "mongodb",
      "target": "orders",
      "pool": "application",
      "serverPool": "server-1",
      "driverVersion": "6.20.0",
      "coverage": "complete",
      "supported": [
        "open",
        "busy",
        "idle",
        "waiting",
        "acquisition",
        "failures",
        "created",
        "closed"
      ],
      "snapshot": {
        "open": 4,
        "busy": 1,
        "idle": 3,
        "waiting": 0
      },
      "peaks": {
        "open": 4,
        "busy": 2,
        "waiting": 0
      },
      "acquisition": {
        "counts": [
          0,
          1,
          0,
          0,
          0,
          0,
          0,
          0,
          0,
          0,
          0
        ],
        "sumMs": 4
      },
      "failures": 0,
      "created": 4,
      "closed": 0,
      "minimum": 0,
      "maximum": 10
    }
  ],
  "exporter": {
    "dropped": 0,
    "failures": 0
  }
}

Set INBRIEF_ORIGIN to your deployment's HTTPS origin. Set INBRIEF_CURL_CONFIG to an owner-readable file provisioned through your normal secret mechanism, containing a curl header entry for Authorization: Bearer <ingest key>. Do not commit that file, paste a real key into shell history, or put credentials in the URL. This keeps the actual key out of command-line arguments.

curl --fail-with-body --max-time 3 --proto '=https' \
  --config "$INBRIEF_CURL_CONFIG" \
  --header 'Content-Type: application/json' \
  --data-binary @database-report.json \
  "$INBRIEF_ORIGIN/api/v1/database-health/reports"

Successful durable acceptance returns HTTP 201 with {"version":1,"accepted":true,"duplicate":false}. An identical retry returns the same acknowledgement with duplicate:true. Acknowledgement means persistence completed; it does not claim the database is healthy.

A fresh process chooses a new session UUID. Its service, environment, revision and startedAt remain fixed. Increment sequence for each new non-overlapping interval; retry the same body with the same sequence. Identical retries are acknowledged, changed content conflicts, and delayed reports do not replace newer current snapshots. Reports may arrive up to 15 minutes late with 30 seconds of future clock tolerance.

Gauges describe the interval's final snapshot; peaks describe the highest observed value within that interval. Busy means checked out, and open equals busy plus idle when all three are known. Creation, closure and failure counters cover only that interval and reset for the next report. Exporter dropped/failures counters describe the reporting process's lifetime.

Declare only measurements the adapter supports. Unsupported measurements must be null, and partial coverage can leave supported values or interval peaks unknown. Complete coverage requires all declared values and valid peaks. Each serverPool alias distinguishes a server pool within the process; do not combine topology members.

Acquisition is a histogram of successful acquisitions in milliseconds. Its 11 disjoint counts use upper bounds 1, 5, 10, 25, 50, 100, 250, 500, 1000, 5000 and positive infinity. sumMs is the total successful acquisition duration; failures are separate. Merge bucket counts and sums across intervals before deriving a percentile. The displayed p95 is a bucket upper bound, not an average of p95 values.

Requests are limited to 64 KiB and 16 pools. An interval must span more than zero and no more than 120 seconds, after the session start. Per-session limits are 120 reports and 16 distinct server pools per hour. The page limit is 1,024 reporting requests per minute. Current pool measurements expire after three minutes; missing reports do not become zero.

Optional Node.js reporter

The reporter is a private pilot package supplied as a tarball, not a public npm package. It runs on Node.js 24. Attach it before the application pool is used, send to your InBrief origin plus /api/v1/database-health/reports, and stop the reporter during application shutdown. It does not close the application's database clients.

SDK reports use 60-second intervals with jitter, up to four queued reports, three attempts per report and a three-second HTTP timeout. Inspect exporter statistics for dropped reports or failed exports. Direct-connection check intervals do not alter SDK export intervals.

Errors and retry behavior

400 means the contract or sample time is invalid; 401 means the key is missing, invalid or revoked; 403 means the caller lacks the required access; 404 can indicate an unavailable feature or scoped resource; 409 means conflicting identity or data; 413 means the payload is too large; 429 means a rate or source limit was reached. Correct permanent errors before retrying. Back off on temporary failures and preserve the original identity and body.

For setup, pricing and interpretation, see Database Health. The existing Event API reports request traffic for Internal analytics and remains separate.