Add deployment environments to events

Author: ejsmith

.agents/skills/exceptionless-javascript/SKILL.md

@@ -9,6 +9,8 @@ Use this skill to produce source-accurate setup code, integration guidance, and
 
 Keep answers compact. Prefer pointing to official docs for broad product behavior, and use local package READMEs/source to correct stale snippets or repo-specific package details.
 
+Deployment environments use `config.environment` or `config.setEnvironment(name)` as the default, and `builder.setEnvironment(name)` for overrides. They serialize as top-level `environment`, separately from `data.@environment`. See [configuration.md](references/configuration.md).
+
 ## Official Docs
 
 Primary docs:

.agents/skills/exceptionless-javascript/references/configuration.md

@@ -23,12 +23,16 @@ import { Exceptionless } from "@exceptionless/browser";
 await Exceptionless.startup((config) => {
   config.apiKey = "API_KEY_HERE";
   config.version = "1.2.3";
+  config.environment = "production";
   config.setUserIdentity("12345678", "Blake");
   config.defaultTags.push("Example", "JavaScript");
-  config.defaultData["deployment"] = { environment: "production" };
 });
 ```
 
+## Deployment environment
+
+Set `config.environment = "production"` or call `config.setEnvironment("production")`. Per-event `setEnvironment("staging")` overrides the default. Names are trimmed and lowercased; empty names, names longer than 64 characters, and control characters are ignored. Missing values remain unspecified. This property is independent of `data.@environment` runtime metadata and of the application version. It does not change server stack grouping or create per-environment status.
+
 ## Privacy
 
 For deeper guidance on PII removal, read [data-exclusions.md](data-exclusions.md).

.agents/skills/exceptionless-javascript/references/sending-events.md

@@ -9,6 +9,14 @@ Use the platform package's `Exceptionless` singleton unless the user is building
 
 ## Common Events
 
+Deployment environments can be overridden per event:
+
+```js
+await Exceptionless.createLog("Deployment complete").setEnvironment("staging").submit();
+```
+
+Without an override, the event uses `config.environment`. Repeated errors from different environments are queued separately; the server still groups the same error into one stack.
+
 ```js
 import { Exceptionless } from "@exceptionless/browser";
 

README.md

@@ -8,6 +8,8 @@ The definition of the word exceptionless is: to be without exception. Exceptionl
 
 ## Browser
 
