@depup/elastic-apm-node 4.15.0-depup.0

package/lib/opentelemetry-bridge/OTelTracer.js

@@ -0,0 +1,201 @@
+/*
+ * Copyright Elasticsearch B.V. and other contributors where applicable.
+ * Licensed under the BSD 2-Clause License; you may not use this file except in
+ * compliance with the BSD 2-Clause License.
+ */
+
+'use strict';
+
+const otel = require('@opentelemetry/api');
+
+const oblog = require('./oblog');
+const { OTelBridgeRunContext } = require('./OTelBridgeRunContext');
+const { OTelSpan } = require('./OTelSpan');
+const Transaction = require('../instrumentation/transaction');
+const { OTelBridgeNonRecordingSpan } = require('./OTelBridgeNonRecordingSpan');
+const {
+  epochMsFromOTelTimeInput,
+  otelSpanContextFromTraceContext,
+  traceparentStrFromOTelSpanContext,
+} = require('./otelutils');
+const { OUTCOME_UNKNOWN } = require('../constants');
+
+// Implements interface Tracer from:
+// https://github.com/open-telemetry/opentelemetry-js-api/blob/v1.0.4/src/trace/tracer.ts
+class OTelTracer {
+  constructor(agent) {
+    this._agent = agent;
+    this._ins = agent._instrumentation;
+  }
+
+  /**
+   * Starts a new {@link Span}. Start the span without setting it on context.
+   *
+   * This method do NOT modify the current Context.
+   *
+   * @param name The name of the span
+   * @param [options] SpanOptions used for span creation
+   * @param [context] Context to use to extract parent
+   * @returns Span The newly created span
+   * @example
+   *     const span = tracer.startSpan('op');
+   *     span.setAttribute('key', 'value');
+   *     span.end();
+   */
+  startSpan(name, otelSpanOptions = {}, otelContext = otel.context.active()) {
+    oblog.apicall(
+      'OTelTracer.startSpan(name=%s, options=%j, context=%s)',
+      name,
+      otelSpanOptions,
+      otelContext,
+    );
+
+    // Get the parent info for the new span.
+    // We want to get a core Transaction or Span as a parent, when possible,
+    // because that is required to support the span compression feature.
+    let parentGenericSpan;
+    let parentOTelSpanContext;
+    if (otelSpanOptions.root) {
+      // Pass through: explicitly want no parent.
+    } else if (otelContext instanceof OTelBridgeRunContext) {
+      parentGenericSpan =
+        otelContext.currSpan() || otelContext.currTransaction();
+      if (parentGenericSpan instanceof OTelBridgeNonRecordingSpan) {
+        // This isn't a real Transaction we can use. It is a placeholder
+        // to propagate its SpanContext. Grab just that.
+        parentOTelSpanContext = parentGenericSpan.spanContext();
+        parentGenericSpan = null;
+      }
+    } else {
+      // `otelContext` is any object that is meant to satisfy `interface
+      // Context`. This may hold an OTel `SpanContext` that should be
+      // propagated.
+      parentOTelSpanContext = otel.trace.getSpanContext(otelContext);
+    }
+
+    const createOpts = {};
+    if (otelSpanOptions.links) {
+      // Span link *attributes* are not currently supported, they are silently dropped.
+      createOpts.links = otelSpanOptions.links
+        .filter(
+          (otelLink) =>
+            otelLink &&
+            otelLink.context &&
+            otel.isSpanContextValid(otelLink.context),
+        )
+        .map((otelLink) => {
+          return {
+            context: traceparentStrFromOTelSpanContext(otelLink.context),
+          };
+        });
+    }
+
+    // Create the new Span/Transaction.
+    let newTransOrSpan = null;
+    if (parentGenericSpan) {
+      // New child span.
+      const trans =
+        parentGenericSpan instanceof Transaction
+          ? parentGenericSpan
+          : parentGenericSpan.transaction;
+      createOpts.childOf = parentGenericSpan;
+      if (otelSpanOptions.startTime) {
+        createOpts.startTime = epochMsFromOTelTimeInput(
+          otelSpanOptions.startTime,
+        );
+      }
+      if (
+        otelSpanOptions.kind === otel.SpanKind.CLIENT ||
+        otelSpanOptions.kind === otel.SpanKind.PRODUCER
+      ) {
+        createOpts.exitSpan = true;
+      }
+      newTransOrSpan = trans.createSpan(name, createOpts);
+
+      // There might be no span, e.g. if the span is a child of an exit span. We
+      // have to return some OTelSpan, and we also want to propagate the
+      // parent's trace-context, if any.
+      if (!newTransOrSpan) {
+        return otel.trace.wrapSpanContext(
+          otelSpanContextFromTraceContext(parentGenericSpan._context),
+        );
+      }
+    } else if (
+      parentOTelSpanContext &&
+      otel.isSpanContextValid(parentOTelSpanContext)
+    ) {
+      // New continuing transaction.
+      // Note: This is *not* using `SpanContext.isRemote`. I am not sure if it
+      // is relevant unless using something, like @opentelemetry/core's
+      // `W3CTraceContextPropagator`, that sets `isRemote = true`. Nothing in
+      // @opentelemetry/api itself sets isRemote.
+      createOpts.childOf = traceparentStrFromOTelSpanContext(
+        parentOTelSpanContext,
+      );
+      if (parentOTelSpanContext.traceState) {
+        createOpts.tracestate = parentOTelSpanContext.traceState.serialize();
+      }
+      if (otelSpanOptions.startTime !== undefined) {
+        createOpts.startTime = epochMsFromOTelTimeInput(
+          otelSpanOptions.startTime,
+        );
+      }
+      newTransOrSpan = this._ins.createTransaction(name, createOpts);
+    } else {
+      // New root transaction.
+      if (otelSpanOptions.startTime !== undefined) {
+        createOpts.startTime = epochMsFromOTelTimeInput(
+          otelSpanOptions.startTime,
+        );
+      }
+      newTransOrSpan = this._ins.createTransaction(name, createOpts);
+    }
+
+    newTransOrSpan._setOTelKind(
+      otel.SpanKind[otelSpanOptions.kind || otel.SpanKind.INTERNAL],
+    );
+
+    // Explicitly use the higher-priority user outcome API to prevent the agent
+    // inferring the outcome from any reported errors or HTTP status code.
+    newTransOrSpan.setOutcome(OUTCOME_UNKNOWN);
+
+    const otelSpan = new OTelSpan(newTransOrSpan);
+    otelSpan.setAttributes(otelSpanOptions.attributes);
+
+    return otelSpan;
+  }
+
+  // startActiveSpan(name[, options[, context]], fn)
+  //
+  // Interface: https://github.com/open-telemetry/opentelemetry-js-api/blob/main/src/trace/tracer.ts#L41
+  // Adapted from: https://github.com/open-telemetry/opentelemetry-js/blob/main/packages/opentelemetry-sdk-trace-base/src/Tracer.ts
+  startActiveSpan(name, otelSpanOptions, otelContext, fn) {
+    oblog.apicall(
+      'OTelTracer.startActiveSpan(name=%s, options=%j, context=%s, fn)',
+      name,
+      otelSpanOptions,
+      otelContext,
+    );
+
+    if (arguments.length < 2) {
+      return;
+    } else if (arguments.length === 2) {
+      fn = otelSpanOptions;
+      otelSpanOptions = undefined;
+      otelContext = undefined;
+    } else if (arguments.length === 3) {
+      fn = otelContext;
+      otelContext = undefined;
+    }
+
+    const parentContext = otelContext || otel.context.active();
+    const span = this.startSpan(name, otelSpanOptions, parentContext);
+    const contextWithSpanSet = otel.trace.setSpan(parentContext, span);
+
+    return otel.context.with(contextWithSpanSet, fn, undefined, span);
+  }
+}
+
+module.exports = {
+  OTelTracer,
+};

