[Monitor OpenTelemetry Exporter] Update Customer SDK Stats Drop Reason (#35599)

### Packages impacted by this PR
@azure/monitor-opentelemetry-exporter

### Describe the problem that is addressed by this PR
This pull request refines how drop and retry reasons are tracked and
reported for customer SDK Stats in the Azure Monitor OpenTelemetry
exporter. The main focus is on improving the clarity and categorization
of drop/retry reasons, especially for client exceptions, and updating
related enums, method signatures, and tests to support these changes.

### Drop/Retry Reason Categorization and API Updates

* Enhanced drop and retry reason tracking by introducing the
`ExceptionType` enum, allowing explicit and well-known categorization
(such as "Network exception", "Timeout exception", etc.) for client
exceptions, rather than relying on raw exception messages. Method
signatures for `countDroppedItems` and `countRetryItems` now accept an
optional `exceptionType` parameter for better specificity.
[[1]](diffhunk://#diff-2f4066f1034ba4adc1b1010a2db050dd609f6b2f1d5935ac9e0574d293c148f1L12-R12)
[[2]](diffhunk://#diff-2f4066f1034ba4adc1b1010a2db050dd609f6b2f1d5935ac9e0574d293c148f1L264-R271)
[[3]](diffhunk://#diff-2f4066f1034ba4adc1b1010a2db050dd609f6b2f1d5935ac9e0574d293c148f1R305-R322)
[[4]](diffhunk://#diff-2f4066f1034ba4adc1b1010a2db050dd609f6b2f1d5935ac9e0574d293c148f1R465-R482)
[[5]](diffhunk://#diff-88b62eef1c76c2db9a03f6c670881c41bab6de71bbb9c3fceeb1c33f0c9a455dR225-R235)
* Updated the logic for generating drop/retry reason strings to use more
descriptive and consistent values (e.g., "Bad request", "Internal server
error", "Client exception") and removed ambiguous or redundant
drop/retry codes from the `DropCode` and `RetryCode` enums.
[[1]](diffhunk://#diff-2f4066f1034ba4adc1b1010a2db050dd609f6b2f1d5935ac9e0574d293c148f1L323-R373)
[[2]](diffhunk://#diff-2f4066f1034ba4adc1b1010a2db050dd609f6b2f1d5935ac9e0574d293c148f1L381-R414)
[[3]](diffhunk://#diff-2f4066f1034ba4adc1b1010a2db050dd609f6b2f1d5935ac9e0574d293c148f1L479-R496)
[[4]](diffhunk://#diff-88b62eef1c76c2db9a03f6c670881c41bab6de71bbb9c3fceeb1c33f0c9a455dL185-L195)

### Integration and Usage Improvements

* Refactored internal usage to pass the appropriate `ExceptionType` when
recording dropped or retried items, ensuring that reasons are
categorized correctly in all relevant code paths, including persistent
storage and sender logic.
[[1]](diffhunk://#diff-3614c3b3d4cc1da2e731ad02fe179b1a84a8d0dcfd9be0baaa5140063aa91305L201-R207)
[[2]](diffhunk://#diff-3614c3b3d4cc1da2e731ad02fe179b1a84a8d0dcfd9be0baaa5140063aa91305R241)
[[3]](diffhunk://#diff-3614c3b3d4cc1da2e731ad02fe179b1a84a8d0dcfd9be0baaa5140063aa91305R278)
[[4]](diffhunk://#diff-80933cb94c81fd07a551d1a848a4bd43ff16ab274bdf75fb5e92567a76a2bbcdR199)
* Updated tests to verify the new reason categorization, ensuring that
drop/retry reasons are mapped to the correct well-known categories and
that exception messages are only used for client exceptions. Test
descriptions and assertions have been clarified to reflect the new
behavior.
[[1]](diffhunk://#diff-e92bd4b395d01c03dd800ccdfb0053a70100c18c216dcde1d6789be817018427R744)
[[2]](diffhunk://#diff-e92bd4b395d01c03dd800ccdfb0053a70100c18c216dcde1d6789be817018427R775-R780)
[[3]](diffhunk://#diff-e92bd4b395d01c03dd800ccdfb0053a70100c18c216dcde1d6789be817018427L799-R802)
[[4]](diffhunk://#diff-d1341d0902c02c5da1fa738a22afc4b7f186367d0e29fff1db008c4ec9c05e68L99-R100)
[[5]](diffhunk://#diff-d1341d0902c02c5da1fa738a22afc4b7f186367d0e29fff1db008c4ec9c05e68L119-R128)

### Documentation

* Updated the changelog to reflect the renaming of the feature and the
changes to drop.reason values for customer SDK Stats.

**Documentation:**

* Updated the changelog to note the change to drop.reason values for
customer SDK Stats.

### Command used to generate this PR:**_(Applicable only to SDK release
request PRs)_

### Checklists
- [x] Added impacted package name to the issue description
- [ ] Does this PR needs any fixes in the SDK Generator?** _(If so,
create an Issue in the
[Autorest/typescript](https://github.com/Azure/autorest.typescript)
repository and link it here)_
- [x] Added a changelog (if necessary)

Author: JacksonWeber

sdk/monitor/monitor-opentelemetry-exporter/CHANGELOG.md

@@ -11,6 +11,7 @@
 ### Other Changes
 
 - Renamed Customer Statsbeat feature to customer SDK Stats.
+- Update drop.reason values for customer SDK Stats.
 - Update logic setting ai.location.ip to use the microsoft.client.ip value by default.
 
 ## 1.0.0-beta.33 (2025-08-04)

sdk/monitor/monitor-opentelemetry-exporter/src/export/statsbeat/customerSDKStats.ts

@@ -9,7 +9,7 @@ import type { AzureMonitorExporterOptions } from "../../index.js";
 import * as ai from "../../utils/constants/applicationinsights.js";
 import { StatsbeatMetrics } from "./statsbeatMetrics.js";
 import type { CustomerSDKStatsProperties, StatsbeatOptions } from "./types.js";
-import { CustomerSDKStats, DropCode, RetryCode } from "./types.js";
+import { CustomerSDKStats, DropCode, RetryCode, ExceptionType, DropReason } from "./types.js";
 import { CustomSDKStatsCounter, STATSBEAT_LANGUAGE, TelemetryType } from "./types.js";
 import { getAttachType } from "../../utils/metricUtils.js";
 import { AzureMonitorStatsbeatExporter } from "./statsbeatExporter.js";
@@ -282,11 +282,13 @@ export class CustomerSDKStatsMetrics extends StatsbeatMetrics {
    * @param envelopes - Array of envelopes dropped
    * @param dropCode - The drop code indicating the reason for drop
    * @param exceptionMessage - Optional exception message when dropCode is CLIENT_EXCEPTION
+   * @param exceptionType - Optional explicit exception type override when dropCode is CLIENT_EXCEPTION
    */
   public countDroppedItems(
     envelopes: Envelope[],
     dropCode: DropCode | number,
     exceptionMessage?: string,
+    exceptionType?: ExceptionType,
   ): void {
     const counter: CustomerSDKStats = this.customerSDKStatsCounter;
     let telemetry_type: TelemetryType;
@@ -308,7 +310,7 @@ export class CustomerSDKStatsMetrics extends StatsbeatMetrics {
       }
 
       // Generate a low-cardinality, informative reason description
-      const reason = this.getDropReason(dropCode, exceptionMessage);
+      const reason = this.getDropReason(dropCode, exceptionMessage, exceptionType);
 
       // Get or create the success map for this reason
       let successMap = reasonMap.get(reason);
@@ -335,15 +337,24 @@ export class CustomerSDKStatsMetrics extends StatsbeatMetrics {
    * Generates a low-cardinality, informative description for drop reasons
    * @param dropCode - The drop code (enum value or status code number)
    * @param exceptionMessage - Optional exception message for CLIENT_EXCEPTION
+   * @param exceptionType - Optional explicit exception type override for CLIENT_EXCEPTION
    * @returns A descriptive reason string with low cardinality
    */
-  private getDropReason(dropCode: DropCode | number, exceptionMessage?: string): string {
+  private getDropReason(
+    dropCode: DropCode | number,
+    exceptionMessage?: string,
+    exceptionType?: ExceptionType,
+  ): string {
     if (dropCode === DropCode.CLIENT_EXCEPTION) {
-      // For client exceptions, derive a low-cardinality reason from the exception message
+      // If an explicit exception type is provided, use it
+      if (exceptionType) {
+        return exceptionType;
+      }
+      // For client exceptions, derive a well-known exception category from the exception message
       if (exceptionMessage) {
         return this.categorizeExceptionMessage(exceptionMessage);
       }
-      return "unknown_exception";
+      return ExceptionType.CLIENT_EXCEPTION; // Default to "Client exception" if no message provided
     }
 
     // Handle status code drop codes (numeric values)
@@ -353,54 +364,46 @@ export class CustomerSDKStatsMetrics extends StatsbeatMetrics {
 
     // Handle other enum drop codes
     switch (dropCode) {
-      case DropCode.CLIENT_EXPIRED_DATA:
-        return "expired_data";
       case DropCode.CLIENT_READONLY:
-        return "readonly_mode";
-      case DropCode.CLIENT_STALE_DATA:
-        return "stale_data";
+        return DropReason.CLIENT_READONLY;
       case DropCode.CLIENT_PERSISTENCE_CAPACITY:
-        return "persistence_full";
-      case DropCode.NON_RETRYABLE_STATUS_CODE:
-        return "non_retryable_status";
+        return DropReason.CLIENT_PERSISTENCE_CAPACITY;
       case DropCode.UNKNOWN:
       default:
-        return "unknown_reason";
+        return DropReason.UNKNOWN;
     }
   }
 
   /**
-   * Categorizes exception messages into low-cardinality groups
+   * Categorizes exception messages into well-known exception categories
    * @param exceptionMessage - The exception message to categorize
-   * @returns A low-cardinality category string
+   * @returns A well-known exception category string
    */
-  private categorizeExceptionMessage(exceptionMessage: string): string {
+  private categorizeExceptionMessage(exceptionMessage: string): ExceptionType {
     const message = exceptionMessage.toLowerCase();
 
     if (message.includes("timeout") || message.includes("timed out")) {
-      return "timeout_exception";
-    }
-    if (message.includes("network") || message.includes("connection")) {
-      return "network_exception";
+      return ExceptionType.TIMEOUT_EXCEPTION;
     }
     if (
-      message.includes("auth") ||
-      message.includes("unauthorized") ||
-      message.includes("forbidden")
+      message.includes("network") ||
+      message.includes("connection") ||
+      message.includes("dns") ||
+      message.includes("socket")
     ) {
-      return "auth_exception";
-    }
-    if (message.includes("parsing") || message.includes("parse") || message.includes("invalid")) {
-      return "parsing_exception";
-    }
-    if (message.includes("disk") || message.includes("storage") || message.includes("file")) {
-      return "storage_exception";
+      return ExceptionType.NETWORK_EXCEPTION;
     }
-    if (message.includes("memory") || message.includes("out of memory")) {
-      return "memory_exception";
+    if (
+      message.includes("disk") ||
+      message.includes("storage") ||
+      message.includes("file") ||
+      message.includes("persist")
+    ) {
+      return ExceptionType.STORAGE_EXCEPTION;
     }
 
-    return "other_exception";
+    // Default to Client exception for any other cases
+    return ExceptionType.CLIENT_EXCEPTION;
   }
 
   /**
@@ -412,36 +415,36 @@ export class CustomerSDKStatsMetrics extends StatsbeatMetrics {
     if (statusCode >= 400 && statusCode < 500) {
       switch (statusCode) {
         case 400:
-          return "bad_request";
+          return "Bad request";
         case 401:
-          return "unauthorized";
+          return "Unauthorized";
         case 403:
-          return "forbidden";
+          return "Forbidden";
         case 404:
-          return "not_found";
+          return "Not found";
         case 408:
-          return "request_timeout";
+          return "Request timeout";
         case 413:
-          return "payload_too_large";
+          return "Payload too large";
         case 429:
-          return "too_many_requests";
+          return "Too many requests";
         default:
-          return "client_error_4xx";
+          return "Client error 4xx";
       }
     }
 
     if (statusCode >= 500 && statusCode < 600) {
       switch (statusCode) {
         case 500:
-          return "internal_server_error";
+          return "Internal server error";
         case 502:
-          return "bad_gateway";
+          return "Bad gateway";
         case 503:
-          return "service_unavailable";
+          return "Service unavailable";
         case 504:
-          return "gateway_timeout";
+          return "Gateway timeout";
         default:
-          return "server_error_5xx";
+          return "Server error 5xx";
       }
     }
 
@@ -451,13 +454,14 @@ export class CustomerSDKStatsMetrics extends StatsbeatMetrics {
    * Tracks retried envelopes
    * @param envelopes - Number of envelopes retried
    * @param retryCode - The retry code indicating the reason for retry
-   * @param telemetry_type - The type of telemetry being tracked
    * @param exceptionMessage - Optional exception message when retryCode is CLIENT_EXCEPTION
+   * @param exceptionType - Optional explicit exception type override when retryCode is CLIENT_EXCEPTION
    */
   public countRetryItems(
     envelopes: Envelope[],
     retryCode: RetryCode | number,
     exceptionMessage?: string,
+    exceptionType?: ExceptionType,
   ): void {
     const counter: CustomerSDKStats = this.customerSDKStatsCounter;
     let telemetry_type: TelemetryType;
@@ -479,7 +483,7 @@ export class CustomerSDKStatsMetrics extends StatsbeatMetrics {
       }
 
       // Generate a low-cardinality, informative reason description
-      const reason = this.getRetryReason(retryCode, exceptionMessage);
+      const reason = this.getRetryReason(retryCode, exceptionMessage, exceptionType);
 
       // Update the count for this reason
       const currentCount = reasonMap.get(reason) || 0;
@@ -491,15 +495,24 @@ export class CustomerSDKStatsMetrics extends StatsbeatMetrics {
    * Generates a low-cardinality, informative description for retry reasons
    * @param retryCode - The retry code (enum value or status code number)
    * @param exceptionMessage - Optional exception message for CLIENT_EXCEPTION
+   * @param exceptionType - Optional explicit exception type override for CLIENT_EXCEPTION
    * @returns A descriptive reason string with low cardinality
    */
-  private getRetryReason(retryCode: RetryCode | number, exceptionMessage?: string): string {
+  private getRetryReason(
+    retryCode: RetryCode | number,
+    exceptionMessage?: string,
+    exceptionType?: ExceptionType,
+  ): string {
     if (retryCode === RetryCode.CLIENT_EXCEPTION) {
+      // If an explicit exception type is provided, use it
+      if (exceptionType) {
+        return exceptionType;
+      }
       // For client exceptions, derive a low-cardinality reason from the exception message
       if (exceptionMessage) {
         return this.categorizeExceptionMessage(exceptionMessage);
       }
-      return "unknown_exception";
+      return ExceptionType.CLIENT_EXCEPTION;
     }
 
     // Handle status code retry codes (numeric values)
@@ -510,12 +523,10 @@ export class CustomerSDKStatsMetrics extends StatsbeatMetrics {
     // Handle other enum retry codes
     switch (retryCode) {
       case RetryCode.CLIENT_TIMEOUT:
-        return "client_timeout";
-      case RetryCode.RETRYABLE_STATUS_CODE:
-        return "retryable_status";
+        return "Client timeout";
       case RetryCode.UNKNOWN:
       default:
-        return "unknown_reason";
+        return "Unknown reason";
     }
   }
 

sdk/monitor/monitor-opentelemetry-exporter/src/export/statsbeat/types.ts

@@ -187,19 +187,15 @@ export enum TelemetryType {
 
 export enum DropCode {
   CLIENT_EXCEPTION = "CLIENT_EXCEPTION",
-  CLIENT_EXPIRED_DATA = "CLIENT_EXPIRED_DATA",
   CLIENT_READONLY = "CLIENT_READONLY",
-  CLIENT_STALE_DATA = "CLIENT_STALE_DATA",
   CLIENT_PERSISTENCE_CAPACITY = "CLIENT_PERSISTENCE_CAPACITY",
-  NON_RETRYABLE_STATUS_CODE = "NON_RETRYABLE_STATUS_CODE",
   CLIENT_STORAGE_DISABLED = "CLIENT_STORAGE_DISABLED",
   UNKNOWN = "UNKNOWN",
 }
 
 export enum RetryCode {
   CLIENT_EXCEPTION = "CLIENT_EXCEPTION",
   CLIENT_TIMEOUT = "CLIENT_TIMEOUT",
-  RETRYABLE_STATUS_CODE = "RETRYABLE_STATUS_CODE",
   UNKNOWN = "UNKNOWN",
 }
 
@@ -232,6 +228,26 @@ export enum StatsbeatFeatureType {
   INSTRUMENTATION = 1,
 }
 
+/**
+ * Exception types for client exceptions
+ * @internal
+ */
+export enum ExceptionType {
+  CLIENT_EXCEPTION = "Client exception",
+  NETWORK_EXCEPTION = "Network exception",
+  STORAGE_EXCEPTION = "Storage exception",
+  TIMEOUT_EXCEPTION = "Timeout exception",
+}
+
+/**
+ * Reasons for dropping telemetry
+ */
+export enum DropReason {
+  CLIENT_READONLY = "Client readonly",
+  CLIENT_PERSISTENCE_CAPACITY = "Client persistence capacity",
+  UNKNOWN = "Unknown",
+}
+
 /**
  * Status codes indicating that we should shutdown statsbeat
  * @internal

sdk/monitor/monitor-opentelemetry-exporter/src/platform/nodejs/baseSender.ts

@@ -3,6 +3,7 @@
 
 import { diag } from "@opentelemetry/api";
 import type { PersistentStorage, SenderResult } from "../../types.js";
+import { ExceptionType } from "../../export/statsbeat/types.js";
 import type { AzureMonitorExporterOptions } from "../../config.js";
 import { FileSystemPersist } from "./persist/index.js";
 import type { ExportResult } from "@opentelemetry/core";
@@ -247,6 +248,7 @@ export abstract class BaseSender {
               envelopes,
               DropCode.CLIENT_EXCEPTION,
               redirectError.message,
+              ExceptionType.CLIENT_EXCEPTION,
             );
           }
           return { code: ExportResultCode.FAILED, error: redirectError };
@@ -283,6 +285,7 @@ export abstract class BaseSender {
             envelopes,
             RetryCode.CLIENT_TIMEOUT,
             "timeout_exception",
+            ExceptionType.TIMEOUT_EXCEPTION,
           );
           diag.error("Request timed out. Error message:", restError.message);
         } else if (restError.statusCode) {

sdk/monitor/monitor-opentelemetry-exporter/src/platform/nodejs/persist/fileSystemPersist.ts

@@ -10,7 +10,7 @@ import { confirmDirExists, getShallowDirectorySize } from "./fileSystemHelpers.j
 import type { AzureMonitorExporterOptions } from "../../../config.js";
 import { readdir, readFile, stat, unlink, writeFile } from "node:fs/promises";
 import type { CustomerSDKStatsMetrics } from "../../../export/statsbeat/customerSDKStats.js";
-import { DropCode } from "../../../export/statsbeat/types.js";
+import { DropCode, ExceptionType } from "../../../export/statsbeat/types.js";
 import type { TelemetryItem as Envelope } from "../../../generated/index.js";
 
 /**
@@ -196,6 +196,7 @@ export class FileSystemPersist implements PersistentStorage {
         envelopes,
         DropCode.CLIENT_EXCEPTION,
         writeError?.message,
+        ExceptionType.STORAGE_EXCEPTION,
       );
       diag.warn(`Error writing file to persistent file storage`, writeError);
       return false;

sdk/monitor/monitor-opentelemetry-exporter/test/internal/baseSender.spec.ts

@@ -743,6 +743,7 @@ describe("BaseSender", () => {
         envelopes,
         "CLIENT_EXCEPTION",
         "Circular redirect",
+        "Client exception",
       );
     });
 
@@ -774,7 +775,7 @@ describe("BaseSender", () => {
       );
     });
 
-    it("should not capture exception.message for NON_RETRYABLE_STATUS_CODE", async () => {
+    it("should not capture exception.message for status code errors", async () => {
       testSender.sendMock.mockResolvedValue({
         statusCode: 400,
         result: "Bad Request",
@@ -796,7 +797,7 @@ describe("BaseSender", () => {
       expect(result.code).toBe(ExportResultCode.FAILED);
       expect(mockCustomerSDKStatsMetrics.countDroppedItems).toHaveBeenCalledWith(envelopes, 400);
 
-      // Verify exception.message is not passed for non-client exceptions
+      // Verify exception.message is not passed for status code errors
       const call = mockCustomerSDKStatsMetrics.countDroppedItems.mock.calls[0];
       expect(call.length).toBe(2); // envelopes array, drop code (no drop reason)
     });