Design V3 for simple cross-platform clients

Author: ejsmith

docs/event-ingestion-v3-architecture.md

@@ -5,6 +5,10 @@ methodology for [issue #2368](https://github.com/exceptionless/Exceptionless/iss
 It is deliberately separate from the public API documentation until the V3
 contract is ready for rollout.
 
+The companion [client protocol and ecosystem plan](event-ingestion-v3-client-protocol.md)
+defines the minimum sender, capability profiles, Sentry and Raygun comparison,
+and compatibility rules for future event and non-event telemetry.
+
 ## Objectives
 
 Event ingestion V3 is a breaking, performance-first API with these invariants:
@@ -22,6 +26,9 @@ Event ingestion V3 is a breaking, performance-first API with these invariants:
   not enqueue it for another process to deserialize.
 - Clients send raw stack traces. The server computes the grouping fingerprint
   and builds the persisted structured error.
+- A new language can implement the core sender using only its standard HTTPS
+  and JSON facilities. Advanced reliability and framework features are
+  independently testable capability profiles, not ingestion prerequisites.
 - Events assigned to discarded stacks terminate before billable admission,
   full error materialization, event persistence, stack statistics, or side
   effects.
@@ -245,6 +252,9 @@ Completion requires all of the following evidence:
 - Multi-instance tests for route status changes and quota reservation.
 - V2 serialization audit results before and after shared-service adoption.
 - OpenAPI V3 baseline and HTTP samples.
+- Language-neutral client specification, golden fixtures, black-box conformance
+  tests, and timed new-language implementation evidence meeting the client
+  effort gates.
 - Microbenchmark reports and end-to-end load results for the scenario matrix.
 - A staged rollout through the internal project and selected projects with a
   documented rollback switch.
@@ -280,6 +290,18 @@ hashed raw-trace fallback and increment a parser-fallback metric without logging
 the trace. Optional `stacking.signature_data` and `stacking.title` provide
 explicit manual stacking.
 
+Only `id` and `type` are required. Maintained SDKs should also identify
+themselves with `client.name` and `client.version`; applications can send
+first-class `version` and `level` values without knowing internal event data
+keys. Unknown event properties are ignored so additions remain compatible.
+
+`/api/v3/events` remains an event-only NDJSON stream. It will not acquire a
+per-line kind/payload wrapper or a stream header. A future optional,
+length-delimited advanced transport can carry the exact same event JSON beside
+attachments, minidumps, profiles, or other typed items. This keeps the minimum
+client smaller than Sentry's envelope implementation without forcing binary or
+heterogeneous data into the event object.
+
 The executable reference client and repeatable load harness live in
 `benchmarks/Exceptionless.Ingestion.Load`; usage is documented in
 `benchmarks/README.md`. It can submit the same conceptual corpus through the

docs/event-ingestion-v3-client-protocol.md

@@ -32,6 +32,14 @@ public sealed record EventIngestionV3Event
 
     public string[]? Tags { get; init; }
 
+    [StringLength(EventIngestionV3Limits.MaximumVersionLength, MinimumLength = 1)]
+    public string? Version { get; init; }
+
+    [StringLength(EventIngestionV3Limits.MaximumLevelLength, MinimumLength = 1)]
+    public string? Level { get; init; }
+
+    public EventIngestionV3Client? Client { get; init; }
+
     [StringLength(EventIngestionV3Limits.MaximumExceptionTypeLength, MinimumLength = 1)]
     public string? ExceptionType { get; init; }
 
@@ -49,6 +57,17 @@ public sealed record EventIngestionV3Event
     public JsonElement? Data { get; init; }
 }
 
