dd-trace 6.19.0 → 6.20.0

package/packages/dd-trace/src/openfeature/writers/flag-evaluation-context.js

@@ -0,0 +1,262 @@
+'use strict'
+
+const { types: { isDate, isProxy } } = require('node:util')
+
+const { normalizeTargetingKey } = require('./flag-evaluation-pii')
+
+const MAX_CONTEXT_FIELDS = 256
+const MAX_KEY_LENGTH = 256
+const MAX_VALUE_LENGTH = 256
+const MAX_LIST_ELEMENTS = 256
+const MAX_STRUCTURE_PROPERTIES = 256
+const MAX_SNAPSHOT_DEPTH = 4
+const MAX_VISITED_NODES = MAX_CONTEXT_FIELDS * (MAX_SNAPSHOT_DEPTH + 1)
+const OMIT_CONTEXT_VALUE = Symbol('omit context value')
+
+/** @typedef {string | number | boolean | null} ContextScalar */
+/** @typedef {Readonly<Record<string, ContextScalar>>} ContextSnapshot */
+/** @typedef {Array<[string, ContextScalar]>} ContextEntries */
+/**
+ * @typedef {object} Frame
+ * @property {object} container
+ * @property {string} prefix
+ * @property {number} depth
+ * @property {string[] | undefined} keys
+ * @property {number} index
+ * @property {number} limit
+ */
+
+/**
+ * Only plain data records are supported; caller-defined behavior is not part of telemetry.
+ * Check proxies before any reflection, including revoked proxies.
+ *
+ * @param {unknown} value
+ * @returns {value is Record<string, unknown>}
+ */
+function isRecord (value) {
+  if (value === null || typeof value !== 'object' || isProxy(value)) return false
+  const prototype = Object.getPrototypeOf(value)
+  return prototype === null || prototype === Object.prototype
+}
+
+/**
+ * Revalidate a hook-owned scalar snapshot without invoking caller behavior.
+ * Aggregation and serialization call this independently at their privacy boundaries.
+ *
+ * @param {unknown} value
+ * @returns {ContextSnapshot | undefined}
+ */
+function validateContextSnapshot (value) {
+  if (!isRecord(value)) return
+  /** @type {Record<string, ContextScalar>} */
+  const attrs = Object.create(null)
+  let hasAttrs = false
+  for (const key of Object.keys(value)) {
+    const item = validatedContextValue(value, key)
+    if (item === OMIT_CONTEXT_VALUE) continue
+    attrs[key] = item
+    hasAttrs = true
+  }
+  return hasAttrs ? Object.freeze(attrs) : undefined
+}
+
+/**
+ * Share the privacy checks without making serialization allocate identity tuples.
+ * The sentinel distinguishes rejected values from a valid null scalar.
+ *
+ * @param {Record<string, unknown>} snapshot
+ * @param {string} key
+ * @returns {ContextScalar | typeof OMIT_CONTEXT_VALUE}
+ */
+function validatedContextValue (snapshot, key) {
+  const descriptor = Object.getOwnPropertyDescriptor(snapshot, key)
+  if (!descriptor?.enumerable || !Object.hasOwn(descriptor, 'value')) return OMIT_CONTEXT_VALUE
+  const item = descriptor.value
+  if (normalizeTargetingKey(key) === undefined) return OMIT_CONTEXT_VALUE
+  if (item === null || typeof item === 'boolean' ||
+    (typeof item === 'number' && Number.isFinite(item)) ||
+    (typeof item === 'string' && normalizeTargetingKey(item) !== undefined)) return item
+  return OMIT_CONTEXT_VALUE
+}
+
+/**
+ * Validate once and order the scalar entries for aggregation identity. Returning
+ * tuples lets the complete key be JSON-encoded once, preserving scalar types and
+ * escaping delimiters without embedding an already-encoded context string.
+ *
+ * @param {unknown} value - Hook-owned snapshot, after queue handoff
+ * @returns {ContextEntries | undefined}
+ */
+function validatedContextEntries (value) {
+  if (!isRecord(value)) return
+  /** @type {ContextEntries} */
+  const entries = []
+  for (const key of Object.keys(value).sort()) {
+    const item = validatedContextValue(value, key)
+    if (item !== OMIT_CONTEXT_VALUE) entries.push([key, item])
+  }
+  return entries.length > 0 ? entries : undefined
+}
+
+/**
+ * Materialize owned, immutable attributes only when they will be retained or sent.
+ * Callers must obtain entries from validatedContextEntries, never caller-owned data.
+ *
+ * @param {ContextEntries | undefined} entries
+ * @returns {ContextSnapshot | undefined}
+ */
+function snapshotFromEntries (entries) {
+  if (entries === undefined) return
+  /** @type {Record<string, ContextScalar>} */
+  const attrs = Object.create(null)
+  for (const [key, value] of entries) attrs[key] = value
+  return Object.freeze(attrs)
+}
+
+/**
+ * Retain only a capped set of property names, in JavaScript's natural key order.
+ *
+ * Object.keys must enumerate the complete object: JS has no bounded own-key API.
+ * The key-list allocation is proportional to object width, unlike indexed array
+ * traversal. Explicit traversal, frame retention, and output are independently capped.
+ *
+ * @param {object} container
+ * @param {string} prefix
+ * @param {number} depth
+ * @param {Set<string>} reasons
+ * @returns {Frame}
+ */
+function createFrame (container, prefix, depth, reasons) {
+  let keys
+  let limit
+  if (Array.isArray(container)) {
+    limit = Math.min(container.length, MAX_LIST_ELEMENTS)
+    if (container.length > limit) reasons.add('max_list_elements')
+  } else {
+    const allKeys = Object.keys(container)
+    if (depth === -1) {
+      const excluded = Object.getOwnPropertyDescriptor(container, 'targetingKey')?.enumerable === true
+      if (allKeys.length - Number(excluded) > MAX_STRUCTURE_PROPERTIES) reasons.add('max_context_fields')
+      keys = allKeys.slice(0, MAX_STRUCTURE_PROPERTIES + 1)
+        .filter(key => key !== 'targetingKey').slice(0, MAX_STRUCTURE_PROPERTIES)
+    } else {
+      if (allKeys.length > MAX_STRUCTURE_PROPERTIES) reasons.add('max_structure_properties')
+      keys = allKeys.slice(0, MAX_STRUCTURE_PROPERTIES)
+    }
+    limit = keys.length
+  }
+  return { container, prefix, depth, keys, index: 0, limit }
+}
+
+/**
+ * Flatten consented context into a frozen, scalar-only snapshot before enqueue.
+ * No getters, proxy traps, iterators, or caller serialization hooks are invoked.
+ * The caller must check capacity and consent before calling this function.
+ *
+ * @param {unknown} context - Caller-owned OpenFeature context
+ * @returns {{ attrs: ContextSnapshot, reasons: Set<string> }}
+ */
+function snapshotEvaluationContext (context) {
+  /** @type {Record<string, ContextScalar>} */
+  const attrs = Object.create(null)
+  const reasons = new Set()
+  if (!isRecord(context)) {
+    if (context !== null && context !== undefined) reasons.add('unsupported_type')
+    return { attrs: Object.freeze(attrs), reasons }
+  }
+
+  const root = /** @type {object} */ (context)
+  const ancestors = new WeakSet([root])
+  const stack = [createFrame(root, '', -1, reasons)]
+  let visited = 0
+  let fields = 0
+
+  while (stack.length > 0) {
+    const frame = /** @type {Frame} */ (stack.at(-1))
+    if (frame.index === frame.limit) {
+      ancestors.delete(frame.container)
+      stack.pop()
+      continue
+    }
+    if (fields === MAX_CONTEXT_FIELDS) {
+      reasons.add('max_context_fields')
+      break
+    }
+    if (visited === MAX_VISITED_NODES) {
+      reasons.add('max_visited_nodes')
+      break
+    }
+    visited++
+    const key = frame.keys ? frame.keys[frame.index++] : String(frame.index++)
+    const prefix = frame.depth === -1 ? key : frame.prefix + '.' + key
+    if (prefix.length > MAX_KEY_LENGTH) {
+      reasons.add('max_key_length')
+      continue
+    }
+    if (normalizeTargetingKey(prefix) === undefined) {
+      reasons.add('invalid_encoding')
+      continue
+    }
+
+    const descriptor = Object.getOwnPropertyDescriptor(frame.container, key)
+    if (!descriptor?.enumerable) continue
+    if (!Object.hasOwn(descriptor, 'value')) {
+      reasons.add('unsupported_type')
+      continue
+    }
+    /** @type {unknown} */
+    let value = descriptor.value
+    if (typeof value === 'string') {
+      if (value.length > MAX_VALUE_LENGTH) {
+        reasons.add('max_value_length')
+        continue
+      }
+      if (normalizeTargetingKey(value) === undefined) {
+        reasons.add('invalid_encoding')
+        continue
+      }
+    } else if (value !== null && typeof value === 'object') {
+      if (isProxy(value)) {
+        reasons.add('unsupported_type')
+        continue
+      }
+      if (isDate(value)) {
+        if (!Number.isFinite(Date.prototype.getTime.call(value))) {
+          reasons.add('unsupported_type')
+          continue
+        }
+        value = Date.prototype.toISOString.call(value)
+      } else {
+        if (!Array.isArray(value) && !isRecord(value)) {
+          reasons.add('unsupported_type')
+          continue
+        }
+        const depth = frame.depth + 1
+        if (depth >= MAX_SNAPSHOT_DEPTH) {
+          reasons.add('max_snapshot_depth')
+          continue
+        }
+        if (ancestors.has(value)) {
+          reasons.add('cycle')
+          continue
+        }
+        ancestors.add(value)
+        stack.push(createFrame(value, prefix, depth, reasons))
+        continue
+      }
+    } else if (
+      value !== null && typeof value !== 'boolean' &&
+      (typeof value !== 'number' || !Number.isFinite(value))
+    ) {
+      reasons.add('unsupported_type')
+      continue
+    }
+
+    if (!Object.hasOwn(attrs, prefix)) fields++
+    attrs[prefix] = /** @type {ContextScalar} */ (value)
+  }
+
+  return { attrs: Object.freeze(attrs), reasons }
+}
+
+module.exports = { snapshotEvaluationContext, validatedContextEntries, snapshotFromEntries, validateContextSnapshot }

