wardx 0.7.0 → 0.9.0

package/README.md

@@ -8,6 +8,26 @@ The SDK records logs, events, and metrics. The SDK also gets Remote Config and a
 
 A measure call changes local memory only. The SDK sends frames on a timer. The SDK uses HTTP `POST /v1/sync` with JSON and gzip.
 
+## Disable the SDK
+
+`enabled` defaults to `true`. Set it when creating the client:
+
+```js
+const wardx = createWardx({ enabled: false });
+const requests = wardx.counter('requests');
+requests.inc();
+await wardx.shutdown();
+```
+
+When disabled, credentials and other connection options are unnecessary. Metric
+handles, timers, events, logs, identity, retention, and experiment goals do nothing.
+The client does not initialize the telemetry engine, transport, or background
+timers, and does not hash identifiers or call the tracer. `flush()` and `shutdown()`
+resolve immediately. `config.get(key, fallback)` returns the supplied fallback.
+
+The mode is fixed at creation; changing the options or `settings` afterward does
+not toggle it. Cached metric handles remain safe to call, including after shutdown.
+
 ## Install
 
 ```bash
@@ -43,7 +63,7 @@ To receive frames, run an ingest server. Install `@wardx/server` and start it wi
 
 ## Start the SDK
 
-`createWardx` requires these keys:
+When enabled, `createWardx` requires these keys:
 
 | Key | Description |
 | --- | --- |
@@ -59,6 +79,48 @@ Optional keys include `tracer` and overrides for centralized values in `@wardx/c
 
 The SDK starts a bootstrap sync immediately. The SDK then syncs on `syncIntervalMs` with jitter.
 
+## Recommended: bind once, measure through handles
+
+Create metric handles once per client and stable name/dimension combination,
+then reuse them in handlers, callbacks, and loops. This avoids repeated dimension
+validation, series-key construction, and registry lookup. Normal aggregation
+windows and flushes reset values, not handles. Rebind when replacing the client;
+do not mutate a dimension dictionary to retarget an existing handle.
+
+For varying dimensions, bind one recorder per application-owned, bounded value
+set (mode, region, source). Never build an unbounded handle cache keyed by user
+IDs or arbitrary input. Keep histogram buckets fixed. Timer tokens measure one
+operation: create a fresh token for each operation, not one token for the client.
+For a hot duration path, reuse a histogram and observe an application-measured
+elapsed duration instead. Events, logs, retention, and experiment goals remain
+per-occurrence calls.
+
+```js
+function createMatchTelemetry(wardx, mode) {
+  const completed = wardx.counter('match.completed', { mode });
+  const duration = wardx.histogram('match.duration_ms', {
+    mode, buckets: [30_000, 60_000, 180_000, 600_000, 1_800_000]
+  });
+  const players = wardx.distinct('match.players', { mode });
+  return {
+    onCompleted(durationMs, userId) {
+      completed.inc();
+      duration.observe(durationMs);
+      players.add(userId);
+    }
+  };
+}
+
+const rankedTelemetry = createMatchTelemetry(wardx, 'ranked');
+// In each ranked-match callback:
+rankedTelemetry.onCompleted(durationMs, userId);
+```
+
+The same setup works with `enabled: false`: cached handles are inert. An inline
+lookup is valid for occasional instrumentation; prefer stored handles for
+recurring work. API reference tables show lookup and measurement together only
+to identify the methods.
+
 ## Use case 1: Instrument a Node.js service
 
 **When:** You run a Node.js process and you need telemetry.