package/lib/opentelemetry-bridge/OTelTracerProvider.js

@@ -0,0 +1,25 @@
+/*
+ * Copyright Elasticsearch B.V. and other contributors where applicable.
+ * Licensed under the BSD 2-Clause License; you may not use this file except in
+ * compliance with the BSD 2-Clause License.
+ */
+
+'use strict';
+
+const oblog = require('./oblog');
+
+class OTelTracerProvider {
+  // @param {OTelTracer} tracer
+  constructor(tracer) {
+    this._tracer = tracer;
+  }
+
+  getTracer(_name, _version, _options) {
+    oblog.apicall('OTelTracerProvider.getTracer(...)');
+    return this._tracer;
+  }
+}
+
+module.exports = {
+  OTelTracerProvider,
+};

package/lib/opentelemetry-bridge/README.md

@@ -0,0 +1,244 @@
+# OpenTelemetry Bridge
+
+This document includes design / developer / maintenance notes for the
+Node.js APM Agent *OpenTelemetry Bridge*.
+
+Spec: https://github.com/elastic/apm/blob/main/specs/agents/tracing-api-otel.md
+
+## Maintenance
+
+- We should release a new agent version with an updated "@opentelemetry/api"
+  dependency relatively soon after any new *minor* release. Otherwise a user
+  upgrading their "@opentelemetry/api" dep to "1.x+1", e.g. "1.2.0", will find
+  that the OTel Bridge which uses version "1.x", e.g. "1.1.0" or lower, does
+  not work.
+
+  The reason is that the OTel Bridge registers global providers (e.g.
+  `otel.trace.setGlobalTracerProvider`) with its version of the OTel API. When
+  user code attempts to *get* a tracer with **its version** of the OTel API, the
+  [OTel API compatibility logic](https://github.com/open-telemetry/opentelemetry-js-api/blob/v1.1.0/src/internal/semver.ts#L24-L33)
+  decides that using a v1.1.x Tracer with a v1.2.0 Tracer API is not compatible
+  and falls back to a noop implementation.
+
+
+## Development / Debugging
+
+When doing development on, or debugging the OTel Bridge, it might be helpful to
+enable logging of (almost) every `@opentelemetry/api` call into the bridge.
+This is done by setting this in `lib/opentelemetry-bridge/setup.js`.
+
+    const LOG_OTEL_API_CALLS = true
+
+It looks like this:
+
+```
+% cd test/opentelemetry-bridge/fixtures
+% ELASTIC_APM_OPENTELEMETRY_BRIDGE_ENABLED=true node -r ../../../start.js start-span.js
+otelapi: OTelTracerProvider.getTracer(...)
+otelapi: OTelContextManager.active()
+otelapi: OTelTracer.startSpan(name=mySpan, options={}, context=OTelBridgeRunContext<>)
+otelapi: OTelContextManager.active()
+otelapi: OTelBridgeRunContext.getValue(Symbol(OpenTelemetry Context Key SPAN))
+otelapi: OTelSpan<Transaction<52260136515317aa, "mySpan">>.end(endTime=undefined)
+```
+
+Together with the agent's usual debug logging, this can help show how the bridge
+is working.
+
+```
+% ELASTIC_APM_OPENTELEMETRY_BRIDGE_ENABLED=true \
+    ELASTIC_APM_LOG_LEVEL=debug \
+    node -r ../../../start.js start-span.js | ecslog
+...
+```
+
+
+## Naming
+
+In general, the following variable/class/file naming is used:
+
+- A class that implements an OTel interface is prefixed with "OTel". For
+  example `class OTelSpan` implements OTel `interface Span`.
+- A class that bridges between an OTel interface and an object in the APM
+  agent is prefixed with `OTelBridge`. For example `OTelBridgeRunContext`
+  bridges between an OTel `interface Context` and the APM agent's `RunContext`,
+  i.e. it implements both interfaces/APIs.
+- A variable that holds an OpenTelemetry object is prefixed with `otel`, or
+  `...OTel...` if it in the middle of the var name. Some examples:
+  - `otelSpanOptions` holds an OTel `SpanOptions` instance
+  - `parentOTelSpanContext`
+  - `epochMsFromOTelTimeInput()` converts from an OTel `TimeInput` to a number
+    of milliseconds since the Unix epoch
+
+
+## Design Overview
+
+The OpenTelemetry API is, currently, [these four interfaces](https://github.com/open-telemetry/opentelemetry-js-api/tree/main/src/api/):
+
+- `otel.context.*` - API for managing Context, i.e. what the APM agent calls
+  "run context". More below.
+- `otel.trace.*` - API for manipulating spans, and getting a `Tracer` to
+  create spans. More below.
+- `otel.diag.*` - This is used to hook into internal OpenTelemetry diagnostics,
+  i.e. internal logging. There is very little `otel.diag` usage in
+  `@opentelemetry/api`, more in the SDK. The APM agent hooks up `otel.diag`
+  logging to its own logger **if `logLevel=trace`**.
+- `otel.propagation.*` - Used for abstracting trace-context propagation
+  (reading/writing "traceparent" et al headers) and Baggage handling. This
+  isn't touched by the OTel Bridge, and shouldn't be necessary until either
+  the bridge supports Baggage or TextMapPropagator implementations like
+  `W3CTraceContextPropagator`. The APM agent implements its own internally.
+
+In `Agent#start()`, if the `opentelemetryBridgeEnabled` config is true, then
+a global [`ContextManager`](./OTelContextManager.js) and a global [`TracerProvider`](./OTelTracerProvider.js) are registered, which "enables" the bridge.
+
+From the OTel Bridge spec:
+
+> In order to avoid potentially complex and tedious synchronization issues
+> between OTel and our existing agent implementations, the bridge implementation
+> SHOULD provide an abstraction to have a single "active context" storage.
+
+For this bridge, the agent's `RunContext` class was extended to support the
+small [`interface Context`](https://github.com/open-telemetry/opentelemetry-js-api/blob/v1.1.0/src/context/types.ts#L17-L41)
+API and the agent's run context managers were updated to allow passing in a
+subclass of `RunContext` to use. So the "single active context storage" is
+instances of [`OTelBridgeRunContext`](./OTelBridgeRunContext.js) in the agent's
+usual run context managers.
+
+The way the "active span" is tracked by the OTel API is to call
+`context.setValue(SPAN_KEY, span)`. The `OTelBridgeRunContext` class translates
+calls using `SPAN_KEY` into the API that the agent's RunContext class uses.
+Roughly this:
+
+- `context.setValue(SPAN_KEY, span)` -> `this.enterSpan(span)`
+- `context.getValue(SPAN_KEY)` -> `return new OTelSpan(this.currSpan())`
+
+Otherwise the `*RunContextManager` classes in the agent map very well to the
+OpenTelemetry `ContextManager` interface: the [`OTelContextManager`](./OTelContextManager.js)
+implementation is very straightforward.
+
+The `@opentelemetry/api` supports two ways to create objects that are internally
+implemented and do not call the registered global providers.
+
+1. `otel.trace.wrapSpanContext(...)` supports creating a `NonRecordingSpan` (a
+   class that isn't exported) instance that implements `interface Span`. [This
+   test fixture](../../test/opentelemetry-bridge/fixtures/nonrecordingspan-parent.js)
+   shows a use case. The bridge wraps this in an `OTelBridgeNonRecordingSpan`
+   that implements both OTel `interface Span` and the agent's Transaction API.
+2. `otel.ROOT_CONTEXT` is a singleton object (an internal `BaseContext` class
+   instance) that implements `interface Context` but is not created via any
+   bridge API. That means bridge code cannot rely on a given `context` argument
+   being an instance of its `OTelBridgeRunContext` class.
+   [This test fixtures](../../test/opentelemetry-bridge/fixtures/using-root-context.js)
+   shows an example.
+
+The trickiest part of the bridge is handling these two cases, especially at
+the top of `startSpan` in [`OTelTracer`](./OTelTracer.js)
+
+
+## Limitations / Differences with OpenTelemetry SDK
+
+- The OpenTelemetry SDK defines [SpanLimits](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/sdk.md#span-limits).
+  This OpenTelemetry Bridge differs as follows:
+  - Attribute count is not limited. The OTel SDK defaults to a limit of 128.
+    (To implement this, start at `maybeSetOTelAttr` in "OTelSpan.js".)
+  - Attribute value strings are truncated at 1024 bytes. The OpenTelemetry SDK
+    uses `AttributeValueLengthLimit (Default=Infinity)`.
+    (We could consider using the configurable `longFieldMaxLength` for the
+    attribute value truncation limit, if there is a need.)
+  - Span events are not currently supported by this bridge.
+  - Span link *attributes* are not supported by the bridge (Elastic APM
+    supports span links, but not span link attributes).
+
+- The OpenTelemetry Bridge spec says APM agents
+  ["MAY"](https://github.com/elastic/apm/blob/main/specs/agents/tracing-api-otel.md#attributes-mapping)
+  report OTel span attributes as spad and transaction *labels* if the upstream
+  APM Server is less than version 7.16. This implementation opts *not* to do
+  that. The OTel spec allows a larger range of types for span attributes values
+  than is allowed for "tags" (aka labels) in the APM Server intake API, so some
+  further filtering of attributes would be required.
+
+- There is a semantic difference between this OTel Bridge and the OpenTelemetry
+  SDK with `span.end()` that could impact parent/child relationships of spans.
+  This demonstrates the different:
+
+    ```js
+    const otel = require('@opentelemetry/api')
+    const tracer = otel.trace.getTracer()
+    tracer.startActiveSpan('s1', s1 => {
+      tracer.startActiveSpan('s2', s2 => {
+        s2.end()
+      })
+      s1.end()
+      tracer.startActiveSpan('s3', s3 => {
+        s3.end()
+      })
+    })
+    ```
+
+  With the OTel SDK that will yield:
+
+    ```
+    span s1
+    `- span s2
+    `- span s3
+    ```
+
+  With the Elastic APM agent:
+
+    ```
+    transaction s1
+    `- span s2
+    transaction s3
+    ```
+
+  In current Elastic APM semantics, when a span is ended (e.g. `s1` above) it is
+  *no longer the current/active span in that async context*. This is historical
+  and allows a stack of current spans in sync code, e.g.:
+
+    ```js
+    const t1 = apm.startTransaction('t1')
+    const s2 = apm.startSpan('s2')
+    const s3 = apm.startSpan('s3') // s3 is a child of s2
+    s3.end() // s3 is no longer active (popped off the stack)
+    const s4 = apm.startSpan('s4') // s4 is a child of s2
+    s4.end()
+    s2.end()
+    t1.end()
+    ```
+
+  This semantic difference is not expected to be common, because it is expected
+  that typically OTel API user code will end a span only at the end of its
+  function:
+
+    ```js
+    tracer.startActiveSpan('mySpan', mySpan => {
+      // ...
+      mySpan.end() // .end() only at end of function block
+    })
+    ```
+
+  Note that active span context *is* properly maintained when a new async task
+  is created (e.g. with `setTimeout`, etc.), so the following code produces
+  the expected trace:
+
+    ```js
+    tracer.startActiveSpan('s1', s1 => {
+    setImmediate(() => {
+      tracer.startActiveSpan('s2', s2 => {
+        s2.end()
+      })
+      setTimeout(() => {  // s1 is bound as the active span in this async task.
+        tracer.startActiveSpan('s3', s3 => {
+          s3.end()
+        })
+      }, 100)
+      s1.end()
+    })
+    ```
+
+  If this *does* turn out to be a common issue, the OTel semantics for span.end()
+  can likely be accommodated.
+
+
+

package/lib/opentelemetry-bridge/index.js

@@ -0,0 +1,15 @@
+/*
+ * Copyright Elasticsearch B.V. and other contributors where applicable.
+ * Licensed under the BSD 2-Clause License; you may not use this file except in
+ * compliance with the BSD 2-Clause License.
+ */
+
+'use strict';
+
+const { OTelBridgeRunContext } = require('./OTelBridgeRunContext');
+const { setupOTelBridge } = require('./setup');
+
+module.exports = {
+  OTelBridgeRunContext,
+  setupOTelBridge,
+};

package/lib/opentelemetry-bridge/oblog.js

@@ -0,0 +1,23 @@
+/*
+ * Copyright Elasticsearch B.V. and other contributors where applicable.
+ * Licensed under the BSD 2-Clause License; you may not use this file except in
+ * compliance with the BSD 2-Clause License.
+ */
+
+'use strict';
+
+// This is the (O)penTelemetry (B)ridge (LOG) facility.
+//
+// It is used for development/debugging of the OTel Bridge to emit a log line
+// for (almost) every OTel API call. OTel Bridge implementations typically
+// call `oblog.apicall(...)`. During development/debugging there is a block in
+// "setup.js" that is enabled to turn this logging on. This should always be
+// disabled for any release code.
+
+module.exports = {
+  setApiCallLogFn(logFn) {
+    module.exports.apicall = logFn;
+  },
+
+  apicall() {},
+};

package/lib/opentelemetry-bridge/opentelemetry-core-mini/README.md

@@ -0,0 +1,3 @@
+This holds a very small subset of the `@opentelemetry/core` package, instead of
+having a dependency on it. "Very small" here is just the `TraceState` class, as
+opposed to a ~2.6M dependency.

package/lib/opentelemetry-bridge/opentelemetry-core-mini/internal/validators.js

@@ -0,0 +1,52 @@
+/*
+ * Copyright Elasticsearch B.V. and other contributors where applicable.
+ * Licensed under the BSD 2-Clause License; you may not use this file except in
+ * compliance with the BSD 2-Clause License.
+ */
+
+// Adapted from @opentelemetry/core.
+
+"use strict";
+/*
+ * Copyright The OpenTelemetry Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+const VALID_KEY_CHAR_RANGE = '[_0-9a-z-*/]';
+const VALID_KEY = `[a-z]${VALID_KEY_CHAR_RANGE}{0,255}`;
+const VALID_VENDOR_KEY = `[a-z0-9]${VALID_KEY_CHAR_RANGE}{0,240}@[a-z]${VALID_KEY_CHAR_RANGE}{0,13}`;
+const VALID_KEY_REGEX = new RegExp(`^(?:${VALID_KEY}|${VALID_VENDOR_KEY})$`);
+const VALID_VALUE_BASE_REGEX = /^[ -~]{0,255}[!-~]$/;
+const INVALID_VALUE_COMMA_EQUAL_REGEX = /,|=/;
+/**
+ * Key is opaque string up to 256 characters printable. It MUST begin with a
+ * lowercase letter, and can only contain lowercase letters a-z, digits 0-9,
+ * underscores _, dashes -, asterisks *, and forward slashes /.
+ * For multi-tenant vendor scenarios, an at sign (@) can be used to prefix the
+ * vendor name. Vendors SHOULD set the tenant ID at the beginning of the key.
+ * see https://www.w3.org/TR/trace-context/#key
+ */
+function validateKey(key) {
+    return VALID_KEY_REGEX.test(key);
+}
+exports.validateKey = validateKey;
+/**
+ * Value is opaque string up to 256 characters printable ASCII RFC0020
+ * characters (i.e., the range 0x20 to 0x7E) except comma , and =.
+ */
+function validateValue(value) {
+    return (VALID_VALUE_BASE_REGEX.test(value) &&
+        !INVALID_VALUE_COMMA_EQUAL_REGEX.test(value));
+}
+exports.validateValue = validateValue;
+//# sourceMappingURL=validators.js.map

package/lib/opentelemetry-bridge/opentelemetry-core-mini/trace/TraceState.js

@@ -0,0 +1,109 @@
+/*
+ * Copyright Elasticsearch B.V. and other contributors where applicable.
+ * Licensed under the BSD 2-Clause License; you may not use this file except in
+ * compliance with the BSD 2-Clause License.
+ */
+
+// Adapted from @opentelemetry/core.
+
+"use strict";
+/*
+ * Copyright The OpenTelemetry Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+const validators_1 = require("../internal/validators");
+const MAX_TRACE_STATE_ITEMS = 32;
+const MAX_TRACE_STATE_LEN = 512;
+const LIST_MEMBERS_SEPARATOR = ',';
+const LIST_MEMBER_KEY_VALUE_SPLITTER = '=';
+/**
+ * TraceState must be a class and not a simple object type because of the spec
+ * requirement (https://www.w3.org/TR/trace-context/#tracestate-field).
+ *
+ * Here is the list of allowed mutations:
+ * - New key-value pair should be added into the beginning of the list
+ * - The value of any key can be updated. Modified keys MUST be moved to the
+ * beginning of the list.
+ */
+class TraceState {
+    constructor(rawTraceState) {
+        this._internalState = new Map();
+        if (rawTraceState)
+            this._parse(rawTraceState);
+    }
+    set(key, value) {
+        // TODO: Benchmark the different approaches(map vs list) and
+        // use the faster one.
+        const traceState = this._clone();
+        if (traceState._internalState.has(key)) {
+            traceState._internalState.delete(key);
+        }
+        traceState._internalState.set(key, value);
+        return traceState;
+    }
+    unset(key) {
+        const traceState = this._clone();
+        traceState._internalState.delete(key);
+        return traceState;
+    }
+    get(key) {
+        return this._internalState.get(key);
+    }
+    serialize() {
+        return this._keys()
+            .reduce((agg, key) => {
+            agg.push(key + LIST_MEMBER_KEY_VALUE_SPLITTER + this.get(key));
+            return agg;
+        }, [])
+            .join(LIST_MEMBERS_SEPARATOR);
+    }
+    _parse(rawTraceState) {
+        if (rawTraceState.length > MAX_TRACE_STATE_LEN)
+            return;
+        this._internalState = rawTraceState
+            .split(LIST_MEMBERS_SEPARATOR)
+            .reverse() // Store in reverse so new keys (.set(...)) will be placed at the beginning
+            .reduce((agg, part) => {
+            const listMember = part.trim(); // Optional Whitespace (OWS) handling
+            const i = listMember.indexOf(LIST_MEMBER_KEY_VALUE_SPLITTER);
+            if (i !== -1) {
+                const key = listMember.slice(0, i);
+                const value = listMember.slice(i + 1, part.length);
+                if ((0, validators_1.validateKey)(key) && (0, validators_1.validateValue)(value)) {
+                    agg.set(key, value);
+                }
+                else {
+                    // TODO: Consider to add warning log
+                }
+            }
+            return agg;
+        }, new Map());
+        // Because of the reverse() requirement, trunc must be done after map is created
+        if (this._internalState.size > MAX_TRACE_STATE_ITEMS) {
+            this._internalState = new Map(Array.from(this._internalState.entries())
+                .reverse() // Use reverse same as original tracestate parse chain
+                .slice(0, MAX_TRACE_STATE_ITEMS));
+        }
+    }
+    _keys() {
+        return Array.from(this._internalState.keys()).reverse();
+    }
+    _clone() {
+        const traceState = new TraceState();
+        traceState._internalState = new Map(this._internalState);
+        return traceState;
+    }
+}
+exports.TraceState = TraceState;
+//# sourceMappingURL=TraceState.js.map