Package org.elasticsearch.xpack.esql.datasources.spi

Class StorageObjectMetricsCounters

java.lang.Object
org.elasticsearch.xpack.esql.datasources.spi.StorageObjectMetricsCounters
public final class StorageObjectMetricsCounters extends Object
Mutable, thread-safe counter struct for storage I/O. Provider implementations hold one of these per StorageObject instance, increment it around each I/O call, and surface the latest values via snapshot() from StorageObject.metrics().

The split between this mutable struct and the immutable StorageObjectMetrics snapshot mirrors the Collector(LongAdder, LongAdder) / BlobStoreActionStats pattern used by ES repository plugins (see GcsRepositoryStatsCollector).

LongAdder is preferred over AtomicLong because async SDK callbacks may concurrently increment from multiple threads and contention on a single AtomicLong would dominate hot paths in object-store reads.

In addition to the profile snapshot, the same request/retry events are published to the node ExternalSourceMetrics once a StorageObjectMetricsCounters.Sink is attached (the operator wiring does this when it opens a storage object). Until then the sink is StorageObjectMetricsCounters.Sink.NONE and the publishing path is skipped entirely, so the profile-only behaviour is unchanged and allocation-free.

  • Constructor Details

    • StorageObjectMetricsCounters

      public StorageObjectMetricsCounters()

  • Method Details

    • attach

      public void attach(ExternalSourceMetrics metrics, String scheme)
      Attaches the node telemetry sink and the storage scheme dimension, so subsequent request/retry events are published to ExternalSourceMetrics as well as the profile snapshot. Idempotent; safe to call again as the same object is reused across reads.

    • addRequest

      public void addRequest(long durationNanos, long bytes)
      Records one completed request with its duration and the bytes returned.

    • addRetry

      public void addRetry()
      Records one automatic retry triggered inside an in-flight request.

    • addRetryProfileOnly

      public void addRetryProfileOnly()
      Records one retry for the per-query profile snapshot only — bumps retryCount but does not publish to the node ExternalSourceMetrics sink. Used by metadata ops (length/lastModified/exists) on RetryableStorageObject: those ops never bump the read-scoped requests.total, so publishing their retries to the registry would leak storage.retries.total past storage.requests.total (a scope violation on retryable providers). The read path uses addRetry() so its retries reach the registry as before.

    • addError

      public void addError()
      Records one object-store read that exhausted retries and gave up terminally. Telemetry-only: it does not touch the profile snapshot (only request/retry/bytes counters surface there). No-op when no sink is attached; the record method self-guards so an instrumentation failure never breaks the read path.

    • addThrottled

      public void addThrottled()
      Records one object-store read whose terminal failure was a provider throttling response. Telemetry-only.

    • addReadStall

      public void addReadStall(long millis)
      Records the cumulative time an object-store read spent in retry backoff. Telemetry-only; skipped when the read never backed off (millis <= 0) so the histogram is not flooded with zero observations.

    • snapshot

      public StorageObjectMetrics snapshot()
      Returns an immutable snapshot of the current counter values.