Struct TracingRateLimitLayer 

pub struct TracingRateLimitLayer<S = Arc<ShardedStorage<EventSignature, EventState>>>
where
    S: Storage<EventSignature, EventState> + Clone,
{ /* private fields */ }

A tracing::Layer that applies rate limiting to events.

This layer intercepts events, computes their signature, and decides whether to allow or suppress them based on the configured policy.

Optionally emits periodic summaries of suppressed events when active emission is enabled (requires async feature).

Implementations

impl<S> TracingRateLimitLayer<S>

where S: Storage<EventSignature, EventState> + Clone,

pub fn should_allow(&self, signature: EventSignature) -> bool

Check if an event should be allowed through.

pub fn should_allow_with_metadata( &self, signature: EventSignature, metadata: EventMetadata, ) -> bool

Check if an event should be allowed through and capture metadata.

This method stores event metadata on first occurrence so summaries can show human-readable event details instead of just signature hashes.

Note: Only available with the human-readable feature flag.

pub fn limiter(&self) -> &RateLimiter<S>

Get a reference to the underlying limiter.

pub fn metrics(&self) -> &Metrics

Get a reference to the metrics.

Returns metrics about rate limiting behavior including:

• Events allowed
• Events suppressed
• Signatures evicted

pub fn signature_count(&self) -> usize

Get the current number of tracked signatures.

pub fn circuit_breaker(&self) -> &Arc<CircuitBreaker>

Get a reference to the circuit breaker.

Use this to check the circuit breaker state and health:

• circuit_breaker().state() - Current circuit state
• circuit_breaker().consecutive_failures() - Failure count

pub async fn shutdown(&self) -> Result<(), ShutdownError>

Shutdown the active suppression summary emitter, if running.

This method gracefully stops the background emission task. If active emission is not enabled, this method does nothing.

Requires the async feature.

Errors

Returns an error if the emitter task fails to shut down gracefully.

Example

let layer = TracingRateLimitLayer::builder()
    .with_active_emission(true)
    .build()
    .unwrap();

// Use the layer...

// Shutdown before dropping
layer.shutdown().await.expect("shutdown failed");

impl TracingRateLimitLayer<Arc<ShardedStorage<EventSignature, EventState>>>

pub fn builder() -> TracingRateLimitLayerBuilder

Create a builder for configuring the layer.

Defaults:

• Policy: token bucket (50 burst capacity, 1 token/sec refill rate)
• Max signatures: 10,000 (with LRU eviction)
• Summary interval: 30 seconds
• Active emission: disabled
• Summary formatter: default (WARN level with signature and count)

pub fn new() -> Self

Create a layer with default settings.

Equivalent to TracingRateLimitLayer::builder().build().unwrap().

Defaults:

• Policy: token bucket (50 burst capacity, 1 token/sec refill rate = 60/min)
• Max signatures: 10,000 (with LRU eviction)
• Summary interval: 30 seconds

Panics

This method cannot panic because all default values are valid.

pub fn with_storage<ST>( storage: ST, policy: Policy, clock: Arc<dyn Clock>, ) -> TracingRateLimitLayer<ST>

where ST: Storage<EventSignature, EventState> + Clone,

Create a layer with custom storage backend.

This allows using alternative storage implementations like Redis for distributed rate limiting across multiple application instances.

Arguments

• storage - Custom storage implementation (must implement Storage<EventSignature, EventState>)
• policy - Rate limiting policy to apply
• clock - Clock implementation (use SystemClock::new() for production)

Example with Redis

use tracing_throttle::{TracingRateLimitLayer, RedisStorage, Policy, SystemClock};
use std::sync::Arc;

#[tokio::main]
async fn main() {
    let storage = Arc::new(
        RedisStorage::connect("redis://127.0.0.1/")
            .await
            .expect("Failed to connect")
    );
    let policy = Policy::token_bucket(100.0, 10.0).unwrap();
    let clock = Arc::new(SystemClock::new());

    let layer = TracingRateLimitLayer::with_storage(storage, policy, clock);
}

Trait Implementations

impl<S> Clone for TracingRateLimitLayer<S>

where S: Storage<EventSignature, EventState> + Clone + Clone,

fn clone(&self) -> TracingRateLimitLayer<S>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Default for TracingRateLimitLayer<Arc<ShardedStorage<EventSignature, EventState>>>

fn default() -> Self

Returns the “default value” for a type.

impl<S, Sub> Filter<Sub> for TracingRateLimitLayer<S>

where S: Storage<EventSignature, EventState> + Clone, Sub: Subscriber + for<'lookup> LookupSpan<'lookup>,