package/packages/dd-trace/src/openfeature/writers/flag-evaluation-payload.js

@@ -0,0 +1,181 @@
+'use strict'
+
+const { EVP_EVENT_SIZE_LIMIT, EVP_PAYLOAD_SIZE_LIMIT } = require('../constants/constants')
+const { validateContextSnapshot } = require('./flag-evaluation-context')
+const { prefixedTargetingKeyDigest, normalizeTargetingKey, protectedErrorCode } = require('./flag-evaluation-pii')
+const { recordDegraded, recordDropped, recordPayloadSplit } = require('./flag-evaluation-telemetry')
+
+/** @typedef {import('./flag-evaluation-aggregation').AggregationEntry} AggregationEntry */
+/** @typedef {import('./flag-evaluation-context').ContextSnapshot} ContextSnapshot */
+/**
+ * @typedef {object} FlagEvaluationBatchContext
+ * @property {string} service
+ * @property {string} [env]
+ * @property {string} [version]
+ */
+/**
+ * @typedef {object} FlagEvaluationRow
+ * @property {number} timestamp
+ * @property {{ key: string }} flag
+ * @property {number} first_evaluation
+ * @property {number} last_evaluation
+ * @property {number} evaluation_count
+ * @property {boolean} [runtime_default_used]
+ * @property {string} [targeting_key]
+ * @property {{ evaluation: ContextSnapshot }} [context]
+ * @property {{ key: string }} [variant]
+ * @property {{ key: string }} [allocation]
+ * @property {{ message: string }} [error]
+ */
+/** @typedef {{ encoded: string, rows: number, evaluations: number }} EncodedFlagEvaluationPayload */
+
+/**
+ * @param {AggregationEntry} entry
+ * @param {number} timestamp
+ * @param {boolean} degraded
+ * @returns {FlagEvaluationRow | undefined}
+ */
+function makeRow (entry, timestamp, degraded) {
+  const flagKey = normalizeTargetingKey(entry.flagKey)
+  if (flagKey === undefined || !Number.isSafeInteger(entry.first) || !Number.isSafeInteger(entry.last) ||
+    !Number.isSafeInteger(entry.count) || entry.count < 1) return
+  /** @type {FlagEvaluationRow} */
+  const row = {
+    timestamp,
+    flag: { key: flagKey },
+    first_evaluation: entry.first,
+    last_evaluation: entry.last,
+    evaluation_count: entry.count,
+  }
+  if (entry.runtimeDefault === true) row.runtime_default_used = true
+  const variant = normalizeTargetingKey(entry.variant)
+  const allocation = normalizeTargetingKey(entry.allocation)
+  if (variant) row.variant = { key: variant }
+  if (allocation) row.allocation = { key: allocation }
+  const error = protectedErrorCode(entry.error)
+  if (error !== undefined) row.error = { message: error }
+  if (!degraded) {
+    const targetingKey = entry.consent === true
+      ? normalizeTargetingKey(entry.rawTargetingKey)
+      : prefixedTargetingKeyDigest(entry.rawTargetingKey)
+    if (targetingKey !== undefined) row.targeting_key = targetingKey
+    const attrs = entry.consent === true ? validateContextSnapshot(entry.attrs) : undefined
+    if (attrs !== undefined) row.context = { evaluation: attrs }
+  }
+  return row
+}
+
+/**
+ * Advance serialization only when the transport has room for another complete envelope.
+ * Takes ownership of the detached aggregate maps and clears them when iteration starts.
+ *
+ * @param {Map<string, AggregationEntry>} full
+ * @param {Map<string, AggregationEntry>} degraded
+ * @param {FlagEvaluationBatchContext} context
+ * @param {number} timestamp
+ * @param {(count: number) => void} [onConsumed] - Transfer observation ownership on encoding or discard
+ * @yields {EncodedFlagEvaluationPayload} One envelope bounded by the existing EVP payload limit.
+ */
+function * iterateFlagEvaluationPayloads (full, degraded, context, timestamp, onConsumed) {
+  const prefix = '{"context":' + JSON.stringify(context) + ',"flagEvaluations":['
+  const suffix = ']}'
+  /** @type {string[]} */
+  let encodedRows = []
+  let evaluations = 0
+  let payloadCount = 0
+  let size = Buffer.byteLength(prefix) + Buffer.byteLength(suffix)
+
+  const close = () => {
+    const payload = { encoded: prefix + encodedRows.join(',') + suffix, rows: encodedRows.length, evaluations }
+    if (payloadCount > 0) recordPayloadSplit()
+    payloadCount++
+    evaluations = 0
+    encodedRows = []
+    size = Buffer.byteLength(prefix) + Buffer.byteLength(suffix)
+    return payload
+  }
+
+  /**
+   * @param {string} reason
+   * @param {number} count
+   */
+  const drop = (reason, count) => {
+    onConsumed?.(count)
+    recordDropped(reason, count)
+  }
+
+  /** @type {Array<[AggregationEntry, boolean]>} */
+  const entries = []
+  for (const entry of full.values()) entries.push([entry, false])
+  for (const entry of degraded.values()) entries.push([entry, true])
+
+  // Lookup keys are no longer needed after aggregation. Pop entries in their original
+  // order so a paused flush does not retain entries that have already been encoded.
+  full.clear()
+  degraded.clear()
+  entries.reverse()
+  while (entries.length > 0) {
+    const [entry, aggregateDegraded] = /** @type {[AggregationEntry, boolean]} */ (entries.pop())
+    const row = makeRow(entry, timestamp, aggregateDegraded)
+    if (row === undefined) {
+      drop('serialization_error', entry.count)
+      continue
+    }
+    let serializedRow = row
+    let encoded
+    try {
+      encoded = JSON.stringify(serializedRow)
+    } catch {
+      drop('serialization_error', serializedRow.evaluation_count)
+      continue
+    }
+
+    let canDegrade = serializedRow.targeting_key !== undefined || serializedRow.context !== undefined
+    const degrade = () => {
+      if (!canDegrade) return false
+      serializedRow = { ...serializedRow }
+      delete serializedRow.targeting_key
+      delete serializedRow.context
+      encoded = JSON.stringify(serializedRow)
+      recordDegraded('payload_limit', serializedRow.evaluation_count)
+      canDegrade = false
+      return true
+    }
+
+    try {
+      if (Buffer.byteLength(encoded) > EVP_EVENT_SIZE_LIMIT) degrade()
+    } catch {
+      drop('serialization_error', serializedRow.evaluation_count)
+      continue
+    }
+    if (Buffer.byteLength(encoded) > EVP_EVENT_SIZE_LIMIT) {
+      drop('payload_limit', serializedRow.evaluation_count)
+      continue
+    }
+
+    let addition = Buffer.byteLength(encoded) + Number(encodedRows.length > 0)
+    if (size + addition > EVP_PAYLOAD_SIZE_LIMIT && encodedRows.length > 0) {
+      yield close()
+      addition = Buffer.byteLength(encoded)
+    }
+    if (size + addition > EVP_PAYLOAD_SIZE_LIMIT) {
+      try {
+        if (degrade()) addition = Buffer.byteLength(encoded)
+      } catch {
+        drop('serialization_error', serializedRow.evaluation_count)
+        continue
+      }
+    }
+    if (size + addition > EVP_PAYLOAD_SIZE_LIMIT) {
+      drop('payload_limit', serializedRow.evaluation_count)
+      continue
+    }
+    encodedRows.push(encoded)
+    onConsumed?.(serializedRow.evaluation_count)
+    evaluations += serializedRow.evaluation_count
+    size += addition
+  }
+  if (encodedRows.length > 0) yield close()
+}
+
+module.exports = { iterateFlagEvaluationPayloads }

