Package org.mockserver.metrics

Class Metrics

java.lang.Object
org.mockserver.metrics.Metrics
public class Metrics extends Object
Author:
jamesdbloom

  • Constructor Details

  • Method Details

    • resetAdditionalMetricsForTesting

      public static void resetAdditionalMetricsForTesting()
      Reset the one-shot registration guard and null all lazily-registered metrics so that a subsequent new Metrics(configuration) call re-registers them. Also clears the default Prometheus registry.

      Public for cross-package test access (e.g. chaos injection tests); intended for test use only to guarantee deterministic test ordering.

    • clear

      public static void clear()

    • clear

      public static void clear(Metrics.Name name)

    • set

      public void set(Metrics.Name name, Integer value)

    • get

      public static Integer get(Metrics.Name name)

    • registerOtelRequestDurationHistogram

      public static void registerOtelRequestDurationHistogram(io.opentelemetry.api.metrics.DoubleHistogram histogram)
      Register an OTel histogram for request duration. Called by OtelMetricsExporter when OTLP export is enabled.

    • observeRequestDurationSeconds

      public static void observeRequestDurationSeconds(double seconds)
      Record a request-handling duration (seconds) in the latency histogram. No-op unless metrics are enabled (the histogram is null until then), so a caller on the request hot path pays nothing when metrics are off.

    • observeRequestDurationByMethodSeconds

      public static void observeRequestDurationByMethodSeconds(double seconds, String method)
      Record a request-handling duration (seconds) in the per-method labeled histogram. No-op unless route labels are enabled.
      Parameters:
      seconds - duration in seconds
      method - the HTTP method (e.g. "GET", "POST")

    • getSlowRequestCount

      public static long getSlowRequestCount()
      Return the current slow-request count, or 0 if metrics are disabled. Used by OtelMetricsExporter to mirror the Prometheus counter via OTLP.

    • incrementSlowRequestTotal

      public static void incrementSlowRequestTotal()
      Increment the slow request counter. No-op unless metrics are enabled.

    • incrementDroppedLogEvents

      public static void incrementDroppedLogEvents()
      Increment the dropped-log-events counter (event-log ring buffer full). No-op unless metrics are enabled (the counter is null otherwise). The authoritative, always-available count is maintained on MockServerEventLog.getDroppedLogEventCount(); this mirrors it to Prometheus when metrics are on.

    • getDroppedLogEventCount

      public static long getDroppedLogEventCount()
      Return the current dropped-log-events count, or 0 if metrics are disabled.

    • observeForwardRequest

      public static void observeForwardRequest(String upstreamHost, Integer statusCode, double latencySeconds)
      Record observability for a single forwarded/proxied request: its latency (seconds) in the per-upstream histogram and a count in the per-upstream, per-status-class counter. No-op unless metrics are enabled (both metrics are null until then), so the forward path pays nothing when metrics are off.

      Cardinality is bounded by the number of distinct upstream hosts (the upstream_host label is the host only — never the full URL/path) and the five status classes (1xx..5xx). A null/blank host is recorded as "unknown".

      Parameters:
      upstreamHost - the resolved upstream host (no port, no path)
      statusCode - the upstream response status code, or null if unknown
      latencySeconds - the forward latency in seconds (negative values are clamped to 0)

    • getForwardRequestCount

      public static long getForwardRequestCount(String upstreamHost, String statusClass)
      Return the current forward-request count for the given upstream host and status class, or 0 if metrics are disabled.

    • isForwardMetricsActive

      public static boolean isForwardMetricsActive()
      Return true if the per-upstream forward metrics are registered (i.e. metrics are enabled).

    • getHttpChaosInjectedCount

      public static long getHttpChaosInjectedCount(String faultType)
      Return the current chaos-injected count for the given fault type, or 0 if metrics are disabled. Used by OtelMetricsExporter to mirror the Prometheus counter via OTLP.

    • incrementHttpChaosInjected

      public static void incrementHttpChaosInjected(String faultType)
      Increment the HTTP chaos injected counter for the given fault type. No-op when metrics are disabled (counter not registered) or faultType is null.
      Parameters:
      faultType - one of "drop", "error", "latency", "truncate", "malformed", "slow", "quota", "graphql", or "rateLimit"

    • incrementChaosAutoHalt

      public static void incrementChaosAutoHalt()
      Increment the chaos auto-halt counter. Called by ChaosAutoHaltMonitor when the circuit-breaker triggers. No-op when metrics are disabled (counter not registered).

    • getChaosAutoHaltCount

      public static long getChaosAutoHaltCount()
      Return the current chaos auto-halt count, or 0 if metrics are disabled.

    • incrementMcpToolCall

      public static void incrementMcpToolCall(String toolName)
      Increment the MCP tool call counter for the given tool name. No-op when metrics are disabled (counter not registered) or toolName is null. Counts each completed tool invocation (called after the tool handler returns).
      Parameters:
      toolName - the name of the MCP tool invoked (from the bounded tool registry)

    • getMcpToolCallCount

      public static long getMcpToolCallCount(String toolName)
      Return the current MCP tool call count for the given tool name, or 0 if metrics are disabled.

    • incrementAsyncMessagePublished

      public static void incrementAsyncMessagePublished(String channel)
      Increment the async-messages-published counter for the given channel. No-op when metrics are disabled (counter not registered) or channel is null. Called by the mockserver-async publish path (one increment per message published to a broker).
      Parameters:
      channel - the broker channel/topic the message was published to

    • incrementAsyncMessageConsumed

      public static void incrementAsyncMessageConsumed(String channel)
      Increment the async-messages-consumed counter for the given channel. No-op when metrics are disabled (counter not registered) or channel is null. Called by the mockserver-async subscriber record path (one increment per message recorded from a broker).
      Parameters:
      channel - the broker channel/topic the message was consumed from

    • getAsyncMessagePublishedCount

      public static long getAsyncMessagePublishedCount(String channel)
      Return the current async-messages-published count for the given channel, or 0 if metrics are disabled.

    • getAsyncMessageConsumedCount

      public static long getAsyncMessageConsumedCount(String channel)
      Return the current async-messages-consumed count for the given channel, or 0 if metrics are disabled.

    • incrementLlmTokens

      public static void incrementLlmTokens(String provider, String model, long inputTokens, long outputTokens, Double costUsd)
      Increment the LLM token and cost counters for a served or forwarded completion. No-op when LLM metrics are not registered (llmMetricsEnabled is false or metrics are disabled). Fail-soft: a null or unresolvable provider/model is recorded as "unknown".
      Parameters:
      provider - the LLM provider name (e.g. "ANTHROPIC", "OPENAI")
      model - the model name (e.g. "claude-opus-4")
      inputTokens - number of input tokens (may be 0)
      outputTokens - number of output tokens (may be 0)
      costUsd - estimated cost in USD (may be 0.0; null means unknown and is skipped)

    • getLlmInputTokens

      public static long getLlmInputTokens(String provider, String model)
      Return the current LLM input token count for the given provider and model, or 0 if LLM metrics are disabled.

    • getLlmOutputTokens

      public static long getLlmOutputTokens(String provider, String model)
      Return the current LLM output token count for the given provider and model, or 0 if LLM metrics are disabled.

    • getLlmCostUsd

      public static double getLlmCostUsd(String provider, String model)
      Return the current cumulative LLM cost in USD for the given provider and model, or 0.0 if LLM metrics are disabled.

    • getLlmCostUsdTotal

      public static double getLlmCostUsdTotal()
      Return the aggregate cumulative LLM cost in USD across all providers and models. Used by the cost-budget circuit-breaker. Returns 0.0 if LLM metrics are disabled.

    • isLlmMetricsActive

      public static boolean isLlmMetricsActive()
      Return true if LLM token/cost counters are registered (i.e. both metricsEnabled and llmMetricsEnabled are true).

    • incrementLlmCostBudgetTripped

      public static void incrementLlmCostBudgetTripped()
      Increment the LLM cost-budget circuit-breaker tripped counter. No-op when metrics are disabled (counter not registered).

    • getLlmCostBudgetTrippedCount

      public static long getLlmCostBudgetTrippedCount()
      Return the current LLM cost-budget tripped count, or 0 if metrics are disabled.

    • incrementExpectationMatched

      public static void incrementExpectationMatched(String expectationId)
      Increment the per-expectation match counter for the given stable expectation id.

      No-op unless per-expectation metrics are enabled (Configuration.perExpectationMetricsEnabled()) AND metrics are enabled (the counter is null otherwise), or when expectationId is null. Labeled by the stable expectation id (not the request path) so cardinality is bounded by the number of distinct expectations.

      Parameters:
      expectationId - the stable id of the matched expectation

    • getExpectationMatchedCount

      public static long getExpectationMatchedCount(String expectationId)
      Return the current per-expectation match count for the given expectation id, or 0 if the per-expectation counter is not registered.

    • isPerExpectationMetricsActive

      public static boolean isPerExpectationMetricsActive()
      Return true if the per-expectation match counter is registered (i.e. both metricsEnabled and perExpectationMetricsEnabled are on).

    • setActiveExpectationsSupplier

      public static void setActiveExpectationsSupplier(Supplier<List<Expectation>> supplier)
      Set the supplier of active expectations. Called by HttpState at startup so the expectations-by-type GaugeWithCallback can read live state at scrape time without a core-to-netty dependency.
      Parameters:
      supplier - returns the list of currently-active expectations

    • getActiveExpectationCountByType

      public static Map<String,Integer> getActiveExpectationCountByType()
      Per-action-type count of currently-active expectations. Backs the mock_server_expectations_by_type Prometheus gauge; reads the live expectation list at scrape time via the registered supplier.

    • getActiveServiceChaosCountByFaultType

      public static Map<String,Integer> getActiveServiceChaosCountByFaultType()
      Per-fault-type count of currently-active service-scoped chaos profiles. Backs the mock_server_active_service_chaos Prometheus gauge and its OTLP mirror; reads the registry directly (not gated on metricsEnabled, the gauge is only registered when metrics are on).

    • setClusterMemberCountSupplier

      public static void setClusterMemberCountSupplier(Supplier<Integer> supplier)
      Set the supplier of the current cluster member count. Called by HttpState at startup so the mock_server_cluster_members GaugeWithCallback can read live membership from the StateBackend at scrape time without Metrics depending on the state package.
      Parameters:
      supplier - returns the current number of cluster members

    • getClusterMemberCount

      public static int getClusterMemberCount()
      Current cluster member count, backing the mock_server_cluster_members gauge. Returns 1 (single local node) when no supplier is registered or the supplier fails/returns a non-positive value.

    • getOpenUpstreamCircuitCount

      public static int getOpenUpstreamCircuitCount()
      Number of upstreams whose forward/proxy circuit breaker is currently open, backing the mock_server_upstream_circuit_open gauge. Reads the live ForwardCircuitBreaker registry at scrape time; returns 0 when the breaker is disabled or no upstream is open.

    • isLoadMetricsActive

      public static boolean isLoadMetricsActive()
      True if the load metric family is registered (i.e. metrics are enabled).

    • evictLoadRun

      public static void evictLoadRun(String runId)
      Evict every durable mock_server_load_* series whose run_id label equals the given run id, bounding accumulation of completed-run series. Each load run uses a fresh UUID run_id label; without eviction the Prometheus client retains those datapoints in the registry forever (memory growth, slower scrapes and loadLatencyPercentileMillis). The orchestrator calls this for the previous run when a new run starts, so the most-recent completed run stays scrapeable while accumulation is bounded to at most one completed run.

      The Prometheus client 1.8.0 exposes removeIf(Function<List<String>, Boolean>) on stateful metrics, keyed by label values in registration order. run_id is index 1 in every load metric's label schema (the fixed structured labels begin scenario, run_id, … and the scalar counters are scenario, run_id, …). The gauges are deliberately untouched — they self-clear via the orchestrator's empty-callback readers. No-op when metrics are disabled (the metrics are null) or runId is null.

    • observeLoadRequest

      public static void observeLoadRequest(String scenario, String runId, String step, String route, String method, Integer statusCode, double latencySeconds, long requestBytes, long responseBytes, String traceId, Map<String,String> customLabels)
      Record one completed load-scenario request: its duration in the histogram (with an optional trace_id exemplar), the request/response body byte counts, and a request count — all labeled by the fixed structured labels plus the allowlisted custom labels. The full custom-label map is mirrored to OTLP as attributes (arbitrary keys). No-op when load metrics are off.
      Parameters:
      scenario - the scenario name
      runId - the stable per-run id
      step - the step label (step name or index)
      route - the low-cardinality templatised route label
      method - the HTTP method
      statusCode - the upstream response status code, or null
      latencySeconds - the request latency in seconds (negative clamped to 0)
      requestBytes - request body byte count
      responseBytes - response body byte count
      traceId - the request's trace id for the histogram exemplar, or null
      customLabels - merged scenario+step custom labels (may be null/empty)

    • incrementLoadIteration

      public static void incrementLoadIteration(String scenario, String runId)
      Increment the completed-iteration counter (labels scenario, run_id). No-op when off.

    • incrementLoadThrottled

      public static void incrementLoadThrottled(String scenario, String runId, String reason)
      Increment the throttled-dispatch counter for the given reason.
      Parameters:
      reason - one of "inflight_cap" or "rate_limit"

    • incrementLoadError

      public static void incrementLoadError(String scenario, String runId, String kind)
      Increment the error counter for the given kind.
      Parameters:
      kind - one of "timeout", "connection", "render", "http_5xx", "null_response"

    • setLoadGaugeReaders

      public static void setLoadGaugeReaders(Supplier<Map<Metrics.LoadGaugeKey,Integer>> activeVusReader, Supplier<Map<Metrics.LoadGaugeKey,Integer>> inflightReader)
      Register the live readers for the active-VU and in-flight load gauges. Called by the orchestrator on start (and cleared with null on stop), so the gauges read the running scenario at scrape time. Mirrors the chaos GaugeWithCallback pattern.

    • registerOtelLoadInstruments

      public static void registerOtelLoadInstruments(io.opentelemetry.api.metrics.DoubleHistogram duration, io.opentelemetry.api.metrics.LongCounter requests, io.opentelemetry.api.metrics.LongCounter requestBytes, io.opentelemetry.api.metrics.LongCounter responseBytes, io.opentelemetry.api.metrics.LongCounter iterations, io.opentelemetry.api.metrics.LongCounter throttled, io.opentelemetry.api.metrics.LongCounter errors)
      Install the OTel load instruments. Called by OtelMetricsExporter when OTLP export is enabled; passing null on stop clears them so the load path stops mirroring to OTLP.

    • getLoadActiveVus

      public static Map<Metrics.LoadGaugeKey,Integer> getLoadActiveVus()
      Live readers for the OTEL load observable gauges (active VUs / in-flight).

    • getLoadInflightRequests

      public static Map<Metrics.LoadGaugeKey,Integer> getLoadInflightRequests()

    • getLoadRequestCount

      public static long getLoadRequestCount(String scenario, String runId, String step, String route, String method, String statusClass)
      Read a per-request load counter value for a fixed-label combination (custom labels empty). Test helper.

    • getLoadThrottledCount

      public static long getLoadThrottledCount(String scenario, String runId, String reason)

    • getLoadErrorCount

      public static long getLoadErrorCount(String scenario, String runId, String kind)

    • getLoadIterationCount

      public static long getLoadIterationCount(String scenario, String runId)

    • loadLatencyPercentileMillis

      public static long loadLatencyPercentileMillis(String scenario, String runId, int pct)
      Derive a latency percentile (millis) for the given fixed-label combination from the load histogram's classic buckets — bounded memory, no reservoir. Returns the upper bound of the bucket in which the requested rank falls (the standard histogram-quantile interpolation point for classic buckets), or 0 when there are no observations. Any percentile is also directly queryable from the histogram in Prometheus via histogram_quantile.
      Parameters:
      pct - percentile in 0..100

    • increment

      public void increment(Metrics.Name name)

    • increment

      public void increment(Action.Type type)

    • decrement

      public void decrement(Metrics.Name name)

    • decrement

      public void decrement(Action.Type type)

    • clearRequestAndExpectationMetrics

      public static void clearRequestAndExpectationMetrics()

    • clearActionMetrics

      public static void clearActionMetrics()

    • clearWebSocketMetrics

      public static void clearWebSocketMetrics()