Struct SetMetricDetail 

pub struct SetMetricDetail {
    pub client_id: String,
    pub detail: Option<i32>,
    pub ttl_seconds: Option<u32>,
    pub clear: Option<bool>,
    pub reason: Option<String>,
    pub peer_pid: Option<i32>,
    pub peer_session_ulid: Option<String>,
}

Apply, renew, or release a runtime cardinality lease on the metrics drain.

Leasing model: sozu top (and any future TUI client) leases a higher MetricDetail for the duration of an interactive session. The worker’s effective detail is max(configured, max(active leases)), where configured is MetricsConfig.detail from the static configuration. Multiple clients can lease independently; the worker keeps a client_id- keyed table and uses the maximum across active entries.

Lifecycle:

1. Apply: send SetMetricDetail{ client_id, detail, ttl_seconds, reason }. The worker stores (client_id) -> (detail, expires_at = now + ttl). If a lease for client_id already exists, it is REPLACED (acts as a renewal). The renewer client is expected to re-send every ttl/2.
2. Expire: leases self-expire server-side at expires_at. The worker’s janitor (5s polled tick at the top of notify) prunes expired leases and recomputes effective. Crash safety: a dead client is forgotten.
3. Clear: send SetMetricDetail{ client_id, clear: true } for explicit revocation. client_id must match the leased entry; mismatched IDs are silently ignored (other clients’ leases are not affected).

Audit

Every operator-initiated effective-level transition emits an EventKind::METRIC_DETAIL_CHANGED event on SubscribeEvents with the previous and new effective levels and the requesting client_id plus optional reason text. Renewal-no-op (same effective level) is NOT emitted.

Emitter scope: operator-initiated transitions emit METRIC_DETAIL_CHANGED via the master-side audit log. Worker-local transitions — the polled janitor expiring a lease, or a worker-local clear/apply after a master fan-out — are not yet surfaced; follow-up tracked separately.

Backwards compatibility

Workers that pre-date this verb cannot decode SetMetricDetail and return WorkerResponse::error("unknown request type") which folds into the standard fan-out error tally (extras.fanout.workers_err); operators see “succeeded with errors” rather than a dedicated capability-skip list. Production deployments keep master + workers in sync via the UpgradeMain hot-upgrade flow, so this mixed-version state is transient. The master itself also leases (mirroring the symmetric setup_metrics path) so the audit log has a single canonical row when an operator flips detail across the fleet.

Fields

client_id: String

Stable identifier for the leasing client (sozu top uses top:<pid>:<random>). Required so multiple TUIs / scrapers / other tooling can lease independently.

detail: Option<i32>

Target detail for the lease. Required when clear is false/absent.

ttl_seconds: Option<u32>

Time-to-live for the lease in seconds. The worker rejects (FAILURE) values larger than 300s to bound the worst-case effect of a stuck renewer. Defaults server-side to 60s when absent (the master treats 0 as “use default” and emits a warning).

clear: Option<bool>

When true, releases the lease for client_id instead of applying. detail and ttl_seconds are ignored when clear is true.

reason: Option<String>

Optional human-readable provenance for the audit log (e.g. "sozu top --detail backend", "prometheus-scraper:sozu-1").

peer_pid: Option<i32>

Master-populated peer binding. These fields are NOT set by clients — the master fills them in bin/src/command/requests.rs::worker_request from the connecting ClientSession (actor_pid + session_ulid) before forwarding to workers. The worker stores the binding alongside the lease and rejects subsequent clear requests whose binding does not match the apply-time binding. Prevents one same-UID operator from accidentally (or deliberately) clearing another operator’s lease by guessing the client_id format. A None value means “binding not available” — the worker accepts any matching client_id clear, preserving compat with pre-binding callers and with platforms whose unix socket peer credentials are unavailable.

peer_session_ulid: Option<String>

Implementations

impl SetMetricDetail

pub fn detail(&self) -> MetricDetail

Returns the enum value of detail, or the default if the field is unset or set to an invalid enum value.

pub fn set_detail(&mut self, value: MetricDetail)

Sets detail to the provided enum value.

pub fn ttl_seconds(&self) -> u32

Returns the value of ttl_seconds, or the default value if ttl_seconds is unset.

pub fn clear(&self) -> bool

Returns the value of clear, or the default value if clear is unset.

pub fn reason(&self) -> &str

Returns the value of reason, or the default value if reason is unset.

pub fn peer_pid(&self) -> i32

Returns the value of peer_pid, or the default value if peer_pid is unset.

pub fn peer_session_ulid(&self) -> &str

Returns the value of peer_session_ulid, or the default value if peer_session_ulid is unset.

Trait Implementations

impl Clone for SetMetricDetail

fn clone(&self) -> SetMetricDetail

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for SetMetricDetail

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for SetMetricDetail

fn default() -> Self

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for SetMetricDetail

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Hash for SetMetricDetail

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl Message for SetMetricDetail

fn encoded_len(&self) -> usize

Returns the encoded length of the message without a length delimiter.

fn clear(&mut self)

Clears the message, resetting all fields to their default.

fn encode(&self, buf: &mut impl BufMut) -> Result<(), EncodeError>

where Self: Sized,

Encodes the message to a buffer.

fn encode_to_vec(&self) -> Vec<u8>

where Self: Sized,

Encodes the message to a newly allocated buffer.

fn encode_length_delimited( &self, buf: &mut impl BufMut, ) -> Result<(), EncodeError>

where Self: Sized,

Encodes the message with a length-delimiter to a buffer.

fn encode_length_delimited_to_vec(&self) -> Vec<u8>

where Self: Sized,

Encodes the message with a length-delimiter to a newly allocated buffer.

fn decode(buf: impl Buf) -> Result<Self, DecodeError>

where Self: Default,

Decodes an instance of the message from a buffer.

fn decode_length_delimited(buf: impl Buf) -> Result<Self, DecodeError>

where Self: Default,

Decodes a length-delimited instance of the message from the buffer.

fn merge(&mut self, buf: impl Buf) -> Result<(), DecodeError>

where Self: Sized,

Decodes an instance of the message from a buffer, and merges it into self.

fn merge_length_delimited(&mut self, buf: impl Buf) -> Result<(), DecodeError>

where Self: Sized,

Decodes a length-delimited instance of the message from buffer, and merges it into self.

impl Ord for SetMetricDetail

fn cmp(&self, other: &SetMetricDetail) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl PartialEq for SetMetricDetail

fn eq(&self, other: &SetMetricDetail) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialOrd for SetMetricDetail

fn partial_cmp(&self, other: &SetMetricDetail) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl Serialize for SetMetricDetail

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl Eq for SetMetricDetail

impl StructuralPartialEq for SetMetricDetail