feat: Enable adding custom data to diagnostic events (serverpod#3363)

This adds the ability to include custom data when submitting diagnostic events.

It is intended to be used by application (user) code, not framework code. The content to include and how to handle it in the event handlers is up to the user.

Closes serverpod#3332 

The solution differs slightly from the suggestion in the issue: Rather than extending the context, this is included as a key/value map in the event itself. This makes sense since the context types are framework-managed and this is an entirely user-owned data payload for individual events.

## Pre-launch Checklist

- [x] I read the [Contribute](https://docs.serverpod.dev/contribute) page and followed the process outlined there for submitting PRs.
- [x] This update contains only one single feature or bug fix and nothing else. (If you are submitting multiple fixes, please make multiple PRs.)
- [x] I read and followed the [Dart Style Guide](https://dart.dev/guides/language/effective-dart/style) and formatted the code with [dart format](https://dart.dev/tools/dart-format).
- [x] I listed at least one issue that this PR fixes in the description above.
- [x] I updated/added relevant documentation (doc comments with `///`), and made sure that the documentation follows the same style as other Serverpod documentation. I checked spelling and grammar.
- [x] I added new tests to check the change I am making.
- [x] All existing and new tests are passing.
- [x] Any breaking changes are documented below.

If you need help, consider asking for advice on the [discussion board](https://github.com/serverpod/serverpod/discussions).

## Breaking changes

No, does not change any existing API. Adds an optional initialization field to the diagnostic event constructor.

Author: christerswahn

packages/serverpod/lib/src/server/diagnostic_events/event_handler.dart

@@ -10,7 +10,13 @@ enum OriginSpace {
 }
 
 /// Base interface for all diagnostic events.
-abstract interface class DiagnosticEvent {}
+abstract interface class DiagnosticEvent {
+  /// Custom key/value data added to the event.
+  ///
+  /// It is up to application code submitting events
+  /// and event handler implementations how to use this data.
+  Map<String, Object> get custom;
+}
 
 /// An event that represents an exception that occurred in the server.
 class ExceptionEvent implements DiagnosticEvent {
@@ -23,11 +29,15 @@ class ExceptionEvent implements DiagnosticEvent {
   /// An optional message associated with the exception.
   final String? message;
 
+  @override
+  final Map<String, Object> custom;
+
   /// Creates a new [ExceptionEvent].
   const ExceptionEvent(
     this.exception,
     this.stackTrace, {
     this.message,
+    this.custom = const {},
   });
 
   /// Returns a string representation of this context.

tests/serverpod_test_server/lib/src/endpoints/diagnostic_event_test_endpoint.dart

@@ -6,7 +6,11 @@ class DiagnosticEventTestEndpoint extends Endpoint {
       throw Exception('An exception is thrown');
     } catch (e, stackTrace) {
       session.serverpod.experimental.submitDiagnosticEvent(
-        ExceptionEvent(e, stackTrace),
+        ExceptionEvent(
+          e,
+          stackTrace,
+          custom: {'customKey': 'customValue'},
+        ),
         session: session,
       );
     }

tests/serverpod_test_server/test_integration/diagnostics/diagnostic_events_api_test.dart

@@ -22,6 +22,7 @@ void main() {
 
       final record = await exceptionHandler.events.first.timeout(timeout);
       expect(record.event.exception, isA<Exception>());
+      expect(record.event.custom, equals({'customKey': 'customValue'}));
       expect(record.space, equals(OriginSpace.application));
       expect(record.context, isA<DiagnosticEventContext>());
       expect(