package/packages/dd-trace/src/openfeature/writers/flag-evaluation-pii.js

@@ -0,0 +1,108 @@
+'use strict'
+
+const { hashTargetingKey: digestTargetingKey } = require('../encoding')
+
+// Keep this vocabulary explicit: an upstream enum addition needs a privacy review.
+const ERROR_CODES = new Set([
+  'PROVIDER_NOT_READY',
+  'PROVIDER_FATAL',
+  'FLAG_NOT_FOUND',
+  'PARSE_ERROR',
+  'TYPE_MISMATCH',
+  'TARGETING_KEY_MISSING',
+  'INVALID_CONTEXT',
+  'GENERAL',
+])
+
+/**
+ * Validate targeting text before UTF-8 encoding, which would repair lone surrogates.
+ * Empty text is valid and distinct from a missing key. Do not coerce customer input.
+ *
+ * @param {unknown} value - Evaluation targeting key
+ * @returns {string | undefined}
+ */
+function normalizeTargetingKey (value) {
+  if (typeof value !== 'string') return
+
+  for (let i = 0; i < value.length; i++) {
+    const code = value.charCodeAt(i)
+    if (code >= 0xD8_00 && code <= 0xDB_FF) {
+      if (++i === value.length) return
+      const low = value.charCodeAt(i)
+      if (low < 0xDC_00 || low > 0xDF_FF) return
+    } else if (code >= 0xDC_00 && code <= 0xDF_FF) {
+      return
+    }
+  }
+
+  return value
+}
+
+/**
+ * Apply EVP's protected targeting-key policy using the shared SHA-256 primitive.
+ * The cross-SDK contract deliberately uses an unsalted, stable digest for subject counts.
+ * This is pseudonymization, not anonymity: guessable keys remain guessable and equal
+ * keys produce equal hashes across services and organizations. An org-scoped salt
+ * requires a coordinated configuration/backend contract, not a JS-only secret.
+ * This runs after queue handoff; hashing must not move onto the evaluation hot path.
+ *
+ * @param {unknown} value - Raw evaluation targeting key, never a previously emitted hash
+ * @returns {string | undefined}
+ */
+function prefixedTargetingKeyDigest (value) {
+  const key = normalizeTargetingKey(value)
+  if (key === undefined || key === '') return key
+  return 'sha256_' + digestTargetingKey(key)
+}
+
+/**
+ * Preserve only approved OpenFeature codes on the wire, in every consent mode.
+ * Absence means no error; malformed or unknown supplied codes become GENERAL.
+ *
+ * @param {unknown} value - OpenFeature errorCode, never errorMessage
+ * @returns {string | undefined}
+ */
+function protectedErrorCode (value) {
+  if (value === undefined || value === null || value === '') return
+  return typeof value === 'string' && ERROR_CODES.has(value) ? value : 'GENERAL'
+}
+
+/**
+ * Optional metadata dimensions omit empty text; targeting keys deliberately preserve it.
+ *
+ * @param {unknown} value
+ * @returns {string | undefined}
+ */
+function optionalKey (value) {
+  const key = normalizeTargetingKey(value)
+  return key === undefined || key.length === 0 ? undefined : key
+}
+
+/**
+ * Shape observations at both admission boundaries; each caller counts omitted targeting keys.
+ *
+ * @param {import('./flag-evaluation-aggregation').FlagEvaluationEvent} event
+ * @param {string | undefined} targetingKey - Targeting key already validated by the caller
+ */
+function normalizeFlagEvaluationEvent (event, targetingKey) {
+  const consent = event.observeFullEvaluationData === true
+  return {
+    flagKey: normalizeTargetingKey(event.flagKey),
+    variant: optionalKey(event.variant),
+    allocationKey: optionalKey(event.allocationKey),
+    runtimeDefault: event.runtimeDefault === true,
+    errorCode: protectedErrorCode(event.errorCode),
+    targetingKey,
+    attrs: consent ? event.attrs : undefined,
+    observeFullEvaluationData: consent,
+    timestamp: typeof event.timestamp === 'number' ? event.timestamp : NaN,
+  }
+}
+
+module.exports = {
+  normalizeFlagEvaluationEvent,
+  normalizeTargetingKey,
+  optionalKey,
+  prefixedTargetingKeyDigest,
+  protectedErrorCode,
+}

