feat(integrations): Improve error formatting in ZodErrors integration

- Include full key path rather than the top level key in title
- Improve message for validation issues with no path
- Add option to include extended issue information as an attachment

Author: jahands

packages/core/package.json

@@ -61,5 +61,8 @@
   "volta": {
     "extends": "../../package.json"
   },
-  "sideEffects": false
+  "sideEffects": false,
+  "devDependencies": {
+    "zod": "^3.24.1"
+  }
 }

packages/core/src/integrations/zoderrors.ts

@@ -5,33 +5,45 @@ import { truncate } from '../utils-hoist/string';
 
 interface ZodErrorsOptions {
   key?: string;
+  /**
+   * Limits the number of Zod errors inlined in each Sentry event.
+   *
+   * @default 10
+   */
   limit?: number;
+  /**
+   * Save full error info as an attachment in Sentry
+   *
+   * @default false
+   */
+  saveAttachments?: boolean;
 }
 
 const DEFAULT_LIMIT = 10;
 const INTEGRATION_NAME = 'ZodErrors';
 
-// Simplified ZodIssue type definition
+/**
+ * Simplified ZodIssue type definition
+ */
 interface ZodIssue {
   path: (string | number)[];
   message?: string;
-  expected?: string | number;
-  received?: string | number;
+  expected?: unknown;
+  received?: unknown;
   unionErrors?: unknown[];
   keys?: unknown[];
+  invalid_literal?: unknown;
 }
 
 interface ZodError extends Error {
   issues: ZodIssue[];
-
-  get errors(): ZodError['issues'];
 }
 
 function originalExceptionIsZodError(originalException: unknown): originalException is ZodError {
   return (
     isError(originalException) &&
     originalException.name === 'ZodError' &&
-    Array.isArray((originalException as ZodError).errors)
+    Array.isArray((originalException as ZodError).issues)
   );
 }
 
