RateLimitMetrics class abstract interface

Defines the contract for recording and reporting rate limit activity metrics.

The RateLimitMetrics interface provides visibility into runtime behavior of rate-limited operations by tracking requests, blocks, and reset events. Implementations can use this interface to collect, analyze, and visualize traffic control patterns across distributed systems.

Overview

Each rate limit configuration can be associated with a RateLimitMetrics instance that tracks quantitative data such as:

  • Allowed (successful) requests
  • Denied (rate-limited) requests
  • Reset operations (window resets or manual resets)
  • Last update timestamp

Metrics can be consumed by monitoring tools, observability dashboards, or auditing components to measure traffic distribution and rate-limit efficiency over time.

Typical Implementations

  • DefaultRateLimitMetrics
  • DistributedRateLimitMetrics
  • InMemoryRateLimitMetrics

Integration

  • Used internally by RateLimitManager and RateLimitStorage.
  • Exposed via RateLimitEndpoint for operational dashboards.
  • Can be reset periodically to align with observation windows.
  • Serves as a data source for analytics or visualization backends.

Example

final metrics = InMemoryRateLimitMetrics('auth');

metrics.recordAllowed('user:42');
metrics.recordDenied('user:17');

print(metrics.buildGraph());

Example output:

{
  "rate_limit_name": "auth",
  "operations": {
    "allowed": {"user:42": 3},
    "denied": {"user:17": 1},
    "resets": 0
  },
  "last_updated": "2025-10-20T12:34:56Z"
}
Implementers

Properties

hashCode → int
The hash code for this object.
no setterinherited
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited

Methods

buildGraph() → Map<String, Object>
Builds a structured, JSON-compatible representation of the rate limit metrics.
decrementAllowed(Object identifier) → int
Decrements the allowed request counter for the specified identifier.
decrementDenied(Object identifier) → int
Decrements the denied request counter for the specified identifier.
getAllowedRequests() → int
Returns the total number of allowed (non-denied) requests recorded.
getDeniedRequests() → int
Returns the total number of denied requests recorded.
getLastUpdated() → ZonedDateTime
Returns the timestamp of the last metric update.
getName() → String
Returns the logical name of the rate limit metric instance.
getResets() → int
Returns the total number of reset events recorded.
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
recordAllowed(Object identifier) → void
Records an allowed request for the specified identifier.
recordDenied(Object identifier) → void
Records a denied request for the specified identifier.
recordReset(Object identifier) → void
Records a rate limit reset event for the specified identifier.
reset() → void
Resets all metrics to zero, clearing accumulated statistics.
toString() → String
A string representation of this object.
inherited

Operators

operator ==(Object other) → bool
The equality operator.
inherited