feat(telemetry): stable reason codes, reasonDesc field

- Ports "reasonDesc" from IDE telemetry.
- Add stable reason codes for easier metric tracking

Author: hayemaxi

crates/chat-cli/src/api_client/error.rs

@@ -8,13 +8,15 @@ use amzn_consolas_client::operation::generate_recommendations::GenerateRecommend
 use amzn_consolas_client::operation::list_customizations::ListCustomizationsError;
 use amzn_qdeveloper_streaming_client::operation::send_message::SendMessageError as QDeveloperSendMessageError;
 use amzn_qdeveloper_streaming_client::types::error::ChatResponseStreamError as QDeveloperChatResponseStreamError;
+use aws_sdk_ssooidc::error::ProvideErrorMetadata;
 use aws_smithy_runtime_api::client::orchestrator::HttpResponse;
 pub use aws_smithy_runtime_api::client::result::SdkError;
 use aws_smithy_types::event_stream::RawMessage;
 use thiserror::Error;
 
 use crate::auth::AuthError;
 use crate::aws_common::SdkErrorDisplay;
+use crate::telemetry::ReasonCode;
 
 #[derive(Debug, Error)]
 pub enum ApiClientError {
@@ -68,6 +70,36 @@ pub enum ApiClientError {
     AuthError(#[from] AuthError),
 }
 
+impl ReasonCode for ApiClientError {
+    fn reason_code(&self) -> String {
+        match self {
+            ApiClientError::GenerateCompletions(e) => sdk_error_code(e),
+            ApiClientError::GenerateRecommendations(e) => sdk_error_code(e),
+            ApiClientError::ListAvailableCustomizations(e) => sdk_error_code(e),
+            ApiClientError::ListAvailableServices(e) => sdk_error_code(e),
+            ApiClientError::CodewhispererGenerateAssistantResponse(e) => sdk_error_code(e),
+            ApiClientError::QDeveloperSendMessage(e) => sdk_error_code(e),
+            ApiClientError::CodewhispererChatResponseStream(e) => sdk_error_code(e),
+            ApiClientError::QDeveloperChatResponseStream(e) => sdk_error_code(e),
+            ApiClientError::ListAvailableProfilesError(e) => sdk_error_code(e),
+            ApiClientError::SendTelemetryEvent(e) => sdk_error_code(e),
+            ApiClientError::QuotaBreach(_) => "QuotaBreachError".to_string(),
+            ApiClientError::ContextWindowOverflow => "ContextWindowOverflow".to_string(),
+            ApiClientError::SmithyBuild(_) => "SmithyBuildError".to_string(),
+            ApiClientError::AuthError(_) => "AuthError".to_string(),
+        }
+    }
+}
+
+fn sdk_error_code<T, R>(e: &SdkError<T, R>) -> String
+where
+    T: ProvideErrorMetadata,
+{
+    e.as_service_error()
+        .and_then(|se| se.meta().code().map(str::to_string))
+        .unwrap_or_else(|| e.to_string())
+}
+
 #[cfg(test)]
 mod tests {
     use std::error::Error as _;

crates/chat-cli/src/cli/chat/mod.rs

@@ -22,7 +22,6 @@ use std::collections::{
     HashSet,
     VecDeque,
 };
-use std::error::Error;
 use std::io::{
     IsTerminal,
     Read,
@@ -66,7 +65,6 @@ use crossterm::{
     terminal,
 };
 use eyre::{
-    Chain,
     ErrReport,
     Result,
     bail,
@@ -158,8 +156,10 @@ use crate::mcp_client::{
 use crate::platform::Context;
 use crate::telemetry::core::ToolUseEventBuilder;
 use crate::telemetry::{
+    ReasonCode,
     TelemetryResult,
     TelemetryThread,
+    get_error_reason,
 };
 
 #[derive(Debug, Clone, PartialEq, Eq, Default, Args)]
@@ -494,6 +494,21 @@ pub enum ChatError {
     GetPromptError(#[from] GetPromptError),
 }
 
+impl ReasonCode for ChatError {
+    fn reason_code(&self) -> String {
+        match self {
+            ChatError::Client(e) => e.reason_code(),
+            ChatError::ResponseStream(e) => e.reason_code(),
+            ChatError::Std(_) => "StdIoError".to_string(),
+            ChatError::Readline(_) => "ReadlineError".to_string(),
+            ChatError::Custom(_) => "GenericError".to_string(),
+            ChatError::Interrupted { .. } => "Interrupted".to_string(),
+            ChatError::NonInteractiveToolApproval => "NonInteractiveToolApprovalError".to_string(),
+            ChatError::GetPromptError(_) => "GetPromptError".to_string(),
+        }
+    }
+}
+
 pub struct ChatContext {
     ctx: Arc<Context>,
     /// The [Write] destination for printing conversation text.
@@ -869,7 +884,7 @@ impl ChatContext {
                 ChatState::HandleResponseStream(response) => tokio::select! {
                     res = self.handle_response(database, telemetry, response) => res,
                     Ok(_) = ctrl_c_stream => {
-                        self.send_chat_telemetry(database, telemetry, None, TelemetryResult::Cancelled, None).await;
+                        self.send_chat_telemetry(database, telemetry, None, TelemetryResult::Cancelled, None, None).await;
 
                         Err(ChatError::Interrupted { tool_uses: None })
                     }
@@ -894,7 +909,8 @@ impl ChatContext {
         match result {
             Ok(state) => Ok(state),
             Err(e) => {
-                self.send_error_telemetry(database, telemetry, get_error_string(&e))
+                let (reason, reason_desc) = get_error_reason(&e);
+                self.send_error_telemetry(database, telemetry, reason, Some(reason_desc))
                     .await;
 
                 macro_rules! print_err {
@@ -1089,12 +1105,14 @@ impl ChatContext {
         let response = match response {
             Ok(res) => res,
             Err(e) => {
+                let (reason, reason_desc) = get_error_reason(&e);
                 self.send_chat_telemetry(
                     database,
                     telemetry,
                     None,
                     TelemetryResult::Failed,
-                    Some(get_error_string(&e)),
+                    Some(reason),
+                    Some(reason_desc),
                 )
                 .await;
                 match e {
@@ -1137,12 +1155,14 @@ impl ChatContext {
                         if let Some(request_id) = &err.request_id {
                             self.failed_request_ids.push(request_id.clone());
                         };
+                        let (reason, reason_desc) = get_error_reason(&err);
                         self.send_chat_telemetry(
                             database,
                             telemetry,
                             err.request_id.clone(),
                             TelemetryResult::Failed,
-                            Some(get_error_string(&err)),
+                            Some(reason),
+                            Some(reason_desc),
                         )
                         .await;
                         return Err(err.into());
@@ -1160,7 +1180,8 @@ impl ChatContext {
                 cursor::Show
             )?;
         }
-        self.send_chat_telemetry(database, telemetry, request_id, TelemetryResult::Succeeded, None)
+
+        self.send_chat_telemetry(database, telemetry, request_id, TelemetryResult::Succeeded, None, None)
             .await;
 
         self.conversation_state.replace_history_with_summary(summary.clone());
@@ -3266,12 +3287,14 @@ impl ChatContext {
                         self.failed_request_ids.push(request_id.clone());
                     };
 
+                    let (reason, reason_desc) = get_error_reason(&recv_error);
                     self.send_chat_telemetry(
                         database,
                         telemetry,
                         recv_error.request_id.clone(),
                         TelemetryResult::Failed,
-                        Some(get_error_string(&recv_error)),
+                        Some(reason),
+                        Some(reason_desc),
                     )
                     .await;
 
@@ -3383,7 +3406,7 @@ impl ChatContext {
             }
 
             if ended {
-                self.send_chat_telemetry(database, telemetry, request_id, TelemetryResult::Succeeded, None)
+                self.send_chat_telemetry(database, telemetry, request_id, TelemetryResult::Succeeded, None, None)
                     .await;
 
                 if self.interactive
@@ -3680,6 +3703,7 @@ impl ChatContext {
         request_id: Option<String>,
         result: TelemetryResult,
         reason: Option<String>,
+        reason_desc: Option<String>,
     ) {
         telemetry
             .send_chat_added_message(
@@ -3690,19 +3714,27 @@ impl ChatContext {
                 self.conversation_state.context_message_length(),
                 result,
                 reason,
+                reason_desc,
             )
             .await
             .ok();
     }
 
-    async fn send_error_telemetry(&self, database: &Database, telemetry: &TelemetryThread, reason: String) {
+    async fn send_error_telemetry(
+        &self,
+        database: &Database,
+        telemetry: &TelemetryThread,
+        reason: String,
+        reason_desc: Option<String>,
+    ) {
         telemetry
             .send_response_error(
                 database,
                 self.conversation_state.conversation_id().to_owned(),
                 self.conversation_state.context_message_length(),
                 TelemetryResult::Failed,
                 Some(reason),
+                reason_desc,
             )
             .await
             .ok();
@@ -3805,22 +3837,6 @@ fn create_stream(model_responses: serde_json::Value) -> StreamingClient {
     StreamingClient::mock(mock)
 }
 
-/// Returns surface error + root cause as a string. If there is only one error
-/// in the chain, return that as a string.
-fn get_error_string(error: &(dyn Error + 'static)) -> String {
-    let err_chain = Chain::new(error);
-
-    if err_chain.len() > 1 {
-        format!(
-            "'{}' caused by: {}",
-            error,
-            err_chain.last().map_or("UNKNOWN".to_string(), |e| e.to_string())
-        )
-    } else {
-        error.to_string()
-    }
-}
-
 #[cfg(test)]
 mod tests {
     use super::*;

crates/chat-cli/src/cli/chat/parser.rs

@@ -21,6 +21,7 @@ use super::message::{
 };
 use crate::api_client::clients::SendMessageOutput;
 use crate::api_client::model::ChatResponseStream;
+use crate::telemetry::ReasonCode;
 
 #[derive(Debug, Error)]
 pub struct RecvError {
@@ -30,6 +31,12 @@ pub struct RecvError {
     pub source: RecvErrorKind,
 }
 
+impl ReasonCode for RecvError {
+    fn reason_code(&self) -> String {
+        "RecvError".to_string()
+    }
+}
+
 impl std::fmt::Display for RecvError {
     fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
         write!(f, "Failed to receive the next message: ")?;

crates/chat-cli/src/telemetry/core.rs

@@ -130,6 +130,7 @@ impl Event {
                 request_id,
                 result,
                 reason,
+                reason_desc,
                 ..
             } => Some(
                 CodewhispererterminalAddChatMessage {
@@ -144,6 +145,7 @@ impl Event {
                     codewhispererterminal_context_file_length: context_file_length.map(|l| l as i64).map(Into::into),
                     result: result.to_string().into(),
                     reason: reason.map(Into::into),
+                    reason_desc: reason_desc.map(Into::into),
                 }
                 .into_metric_datum(),
             ),
@@ -242,6 +244,7 @@ impl Event {
                 context_file_length,
                 result,
                 reason,
+                reason_desc,
             } => Some(
                 AmazonqMessageResponseError {
                     create_time: self.created_time,
@@ -252,6 +255,7 @@ impl Event {
                     sso_region: self.sso_region.map(Into::into),
                     result: Some(result.to_string().into()),
                     reason: reason.map(Into::into),
+                    reason_desc: reason_desc.map(Into::into),
                 }
                 .into_metric_datum(),
             ),
@@ -286,6 +290,7 @@ pub enum EventType {
         context_file_length: Option<usize>,
         result: TelemetryResult,
         reason: Option<String>,
+        reason_desc: Option<String>,
     },
     ToolUseSuggested {
         conversation_id: String,
@@ -322,6 +327,7 @@ pub enum EventType {
     MessageResponseError {
         result: TelemetryResult,
         reason: Option<String>,
+        reason_desc: Option<String>,
         conversation_id: String,
         context_file_length: Option<usize>,
     },

crates/chat-cli/src/telemetry/definitions.rs

@@ -29,6 +29,7 @@ mod tests {
             codewhispererterminal_utterance_id: Some("message_id".to_owned().into()),
             result: crate::telemetry::definitions::types::Result::new("Succeeded".to_string()),
             reason: None,
+            reason_desc: None,
         });
 
         let s = serde_json::to_string_pretty(&metric_datum_init).unwrap();

crates/chat-cli/src/telemetry/mod.rs

@@ -195,6 +195,7 @@ impl TelemetryThread {
         context_file_length: Option<usize>,
         result: TelemetryResult,
         reason: Option<String>,
+        reason_desc: Option<String>,
     ) -> Result<(), TelemetryError> {
         let mut event = Event::new(EventType::ChatAddedMessage {
             conversation_id,
@@ -203,6 +204,7 @@ impl TelemetryThread {
             context_file_length,
             result,
             reason,
+            reason_desc,
         });
         set_start_url_and_region(database, &mut event).await;
 
@@ -278,10 +280,12 @@ impl TelemetryThread {
         context_file_length: Option<usize>,
         result: TelemetryResult,
         reason: Option<String>,
+        reason_desc: Option<String>,
     ) -> Result<(), TelemetryError> {
         let mut event = Event::new(EventType::MessageResponseError {
             result,
             reason,
+            reason_desc,
             conversation_id,
             context_file_length,
         });
@@ -476,6 +480,29 @@ impl TelemetryClient {
     }
 }
 
+pub trait ReasonCode: std::error::Error {
+    fn reason_code(&self) -> String;
+}
+
+/// Returns a generic error reason + reason description pair.
+pub fn get_error_reason<E>(error: &E) -> (String, String)
+where
+    E: ReasonCode + 'static,
+{
+    let err_chain = eyre::Chain::new(error);
+    let reason_desc = if err_chain.len() > 1 {
+        format!(
+            "'{}' caused by: {}",
+            error,
+            err_chain.last().map_or("UNKNOWN".to_string(), |e| e.to_string())
+        )
+    } else {
+        error.to_string()
+    };
+
+    (error.reason_code(), reason_desc)
+}
+
 #[cfg(test)]
 mod test {
     use uuid::uuid;
@@ -537,6 +564,7 @@ mod test {
                 Some(123),
                 TelemetryResult::Succeeded,
                 None,
+                None,
             )
             .await
             .ok();