# 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:

- **`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**:

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

A valid API token is required.

```shell
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.