@@ -45,9 +57,18 @@ type SingleLevelZodIssue<T extends ZodIssue> = {
 
 /**
  * Formats child objects or arrays to a string
- * That is preserved when sent to Sentry
+ * that is preserved when sent to Sentry.
+ *
+ * Without this, we end up with something like this in Sentry:
+ *
+ * [
+ *  [Object],
+ *  [Object],
+ *  [Object],
+ *  [Object]
+ * ]
  */
-function formatIssueTitle(issue: ZodIssue): SingleLevelZodIssue<ZodIssue> {
+export function flattenIssue(issue: ZodIssue): SingleLevelZodIssue<ZodIssue> {
   return {
     ...issue,
     path: 'path' in issue && Array.isArray(issue.path) ? issue.path.join('.') : undefined,
@@ -56,64 +77,142 @@ function formatIssueTitle(issue: ZodIssue): SingleLevelZodIssue<ZodIssue> {
   };
 }
 
+/**
+ * Takes ZodError issue path array and returns a flattened version as a string.
+ * This makes it easier to display paths within a Sentry error message.
+ *
+ * Array indexes are normalized to reduce duplicate entries
+ *
+ * @param path ZodError issue path
+ * @returns flattened path
+ *
+ * @example
+ * flattenIssuePath([0, 'foo', 1, 'bar']) // -> '<array>.foo.<array>.bar'
+ */
+export function flattenIssuePath(path: Array<string | number>): string {
+  return path
+    .map(p => {
+      if (typeof p === 'number') {
+        return '<array>';
+      } else {
+        return p;
+      }
+    })
+    .join('.');
+}
+
 /**
  * Zod error message is a stringified version of ZodError.issues
  * This doesn't display well in the Sentry UI. Replace it with something shorter.
  */
-function formatIssueMessage(zodError: ZodError): string {
+export function formatIssueMessage(zodError: ZodError): string {
   const errorKeyMap = new Set<string | number | symbol>();
   for (const iss of zodError.issues) {
-    if (iss.path?.[0]) {
-      errorKeyMap.add(iss.path[0]);
+    const issuePath = flattenIssuePath(iss.path);
+    if (issuePath.length > 0) {
+      errorKeyMap.add(issuePath);
     }
   }
-  const errorKeys = Array.from(errorKeyMap);
 
+  const errorKeys = Array.from(errorKeyMap);
+  if (errorKeys.length === 0) {
+    // If there are no keys, then we're likely validating the root
+    // variable rather than a key within an object. This attempts
+    // to extract what type it was that failed to validate.
+    // For example, z.string().parse(123) would return "string" here.
+    let rootExpectedType = 'variable';
+    if (zodError.issues.length > 0) {
+      const iss = zodError.issues[0];
+      if (iss !== undefined && 'expected' in iss && typeof iss.expected === 'string') {
+        rootExpectedType = iss.expected;
+      }
+    }
+    return `Failed to validate ${rootExpectedType}`;
+  }
   return `Failed to validate keys: ${truncate(errorKeys.join(', '), 100)}`;
 }
 
 /**
- * Applies ZodError issues to an event extras and replaces the error message
+ * Applies ZodError issues to an event extra and replaces the error message
  */
-export function applyZodErrorsToEvent(limit: number, event: Event, hint?: EventHint): Event {
+export function applyZodErrorsToEvent(
+  limit: number,
+  saveAttachments: boolean | undefined,
+  event: Event,
+  hint: EventHint,
+): Event {
   if (
     !event.exception?.values ||
-    !hint?.originalException ||
+    !hint.originalException ||
     !originalExceptionIsZodError(hint.originalException) ||
     hint.originalException.issues.length === 0
   ) {
     return event;
   }
 
-  return {
-    ...event,
-    exception: {
-      ...event.exception,
-      values: [
-        {
-          ...event.exception.values[0],
-          value: formatIssueMessage(hint.originalException),
+  try {
+    const flattenedIssues = hint.originalException.issues.map(flattenIssue);
+
+    if (saveAttachments === true) {
+      // Sometimes having the full error details can be helpful.
+      // Attachments have much higher limits, so we can include the full list of issues.
+      if (!Array.isArray(hint.attachments)) {
+        hint.attachments = [];
+      }
+      hint.attachments.push({
+        filename: 'zod_issues.json',
+        data: JSON.stringify({
+          issues: flattenedIssues,
+        }),
+      });
+    }
+
+    return {
+      ...event,
+      exception: {
+        ...event.exception,
+        values: [
+          {
+            ...event.exception.values[0],
+            value: formatIssueMessage(hint.originalException),
+          },
+          ...event.exception.values.slice(1),
+        ],
+      },
+      extra: {
+        ...event.extra,
+        'zoderror.issues': flattenedIssues.slice(0, limit),
+      },
+    };
+  } catch (e) {
+    // Hopefully we never throw errors here, but record it
+    // with the event just in case.
+    return {
+      ...event,
+      extra: {
+        ...event.extra,
+        'zoderrors sentry integration parse error': {
+          message: 'an exception was thrown while processing ZodError within applyZodErrorsToEvent()',
+          error: e instanceof Error ? `${e.name}: ${e.message}\n${e.stack}` : 'unknown',
         },
-        ...event.exception.values.slice(1),
-      ],
-    },
-    extra: {
-      ...event.extra,
-      'zoderror.issues': hint.originalException.errors.slice(0, limit).map(formatIssueTitle),
-    },
-  };
+      },
+    };
+  }
 }
 
 const _zodErrorsIntegration = ((options: ZodErrorsOptions = {}) => {
-  const limit = options.limit || DEFAULT_LIMIT;
+  const limit = options.limit ?? DEFAULT_LIMIT;
 
   return {
     name: INTEGRATION_NAME,
-    processEvent(originalEvent, hint) {
-      const processedEvent = applyZodErrorsToEvent(limit, originalEvent, hint);
+    processEvent(originalEvent, hint): Event {
+      const processedEvent = applyZodErrorsToEvent(limit, options.saveAttachments, originalEvent, hint);
       return processedEvent;
     },
   };
 }) satisfies IntegrationFn;
 
+/**
+ * Sentry integration to process Zod errors, making them easier to work with in Sentry.
+ */
 export const zodErrorsIntegration = defineIntegration(_zodErrorsIntegration);