---
source: https://carbone.io/documentation/developer/on-premise-installation/metrics.html
title: "Metrics (OpenMetrics)"
description: "Monitor Carbone On-Premise with a Prometheus-compatible /metrics endpoint"
generated_at: "2026-07-07"
---

# Metrics (OpenMetrics)

Monitor Carbone On-Premise with a Prometheus-compatible /metrics endpoint

## Overview

Carbone On-Premise exposes an **OpenMetrics** (Prometheus-compatible) endpoint so you can monitor rendering activity and, in a cluster, metadata replication.

## Enable it

The `/metrics` endpoint is served by Carbone's internal server. To expose it, set the internal port and enable [template management](/documentation/developer/on-premise-installation/template-management.md) (which provides the metrics database):

```bash
export CARBONE_TEMPLATE_MANAGEMENT=true
export CARBONE_PEER_PORT=5001
```

You do not need a cluster, a single node is enough. `peerPort` is the internal port Carbone uses for metadata replication, and it also serves `/metrics`. On a standalone node the `carbone_reports_*` metrics are the meaningful ones; the `carbone_db_replication_*` metrics describe a cluster.

> ⚠️ **Warning:** `peerPort` is a private endpoint with **no authentication**, and it also carries cluster replication traffic. Keep it on a private network and never expose it publicly.

## Endpoint

| Property | Value |
| --- | --- |
| Method & path | `GET /metrics` |
| Port | the internal `peerPort` (see [HA and Scaling](/documentation/developer/on-premise-installation/ha-and-scaling.md#high-availability-and-clustering)) |
| Format | OpenMetrics / Prometheus text format (`text/plain`) |

## Scrape with Prometheus

Point Prometheus at the endpoint, using each node's `peerPort` as the target port:

```yaml
scrape_configs:
  - job_name: carbone
    metrics_path: /metrics
    static_configs:
      - targets: ['carbone-node:5001'] # host:peerPort
```

## Available metrics

| Metric | Type | Labels | Description |
| --- | --- | --- | --- |
| `carbone_reports_inflight` | gauge | `stage` (`queued`, `rendering`, `conversion`) | Reports currently in progress inside Carbone. The `conversion` stage counts document conversion jobs waiting in the queue. |
| `carbone_reports_rendered_total` | counter | `result` (`success`, `error`) | Total number of reports rendered, by result. |
| `carbone_db_replication_connected_peers` | gauge | `peer` | Number of peers currently connected to this node. |
| `carbone_db_replication_lag_seconds` | gauge | `peer`, `remote_peer` | Replication lag in seconds (this peer vs upstream peer). |
| `carbone_db_replication_retransmission_requests_total` | counter | `peer`, `direction` (`sent`, `received`) | Retransmission requests for missing, dropped or out-of-order sequences. |
| `carbone_db_replication_messages_total` | counter | `peer`, `direction` | Total replication messages processed by this node. |
| `carbone_db_maintenance_time_seconds_total` | counter | `peer` | Cumulative time spent in maintenance tasks (checks, cleanup, backup). |
| `carbone_db_logical_clock_drift_max_seconds` | gauge | `peer` | Maximum logical clock drift observed versus any peer (absolute value). |
| `carbone_db_read_your_write_timeouts_total` | counter | `peer` | Number of client reads that returned stale or old data. |

## Example response

The endpoint returns every metric listed above; this example is truncated:

```sh
# HELP Number of reports currently in progress inside Carbone (queued, rendering, conversion).
# TYPE gauge
carbone_reports_inflight{stage="queued"} 12
carbone_reports_inflight{stage="rendering"} 5
carbone_reports_inflight{stage="conversion"} 3

# HELP Total number of reports rendered by Carbone, labeled by result.
# TYPE counter
carbone_reports_rendered_total{result="success"} 21
carbone_reports_rendered_total{result="error"} 3

# HELP Number of peers currently connected to this node.
# TYPE gauge
carbone_db_replication_connected_peers{peer="1000"} 1

# HELP Current replication lag in seconds (this peer vs upstream peer)
# TYPE gauge
# UNIT seconds
carbone_db_replication_lag_seconds{peer="1000", remote_peer="3000"} 0.1
```

## Related topics

- [Upgrade Guide](/documentation/developer/on-premise-installation/upgrade-guide.md)
- [Template management](/documentation/developer/on-premise-installation/template-management.md)
- [On-Premise Requirements](/documentation/developer/on-premise-installation/requirements.md)
- [On-Premise plugins](/documentation/developer/on-premise-installation/plugins.md)
- [On-Premise](/documentation/developer/on-premise-installation/introduction.md)
- [Deploy on MacOS](/documentation/developer/on-premise-installation/install-on-macos.md)