feat: Add GroupingKey callback (#115)

README.md

@@ -27,6 +27,7 @@
         - [sendRUMTimingEvent](#sendrumtimingeventeventtype-realusermonitoringtimings-name-string-timeusedinms-number)
     - [Raygun specific types](#raygun-specific-types)
         - [BeforeSendHandler](#beforesendhandler)
+        - [GroupingKeyHandler](#groupingkeyhandler)
         - [Breadcrumb](#breadcrumb)
         - [CrashReportPayload](#crashreportpayload)
         - [CustomData](#customdata)
@@ -293,6 +294,7 @@ const options: RaygunClientOptions = {
   ignoredViews: ["name of view to ignore"],
   logLevel: LogLevel.verbose,
   onBeforeSendingCrashReport: (crashReport) => console.log(crashReport),
+  groupingKey: (crashReport) => crashReport.Details.Error.Message,
   maxErrorReportsStoredOnDevice: 10,
   maxBreadCrumbsPerErrorReport: 10,
 };
@@ -605,6 +607,21 @@ See also:<br/>
 export type BeforeSendHandler = (payload: CrashReportPayload) => CrashReportPayload | null;
 ```
 
+### GroupingKeyHandler
+
+The `GroupingKeyHandler` allows to define a custom grouping key to group error together.
+
+When initializing Raygun, pass a `groupingKey` function.
+This function takes a `CrashReportPayload` and must return either a `string` with the custom grouping key,
+or `null` to use the default grouping.
+
+See also:<br/>
+[CrashReportPayload](#crashreportpayload)
+
+```typescript
+export type GroupingKeyHandler = (payload: CrashReportPayload) => string | null;
+```
+
 <br/>
 <br/>
 
@@ -779,6 +796,7 @@ and will instead be thrown away, and lost forever.
 
 See also:<br/>
 [BeforeSendHandler](#beforesendhandler)
+[GroupingKeyHandler](#groupingkeyhandler)
 
 ```typescript
 export type RaygunClientOptions = {
@@ -793,6 +811,7 @@ export type RaygunClientOptions = {
   customRealUserMonitoringEndpoint?: string;
   logLevel?: LogLevel;
   onBeforeSendingCrashReport?: BeforeSendHandler;
+  groupingKey?: GroupingKeyHandler;
   ignoredURLs?: string[];
   ignoredViews?: string[];
   maxErrorReportsStoredOnDevice?: number;

demo/screens/Home.tsx

@@ -1,7 +1,7 @@
 import {Button, Image, SafeAreaView, ScrollView, StatusBar, Text, View} from "react-native";
 import React, {useState} from "react";
 import {raygunClient, styles} from "../utils/Utils";
-import {BeforeSendHandler, CrashReportPayload, LogLevel, RaygunClientOptions, User} from "raygun4reactnative";
+import {BeforeSendHandler, CrashReportPayload, LogLevel, RaygunClientOptions, User, GroupingKeyHandler } from "raygun4reactnative";
 
 //#region -- Initialization Object -----------------------------------------------------------------
 
@@ -25,6 +25,18 @@ const beforeSendFunc: BeforeSendHandler = (crp: CrashReportPayload) => {
   return crp;
 }
 
+/**
+ * This is an example of a GroupingKeyHandler. This function is parsed through the RaygunClientOptions
+ * and is called before sending any crash report. The return value is used to group crash reports
+ * together. If the return value is null, the grouping key is then ignored.
+ * 
+ * @param crp - The CrashReportPayload that is about to be sent.
+ */
+const groupingKeyFunc: GroupingKeyHandler = (crp: CrashReportPayload) => {
+  // Group all errors with the same message together
+  return crp.Details.Error.Message;
+}
+
 /**
  * This is an array of urls that should be ignored when network monitoring. Like the BeforeSendHandler,
  * this is parsed through the RaygunClientOptions and is used to block network monitoring events
@@ -51,6 +63,7 @@ const options: RaygunClientOptions = {
   enableCrashReporting: true,
   enableRealUserMonitoring: true,
   onBeforeSendingCrashReport: beforeSendFunc,
+  groupingKey: groupingKeyFunc,
   ignoredURLs: ignoredUrls,
   ignoredViews: ignoredViews,
   logLevel: LogLevel.verbose,

sdk/src/CrashReporter.ts

@@ -1,5 +1,12 @@
 import { cleanFilePath, filterOutReactFrames, getCurrentTags, getCurrentUser, noAddressAt, upperFirst } from './Utils';
-import { BeforeSendHandler, Breadcrumb, CrashReportPayload, CustomData, ManualCrashReportDetails } from './Types';
+import {
+  BeforeSendHandler,
+  Breadcrumb,
+  CrashReportPayload,
+  CustomData,
+  GroupingKeyHandler,
+  ManualCrashReportDetails
+} from './Types';
 import { StackFrame } from 'react-native/Libraries/Core/Devtools/parseErrorStack';
 import { NativeModules, Platform } from 'react-native';
 import AsyncStorage from '@react-native-async-storage/async-storage';
@@ -27,6 +34,7 @@ export default class CrashReporter {
   private version: string;
   private disableNativeCrashReporting: boolean;
   private onBeforeSendingCrashReport: BeforeSendHandler | null;
+  private groupingKey: GroupingKeyHandler | null;
   private raygunCrashReportEndpoint = CrashReporter.DEFAULT_RAYGUN_CRASH_REPORTING_ENDPOINT;
   private maxErrorReportsStoredOnDevice: number;
   private maxBreadcrumbsPerErrorReport: number;
@@ -40,6 +48,7 @@ export default class CrashReporter {
    * @param {boolean} disableUnhandledPromiseRejectionReporting - Whether or not to enable unhandled promise rejection reporting.
    * @param {string} customCrashReportingEndpoint - Custom endpoint for Crash Report (may be empty or null).
    * @param {BeforeSendHandler} onBeforeSendingCrashReport - A lambda to execute before each Crash Report transmission.
+   * @param {GroupingKeyHandler} groupingKey - A lambda to determine the grouping key for a Crash Report.
    * @param {string} version - The current version of the RaygunClient.
    * @param {number} maxErrorReportsStoredOnDevice - The total number of error reports that can be in local storage at one time.
    * @param {number} maxBreadCrumbsPerErrorReport - The total number of breadcrumbs an error report can contain.
@@ -50,6 +59,7 @@ export default class CrashReporter {
     disableUnhandledPromiseRejectionReporting: boolean,
     customCrashReportingEndpoint: string,
     onBeforeSendingCrashReport: BeforeSendHandler | null,
+    groupingKey: GroupingKeyHandler | null,
     version: string,
     maxErrorReportsStoredOnDevice: number,
     maxBreadCrumbsPerErrorReport: number
@@ -58,6 +68,7 @@ export default class CrashReporter {
     this.apiKey = apiKey;
     this.disableNativeCrashReporting = disableNativeCrashReporting;
     this.onBeforeSendingCrashReport = onBeforeSendingCrashReport;
+    this.groupingKey = groupingKey;
     this.version = version;
 
     this.maxErrorReportsStoredOnDevice = Math.min(
@@ -331,6 +342,10 @@ export default class CrashReporter {
       return;
     }
 
+    // Set optinal grouping key
+    modifiedPayload.Details.GroupingKey =
+      this.groupingKey && typeof this.groupingKey === 'function' ? this.groupingKey(Object.freeze(payload)) : null;
+
     RaygunLogger.v('Crash Report Payload:', modifiedPayload);
 
     // Send the Crash Report, caching it if the transmission is not successful
@@ -397,7 +412,8 @@ export default class CrashReporter {
         Tags: getCurrentTags(),
         User: getCurrentUser(),
         Breadcrumbs: upperFirst(this.breadcrumbs),
-        Version: this.version || 'Not supplied'
+        Version: this.version || 'Not supplied',
+        GroupingKey: null
       }
     };
   }

sdk/src/RaygunClient.ts

@@ -7,6 +7,7 @@ import {
   BeforeSendHandler,
   Breadcrumb,
   CustomData,
+  GroupingKeyHandler,
   LogLevel,
   ManualCrashReportDetails,
   RaygunClientOptions,
@@ -63,6 +64,7 @@ const init = (raygunClientOptions: RaygunClientOptions) => {
     customRealUserMonitoringEndpoint = '',
     logLevel = LogLevel.warn,
     onBeforeSendingCrashReport = null,
+    groupingKey = null,
     ignoredURLs = [],
     ignoredViews = [],
     maxErrorReportsStoredOnDevice = CrashReporter.MAX_ERROR_REPORTS_STORED_ON_DEVICE,
@@ -81,6 +83,7 @@ const init = (raygunClientOptions: RaygunClientOptions) => {
       disableUnhandledPromiseRejectionReporting,
       customCrashReportingEndpoint || '',
       onBeforeSendingCrashReport as BeforeSendHandler,
+      groupingKey as GroupingKeyHandler,
       version,
       maxErrorReportsStoredOnDevice,
       maxBreadcrumbsPerErrorReport

sdk/src/Types.ts

@@ -12,6 +12,7 @@ export type RaygunClientOptions = {
   customRealUserMonitoringEndpoint?: string;
   logLevel?: LogLevel;
   onBeforeSendingCrashReport?: BeforeSendHandler;
+  groupingKey?: GroupingKeyHandler;
   ignoredURLs?: string[];
   ignoredViews?: string[];
   maxErrorReportsStoredOnDevice?: number;
@@ -84,6 +85,7 @@ export type Breadcrumb = {
   type?: 'manual';
 };
 export type BeforeSendHandler = (payload: CrashReportPayload) => CrashReportPayload | null;
+export type GroupingKeyHandler = (payload: CrashReportPayload) => string | null;
 
 export type CrashReportPayload = {
   OccurredOn: Date;
@@ -104,6 +106,7 @@ export type CrashReportPayload = {
     User?: User;
     Breadcrumbs?: Breadcrumb[];
     Version: string;
+    GroupingKey: string | null;
   };
 };
 

sdk/src/index.ts

@@ -20,6 +20,7 @@ import {
   CrashReportPayload,
   CustomData,
   Environment,
+  GroupingKeyHandler,
   LogLevel,
   ManualCrashReportDetails,
   RaygunClientOptions,
@@ -50,6 +51,7 @@ export type {
   CrashReportPayload,
   CustomData,
   Environment,
+  GroupingKeyHandler,
   ManualCrashReportDetails,
   RaygunClientOptions,
   RaygunStackFrame,