Logging and Monitoring

This guide explains how to observe and monitor EventSourcingDB in production environments. It describes the built-in log output, available health and license endpoints, and how to integrate them into existing monitoring setups.

Logging#

EventSourcingDB logs to standard output using structured JSON. It uses the Go slog standard library, which produces logs that are machine-readable and well-suited for centralized log aggregation.

Each log entry includes a timestamp, log level, message, and optional structured fields such as additional data. The following log levels are used:

INFO: Normal operational messages
WARN: Unusual behavior or predictions of errors
ERROR: Non-recoverable problems

If EventSourcingDB cannot start, for example because a required flag is missing, it logs the reason as ERROR and exits with code 1. In that case, it also writes the error and its usage as plain text to standard error.

Log messages can be consumed by any system capable of parsing and/or forwarding JSON logs.

Health and Monitoring EndpointsChanged in 1.3#

EventSourcingDB provides two HTTP endpoints for status checks and monitoring. Both endpoints use the HTTP method GET.

`/api/v1/ping` – Liveness Check#

This endpoint returns the HTTP status code 200 OK as soon as the database process is running. It requires no authentication and is ideal for liveness and readiness probes or for use with load balancers:

curl -i \
  http://localhost:3000/api/v1/ping

`/api/v1/health` – Health and Metrics#

This endpoint provides detailed health information. By default, it returns a response based on the Health Check Response Format for HTTP APIs. You can change the format using the format query parameter:

?format=rfc returns the same default format, explicitly marked
?format=openmetrics returns the metrics in the OpenMetrics format, see the note below

A valid API token is required.

curl -i \
  -H "Authorization: Bearer <API_TOKEN>" \
  http://localhost:3000/api/v1/health?format=openmetrics

Removed in 1.3Broken in 1.2, fixed in 1.3Prometheus cannot scrape the OpenMetrics output of /api/v1/health?format=openmetrics, and refuses every scrape: the output writes the states of store_operation_mode with the name of the label in quotes and its value without, as in store_operation_mode{"store_operation_mode"=locked} 0, and it ends with #EOF instead of # EOF.

Management UI#

The built-in management UI provides a visual dashboard to display status and metrics from the above endpoints. It is most useful in local or small-scale environments that lack external observability tooling.

In larger setups, health and metrics data should be pulled directly via the API. In such cases, you may want to disable or restrict access to the management UI.

Best Practices#

Changed in 1.3Use /api/v1/ping for lightweight availability checks, and /api/v1/health for monitoring the health of the database. Always capture structured logs from standard output and forward them using a centralized logging pipeline. Restrict access to sensitive endpoints using API tokens and firewall rules, and avoid exposing metrics to the public internet.

This setup provides robust, standards-based observability – suitable for both local development and production-scale deployments.