Class UtilizationProbe

java.lang.Object
com.eqixiac.equinix.design.estate.UtilizationProbe
public final class UtilizationProbe extends Object
Reads bandwidth utilisation for the live connections (and optionally the active ports) of an inventory through POST /fabric/v4/metrics/search and reduces it to p50 / p95 / peak.

Verified live on 2026-11-12 (read-only, one project): a search with one /subject, the names "equinix.fabric.connection.bandwidth_tx.usage" and "equinix.fabric.connection.bandwidth_rx.usage", and a seven-day /dataPoints/endDateTime BETWEEN returned both metrics with unit "bit/s", type "GAUGE" and interval "PT1H"; connections that were not provisioned returned an empty datapoints array. The service requires a single subject per search, so the probe makes one request per resource, pausing between requests and stopping at a ceiling.

A sample is the larger of transmit and receive for the same interval (a Fabric bandwidth limit applies to each direction). Missing data is recorded as unknown with a reason, never as zero.

  • Field Details

    • CONNECTION_TX

      public static final String CONNECTION_TX
      Connection transmit-rate metric name (live 2026-11-12, unit bit/s).
      See Also:

    • CONNECTION_RX

      public static final String CONNECTION_RX
      Connection receive-rate metric name (live 2026-11-12, unit bit/s).
      See Also:

    • PORT_TX

      public static final String PORT_TX
      Port transmit-rate metric name (from the Fabric v4 4.34.0 spec).
      See Also:

    • PORT_RX

      public static final String PORT_RX
      Port receive-rate metric name (from the Fabric v4 4.34.0 spec).
      See Also:

  • Method Details

    • over

      public static UtilizationProbe.Builder over(Fabric fabric)
      A probe over the Fabric metrics API.
      Parameters:
      fabric - the Fabric client
      Returns:
      a builder

    • over

      public static UtilizationProbe.Builder over(UtilizationProbe.MetricFetcher fetcher)
      A probe over any metric source (tests, recorded data).
      Parameters:
      fetcher - the source
      Returns:
      a builder

    • probe

      public UtilizationSnapshot probe(EstateInventory inventory)
      Probes the live connections (and, when enabled, active ports) of an inventory.
      Parameters:
      inventory - the inventory
      Returns:
      the utilisation snapshot

    • reduce

      public static UtilizationSnapshot.Stats reduce(String resourceId, Integer provisionedMbps, List<Metric> metrics)
      Reduces the metrics of one resource: converts rates to Mbps, takes the larger direction per interval, and computes percentiles.
      Parameters:
      resourceId - the resource id
      provisionedMbps - the provisioned bandwidth, or null
      metrics - the metrics returned for the resource
      Returns:
      the stats (unknown when there are no datapoints or the unit is not a rate)