fn enabled(&self, _meta: &Metadata<'_>, _cx: &Context<'_, Sub>) -> bool

Returns true if this layer is interested in a span or event with the given Metadata in the current Context, similarly to Subscriber::enabled.

fn event_enabled(&self, event: &Event<'_>, cx: &Context<'_, Sub>) -> bool

Called before the filtered [Layer]'s [on_event], to determine if on_event` should be called.

fn callsite_enabled(&self, meta: &'static Metadata<'static>) -> Interest

Returns an Interest indicating whether this layer will always, sometimes, or never be interested in the given Metadata.

fn max_level_hint(&self) -> Option<LevelFilter>

Returns an optional hint of the highest verbosity level that this Filter will enable.

fn on_new_span(&self, attrs: &Attributes<'_>, id: &Id, ctx: Context<'_, S>)

Notifies this filter that a new span was constructed with the given Attributes and Id.

fn on_record(&self, id: &Id, values: &Record<'_>, ctx: Context<'_, S>)

Notifies this filter that a span with the given Id recorded the given values.

fn on_enter(&self, id: &Id, ctx: Context<'_, S>)

Notifies this filter that a span with the given ID was entered.

fn on_exit(&self, id: &Id, ctx: Context<'_, S>)

Notifies this filter that a span with the given ID was exited.

fn on_close(&self, id: Id, ctx: Context<'_, S>)

Notifies this filter that a span with the given ID has been closed.

impl<S, Sub> Layer<Sub> for TracingRateLimitLayer<S>

where S: Storage<EventSignature, EventState> + Clone + 'static, Sub: Subscriber + for<'lookup> LookupSpan<'lookup>,

fn on_new_span(&self, attrs: &Attributes<'_>, id: &Id, ctx: Context<'_, Sub>)

Notifies this layer that a new span was constructed with the given Attributes and Id.

fn on_register_dispatch(&self, subscriber: &Dispatch)

Performs late initialization when installing this layer as a Subscriber.

fn on_layer(&mut self, subscriber: &mut S)

Performs late initialization when attaching a Layer to a Subscriber.

fn register_callsite(&self, metadata: &'static Metadata<'static>) -> Interest

Registers a new callsite with this layer, returning whether or not the layer is interested in being notified about the callsite, similarly to Subscriber::register_callsite.

fn enabled(&self, metadata: &Metadata<'_>, ctx: Context<'_, S>) -> bool

Returns true if this layer is interested in a span or event with the given metadata in the current Context, similarly to Subscriber::enabled.

fn on_record(&self, _span: &Id, _values: &Record<'_>, _ctx: Context<'_, S>)

Notifies this layer that a span with the given Id recorded the given values.

fn on_follows_from(&self, _span: &Id, _follows: &Id, _ctx: Context<'_, S>)

Notifies this layer that a span with the ID span recorded that it follows from the span with the ID follows.

fn event_enabled(&self, _event: &Event<'_>, _ctx: Context<'_, S>) -> bool

Called before on_event, to determine if on_event should be called.

fn on_event(&self, _event: &Event<'_>, _ctx: Context<'_, S>)

Notifies this layer that an event has occurred.

fn on_enter(&self, _id: &Id, _ctx: Context<'_, S>)

Notifies this layer that a span with the given ID was entered.

fn on_exit(&self, _id: &Id, _ctx: Context<'_, S>)

Notifies this layer that the span with the given ID was exited.

fn on_close(&self, _id: Id, _ctx: Context<'_, S>)

Notifies this layer that the span with the given ID has been closed.

fn on_id_change(&self, _old: &Id, _new: &Id, _ctx: Context<'_, S>)

Notifies this layer that a span ID has been cloned, and that the subscriber returned a different ID.

fn and_then<L>(self, layer: L) -> Layered<L, Self, S>

where L: Layer<S>, Self: Sized,

Composes this layer around the given Layer, returning a Layered struct implementing Layer.

fn with_subscriber(self, inner: S) -> Layered<Self, S>

where Self: Sized,

Composes this Layer with the given Subscriber, returning a Layered struct that implements Subscriber.

fn with_filter<F>(self, filter: F) -> Filtered<Self, F, S>

where Self: Sized, F: Filter<S>,

Combines self with a Filter, returning a Filtered layer.

fn boxed(self) -> Box<dyn Layer<S> + Sync + Send>

where Self: Sized + Layer<S> + Send + Sync + 'static, S: Subscriber,

Erases the type of this Layer, returning a Boxed dyn Layer trait object.