+public sealed record EventIngestionV3Client
+{
+    [Required]
+    [StringLength(EventIngestionV3Limits.MaximumClientNameLength, MinimumLength = 1)]
+    public required string Name { get; init; }
+
+    [Required]
+    [StringLength(EventIngestionV3Limits.MaximumClientVersionLength, MinimumLength = 1)]
+    public required string Version { get; init; }
+}
+
 public sealed record EventIngestionV3Stacking
 {
     [StringLength(EventIngestionV3Limits.MaximumMessageLength, MinimumLength = 1)]

src/Exceptionless.Core/Models/Ingestion/EventIngestionV3Event.cs

@@ -10,8 +10,11 @@ public static long GetEstimatedSize(EventIngestionV3Event source)
         long size = 128;
         size += GetSize(source.Id) + GetSize(source.Type) + GetSize(source.Source) + GetSize(source.Message);
         size += GetSize(source.ReferenceId) + GetSize(source.ExceptionType) + GetSize(source.StackTrace);
+        size += GetSize(source.Version) + GetSize(source.Level);
         size += GetSize(source.Tags);
         size += GetSize(source.Data);
+        if (source.Client is not null)
+            size += 32 + GetSize(source.Client.Name) + GetSize(source.Client.Version);
         if (source.Stacking is not null)
             size += 32 + GetSize(source.Stacking.Title) + GetSize(source.Stacking.SignatureData);
 

src/Exceptionless.Core/Models/Ingestion/EventIngestionV3EventSizer.cs

@@ -11,6 +11,10 @@ public static class EventIngestionV3Limits
     public const int MaximumStackTraceLength = 256 * 1024;
     public const int MaximumUserIdentityLength = 255;
     public const int MaximumUserNameLength = 255;
+    public const int MaximumVersionLength = 255;
+    public const int MaximumLevelLength = 32;
+    public const int MaximumClientNameLength = 255;
+    public const int MaximumClientVersionLength = 255;
     public const int MaximumTags = 50;
     public const int MaximumTagLength = 255;
     public const int MaximumMetadataEntries = 100;

src/Exceptionless.Core/Models/Ingestion/EventIngestionV3Limits.cs

@@ -12,6 +12,7 @@ namespace Exceptionless.Core.Serialization;
     UseStringEnumConverter = false)]
 [JsonSerializable(typeof(EventIngestionV3Event))]
 [JsonSerializable(typeof(EventIngestionV3Event[]))]
+[JsonSerializable(typeof(EventIngestionV3Client))]
 [JsonSerializable(typeof(EventIngestionV3User))]
 [JsonSerializable(typeof(EventIngestionV3Request))]
 [JsonSerializable(typeof(EventIngestionV3Environment))]

src/Exceptionless.Core/Serialization/EventIngestionJsonContext.cs

