# Prometheus Metrics for Camofox Browser: Complete Monitoring Reference

> Discover the 13 Prometheus metrics for Camofox Browser monitoring request latency, tab lifecycle, memory usage, and failure rates. Enable monitoring via PROMETHEUS_ENABLED=1.

- Repository: [jo/camofox-browser](https://github.com/jo-inc/camofox-browser)
- Tags: api-reference
- Published: 2026-04-15

---

**Camofox Browser exposes 13 Prometheus metrics covering request latency, tab lifecycle, memory usage, and failure rates via the `/metrics` endpoint when the `PROMETHEUS_ENABLED` environment variable is set to `1`.**

The camofox-browser repository ships with a production-ready Prometheus exporter that instruments browser automation workloads without impacting performance when disabled. This guide covers every available metric, implementation details from the source code, and practical PromQL queries for monitoring your browser cluster.

## Enabling the Prometheus Exporter

Metrics collection is disabled by default to minimize overhead. To activate the exporter, set the environment variable in your configuration:

```bash
export PROMETHEUS_ENABLED=1

```

The configuration is read from [`lib/config.js`](https://github.com/jo-inc/camofox-browser/blob/main/lib/config.js) and passed to `initMetrics()` during server startup ([`server.js`](https://github.com/jo-inc/camofox-browser/blob/main/server.js) lines 30–35). When enabled, the server dynamically imports `prom-client`, creates a registry instance, and starts a memory reporter that samples RSS usage every 30 seconds. If the variable is unset, the system falls back to a no-op implementation, allowing metric method calls throughout the codebase to execute safely without guards.

## Counter Metrics

Counters track cumulative events. Camofox Browser registers eight counters covering requests, failures, and lifecycle events.

### camofox_requests_total

**Type:** Counter  
**Labels:** `action`, `status`  
**Source:** [`lib/metrics.js:39-44`](https://github.com/jo-inc/camofox-browser/blob/master/lib/metrics.js#L39-L44)

Tracks total HTTP requests processed by the server, labeled by the derived action (e.g., `create_tab`, `navigate`) and response status (`success` or `error`).

### camofox_tab_lock_timeouts_total

**Type:** Counter  
**Source:** [`lib/metrics.js:45-48`](https://github.com/jo-inc/camofox-browser/blob/master/lib/metrics.js#L45-L48)

Increments each time a request exceeds the configured tab lock timeout and receives an HTTP 503 response.

### camofox_failures_total

**Type:** Counter  
**Labels:** `type`, `action`  
**Source:** [`lib/metrics.js:50-55`](https://github.com/jo-inc/camofox-browser/blob/master/lib/metrics.js#L50-L55)

Aggregates failures by derived error type and the action that triggered them, enabling root-cause analysis of automation errors.

### camofox_restarts_total

**Type:** Counter  
**Labels:** `reason`  
**Source:** [`lib/metrics.js:56-61`](https://github.com/jo-inc/camofox-browser/blob/master/lib/metrics.js#L56-L61)

Counts browser process restarts labeled by trigger reason, such as `proxy_error` or `google_unavailable`.

### camofox_tabs_destroyed_total

**Type:** Counter  
**Labels:** `reason`  
**Source:** [`lib/metrics.js:62-67`](https://github.com/jo-inc/camofox-browser/blob/master/lib/metrics.js#L62-L67)

Tracks forced tab destruction events, with labels indicating whether the cause was `lock_queue` pressure or `consecutive_timeouts`.

### camofox_sessions_expired_total

**Type:** Counter  
**Source:** [`lib/metrics.js:68-72`](https://github.com/jo-inc/camofox-browser/blob/master/lib/metrics.js#L68-L72)

Counts user sessions terminated due to inactivity timeouts.

### camofox_tabs_reaped_total

**Type:** Counter  
**Source:** [`lib/metrics.js:73-77`](https://github.com/jo-inc/camofox-browser/blob/master/lib/metrics.js#L73-L77)

Increments when the idle-reaper mechanism removes inactive tabs to reclaim resources.

### camofox_tabs_recycled_total

**Type:** Counter  
**Source:** [`lib/metrics.js:78-82`](https://github.com/jo-inc/camofox-browser/blob/master/lib/metrics.js#L78-L82)

Tracks tab recycling events triggered when the global tab limit is reached and old tabs must be reused.

## Histogram Metrics

Histograms measure request and page-load latency distributions, enabling percentile calculations.

### camofox_request_duration_seconds

**Type:** Histogram  
**Labels:** `action`  
**Buckets:** 0.05s to 60s (exponential)  
**Source:** [`lib/metrics.js:83-88`](https://github.com/jo-inc/camofox-browser/blob/master/lib/metrics.js#L83-L88)

Records the end-to-end latency for each request action. Use this with `histogram_quantile()` to calculate P95 or P99 latency per action type.

### camofox_page_load_duration_seconds

**Type:** Histogram  
**Buckets:** 0.5s to 60s  
**Source:** [`lib/metrics.js:90-95`](https://github.com/jo-inc/camofox-browser/blob/master/lib/metrics.js#L90-L95)

Measures actual page-load time during navigation events, independent of request overhead.

## Gauge Metrics

Gauges report point-in-time values for current state monitoring.

### camofox_active_tabs

**Type:** Gauge  
**Source:** [`lib/metrics.js:96-100`](https://github.com/jo-inc/camofox-browser/blob/master/lib/metrics.js#L96-L100)

Reports the current number of open browser tabs across all active sessions.

### camofox_tab_lock_queue_depth

**Type:** Gauge  
**Source:** [`lib/metrics.js:101-105`](https://github.com/jo-inc/camofox-browser/blob/master/lib/metrics.js#L101-L105)

Tracks the number of pending HTTP requests waiting to acquire a tab lock. High values indicate resource contention.

### camofox_memory_usage_bytes

**Type:** Gauge  
**Source:** [`lib/metrics.js:106-110`](https://github.com/jo-inc/camofox-browser/blob/master/lib/metrics.js#L106-L110)

Reports the Node.js process Resident Set Size (RSS) in bytes, sampled every 30 seconds by `startMemoryReporter()`.

## Accessing the Metrics Endpoint

Once enabled, metrics are exposed at the HTTP endpoint:

```bash
curl -s http://localhost:9377/metrics

```

The route handler resides in [`server.js`](https://github.com/jo-inc/camofox-browser/blob/main/server.js) around lines 1658–1668. If Prometheus is disabled, the endpoint returns HTTP 404 with a JSON error payload.

Example output (truncated):

```

# HELP camofox_requests_total Total HTTP requests by action and status

# TYPE camofox_requests_total counter

camofox_requests_total{action="create_tab",status="success"} 123
camofox_requests_total{action="navigate",status="error"} 4

# HELP camofox_active_tabs Current number of open browser tabs

# TYPE camofox_active_tabs gauge

camofox_active_tabs 27

# HELP camofox_memory_usage_bytes RSS memory usage in bytes

# TYPE camofox_memory_usage_bytes gauge

camofox_memory_usage_bytes 215904768

```

## PromQL Query Examples

Use these queries in Grafana or Prometheus to visualize camofox-browser performance:

- **Overall request success rate:** `sum(rate(camofox_requests_total{status="success"}[1m])) / sum(rate(camofox_requests_total[1m]))`
- **P95 latency per action:** `histogram_quantile(0.95, sum(rate(camofox_request_duration_seconds_bucket[5m])) by (le,action))`
- **Active tab count:** `camofox_active_tabs`
- **Tab lock queue pressure:** `camofox_tab_lock_queue_depth`
- **Browser restarts by reason:** `sum by (reason) (camofox_restarts_total)`
- **Memory usage trend:** `camofox_memory_usage_bytes`
- **Failures per action:** `sum by (action) (camofox_failures_total)`
- **Tab destruction reasons:** `sum by (reason) (camofox_tabs_destroyed_total)`

## Key Source Files

- **[`lib/metrics.js`](https://github.com/jo-inc/camofox-browser/blob/main/lib/metrics.js)** – Defines all 13 metrics and their initialization logic
- **[`server.js`](https://github.com/jo-inc/camofox-browser/blob/main/server.js)** – Registers the `/metrics` HTTP handler and wires metrics into request processing
- **[`lib/config.js`](https://github.com/jo-inc/camofox-browser/blob/main/lib/config.js)** – Parses `PROMETHEUS_ENABLED` from the environment
- **[`lib/request-utils.js`](https://github.com/jo-inc/camofox-browser/blob/main/lib/request-utils.js)** – Provides `actionFromReq` used to label `requests_total` and `request_duration_seconds`

## Summary

- Enable monitoring by setting `PROMETHEUS_ENABLED=1`, which triggers lazy-loading of `prom-client` in [`lib/metrics.js`](https://github.com/jo-inc/camofox-browser/blob/main/lib/metrics.js).
- The exporter provides **8 counters**, **2 histograms**, and **3 gauges** covering request volume, latency, tab lifecycle, session health, and memory consumption.
- Access metrics via `GET /metrics` (implemented in [`server.js`](https://github.com/jo-inc/camofox-browser/blob/main/server.js)); expect a 404 response if the exporter is disabled.
- All metrics follow Prometheus naming conventions and include actionable labels (`action`, `status`, `reason`, `type`) for high-cardinality slicing in PromQL.

## Frequently Asked Questions

### How do I enable Prometheus metrics in camofox-browser?

Set the environment variable `PROMETHEUS_ENABLED=1` before starting the server. The configuration is read from [`lib/config.js`](https://github.com/jo-inc/camofox-browser/blob/main/lib/config.js) and validated during startup. If disabled, the system uses a no-op implementation to avoid performance overhead.

### Which metrics indicate tab pool health?

Monitor `camofox_active_tabs` for current utilization, `camofox_tab_lock_queue_depth` for request contention, and `camofox_tab_lock_timeouts_total` for capacity shortages. High values in `camofox_tabs_recycled_total` or `camofox_tabs_destroyed_total` indicate aggressive resource management under load.

### How do I calculate request latency percentiles?

Use the `camofox_request_duration_seconds` histogram with the `histogram_quantile()` function. For example, to calculate P95 latency per action over 5 minutes: `histogram_quantile(0.95, sum(rate(camofox_request_duration_seconds_bucket[5m])) by (le,action))`.

### Why does the `/metrics` endpoint return 404?

The endpoint returns 404 when `PROMETHEUS_ENABLED` is unset or falsy, as implemented in [`server.js`](https://github.com/jo-inc/camofox-browser/blob/main/server.js) around line 1660. Verify your environment configuration and restart the server to activate the exporter.