Trait Metrics

Source

pub trait Metrics:
    Send
    + Sync
    + 'static {
    // Provided methods
    fn on_request(&self, _method: &str) { ... }
    fn on_response(&self, _method: &str) { ... }
    fn on_error(&self, _method: &str, _error_kind: &str) { ... }
    fn on_latency(&self, _method: &str, _duration: Duration) { ... }
    fn on_queue_depth_change(&self, _active_queues: usize) { ... }
    fn on_connection_pool_stats(&self, _stats: &ConnectionPoolStats) { ... }
    fn on_persistence_error(&self, _operation: &str, _error_kind: &str) { ... }
    fn on_push_delivery(&self, _outcome: &str) { ... }
}

Expand description

Trait for receiving metrics callbacks from the handler.

All methods have default no-op implementations so that consumers can override only the callbacks they care about.

Provided Methods§

Source

fn on_request(&self, _method: &str)

Called when a request is received, before processing.

Source

fn on_response(&self, _method: &str)

Called when a response is successfully sent.

Source

fn on_error(&self, _method: &str, _error_kind: &str)

Called when a request results in an error.

error_kind is a bounded, low-cardinality discriminant (e.g. ServerError::metric_label), never the free-form error message. Implementations may use it as a metric label/attribute; the caller guarantees it draws from a small fixed set, so a client cannot inflate metric cardinality through it.

Source

fn on_latency(&self, _method: &str, _duration: Duration)

Called when a request completes (successfully or not) with the wall-clock duration from receipt to response.

This is the #1 production observability metric — use it to feed histograms, percentile trackers, or SLO dashboards.

Source

fn on_queue_depth_change(&self, _active_queues: usize)

Called when the number of active event queues changes.

Source

fn on_connection_pool_stats(&self, _stats: &ConnectionPoolStats)

Called with connection pool statistics when available.

Useful for monitoring connection pool health and detecting exhaustion.

Source

fn on_persistence_error(&self, _operation: &str, _error_kind: &str)

Called when the background event processor fails to persist a task.

§Why this is not just a log line

This is the SDK’s one path that can lose data without the client noticing. The streaming reader is a separate subscriber to the event queue, so it receives an event whether or not the store accepted it: a caller watching the stream sees the artifact arrive and the task complete, while a later GetTask returns a task without it.

Until this callback existed, the only report of that was a tracing::error! — and tracing is not a default feature of this crate, so a default build lost the record silently. A metrics callback is always compiled, so the signal cannot be feature-gated away.

Treat any non-zero rate here as data loss in progress. The usual causes are a full disk, an unreachable database, or a store rejecting writes under its own capacity limit.

operation and error_kind are both bounded, low-cardinality discriminants — operation is one of the constants in persistence_operation, and error_kind comes from A2aError::metric_label. Neither carries a task id or a free-form message, so a client cannot inflate metric cardinality through them.

Source

fn on_push_delivery(&self, _outcome: &str)

Called after each attempt to deliver a push notification.

outcome is one of delivered, failed, or timeout.

Push delivery is outward-facing and asynchronous: nothing in the request path observes it, and a webhook that has been refusing every delivery for a day looks exactly like one that was never configured. As with on_persistence_error, the previous report was a tracing macro that a default build compiles away.