Switchyard lets LLM applications route traffic across models and providers while preserving native OpenAI and Anthropic API compatibility - enabling flexible model selection, benchmarking, and cost/performance optimization.
Rust
feat(libsy): warn once when affinity cannot derive a key (#308)
Joelad8478b7b061
diff --git a/crates/libsy-llm-client/tests/observability.rs b/crates/libsy-llm-client/tests/observability.rsindex 18d8f9f35..8e3c66970 100644--- a/crates/libsy-llm-client/tests/observability.rs+++ b/crates/libsy-llm-client/tests/observability.rs@@ -33,8 +33,9 @@ use tracing_subscriber::layer::{Context as LayerContext, SubscriberExt};use tracing_subscriber::registry::LookupSpan;use switchyard_libsy::{- Algorithm, Driver, LibsyError, LlmClassifierConfig, LlmTarget, LlmTargetSet, LlmTaskClassifier,- PickerMode, StageRouter, StageRouterConfig, Step, TaskClassifierConfig,+ AffinityRouter, Algorithm, Classifier, Driver, LibsyError, LlmClassifierConfig, LlmTarget,+ LlmTargetSet, LlmTaskClassifier, PickerMode, StageRouter, StageRouterConfig, Step,+ TaskClassifierConfig,};use switchyard_llm_client::{ClientRouter, RunObservation, RunObserver};use switchyard_protocol::{@@ -570,6 +571,51 @@ fn otel_attribute<'a>(span: &'a SpanData, key: &str) -> Option<&'a OtelValue> {.map(|attribute| &attribute.value)}+#[tokio::test]+async fn affinity_warns_once_when_request_has_no_usable_identity() -> switchyard_libsy::Result<()> {+ let _guard = serialize_test().lock().await;+ let (store, _, _, _, _) = telemetry();+ let event_count = store.events().len();+ let router = AffinityRouter::new().with_message_hash_fallback();+ let mut state = ();+ let mut request = Request {+ llm_request: LlmRequest {+ messages: vec![Message {+ role: Role::User,+ content: vec![ContentBlock::Reasoning {+ text: "provider reasoning".to_string(),+ signature: None,+ }],+ }],+ ..LlmRequest::default()+ },+ raw_request: None,+ metadata: None,+ };++ for _ in 0..2 {+ router.score(&mut state, &mut request, None).await?;+ }++ let events = store.events();+ let warnings = events[event_count..]+ .iter()+ .filter(|event| {+ event.target == "libsy"+ && event.level == "WARN"+ && event+ .fields+ .get("message")+ .is_some_and(|message| message.contains("affinity is enabled"))+ })+ .collect::<Vec<_>>();+ assert_eq!(warnings.len(), 1, "affinity warnings: {warnings:?}");+ assert!(warnings[0].fields.get("message").is_some_and(|message| {+ message.contains("message-hash fallback with usable first-user text")+ }));+ Ok(())+}+#[tokio::test]async fn successful_run_records_metrics_spans_and_decision_log() -> switchyard_libsy::Result<()> {let _guard = serialize_test().lock().await;diff --git a/crates/libsy/src/algorithms/util/affinity.rs b/crates/libsy/src/algorithms/util/affinity.rsindex 6bcbb6815..bef22d17d 100644--- a/crates/libsy/src/algorithms/util/affinity.rs+++ b/crates/libsy/src/algorithms/util/affinity.rs@@ -19,6 +19,7 @@use std::collections::{HashMap, HashSet, hash_map::DefaultHasher};use std::hash::{Hash, Hasher};+use std::sync::atomic::{AtomicBool, Ordering};use async_trait::async_trait;use parking_lot::Mutex;@@ -55,6 +56,8 @@ pub struct AffinityRouter {/// Held on the instance so the two roles share one process-local map through a/// single registered [`Arc`](std::sync::Arc); bounded by [`MAX_ASSIGNMENTS`].assignments: Mutex<HashMap<RoutingIdentity, String>>,+ /// Whether the "no identity to key on" warning has already been emitted.+ unkeyed_warning_emitted: AtomicBool,}impl AffinityRouter {@@ -95,26 +98,45 @@ impl AffinityRouter {/// Derives the stable identity this router should retain for `request`.fn affinity_key(&self, request: &Request) -> Option<RoutingIdentity> {- if let Some(identity) = RoutingIdentity::from_request(request) {- return match identity {- RoutingIdentity::Session(_) if self.subagents_only => None,- identity => Some(identity),- };+ let metadata = request.metadata.as_ref();+ let is_subagent = metadata.is_some_and(|metadata| metadata.is_subagent);+ // This mode handles only subagent requests; root requests intentionally fall through.+ if self.subagents_only && !is_subagent {+ return None;}- // If headers are not present and we are not a subagent, use the message hash based fallback key to do task based routing- let is_subagent = request- .metadata- .as_ref()- .is_some_and(|metadata| metadata.is_subagent);- (!self.subagents_only && !is_subagent && self.message_hash_fallback)- .then(|| {+ let key = match (RoutingIdentity::from_request(request), is_subagent) {+ (Some(identity), _) => Some(identity),+ // Child requests require their explicit session + agent identity and never fall+ // back to task text.+ (None, true) => None,+ (None, false) if self.message_hash_fallback => {first_user_message_hash(request).map(|hash| {tracing::debug!(affinity_key = %hash, "affinity using message hash fallback");RoutingIdentity::Session(hash)})- })- .flatten()+ }+ (None, false) => None,+ };+ // Affinity that never keys anything is silent otherwise: the route reports itself as+ // configured while every turn is classified afresh. Say so once rather than per turn.+ if key.is_none() && self.should_warn_unkeyed() {+ tracing::warn!(+ target: "libsy",+ is_subagent,+ message_hash_fallback = self.message_hash_fallback,+ "affinity is enabled but this request carries no usable identity, so no \+ affinity is applied; root requests need a session id or message-hash \+ fallback with usable first-user text, and child requests need both session \+ and agent ids"+ );+ }+ key+ }++ /// Reports whether this call owns the one-time warning for an unkeyable request.+ fn should_warn_unkeyed(&self) -> bool {+ !self.unkeyed_warning_emitted.swap(true, Ordering::Relaxed)}}@@ -463,6 +485,21 @@ mod tests {Ok(())}+ #[tokio::test]+ async fn subagents_only_root_traffic_does_not_warn() -> Result<(), BoxErr> {+ // Abstaining on root traffic is this mode's contract, so it must not warn.+ let router = AffinityRouter::for_subagents();+ let mut state = ();++ let mut root = request(session("session-1", "agent-1"));+ assert!(scores(&router, &mut state, &mut root).await?.is_empty());+ assert!(+ router.should_warn_unkeyed(),+ "an intentional abstention should leave the warning unconsumed"+ );+ Ok(())+ }+#[test]fn user_message_hash_ignores_non_text_provider_payloads() {let request = |user_message| Request {@@ -519,19 +556,28 @@ mod tests {}#[tokio::test]- async fn message_hash_fallback_abstains_for_subagents() -> Result<(), BoxErr> {- let router = AffinityRouter::new().with_message_hash_fallback();- let mut state = ();- let mut subagent = task_request(- Some(Metadata {- is_subagent: true,- ..Metadata::default()- }),- "Implement the parser.",- None,- );-- assert!(scores(&router, &mut state, &mut subagent).await?.is_empty());+ async fn subagent_without_a_session_abstains_and_warns() -> Result<(), BoxErr> {+ for session_id in [None, Some(String::new())] {+ let router = AffinityRouter::new().with_message_hash_fallback();+ let mut state = ();+ let mut subagent = task_request(+ Some(Metadata {+ session_id,+ agent_id: Some("agent-1".to_string()),+ is_subagent: true,+ ..Metadata::default()+ }),+ "Implement the parser.",+ None,+ );++ retain(&router, &mut state, &mut subagent, "model-a").await?;+ assert!(scores(&router, &mut state, &mut subagent).await?.is_empty());+ assert!(+ !router.should_warn_unkeyed(),+ "an unidentifiable subagent should consume the warning"+ );+ }Ok(())}@@ -670,7 +716,7 @@ mod tests {}#[tokio::test]- async fn subagent_without_an_agent_id_is_not_keyed() -> Result<(), BoxErr> {+ async fn subagent_without_an_agent_id_abstains_and_warns() -> Result<(), BoxErr> {let router = AffinityRouter::new();let mut state = ();@@ -684,6 +730,10 @@ mod tests {let mut req = request(metadata);retain(&router, &mut state, &mut req, "model-a").await?;assert!(scores(&router, &mut state, &mut req).await?.is_empty());+ assert!(+ !router.should_warn_unkeyed(),+ "an unidentifiable subagent should consume the warning"+ );Ok(())}