Prometheus Metric Integration#

HugeGraph collects per-request HTTP metrics and exposes them in Prometheus text format via the /metrics REST endpoint. Metric names are derived from normalized request paths + HTTP methods and must be sanitized to conform to Prometheus naming rules (only [a-zA-Z0-9_:] allowed). The core sanitization and format-writing logic lives in MetricsUtil.java.

Metric Name Construction#

Per-request metric names are assembled in AccessLogFilter, a JAX-RS ContainerResponseFilter that runs after every HTTP response:

1. Normalize the path — normalizePath() replaces dynamic URI segments (graph names, IDs) with their parameter placeholder names so that /hugegraph/vertices/abc123 becomes something stable like graphs/graph/vertices/vertexId.
2. Join path + method — the metric key is built as <normalizedPath>/<HTTP_METHOD> 1.
3. Append suffix — one of four suffixes defined in MetricsUtil is appended 2:
   • TOTAL_COUNTER
   • SUCCESS_COUNTER
   • FAILED_COUNTER
   • RESPONSE_TIME_HISTOGRAM

The resulting raw key (e.g., graphs/hugegraph/vertices/vertexId/GET/TOTAL_COUNTER) is registered with the Codahale MetricRegistry 3.

Sanitization Rules#

Before writing to Prometheus output, every metric key is run through replaceDotDashInKey(), which performs four character substitutions in sequence:

This is the fix introduced in PR #2462 to resolve issue #2354, where slashes and dollar signs in raw metric names were causing invalid Prometheus output.

A second helper, replaceSlashInKey(), performs only slash replacement and is available for narrower use cases.

Prometheus Output (writePrometheusFormat)#

MetricsUtil.writePrometheusFormat() iterates all four Codahale metric types from the registry and renders them as Prometheus text:

• Gauges → gauge type 4
• Histograms → histogram type with count + snapshot percentiles (p50–p999, min, max, mean, stddev) 5
• Meters → histogram type with count + mean/1m/5m/15m rates 6
• Timers → histogram type with rate + snapshot 7

Each metric gets a # HELP and # TYPE header line using the sanitized name. Snapshot percentiles are rendered via exportSnapshot().

writePrometheusFormat() is called from MetricsAPI.baseMetricPrometheusAll() 8, which is the handler backing the /metrics and /metrics/all REST endpoints. The output format is selected by the type query parameter — any value other than "json" returns Prometheus text.

Key Files#