# Health & Metrics

## Health Check

Returns a simple health status. No authentication required. No database check performed.

```
GET /health
```

### Response — `200 OK`

```json
{
  "status": "ok"
}
```

Use this endpoint for load balancer health checks and uptime monitoring.

***

## Prometheus Metrics

Exposes Prometheus-formatted metrics. No authentication required.

```
GET /metrics
```

### Response — `200 OK`

Returns metrics in Prometheus text format.

{% hint style="warning" %}
This endpoint has no authentication. In production, restrict access via AWS Security Groups — only allow your Prometheus scraper's IP to reach this endpoint.
{% endhint %}

### Available Metrics

#### Transaction Metrics

| Metric                                         | Type    | Description                                           |
| ---------------------------------------------- | ------- | ----------------------------------------------------- |
| `ledger_transactions_total`                    | Counter | Total transactions processed (includes rejected ones) |
| `ledger_transactions_success_total`            | Counter | Successfully committed transactions                   |
| `ledger_transactions_insufficient_funds_total` | Counter | Transactions rejected by balance policy               |
| `ledger_transactions_error_total`              | Counter | Transactions that failed due to errors                |

#### Batch Metrics

| Metric                     | Type      | Description                      |
| -------------------------- | --------- | -------------------------------- |
| `ledger_batch_size`        | Histogram | Number of transactions per batch |
| `ledger_batch_duration_ms` | Histogram | Total batch processing time (ms) |
| `ledger_batch_commit_ms`   | Histogram | Postgres COMMIT time (ms)        |

#### HTTP Metrics

| Metric                       | Type      | Description                         |
| ---------------------------- | --------- | ----------------------------------- |
| `ledger_http_requests_total` | Counter   | HTTP requests by method/path/status |
| `ledger_http_duration_ms`    | Histogram | HTTP latency by method/path (ms)    |

#### Idempotency Metrics

| Metric                                     | Type      | Description                      |
| ------------------------------------------ | --------- | -------------------------------- |
| `ledger_idempotency_records_current`       | Gauge     | Current idempotency record count |
| `ledger_idempotency_cleanup_removed_total` | Counter   | Records removed by cleanup job   |
| `ledger_idempotency_cleanup_errors_total`  | Counter   | Cleanup job errors               |
| `ledger_idempotency_cleanup_duration_ms`   | Histogram | Cleanup job duration (ms)        |

### Useful Prometheus Queries

**Transaction throughput (TPS):**

```promql
rate(ledger_transactions_total[1m])
```

**HTTP p99 latency for transactions:**

```promql
histogram_quantile(0.99, rate(ledger_http_duration_ms_bucket{path="/transaction"}[1m]))
```

**Average batch size:**

```promql
rate(ledger_batch_size_sum[1m]) / rate(ledger_batch_size_count[1m])
```

**Insufficient funds rate:**

```promql
rate(ledger_transactions_insufficient_funds_total[1m])
```

**Success rate:**

```promql
rate(ledger_transactions_success_total[1m]) / rate(ledger_transactions_total[1m])
```

### Notes

* Metrics are **in-memory only** — they reset on server restart
* Prometheus stores historical data on disk — Grafana shows history even after restarts
* Prometheus should scrape this endpoint every 10 seconds (default configuration)
* Use Grafana for dashboards and alerting based on these metrics


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://entrytarget.gitbook.io/docs/api-reference/health-and-metrics.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.