@@ -80,10 +142,14 @@ const wardx = createWardx({
 
 wardx.log.info('match_started', { mode: 'ranked', players: 4 });
 wardx.event('match.started', { mode: 'ranked', country: 'AR' });
-wardx.counter('match.completed', { mode: 'ranked' }).inc();
-wardx.gauge('players.online').set(12);
-wardx.histogram('request.duration', { buckets: [10, 25, 50, 100, 250] }).observe(42);
-wardx.distinct('shot.traffic.hids', { result: 'violating' }).add(hid);
+const matchCompleted = wardx.counter('match.completed', { mode: 'ranked' });
+matchCompleted.inc();
+const playersOnline = wardx.gauge('players.online');
+playersOnline.set(12);
+const requestDuration = wardx.histogram('request.duration', { buckets: [10, 25, 50, 100, 250] });
+requestDuration.observe(42);
+const shotTrafficHids = wardx.distinct('shot.traffic.hids', { result: 'violating' });
+shotTrafficHids.add(hid);
 
 const end = wardx.timer('matchmaking.duration');
 end({ result: 'success' });
@@ -108,21 +174,26 @@ Pass the ingest URL, project key, and project name in `createWardx`.
 **Objective:** Use `inc()` for one occurrence. Use `add(n)` for a finite sum.
 
 ```js
-function handleRequest(req, res, wardx) {
-  const requests = wardx.counter('http.requests', { route: 'matchmaking' });
+const requests = wardx.counter('http.requests', { route: 'matchmaking' });
+const errors = wardx.counter('http.errors', { route: 'matchmaking', code: 500 });
+const coinsAwarded = wardx.counter('coins.awarded', { source: 'match' });
+const completedByMode = new Map(['ranked', 'casual'].map((mode) =>
+  [mode, wardx.counter('match.completed', { mode })]
+));
+
+function handleRequest(req, res) {
   requests.inc();
-
-  if (res.statusCode >= 500) {
-    wardx.counter('http.errors', { route: 'matchmaking', code: 500 }).inc();
-  }
+  if (res.statusCode >= 500) errors.inc();
 }
 
-function grantCoins(wardx, amount) {
-  wardx.counter('coins.awarded', { source: 'match' }).add(amount);
+function grantCoins(amount) {
+  coinsAwarded.add(amount);
 }
 
-function completeMatch(wardx, mode) {
-  wardx.counter('match.completed', { mode }).inc();
+function completeMatch(mode) {
+  const completed = completedByMode.get(mode);
+  if (!completed) throw new Error(`Unsupported match mode: ${mode}`);
+  completed.inc();
 }
 ```
 
@@ -131,7 +202,7 @@ To detect abnormal grants, pair this counter with a histogram and a rare anomaly
 ### Procedure
 
 1. Call `counter(name, dims)` to get a series.
-2. Keep that object if you increment in a loop.
+2. Keep that handle in its owning module or component and reuse it across calls and windows.
 3. Call `inc()` to add `1`.
 4. Call `add(n)` to add a finite number.
 
@@ -146,11 +217,17 @@ A counter in a frame is a window delta. The counter is not a lifetime total.
 **Objective:** Call `set(value)` with a finite number. The frame stores the last value and a timestamp.
 
 ```js
-function reportLobby(wardx, lobby) {
-  wardx.gauge('players.online', { region: lobby.region }).set(lobby.playerCount);
-  wardx.gauge('matchmaking.queue_depth').set(lobby.queue.length);
+function createLobbyReporter(wardx, region) {
+  const playersOnline = wardx.gauge('players.online', { region });
+  const queueDepth = wardx.gauge('matchmaking.queue_depth');
+  return (lobby) => {
+    playersOnline.set(lobby.playerCount);
+    queueDepth.set(lobby.queue.length);
+  };
 }
 
+const reportLobby = createLobbyReporter(wardx, 'south-america');
+
 function startQueueProbe(wardx, getQueueDepth) {
   const queue = wardx.gauge('jobs.queue_depth');
   const timer = setInterval(() => {
@@ -176,15 +253,19 @@ If you do not call `set` in a window, that series is not in the frame.
 **Objective:** Call `observe(value)` so the SDK stores count, sum, min, max, and buckets.
 
 ```js
-function recordRequest(wardx, durationMs, bytes) {
-  wardx.histogram('http.duration_ms', { route: 'checkout' }).observe(durationMs);
-  wardx.histogram('http.payload_bytes', {
-    buckets: [256, 1024, 4096, 16384, 65536]
-  }).observe(bytes);
+const requestDuration = wardx.histogram('http.duration_ms', { route: 'checkout' });
+const payloadBytes = wardx.histogram('http.payload_bytes', {
+  buckets: [256, 1024, 4096, 16384, 65536]
+});
+const awardSize = wardx.histogram('coins.award_size');
+
+function recordRequest(durationMs, bytes) {
+  requestDuration.observe(durationMs);
+  payloadBytes.observe(bytes);
 }
 
-function recordAward(wardx, amount, grantId) {
-  wardx.histogram('coins.award_size').observe(amount, { grantId });
+function recordAward(amount, grantId) {
+  awardSize.observe(amount, { grantId });
 }
 ```
 
@@ -205,15 +286,18 @@ If you start and stop a duration in the same process, use `timer` instead of a h
 **Objective:** Start a timer. Stop the timer when the work ends. The SDK records milliseconds in a histogram.
 
 ```js
-export async function handleMatchmaking(req, res, wardx) {
+const matchmakingOk = wardx.counter('matchmaking.ok');
+const matchmakingError = wardx.counter('matchmaking.error');
+
+export async function handleMatchmaking(req, res) {
   const end = wardx.timer('matchmaking.duration', { route: 'matchmaking' });
   try {
     const result = await findMatch(req.body);
-    wardx.counter('matchmaking.ok').inc();
+    matchmakingOk.inc();
     end({ result: 'success' });
     res.end(JSON.stringify(result));
   } catch (err) {
-    wardx.counter('matchmaking.error').inc();
+    matchmakingError.inc();
     wardx.log.error('matchmaking_failed', { code: err.code || 'unknown' });
     end({ result: 'error' });
     res.statusCode = 500;
@@ -238,26 +322,28 @@ The stop function records milliseconds. Dimensions that you pass to the stop fun
 **Objective:** Call `event(name, attrs)`. Do not use an event when a counter is enough.
 
 ```js
-function onMatchStarted(wardx, match) {
-  wardx.event('match.started', {
-    mode: match.mode,
-    country: match.country,
-    players: match.players.length
-  });
-  wardx.counter('match.started', { mode: match.mode }).inc();
+function createMatchStartedRecorder(wardx, mode) {
+  const started = wardx.counter('match.started', { mode });
+  return (match) => {
+    wardx.event('match.started', { mode, country: match.country, players: match.players.length });
+    started.inc();
+  };
 }
 
-function onPurchase(wardx, order) {
-  wardx.event('purchase', {
-    product: order.product,
-    currency: order.currency,
-    amount: order.amount
-  });
-  wardx.counter('purchase.count', { product: order.product }).inc();
-  wardx.counter('purchase.amount', { currency: order.currency }).add(order.amount);
+function createPurchaseRecorder(wardx, product, currency) {
+  const purchases = wardx.counter('purchase.count', { product });
+  const amount = wardx.counter('purchase.amount', { currency });
+  return (order) => {
+    wardx.event('purchase', { product, currency, amount: order.amount });
+    purchases.inc();
+    amount.add(order.amount);
+  };
 }
 
-function onSignup(wardx, user) {
+const onMatchStarted = createMatchStartedRecorder(wardx, 'ranked');
+const onPurchase = createPurchaseRecorder(wardx, 'coins-small', 'USD');
+
+function onSignup(user) {
   wardx.event('signup.completed', { method: user.method });
 }
 ```
@@ -283,21 +369,28 @@ Wardx does not store a user journey. Delivery is at-most-once. Production discar
 Give each step its own name. Do not reuse `screen.view` with a `surface` attr as the funnel. Use `surface` only as a counter dimension when you also need a breakdown of one step.
 
 ```js
-function onOnboardingStart(wardx, channel) {
-  wardx.event('onboarding.start', { channel });
-  wardx.counter('onboarding.start', { channel }).inc();
+function createOnboardingTelemetry(wardx, channel) {
+  const started = wardx.counter('onboarding.start', { channel });
+  const profile = wardx.counter('onboarding.profile');
+  const done = wardx.counter('onboarding.done');
+  return {
+    onStart() {
+      wardx.event('onboarding.start', { channel });
+      started.inc();
+    },
+    onProfile() {
+      wardx.event('onboarding.profile');
+      profile.inc();
+    },
+    onDone(userId) {
+      wardx.event('onboarding.done');
+      done.inc();
+      wardx.experiment.goal('onboarding.done', { subjectId: userId });
+    }
+  };
 }
 
-function onOnboardingProfile(wardx) {
-  wardx.event('onboarding.profile');
-  wardx.counter('onboarding.profile').inc();
-}
-
-function onOnboardingDone(wardx, userId) {
-  wardx.event('onboarding.done');
-  wardx.counter('onboarding.done').inc();
-  wardx.experiment.goal('onboarding.done', { subjectId: userId });
-}
+const onboarding = createOnboardingTelemetry(wardx, 'organic');
 ```
 
 ### Procedure
@@ -361,22 +454,28 @@ Retention requires a server with this feature; older servers cannot compute it.
 Wardx is not a ledger. Delivery is at-most-once. Production discards envelopes after ingest (`sink: "null"`). A player's wallet, and the row that explains one grant, live in the game database. Wardx answers whether the fleet is granting too much, or too large, in a 1-minute window.
 
 ```js
-function grantCoins(wardx, grant) {
-  const { source, amount, reason, id } = grant;
-
-  wardx.counter('coins.awarded', { source }).add(amount);
-  wardx.counter('coins.grants', { source }).inc();
-  wardx.histogram('coins.award_size', {
-    source,
-    buckets: [10, 50, 100, 250, 500, 1000, 5000]
-  }).observe(amount, { grantId: id, reason });
-
-  const maxAward = wardx.config.get('economy.maxAward', 500);
-  if (amount > maxAward) {
-    wardx.event('coins.anomaly', { source, amount, reason, grantId: id });
-    wardx.log.warn('coins_anomaly', { source, amount, reason, grantId: id });
-  }
+function createGrantRecorder(wardx, source) {
+  const awarded = wardx.counter('coins.awarded', { source });
+  const grants = wardx.counter('coins.grants', { source });
+  const size = wardx.histogram('coins.award_size', {
+    source, buckets: [10, 50, 100, 250, 500, 1000, 5000]
+  });
+  return ({ amount, reason, id }) => {
+    awarded.add(amount);
+    grants.inc();
+    size.observe(amount, { grantId: id, reason });
+
+    const maxAward = wardx.config.get('economy.maxAward', 500);
+    if (amount > maxAward) {
+      wardx.event('coins.anomaly', { source, amount, reason, grantId: id });
+      wardx.log.warn('coins_anomaly', { source, amount, reason, grantId: id });
+    }
+  };
 }
+
+const recordMatchGrant = createGrantRecorder(wardx, 'match');
+// After committing each match reward:
+recordMatchGrant({ amount: 50, reason: 'win', id: 'grant-42' });
 ```
 
 `source` is a small set, for example `match`, `daily`, `purchase`, or `admin`.
@@ -423,7 +522,15 @@ If there is no identified subject and you omit `{ subjectId }`, that call is not
 2. If there is no subject (`identify` unset and no `{ subjectId }`), return the Remote Config value.
 3. If an experiment applies to the subject, return the variant value.
 
-The SDK updates the snapshot when a sync response contains a newer `configVersion`. Until that sync, `config.get` returns the fallback or the last snapshot.
+The server first filters keys and experiments by role, then resolves any conditional base values against the instance's metadata and attributes. An applicable experiment still overrides that resolved base. Attributes do not change experiment eligibility, allocation, assignment, or exposure tracking.
+
+SDK 0.9.0 requires `@wardx/server` 0.9.0 or newer. Upgrade the server first: older servers reject the new client fields even when attributes are empty.
+
+Pass an optional flat `attributes` object to `createWardx`, for example `attributes: { os: 'android', build: 119, channel: 'stable' }`. Names are application-defined; values must be strings, finite numbers, or booleans. Wardx's `platform` identifies the SDK runtime (`node`, `csharp`, or `unity`), so use a custom attribute for the operating system. Attributes are shared by the SDK instance, not set per `config.get` subject; do not use an instance's attributes to switch between concurrent users.
+
+`wardx.setAttributes({ os: 'android', build: 120 })` replaces the entire attribute map with a copy. Use `{}` to clear it. The next successful sync resolves the new context; `await wardx.flush()` requests a sync now. Reads remain local and use the last snapshot until then. Attributes travel as client metadata; send only non-secret values.
+
+The SDK updates the snapshot when the project version or the resolved configuration changes. Every successful server response includes an opaque `configContext` token, which the SDK returns on subsequent syncs. The same contract applies with or without rules, allowing context changes to refresh values at the same `configVersion`. Until a successful sync, `config.get` returns the fallback or the last snapshot.
 
 ## Use case 10: Run an A/B experiment and record a goal
 
@@ -436,19 +543,20 @@ The ingest server config can define experiment `message-delay-v1` on key `messag
 On a client with one user, call `identify` once after login. Later `config.get` and `experiment.goal` use that subject. On a server that handles many users, pass `{ subjectId }` on every call. Do not use one SDK instance's default there; it would mix users.
 
 ```js
+const messagesSent = wardx.counter('message.sent');
 wardx.identify(userId);
 const delayMs = wardx.config.get('message.delayMs', 1000);
 setTimeout(() => {
   deliver(text);
-  wardx.counter('message.sent').inc();
+  messagesSent.inc();
   wardx.experiment.goal('message.sent', { value: 1 });
 }, delayMs);
 
-function sendMessage(wardx, userId, text) {
+function sendMessage(userId, text) {
   const delayMs = wardx.config.get('message.delayMs', 1000, { subjectId: userId });
   setTimeout(() => {
     deliver(text);
-    wardx.counter('message.sent').inc();
+    messagesSent.inc();
     wardx.experiment.goal('message.sent', { subjectId: userId, value: 1 });
   }, delayMs);
 }
@@ -483,7 +591,8 @@ const wardx = createWardx({
   privacySalt: 'demo-subject-hash-v1'
 });
 
-wardx.counter('jobs.completed').inc();
+const jobsCompleted = wardx.counter('jobs.completed');
+jobsCompleted.inc();
 await wardx.shutdown();
 ```
 
@@ -561,22 +670,28 @@ Two signals:
 
 ```js
 const SESSION_BUCKETS = [30_000, 60_000, 180_000, 300_000, 600_000, 1_200_000, 1_800_000, 3_600_000];
+const sessionDuration = wardx.histogram('session.duration', { buckets: SESSION_BUCKETS });
+const sessionTime = wardx.counter('session.time_ms');
+const sessionsEnded = wardx.counter('session.ended');
 
-function onPlaySessionStart(wardx, userId) {
+function onPlaySessionStart(userId) {
   wardx.identify(userId);
-  return { startedAt: Date.now() };
+  return { startedAt: performance.now(), reportedMs: 0 };
 }
 
-function onPlaySessionEnd(wardx, session) {
-  const durationMs = Date.now() - session.startedAt;
-  wardx.histogram('session.duration', { buckets: SESSION_BUCKETS }).observe(durationMs);
-  wardx.counter('session.time_ms').add(durationMs);
-  wardx.counter('session.ended').inc();
-  wardx.experiment.goal('session.duration', { value: durationMs });
+function onPlayHeartbeat(session) {
+  const elapsedMs = performance.now() - session.startedAt;
+  sessionTime.add(elapsedMs - session.reportedMs);
+  session.reportedMs = elapsedMs;
 }
 
-function onPlayHeartbeat(wardx, elapsedMs) {
-  wardx.counter('session.time_ms').add(elapsedMs);
+function onPlaySessionEnd(session) {
+  const durationMs = performance.now() - session.startedAt;
+  sessionDuration.observe(durationMs);
+  sessionTime.add(durationMs - session.reportedMs);
+  session.reportedMs = durationMs;
+  sessionsEnded.inc();
+  wardx.experiment.goal('session.duration', { value: durationMs });
 }
 ```
 
@@ -603,22 +718,29 @@ If you only increment `session.time_ms` and never emit the goal, MCP can still s
 The keys must already exist in Remote Config. The game reads them with `config.get`. Variants may only change those keys.
 
 ```js
-function onLevelStart(wardx, userId, levelId) {
-  const enemyHp = wardx.config.get(`level.${levelId}.enemyHp`, 100, { subjectId: userId });
-  wardx.event('level.start', { level: levelId });
-  wardx.counter('level.start', { level: levelId }).inc();
-  return enemyHp;
+function createLevelTelemetry(wardx, levelId) {
+  const started = wardx.counter('level.start', { level: levelId });
+  const failed = wardx.counter('level.fail', { level: levelId });
+  const completed = wardx.counter('level.complete', { level: levelId });
+  return {
+    onStart(userId) {
+      const enemyHp = wardx.config.get(`level.${levelId}.enemyHp`, 100, { subjectId: userId });
+      wardx.event('level.start', { level: levelId });
+      started.inc();
+      return enemyHp;
+    },
+    onFail() {
+      wardx.event('level.fail', { level: levelId });
+      failed.inc();
+    },
+    onComplete() {
+      wardx.event('level.complete', { level: levelId });
+      completed.inc();
+    }
+  };
 }
 
-function onLevelFail(wardx, levelId) {
-  wardx.event('level.fail', { level: levelId });
-  wardx.counter('level.fail', { level: levelId }).inc();
-}
-
-function onLevelComplete(wardx, levelId) {
-  wardx.event('level.complete', { level: levelId });
-  wardx.counter('level.complete', { level: levelId }).inc();
-}
+const levelThree = createLevelTelemetry(wardx, 3);
 ```
 
 `level` is a small set of ids. Do not put a unique run id on the counter.
@@ -636,12 +758,18 @@ From MCP, after onboarding: `upsert_experiment` on the existing keys (`level.3.e
 **Objective:** Count the failure. Log the error with a stack or a provider code. Wardx does not edit source. MCP returns the row. The agent uses `path` or `git` on that role, plus its own file permissions, to change the code.
 
 ```js
-function handleCheckout(req, res, wardx) {
+const paymentOk = wardx.counter('payment.ok');
+const paymentErrors = new Map(['timeout', 'card_declined', 'unknown'].map((code) =>
+  [code, wardx.counter('payment.error', { code })]
+));
+
+function handleCheckout(req, res) {
   try {
     charge(req.body);
-    wardx.counter('payment.ok').inc();
+    paymentOk.inc();
   } catch (err) {
-    wardx.counter('payment.error', { code: err.code || 'unknown' }).inc();
+    const errors = paymentErrors.get(err.code) ?? paymentErrors.get('unknown');
+    errors.inc();
     wardx.log.error('payment_failed', {
       name: err.name,
       code: err.code || 'unknown',
@@ -659,6 +787,10 @@ function clipStack(err, max = 4096) {
 }
 ```
 
+Use the provider's finite error-code vocabulary in `paymentErrors`; map other
+codes to `unknown` without growing the handle cache. The original code remains
+in the log attrs.
+
 `stack` is an attr string. Do not send the Error object.
 
 From MCP: `get_aggregates` for the rate, then `get_recent_logs` with `level: 'error'` and the message. If the role has `path` or `git` in the catalog, the agent opens that checkout and edits there. If those fields are empty, Wardx has no source hint. Do not invent a path.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wardx",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "Node.js SDK for Wardx telemetry, Remote Config, and experiments.",
   "keywords": [
     "wardx",
@@ -37,6 +37,6 @@
     "src"
   ],
   "dependencies": {
-    "@wardx/core": "0.7.0"
+    "@wardx/core": "0.9.0"
   }
 }

package/src/WardxNode.js

@@ -6,6 +6,7 @@ import {
   nextSyncDelayMs,
   ulid
 } from '@wardx/core';
+import { disabledCore } from './disabled.js';
 import { readFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -17,16 +18,24 @@ const pkg = JSON.parse(
   readFileSync(join(dirname(fileURLToPath(import.meta.url)), '..', 'package.json'), 'utf8')
 );
 
+function copyAttributes(attributes) {
+  if (!attributes || typeof attributes !== 'object' || Array.isArray(attributes)) {
+    throw new Error('attributes must be an object');
+  }
+  for (const [key, value] of Object.entries(attributes)) {
+    if (key.length === 0) throw new Error('attributes keys must be non-empty strings');
+    if (typeof value !== 'string' && typeof value !== 'boolean' && !(typeof value === 'number' && Number.isFinite(value))) {
+      throw new Error(`attributes.${key} must be a string, finite number, or boolean`);
+    }
+  }
+  return Object.fromEntries(Object.entries(attributes));
+}
+
 export class WardxNode {
   constructor(settings) {
     this.settings = settings;
-    this._core = new WardxCore(settings);
-    this._transport = createHttpTransport(settings);
-    this._stopped = false;
-    this._shutdownPromise = null;
-    this._syncChain = Promise.resolve();
-    this._instanceId = ulid();
-    this._sessionId = ulid();
+    this._disabled = settings.enabled === false;
+    this._core = this._disabled ? disabledCore : new WardxCore(settings);
     this.log = this._core.log;
     this.config = {
       get: (key, fallback, context) => this._core.configGet(key, fallback, context)
@@ -34,6 +43,15 @@ export class WardxNode {
     this.experiment = {
       goal: (name, context) => this._core.experimentGoal(name, context)
     };
+    if (this._disabled) return;
+    this._attributes = copyAttributes(settings.attributes === undefined ? {} : settings.attributes);
+    this._configContext = undefined;
+    this._transport = createHttpTransport(settings);
+    this._stopped = false;
+    this._shutdownPromise = null;
+    this._syncChain = Promise.resolve();
+    this._instanceId = ulid();
+    this._sessionId = ulid();
     this._aggregateTimer = setInterval(() => {
       this._core.internal.processRssBytes = readProcessRssBytes();
       this._core.snapshotIfDirty();
@@ -51,6 +69,11 @@ export class WardxNode {
     this._core.identify(subjectId);
   }
 
+  setAttributes(attributes) {
+    if (this._disabled) return;
+    this._attributes = copyAttributes(attributes);
+  }
+
   counter(name, dims) {
     return this._core.counter(name, dims);
   }
@@ -76,10 +99,12 @@ export class WardxNode {
   }
 
   flush() {
+    if (this._disabled) return Promise.resolve();
     return this._enqueueSync({ flush: true });
   }
 
   shutdown() {
+    if (this._disabled) return Promise.resolve();
     if (this._shutdownPromise === null) this._shutdownPromise = this._shutdown();
     return this._shutdownPromise;
   }
@@ -121,7 +146,7 @@ export class WardxNode {
       this._core.snapshotIfDirty();
     }
     const frames = this._core.takePendingFrames();
-    if (!flags.bootstrap && frames.length === 0) return;
+    if (!flags.bootstrap && !flags.flush && frames.length === 0) return;
     const envelope = {
       protocol: PROTOCOL_VERSION,
       project: this.settings.project,
@@ -135,9 +160,11 @@ export class WardxNode {
         role: this.settings.role,
         appVersion: this.settings.appVersion,
         environment: this.settings.environment,
-        platform: PLATFORM
+        platform: PLATFORM,
+        attributes: this._attributes
       },
       configVersion: this._core.configStore.version,
+      configContext: this._configContext,
       frames
     };
     const json = JSON.stringify(envelope);
@@ -205,6 +232,7 @@ export class WardxNode {
     }
     if (json.config) {
       this._core.applyConfig(json.configVersion, json.config);
+      this._configContext = json.configContext;
     }
   }
 }

package/src/disabled.js

@@ -0,0 +1,19 @@
+const noop = () => {};
+const counter = Object.freeze({ inc: noop, add: noop });
+const gauge = Object.freeze({ set: noop });
+const histogram = Object.freeze({ observe: noop });
+const distinct = Object.freeze({ add: noop });
+
+export const disabledCore = Object.freeze({
+  counter: () => counter,
+  gauge: () => gauge,
+  histogram: () => histogram,
+  distinct: () => distinct,
+  timer: () => noop,
+  event: noop,
+  retentionActivity: noop,
+  identify: noop,
+  log: Object.freeze({ debug: noop, info: noop, warn: noop, error: noop }),
+  configGet: (key, fallback) => fallback,
+  experimentGoal: noop
+});

package/src/index.d.ts

@@ -70,14 +70,17 @@ export interface ExperimentApi {
   goal(name: string, context?: ExperimentGoalContext): void;
 }
 
+export type DisabledWardxOptions = Partial<CreateWardxOptions> & { enabled: false };
+
 export class WardxNode {
-  settings: ResolvedSettings;
+  settings: ResolvedSettings | DisabledWardxOptions;
   log: LogApi;
   config: ConfigApi;
   experiment: ExperimentApi;
-  constructor(settings: ResolvedSettings);
+  constructor(settings: ResolvedSettings | DisabledWardxOptions);
   retentionActivity(userId: string): void;
   identify(subjectId: string | null | undefined): void;
+  setAttributes(attributes: Record<string, string | number | boolean>): void;
   counter(name: string, dims?: Dimensions | null): CounterHandle;
   gauge(name: string, dims?: Dimensions | null): GaugeHandle;
   histogram(name: string, a?: HistogramOptions | null, b?: HistogramOptions | null): HistogramHandle;
@@ -88,5 +91,5 @@ export class WardxNode {
   shutdown(): Promise<void>;
 }
 
-export function createWardx(options: CreateWardxOptions): WardxNode;
+export function createWardx(options: CreateWardxOptions | DisabledWardxOptions): WardxNode;
 export function createConsoleTracer(options?: ConsoleTracerOptions): Tracer;

package/src/index.js

@@ -3,7 +3,10 @@ import { WardxNode } from './WardxNode.js';
 import { createConsoleTracer } from './trace/createConsoleTracer.js';
 
 export function createWardx(options) {
-  return new WardxNode(resolveSettings(options));
+  if (options?.enabled !== undefined && typeof options.enabled !== 'boolean') {
+    throw new Error('enabled must be a boolean');
+  }
+  return new WardxNode(options?.enabled === false ? { enabled: false } : resolveSettings(options));
 }
 
 export { WardxNode, createConsoleTracer };