Diagnostics and Troubleshooting

Overview#

EventSourcingDB provides a diagnostics endpoint that returns system-level and configuration details. This information can help verify runtime settings, identify resource limitations, or validate license status.

Diagnostics data can be retrieved at any time during normal operation by sending an authorized request.

Requesting Diagnostics#

Changed in 1.3To request a diagnosis, send an HTTP POST request to /api/v2/system/diagnose with the required authorization header:

curl -i \
  -X POST \
  -H "Authorization: Bearer <API_TOKEN>" \
  http://localhost:3000/api/v2/system/diagnose

The server responds with a CloudEvent of the type io.eventsourcingdb.api.server-diagnosed, in an envelope of the type event. Its data holds four sections, which, like their fields, are sorted alphabetically:

• license: The current license: its id, type, and licensee, when it was issued and when it expires (issuedAt, expiresAt), the time that remains (remainingDurationInSeconds), its status, which is valid or expired, and its event capacity (maxEventCapacity).
• options: The options the server was started with: whether HTTP and HTTPS are enabled and their ports, the data directory and whether it is temporary, the heartbeat interval of streams, whether event schemas are required, whether development mode and event signing are enabled, whether the server was started in read-only mode, the rate limit per client, and whether the management UI is enabled.
• system: The operating system, the CPU architecture, the CPU cores of the host (cpuCores) next to those the server may use (usableCpuCores), which the CPU limit of a container lowers, and the memory of the host in bytes (memorySize).
• version: The running EventSourcingDB version and its build revision.

For example, for a server that runs in a container with a limit of four CPUs on a host with eight:

{
  "type": "event",
  "data": {
    "specversion": "1.0",
    "id": "01a17249-c6fb-752e-89a7-834df2a74de4",
    "source": "https://www.eventsourcingdb.io",
    "type": "io.eventsourcingdb.api.server-diagnosed",
    "subject": "/api/v2/system/diagnose",
    "time": "2026-10-25T09:00:00.123456789Z",
    "datacontenttype": "application/json",
    "data": {
      "license": {
        "expiresAt": "2027-10-01T00:00:00Z",
        "id": "6f1c2a4e-8b3d-4e5f-9a0b-1c2d3e4f5a6b",
        "issuedAt": "2026-10-01T00:00:00Z",
        "licensee": "City Library",
        "maxEventCapacity": 9223372036854775807,
        "remainingDurationInSeconds": 29429999.876543213,
        "status": "valid",
        "type": "regular"
      },
      "options": {
        "areEventSchemasRequired": false,
        "dataDirectory": "/var/lib/esdb",
        "heartbeatIntervalInSeconds": 1,
        "httpPort": 3000,
        "httpsPort": 4000,
        "isDataDirectoryTemporary": false,
        "isDevelopmentModeEnabled": false,
        "isEventSigningEnabled": true,
        "isHttpEnabled": true,
        "isHttpsEnabled": false,
        "isReadOnly": false,
        "rateLimitRequestsPerSecond": 4000,
        "withUi": false
      },
      "system": {
        "architecture": "amd64",
        "cpuCores": 8,
        "memorySize": 34359738368,
        "operatingSystem": "linux",
        "usableCpuCores": 4
      },
      "version": {
        "eventSourcingDb": "1.3.0",
        "revision": "8d2f6a1b9c4e7f3a0b5d8e2c6f9a1b4d7e0c3f6a"
      }
    }
  }
}

Durations are given in seconds, with the unit in the name of the field. The diagnosis reports no secrets: neither the API token, nor the license itself, nor the signing key, nor the paths of the files that hold them. And it reports what the server was started with, not what it is doing now: isReadOnly says whether it was started in read-only mode, not whether it is in read-only mode at the moment, which the health route tells.

Typical Use Cases#

Diagnostics information is useful in various operational scenarios. It verifies that the correct EventSourcingDB version and build are deployed, for example after an upgrade. It also helps to inspect system resources such as CPU cores and memory size when investigating performance issues.

Additionally, diagnostics provide details about the license status, including validity and expiration dates, which can help prevent unexpected disruptions. Reviewing runtime configuration settings further supports troubleshooting by highlighting misconfigurations or unexpected option values.

Diagnostics information provides an immediate overview of the database's operational environment, helping to detect issues early and maintain system stability.