Prometheus Metrics for Camofox Browser: Complete Monitoring Reference

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:

export PROMETHEUS_ENABLED=1

The configuration is read from lib/config.js and passed to initMetrics() during server startup (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

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

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

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

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

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

Counts user sessions terminated due to inactivity timeouts.

camofox_tabs_reaped_total

Type: Counter
Source: lib/metrics.js:73-77

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

camofox_tabs_recycled_total

Type: Counter
Source: lib/metrics.js:78-82

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

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

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

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

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

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:

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

The route handler resides in 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 – Defines all 13 metrics and their initialization logic
• server.js – Registers the /metrics HTTP handler and wires metrics into request processing
• lib/config.js – Parses PROMETHEUS_ENABLED from the environment
• 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.
• 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); 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 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 around line 1660. Verify your environment configuration and restart the server to activate the exporter.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}