+Set a deployment environment in startup configuration with `config.environment = "production"` (or `config.setEnvironment("production")`). Override it on an event with `Exceptionless.createLog("Example").setEnvironment("staging").submit()`. Names are trimmed, lowercased, and limited to 64 characters. Missing or invalid names remain unspecified. The top-level `environment` is separate from machine/runtime diagnostics in `data.@environment`; stacks and fixed versions remain shared across environments.
+
 You can install the npm package via `npm install @exceptionless/browser --save`
 or via cdn [`https://unpkg.com/@exceptionless/browser`](https://unpkg.com/@exceptionless/browser).
 Next, you just need to call startup during your app's startup to automatically

packages/core/src/EventBuilder.ts

@@ -3,10 +3,20 @@ import { Event, EventType, KnownEventDataKeys } from "./models/Event.js";
 import { ManualStackingInfo } from "./models/data/ManualStackingInfo.js";
 import { UserInfo } from "./models/data/UserInfo.js";
 import { EventContext } from "./models/EventContext.js";
-import { isEmpty, stringify } from "./Utils.js";
+import { isEmpty, normalizeEnvironment, stringify } from "./Utils.js";
 import { EventPluginContext } from "./plugins/EventPluginContext.js";
 
 export class EventBuilder {
+  public setEnvironment(value: string | null | undefined): EventBuilder {
+    const environment = normalizeEnvironment(value);
+    if (environment) {
+      this.target.environment = environment;
+    } else {
+      delete this.target.environment;
+    }
+    return this;
+  }
+
   public target: Event;
   public client: ExceptionlessClient;
   public context: EventContext;

packages/core/src/Utils.ts

@@ -559,3 +559,11 @@ export function allowProcessToExitWithoutWaitingForTimerOrInterval(timeoutOrInte
     (timeoutOrIntervalId as { unref: () => ReturnType<typeof setTimeout> }).unref();
   }
 }
+export function normalizeEnvironment(value: string | null | undefined): string | undefined {
+  if (typeof value !== "string") {
+    return undefined;
+  }
+  const name = value.trim();
+  // eslint-disable-next-line no-control-regex -- Deployment names cannot contain control characters.
+  return name && name.length <= 64 && !/[\u0000-\u001f\u007f-\u009f]/u.test(name) ? name.toLowerCase() : undefined;
+}

packages/core/src/configuration/Configuration.ts

@@ -13,14 +13,29 @@ import { DefaultEventQueue } from "../queue/DefaultEventQueue.js";
 import { IEventQueue } from "../queue/IEventQueue.js";
 import { ISubmissionClient } from "../submission/ISubmissionClient.js";
 import { DefaultSubmissionClient } from "../submission/DefaultSubmissionClient.js";
-import { guid } from "../Utils.js";
+import { guid, normalizeEnvironment } from "../Utils.js";
 import { KnownEventDataKeys } from "../models/Event.js";
 import { InMemoryStorage } from "../storage/InMemoryStorage.js";
 import { IStorage } from "../storage/IStorage.js";
 import { LocalStorage } from "../storage/LocalStorage.js";
 import { ServerSettings } from "../configuration/SettingsManager.js";
 
 export class Configuration {
+  private _environment: string | undefined;
+
+  /** The default deployment environment for every event. */
+  public get environment(): string | undefined {
+    return this._environment;
+  }
+
+  public set environment(value: string | null | undefined) {
+    this._environment = normalizeEnvironment(value);
+  }
+
+  public setEnvironment(value: string | null | undefined): void {
+    this.environment = value;
+  }
+
   constructor() {
     this.services = {
       lastReferenceIdManager: new DefaultLastReferenceIdManager(),

packages/core/src/models/Event.ts

@@ -8,6 +8,8 @@ import { ManualStackingInfo } from "../models/data/ManualStackingInfo.js";
 export type EventType = "error" | "usage" | "log" | "404" | "session" | string;
 
 export interface Event {
+  /** The deployment environment, such as production or staging. */
+  environment?: string;
   /** The event type (ie. error, log message, feature usage). */
   type?: EventType;
   /** The event source (ie. machine name, log name, feature name). */

packages/core/src/plugins/default/ConfigurationDefaultsPlugin.ts

@@ -1,4 +1,4 @@
-import { isEmpty, stringify } from "../../Utils.js";
+import { isEmpty, normalizeEnvironment, stringify } from "../../Utils.js";
 import { EventPluginContext } from "../../plugins/EventPluginContext.js";
 import { IEventPlugin } from "../../plugins/IEventPlugin.js";
 
@@ -9,6 +9,12 @@ export class ConfigurationDefaultsPlugin implements IEventPlugin {
   public run(context: EventPluginContext): Promise<void> {
     const { dataExclusions, defaultData, defaultTags } = context.client.config;
     const ev = context.event;
+    const environment = normalizeEnvironment(ev.environment ?? context.client.config.environment);
+    if (environment) {
+      ev.environment = environment;
+    } else {
+      delete ev.environment;
+    }
 
     if (defaultTags) {
       ev.tags = [...(ev.tags || []), ...defaultTags];

packages/core/src/plugins/default/DuplicateCheckerPlugin.ts

@@ -50,27 +50,31 @@ export class DuplicateCheckerPlugin implements IEventPlugin {
 
     const error = context.event.data?.[KnownEventDataKeys.Error];
     const hashCode = calculateHashCode(error);
+    const environment = context.event.environment;
     if (hashCode) {
       const count = context.event.count || 1;
       const now = this._getCurrentTime();
 
-      const merged = this._mergedEvents.filter((s) => s.hashCode === hashCode)[0];
+      const merged = this._mergedEvents.find((s) => s.hashCode === hashCode && s.environment === environment);
       if (merged) {
         merged.incrementCount(count);
         merged.updateDate(context.event.date);
         context.log.info("Ignoring duplicate event with hash: " + hashCode);
         context.cancelled = true;
       }
 
-      if (!context.cancelled && this._processedHashCodes.some((h) => h.hash === hashCode && h.timestamp >= now - this._interval)) {
+      if (
+        !context.cancelled &&
+        this._processedHashCodes.some((h) => h.hash === hashCode && h.environment === environment && h.timestamp >= now - this._interval)
+      ) {
         context.log.trace("Adding event with hash: " + hashCode);
         this._mergedEvents.push(new MergedEvent(hashCode, context, count));
         context.cancelled = true;
       }
 
       if (!context.cancelled) {
         context.log.trace(`Enqueueing event with hash: ${hashCode} to cache`);
-        this._processedHashCodes.push({ hash: hashCode, timestamp: now });
+        this._processedHashCodes.push({ hash: hashCode, environment, timestamp: now });
 
         // Only keep the last 50 recent errors.
         while (this._processedHashCodes.length > 50) {
@@ -91,16 +95,19 @@ export class DuplicateCheckerPlugin implements IEventPlugin {
 
 interface TimestampedHash {
   hash: number;
+  environment: string | undefined;
   timestamp: number;
 }
 
 class MergedEvent {
   public hashCode: number;
+  public readonly environment: string | undefined;
   private _count: number;
   private _context: EventPluginContext;
 
   constructor(hashCode: number, context: EventPluginContext, count: number) {
     this.hashCode = hashCode;
+    this.environment = context.event.environment;
     this._context = context;
     this._count = count;
   }