package/packages/dd-trace/src/openfeature/writers/flag-evaluation-telemetry.js

@@ -0,0 +1,154 @@
+'use strict'
+
+let metrics
+/** @type {Int32Array | undefined} */
+let workerState
+
+// Namespace resets clear points, not metric instances. Names and reasons are fixed below.
+/** @type {Map<string, { inc: (value: number) => void }>} */
+const countMetrics = new Map()
+
+const DROP_REASONS = new Set([
+  'pre_queue_overflow',
+  'queue_overflow',
+  'closed',
+  'unavailable',
+  'degraded_cap',
+  'payload_limit',
+  'serialization_error',
+  // Discarded after failed delivery; an ambiguous response does not prove the receiver lost the batch.
+  'delivery_failure',
+  'worker_failure',
+  'shutdown_timeout',
+])
+const DEGRADE_REASONS = new Set(['cardinality_cap', 'payload_limit'])
+const CONTEXT_REASONS = new Set([
+  'max_context_fields',
+  'max_key_length',
+  'max_value_length',
+  'max_list_elements',
+  'max_structure_properties',
+  'max_snapshot_depth',
+  'max_visited_nodes',
+  'cycle',
+  'invalid_encoding',
+  'unsupported_type',
+  'snapshot_error',
+])
+
+// Slot 0 owns admitted input until aggregation; slot 1 owns all accepted observations until delivery/drop.
+// Fixed metric slots follow. Only the application drains them; no message per event or flush.
+/** @type {Array<[string, string | undefined]>} */
+const metricKeys = [
+  ...[...DROP_REASONS].map(reason => /** @type {[string, string]} */ (['flagevaluation.rows.dropped', reason])),
+  ...[...DEGRADE_REASONS].map(reason => /** @type {[string, string]} */ (['flagevaluation.rows.degraded', reason])),
+  ...[...CONTEXT_REASONS].map(reason => /** @type {[string, string]} */ (['flagevaluation.context.truncated', reason])),
+  ['flagevaluation.payload.splits', undefined],
+  ['flagevaluation.targeting_key.omitted', 'invalid'],
+  ['flagevaluation.hook.errors', undefined],
+]
+const metricSlots = new Map(metricKeys.map(([name, reason], index) => [name + ':' + reason, index + 2]))
+
+/** @param {Int32Array} state */
+function configureWorkerTelemetry (state) {
+  workerState = state
+}
+
+function createWorkerState () {
+  return new Int32Array(new SharedArrayBuffer((metricKeys.length + 2) * Int32Array.BYTES_PER_ELEMENT))
+}
+
+/** @param {Int32Array} state */
+function collectWorkerTelemetry (state) {
+  for (let i = 0; i < metricKeys.length; i++) {
+    const value = Atomics.exchange(state, i + 2, 0)
+    const [name, reason] = metricKeys[i]
+    count(name, value, reason)
+  }
+}
+
+/**
+ * Best-effort telemetry must never affect an evaluation or writer drain.
+ *
+ * @param {string} name - Bounded metric name
+ * @param {number} value - Count to add
+ * @param {string} [reason] - Bounded reason tag
+ */
+function count (name, value, reason) {
+  if (!Number.isSafeInteger(value) || value <= 0) return
+  if (workerState) {
+    const slot = /** @type {number} */ (metricSlots.get(name + ':' + reason))
+    // Saturate instead of wrapping if the application stops collecting metrics for a long time.
+    let previous = Atomics.load(workerState, slot)
+    while (Atomics.compareExchange(workerState, slot, previous,
+      Math.min(0x7F_FF_FF_FF, previous + value)) !== previous) {
+      previous = Atomics.load(workerState, slot)
+    }
+    return
+  }
+  try {
+    const id = name + ':' + reason
+    let metric = countMetrics.get(id)
+    if (metric === undefined) {
+      metrics ??= require('../../telemetry/metrics').manager.namespace('general')
+      metric = /** @type {{ inc: (value: number) => void }} */ (
+        metrics.count(name, reason === undefined ? undefined : { reason })
+      )
+      countMetrics.set(id, metric)
+    }
+    metric.inc(value)
+  } catch {}
+}
+
+/**
+ * @param {string} reason
+ * @param {number} [value]
+ */
+function recordDropped (reason, value = 1) {
+  if (!DROP_REASONS.has(reason)) return
+  if (workerState && Number.isSafeInteger(value) && value > 0) Atomics.sub(workerState, 1, value)
+  count('flagevaluation.rows.dropped', value, reason)
+}
+
+/**
+ * @param {string} reason
+ * @param {number} [value]
+ */
+function recordDegraded (reason, value = 1) {
+  if (DEGRADE_REASONS.has(reason)) count('flagevaluation.rows.degraded', value, reason)
+}
+
+/** @param {number} [value] */
+function recordPayloadSplit (value = 1) {
+  count('flagevaluation.payload.splits', value)
+}
+
+/**
+ * @param {string} reason
+ * @param {number} [value]
+ */
+function recordContextTruncated (reason, value = 1) {
+  if (CONTEXT_REASONS.has(reason)) count('flagevaluation.context.truncated', value, reason)
+}
+
+/** @param {number} [value] */
+function recordTargetingKeyOmitted (value = 1) {
+  count('flagevaluation.targeting_key.omitted', value, 'invalid')
+}
+
+/** @param {number} [value] */
+function recordHookError (value = 1) {
+  count('flagevaluation.hook.errors', value)
+}
+
+module.exports = {
+  collectWorkerTelemetry,
+  configureWorkerTelemetry,
+  createWorkerState,
+  recordContextTruncated,
+  recordDegraded,
+  recordDropped,
+  recordHookError,
+  recordPayloadSplit,
+  recordTargetingKeyOmitted,
+}