Skip to content

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:

  • DEBUG: Diagnostic details
  • INFO: Normal operational messages
  • WARN: Unusual behavior or predictions of errors
  • ERROR: Non-recoverable problems
  • FATAL: Critical failures which result in a shutdown and usually lead to process termination

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

Health and Monitoring Endpoints

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 Prometheus-compatible metrics

A valid API token is required.

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

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

Use /api/v1/ping for lightweight availability checks, and /api/v1/health?format=openmetrics for Prometheus-based monitoring. 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.