# 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](https://pkg.go.dev/log/slog)**, 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 Endpoints *(Changed 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**:

```shell
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](https://datatracker.ietf.org/doc/html/draft-inadarei-api-health-check-06)**. 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.

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

*(Removed in 1.3; Broken in 1.2, fixed in 1.3)* **Prometheus 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.3)* Use **`/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.