@@ -163,6 +163,17 @@ public async Task<EventIngestionV3Response> ProcessAsync(
             return $"exception_type cannot exceed {EventIngestionV3Limits.MaximumExceptionTypeLength} characters.";
         if (source.StackTrace?.Length > EventIngestionV3Limits.MaximumStackTraceLength)
             return $"stack_trace cannot exceed {EventIngestionV3Limits.MaximumStackTraceLength} characters.";
+        if (source.Version is not null && (String.IsNullOrWhiteSpace(source.Version) || source.Version.Length > EventIngestionV3Limits.MaximumVersionLength))
+            return $"version must contain between 1 and {EventIngestionV3Limits.MaximumVersionLength} characters.";
+        if (source.Level is not null && (String.IsNullOrWhiteSpace(source.Level) || source.Level.Length > EventIngestionV3Limits.MaximumLevelLength))
+            return $"level must contain between 1 and {EventIngestionV3Limits.MaximumLevelLength} characters.";
+        if (source.Client is not null)
+        {
+            if (String.IsNullOrWhiteSpace(source.Client.Name) || source.Client.Name.Length > EventIngestionV3Limits.MaximumClientNameLength)
+                return $"client.name must contain between 1 and {EventIngestionV3Limits.MaximumClientNameLength} characters.";
+            if (String.IsNullOrWhiteSpace(source.Client.Version) || source.Client.Version.Length > EventIngestionV3Limits.MaximumClientVersionLength)
+                return $"client.version must contain between 1 and {EventIngestionV3Limits.MaximumClientVersionLength} characters.";
+        }
         if (source.Stacking?.Title?.Length > EventIngestionV3Limits.MaximumMessageLength)
             return $"stacking.title cannot exceed {EventIngestionV3Limits.MaximumMessageLength} characters.";
         string? stackingError = ValidateDictionary(source.Stacking?.SignatureData, "stacking.signature_data", value => value.Length <= EventIngestionV3Limits.MaximumMetadataValueLength);

src/Exceptionless.Core/Services/EventIngestionV3Processor.cs

@@ -46,6 +46,19 @@ public PersistentEvent Materialize(EventIngestionV3Event source, StackFingerprin
                 ev.SetManualStackingInfo(fingerprint.Title, fingerprint.SignatureData.ToDictionary(pair => pair.Key, pair => pair.Value));
         }
 
+        if (!String.IsNullOrWhiteSpace(source.Version))
+            ev.SetVersion(source.Version);
+        if (!String.IsNullOrWhiteSpace(source.Level))
+            ev.SetLevel(source.Level.Trim());
+        if (source.Client is not null)
+        {
+            ev.SetSubmissionClient(new SubmissionClient
+            {
+                UserAgent = source.Client.Name.Trim(),
+                Version = source.Client.Version.Trim()
+            });
+        }
+
         if (source.User is not null)
         {
             ev.SetUserIdentity(new UserInfo(source.User.Identity ?? String.Empty, source.User.Name)

src/Exceptionless.Core/Services/EventMaterializer.cs

@@ -303,6 +303,25 @@
   },
   "components": {
     "schemas": {
+      "EventIngestionV3Client": {
+        "required": [
+          "name",
+          "version"
+        ],
+        "type": "object",
+        "properties": {
+          "name": {
+            "maxLength": 255,
+            "minLength": 1,
+            "type": "string"
+          },
+          "version": {
+            "maxLength": 255,
+            "minLength": 1,
+            "type": "string"
+          }
+        }
+      },
       "EventIngestionV3Environment": {
         "type": "object",
         "properties": {
@@ -483,6 +502,32 @@
               "type": "string"
             }
           },
+          "version": {
+            "maxLength": 255,
+            "minLength": 1,
+            "type": [
+              "null",
+              "string"
+            ]
+          },
+          "level": {
+            "maxLength": 32,
+            "minLength": 1,
+            "type": [
+              "null",
+              "string"
+            ]
+          },
+          "client": {
+            "oneOf": [
+              {
+                "type": "null"
+              },
+              {
+                "$ref": "#/components/schemas/EventIngestionV3Client"
+              }
+            ]
+          },
           "exception_type": {
             "maxLength": 2000,
             "minLength": 1,

tests/Exceptionless.Tests/Controllers/Data/openapi-v3.json

@@ -94,6 +94,29 @@ public async Task Post_GzipError_ParsesStructuredStackOnServer()
         Assert.Equal(42, frame.LineNumber);
     }
 
+    [Fact]
+    public async Task Post_ClientMetadata_PersistsFirstClassEventData()
+    {
+        const string payload = """
+            {"id":"v3-client-metadata-0001","type":"log","message":"started","reference_id":"v3-client-metadata-ref-0001","version":"3.4.0","level":"info","client":{"name":"exceptionless.go","version":"1.2.0"}}
+            """;
+
+        using HttpResponseMessage httpResponse = await PostAsync(new StringContent(payload, Encoding.UTF8, "application/x-ndjson"));
+        EventIngestionV3Response response = await DeserializeAsync(httpResponse);
+
+        Assert.Equal(1, response.Persisted);
+        await RefreshDataAsync();
+        var ev = Assert.Single((await _eventRepository.GetByReferenceIdAsync(TestConstants.ProjectId, "v3-client-metadata-ref-0001")).Documents);
+        Assert.Equal("3.4.0", ev.GetVersion());
+        Assert.Equal("info", ev.GetLevel());
+        var client = ev.GetSubmissionClient(
+            GetService<Foundatio.Serializer.ITextSerializer>(),
+            GetService<ILogger<EventIngestionV3EndpointTests>>());
+        Assert.NotNull(client);
+        Assert.Equal("exceptionless.go", client.UserAgent);
+        Assert.Equal("1.2.0", client.Version);
+    }
+
     [Fact]
     public async Task Post_ReplayedEvent_ReturnsDuplicateWithoutSecondWrite()
     {