weflayr 0.16.0 → 0.20.2

package/src/otel/exporter.js

@@ -0,0 +1,113 @@
+'use strict';
+
+const retry = require('async-retry');
+const { OTLPTraceExporter } = require('@opentelemetry/exporter-trace-otlp-http');
+
+const { debug } = require('../logger');
+
+// OTLP-spec retryable statuses: rate-limit + transient server errors.
+const _RETRYABLE_STATUS = new Set([429, 502, 503, 504]);
+
+function _isNonRetryable(err) {
+  // Tells async-retry's `bail` whether to give up: bail on 4xx (other than
+  // 429); retry on retryable statuses and on transport errors (no status).
+  const status = err?.exportResult?.error?.code;
+  return status !== undefined && !_RETRYABLE_STATUS.has(status);
+}
+
+function _formatFailure(result, url) {
+  const err = result?.error;
+  const status = err?.code;
+  const body = typeof err?.data === 'string' ? err.data.slice(0, 200) : undefined;
+  const message = err?.message || String(err) || 'unknown error';
+  let hint = '';
+  if (status === 401 || status === 403) {
+    hint = ' Check your apiKey / WEFLAYR_API_KEY.';
+  } else if (status === 404) {
+    hint = ' Check the baseUrl is correct.';
+  } else if (!status && /ECONN|ENOTFOUND|timeout/i.test(message)) {
+    hint = ' The endpoint is unreachable — check baseUrl and network.';
+  }
+  return (
+    `Weflayr: failed to export telemetry to ${url}` +
+    (status ? ` (HTTP ${status})` : '') +
+    `: ${message}.${hint}` +
+    (body ? ` Response: ${body}` : '')
+  );
+}
+
+// Wrap a callback-style OTel exporter `export(spans, cb)` with retry. Retries
+// transport errors + retryable HTTP statuses; bails on other 4xx.
+function _exportWithRetry(originalExport, { maxRetries, maxRetryMs }) {
+  return (spans, resultCallback) => {
+    retry(
+      async (bail) => {
+        const result = await new Promise((resolve) => originalExport(spans, resolve));
+        if (result?.code === 0) return result;
+        const err = new Error(result?.error?.message || 'export failed');
+        err.exportResult = result;
+        if (_isNonRetryable(err)) {
+          bail(err);
+          return;
+        }
+        throw err;
+      },
+      { retries: maxRetries - 1, minTimeout: 50, maxRetryTime: maxRetryMs, factor: 2 }
+    )
+      .then((result) => resultCallback(result))
+      .catch((err) => resultCallback(err.exportResult || { code: 1, error: err }));
+  };
+}
+
+function buildExporter({
+  baseUrl,
+  apiKey,
+  timeoutMs = 5000,
+  warnOnExportError = true,
+  maxRetries = 2,
+  maxRetryMs = 1000,
+}) {
+  const url = `${baseUrl.replace(/\/$/, '')}/`;
+  const exporter = new OTLPTraceExporter({
+    url,
+    headers: {
+      Authorization: `Bearer ${apiKey}`,
+    },
+    timeoutMillis: timeoutMs,
+  });
+  const originalExport = exporter.export.bind(exporter);
+  const wrappedExport = _exportWithRetry(originalExport, { maxRetries, maxRetryMs });
+  let warned = false;
+  exporter.export = (spans, resultCallback) => {
+    const start = Date.now();
+    debug('exporter.export: posting count=%d', spans.length);
+    wrappedExport(spans, (result) => {
+      const ms = Date.now() - start;
+      if (result && result.code === 0) {
+        debug('exporter.export: ok count=%d elapsed_ms=%d', spans.length, ms);
+      } else {
+        debug(
+          'exporter.export: FAIL count=%d elapsed_ms=%d code=%s error=%s',
+          spans.length,
+          ms,
+          result?.code,
+          result?.error?.message || result?.error || '(none)'
+        );
+        // Surface the first failure on stderr so users notice broken setups
+        // even without NODE_DEBUG=weflayr. Stay quiet after — repeated warns
+        // on a misconfigured key would just spam.
+        if (warnOnExportError && !warned) {
+          warned = true;
+          // console.warn writes to stderr synchronously. process.emitWarning
+          // is queued for the next tick, so a caller doing process.exit() from
+          // their error handler races past it and the warning is lost.
+          console.warn(`[weflayr] ${_formatFailure(result, url)}`);
+        }
+      }
+      resultCallback(result);
+    });
+  };
+  return exporter;
+}
+
+module.exports = { buildExporter, _exportWithRetry, _RETRYABLE_STATUS };

package/src/otel/openai-streaming-usage.js

@@ -0,0 +1,60 @@
+'use strict';
+
+// Backfill token usage onto streamed OpenAI spans.
+//
+// @traceloop/instrumentation-openai (the OpenAI OTel instrumentor we load for
+// the `openai` SDK) does not record token usage for streamed calls: its stream
+// handler accumulates `choices[].delta` but never reads the final usage chunk
+// that OpenAI sends when the request sets `stream_options: { include_usage:
+// true }`. Non-streaming calls work because OpenAI returns `usage` in the
+// response body, which the instrumentor reads directly. The Python OpenLLMetry
+// instrumentor does read the streamed usage, so this gap is JS-only.
+//
+// Read `usage` from the streamed chunks. The instrumentor's streaming handler hands us the span
+// and ends it only after its chunk loop, so when the usage chunk arrives the
+// span is still open and we set the same `gen_ai.usage.*` attributes the
+// instrumentor sets for non-streaming calls.
+
+const USAGE_INPUT_TOKENS_ATTR = 'gen_ai.usage.input_tokens';
+const USAGE_OUTPUT_TOKENS_ATTR = 'gen_ai.usage.output_tokens';
+const USAGE_TOTAL_TOKENS_ATTR = 'gen_ai.usage.total_tokens';
+
+function _setUsageAttributes(span, usage) {
+  if (typeof usage.prompt_tokens === 'number') {
+    span.setAttribute(USAGE_INPUT_TOKENS_ATTR, usage.prompt_tokens);
+  }
+  if (typeof usage.completion_tokens === 'number') {
+    span.setAttribute(USAGE_OUTPUT_TOKENS_ATTR, usage.completion_tokens);
+  }
+  if (typeof usage.total_tokens === 'number') {
+    span.setAttribute(USAGE_TOTAL_TOKENS_ATTR, usage.total_tokens);
+  }
+}
+
+/**
+ * Wrap the OpenAI instrumentor's streaming handler so streamed spans carry
+ * token usage. No-op if the instrumentor's internals have changed shape — the
+ * worst case is streamed spans without token counts, never a crash.
+ */
+function patchOpenAIStreamingUsage(instrumentation) {
+  const originalStreamingWrap = instrumentation._streamingWrapPromise;
+  if (typeof originalStreamingWrap !== 'function') return;
+
+  instrumentation._streamingWrapPromise = function streamingWrapWithUsage(streamArgs) {
+    const span = streamArgs && streamArgs.span;
+    const wrappedStream = originalStreamingWrap.call(this, streamArgs);
+    if (!span) return wrappedStream;
+
+    return (async function* backfillUsage() {
+      for await (const chunk of wrappedStream) {
+        const usage = chunk && chunk.usage;
+        if (usage && span.isRecording()) {
+          _setUsageAttributes(span, usage);
+        }
+        yield chunk;
+      }
+    })();
+  };
+}
+
+module.exports = { patchOpenAIStreamingUsage };

package/src/otel/propagation.js

@@ -0,0 +1,119 @@
+// Copyright 2024 Langfuse GmbH
+// Licensed under the MIT License.
+// Original source: https://github.com/langfuse/langfuse-js/blob/main/packages/core/src/propagation.ts
+//
+// Modifications copyright 2026 Weflayr
+// This file has been modified from its original form:
+//   - Translated from TypeScript to JavaScript
+//   - Replaced Langfuse's fixed schema with Weflayr's structured metadata
+//     (featureName, customerId, providerName, extraTags) plus an
+//     auto-generated per-call uuid
+//   - Removed asBaggage cross-process propagation (not needed yet)
+//   - Removed experiment framework keys
+//   - Structured fields are written under stable `weflayr.*` span attribute
+//     keys; extraTags entries are written verbatim
+//
+// See LICENSE-MIT in the package root for the full license text.
+
+'use strict';
+
+const { randomUUID } = require('node:crypto');
+const { context: otelContext, trace, createContextKey } = require('@opentelemetry/api');
+
+const WEFLAYR_METADATA_CONTEXT_KEY = createContextKey('weflayr_metadata');
+
+const FEATURE_NAME_ATTR = 'weflayr.feature_name';
+const CUSTOMER_ID_ATTR = 'weflayr.customer_id';
+const PROVIDER_NAME_ATTR = 'weflayr.provider_name';
+const UUID_ATTR = 'weflayr.uuid';
+// Prefix for user-supplied `extraTags` so downstream normalizers can pick
+// them out without colliding with instrumentor-set `gen_ai.*` attributes.
+const EXTRA_TAG_PREFIX = 'weflayr.tag.';
+
+function getMergedMetadataFromContext(parentContext) {
+  const ctx = parentContext ?? otelContext.active();
+  const existing = ctx.getValue(WEFLAYR_METADATA_CONTEXT_KEY);
+  return existing && typeof existing === 'object' ? { ...existing } : {};
+}
+
+function _buildAttributes({ featureName, customerId, providerName, extraTags, spanUuid }) {
+  const attributes = {
+    [FEATURE_NAME_ATTR]: featureName,
+    [CUSTOMER_ID_ATTR]: customerId,
+    [UUID_ATTR]: spanUuid,
+  };
+  for (const [key, value] of Object.entries(extraTags)) {
+    attributes[`${EXTRA_TAG_PREFIX}${key}`] = value;
+  }
+  if (providerName !== undefined && providerName !== null) {
+    attributes[PROVIDER_NAME_ATTR] = providerName;
+  }
+  return attributes;
+}
+
+/**
+ * Attach Weflayr metadata to every LLM span created inside this scope.
+ *
+ * Callable form: `propagateMetadata(options, fn)` runs `fn` immediately.
+ * Decorator form: `propagateMetadata(options)` returns a wrapper usable as a
+ * function-decorator (`@propagateMetadata(...)` on class methods) or as a
+ * plain `wrap(fn)` -> wrappedFn helper. Each invocation of the wrapped
+ * function mints a fresh `uuid`, matching the callable form's "one uuid per
+ * propagateMetadata call" contract.
+ */
+function propagateMetadata(options, fn) {
+  if (typeof fn === 'function') {
+    return _runWithMetadata(options, fn);
+  }
+
+  return function decorator(target, key, descriptor) {
+    if (descriptor && typeof descriptor.value === 'function') {
+      const original = descriptor.value;
+      descriptor.value = function wrapped(...args) {
+        return _runWithMetadata(options, () => original.apply(this, args));
+      };
+      return descriptor;
+    }
+    if (typeof target === 'function') {
+      return function wrapped(...args) {
+        return _runWithMetadata(options, () => target.apply(this, args));
+      };
+    }
+    return target;
+  };
+}
+
+function _runWithMetadata(options, fn) {
+  const { featureName, customerId, providerName, extraTags } = options;
+  const attributes = _buildAttributes({
+    featureName,
+    customerId,
+    providerName,
+    extraTags: extraTags ?? {},
+    spanUuid: randomUUID().replace(/-/g, ''),
+  });
+
+  const parent = otelContext.active();
+  const merged = { ...getMergedMetadataFromContext(parent), ...attributes };
+  const newContext = parent.setValue(WEFLAYR_METADATA_CONTEXT_KEY, merged);
+
+  const activeSpan = trace.getActiveSpan();
+  if (activeSpan && activeSpan.isRecording && activeSpan.isRecording()) {
+    for (const [k, v] of Object.entries(attributes)) {
+      activeSpan.setAttribute(k, v);
+    }
+  }
+
+  return otelContext.with(newContext, fn);
+}
+
+module.exports = {
+  propagateMetadata,
+  getMergedMetadataFromContext,
+  WEFLAYR_METADATA_CONTEXT_KEY,
+  FEATURE_NAME_ATTR,
+  CUSTOMER_ID_ATTR,
+  PROVIDER_NAME_ATTR,
+  UUID_ATTR,
+  EXTRA_TAG_PREFIX,
+};

package/src/otel/span-filter.js

@@ -0,0 +1,73 @@
+// Copyright 2024 Langfuse GmbH
+// Licensed under the MIT License.
+// Original source: https://github.com/langfuse/langfuse-js/blob/main/packages/otel/src/span-filter.ts
+//
+// Modifications copyright 2026 Weflayr
+// This file has been modified from its original form:
+//   - Translated from TypeScript to JavaScript
+//   - Dropped the LANGFUSE_TRACER_NAME special case (we have no SDK-internal tracer)
+//   - Dropped isLangfuseSpan
+//
+// See LICENSE-MIT in the package root for the full license text.
+
+'use strict';
+
+const KNOWN_LLM_INSTRUMENTATION_SCOPE_PREFIXES = [
+  'agent_framework',
+  'ai',
+  'haystack',
+  'langsmith',
+  'litellm',
+  'openinference',
+  'opentelemetry.instrumentation.anthropic',
+  'opentelemetry.instrumentation.aws_bedrock',
+  'opentelemetry.instrumentation.bedrock',
+  'opentelemetry.instrumentation.gemini',
+  'opentelemetry.instrumentation.google_genai',
+  'opentelemetry.instrumentation.google_generativeai',
+  'opentelemetry.instrumentation.openai',
+  'opentelemetry.instrumentation.openai_v2',
+  'opentelemetry.instrumentation.vertex_ai',
+  'opentelemetry.instrumentation.vertexai',
+  'strands-agents',
+  'vllm',
+  '@traceloop/instrumentation-openai',
+  '@traceloop/instrumentation-anthropic',
+  '@traceloop/instrumentation-bedrock',
+  '@traceloop/instrumentation-azure',
+  '@traceloop/instrumentation-cohere',
+  '@traceloop/instrumentation-together',
+  '@traceloop/instrumentation-vertexai',
+  '@traceloop/instrumentation-google-generativeai',
+  '@traceloop/instrumentation-langchain',
+  '@traceloop/instrumentation-llamaindex',
+  '@traceloop/instrumentation-pinecone',
+  '@traceloop/instrumentation-chromadb',
+  '@traceloop/instrumentation-qdrant',
+  '@traceloop/instrumentation-mcp',
+];
+
+const EXACT_LLM_INSTRUMENTATION_SCOPES = new Set(['ai']);
+
+function isGenAISpan(span) {
+  return Object.keys(span.attributes).some((key) => key.startsWith('gen_ai.'));
+}
+
+function isKnownLLMInstrumentor(span) {
+  const scope = span.instrumentationScope.name;
+  return KNOWN_LLM_INSTRUMENTATION_SCOPE_PREFIXES.some(
+    (prefix) =>
+      scope === prefix ||
+      (!EXACT_LLM_INSTRUMENTATION_SCOPES.has(prefix) && scope.startsWith(`${prefix}.`))
+  );
+}
+
+function isDefaultExportSpan(span) {
+  return isGenAISpan(span) || isKnownLLMInstrumentor(span);
+}
+
+module.exports = {
+  isGenAISpan,
+  isKnownLLMInstrumentor,
+  isDefaultExportSpan,
+};

package/src/otel/span-processor.js

@@ -0,0 +1,123 @@
+// Copyright 2024 Langfuse GmbH
+// Licensed under the MIT License.
+// Original source: https://github.com/langfuse/langfuse-js/blob/main/packages/otel/src/span-processor.ts
+//
+// Modifications copyright 2026 Weflayr
+// This file has been modified from its original form:
+//   - Translated from TypeScript to JavaScript
+//   - Removed MediaService integration (no media upload support yet)
+//   - Removed LangfuseAPIClient / app-root marker logic (not used)
+//   - Removed Langfuse-specific span attributes (TRACE_INPUT/OUTPUT/METADATA, IS_APP_ROOT, ENVIRONMENT, RELEASE)
+//   - Mask hook now receives the full flat attribute bag, not a {data} envelope, and runs synchronously
+//   - default_tags are applied as span attributes in onStart
+//   - propagated tags come from Weflayr's tag bag (see propagation.js), not Langfuse's typed schema
+//
+// See LICENSE-MIT in the package root for the full license text.
+
+'use strict';
+
+const { SpanStatusCode } = require('@opentelemetry/api');
+const { BatchSpanProcessor, SimpleSpanProcessor } = require('@opentelemetry/sdk-trace-base');
+const { EXTRA_TAG_PREFIX, getMergedMetadataFromContext } = require('./propagation');
+const { isDefaultExportSpan, isKnownLLMInstrumentor } = require('./span-filter');
+const { debug } = require('../logger');
+
+class WeflayrSpanProcessor {
+  constructor({ exporter, exportMode = 'batch', defaultTags = {}, mask, shouldExportSpan } = {}) {
+    if (!exporter) {
+      throw new Error('WeflayrSpanProcessor: exporter is required');
+    }
+    this._delegate =
+      exportMode === 'immediate'
+        ? new SimpleSpanProcessor(exporter)
+        : new BatchSpanProcessor(exporter);
+    this._defaultTags = defaultTags;
+    this._mask = mask;
+    this._shouldExportSpan = shouldExportSpan ?? isDefaultExportSpan;
+    // LLM spans we've started but not yet seen end. On forceFlush we end any
+    // leftovers with ERROR status — covers cases like openllmetry's anthropic
+    // streaming wrapper, which leaks the span when the underlying call
+    // rejects. Generic across providers; no per-provider patching needed.
+    this._openLlmSpans = new Set();
+  }
+
+  onStart(span, parentContext) {
+    for (const [k, v] of Object.entries(this._defaultTags)) {
+      span.setAttribute(`${EXTRA_TAG_PREFIX}${k}`, v);
+    }
+    const propagated = getMergedMetadataFromContext(parentContext);
+    for (const [k, v] of Object.entries(propagated)) {
+      span.setAttribute(k, v);
+    }
+    if (isKnownLLMInstrumentor(span)) {
+      this._openLlmSpans.add(span);
+    }
+    debug(
+      'span start: name=%s defaultTags=%d propagatedMetadata=%d',
+      span.name,
+      Object.keys(this._defaultTags).length,
+      Object.keys(propagated).length
+    );
+    return this._delegate.onStart(span, parentContext);
+  }
+
+  onEnd(span) {
+    this._openLlmSpans.delete(span);
+    try {
+      if (!this._shouldExportSpan(span)) {
+        debug(
+          'span end: filtered out name=%s scope=%s',
+          span.name,
+          span.instrumentationScope?.name
+        );
+        return;
+      }
+    } catch {
+      return;
+    }
+    debug('span end: exporting name=%s scope=%s', span.name, span.instrumentationScope?.name);
+
+    if (this._mask) {
+      try {
+        const masked = this._mask(span.attributes);
+        if (masked && masked !== span.attributes) {
+          for (const k of Object.keys(span.attributes)) delete span.attributes[k];
+          Object.assign(span.attributes, masked);
+        }
+      } catch {
+        for (const k of Object.keys(span.attributes)) delete span.attributes[k];
+      }
+    }
+
+    return this._delegate.onEnd(span);
+  }
+
+  async forceFlush() {
+    this._endOrphanedLlmSpans();
+    return this._delegate.forceFlush();
+  }
+
+  _endOrphanedLlmSpans() {
+    const orphans = [...this._openLlmSpans];
+    this._openLlmSpans.clear();
+    for (const span of orphans) {
+      try {
+        if (typeof span.isRecording === 'function' && !span.isRecording()) continue;
+        span.setStatus({
+          code: SpanStatusCode.ERROR,
+          message: 'weflayr: span did not complete before flush',
+        });
+        span.end();
+        debug('forceFlush: ended orphaned LLM span name=%s', span.name);
+      } catch (err) {
+        debug('forceFlush: failed to end orphan span: %s', err?.message || err);
+      }
+    }
+  }
+
+  shutdown() {
+    return this._delegate.shutdown();
+  }
+}
+
+module.exports = { WeflayrSpanProcessor };

package/src/setup.js

@@ -0,0 +1,168 @@
+'use strict';
+
+const { trace } = require('@opentelemetry/api');
+const { NodeTracerProvider } = require('@opentelemetry/sdk-trace-node');
+const { resourceFromAttributes } = require('@opentelemetry/resources');
+
+const { buildExporter } = require('./otel/exporter');
+const { WeflayrSpanProcessor } = require('./otel/span-processor');
+const { debug } = require('./logger');
+const { version: SDK_VERSION } = require('../package.json');
+
+const SDK_LANGUAGE = 'javascript';
+const DEFAULT_BASE_URL = 'https://api.weflayr.com';
+const CONTENT_CAPTURE_ENV = 'OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT';
+
+const _state = {
+  tracerProvider: null,
+  processor: null,
+  beforeExitListener: null,
+};
+
+// `trace.getTracerProvider()` returns a ProxyTracerProvider that forwards to
+// whoever called `.register()` last. Unwrap it to reach the real provider.
+function _unwrapTracerProvider(p) {
+  if (p && typeof p.getDelegate === 'function') {
+    return p.getDelegate();
+  }
+  return p;
+}
+
+// `NodeTracerProvider` 2.x dropped the public `addSpanProcessor` API —
+// processors are construction-time only. To attach to a provider somebody
+// else owns, we splice into the internal MultiSpanProcessor. This matches
+// the actual public OTel JS guidance for composing post-construction.
+function _attachProcessorToExistingProvider(provider, processor) {
+  if (!provider) return false;
+  if (typeof provider.addSpanProcessor === 'function') {
+    provider.addSpanProcessor(processor);
+    return true;
+  }
+  const multi = provider._activeSpanProcessor;
+  if (multi && Array.isArray(multi._spanProcessors)) {
+    multi._spanProcessors.push(processor);
+    return true;
+  }
+  return false;
+}
+
+/**
+ * Configure the Weflayr SDK.
+ *
+ * Call once per process, before `autoInstrument`. For per-request or
+ * per-tenant data in a long-running server use `propagateMetadata(...)` —
+ * it stores metadata in OTel's `Context` (built on AsyncLocalStorage) and
+ * isolates correctly across concurrent requests.
+ *
+ * Calling `setup` again is supported but replaces the previous
+ * configuration: the prior processor is shut down and detached so we never
+ * stack exporters (which would otherwise double-export every span and leak
+ * HTTP pools).
+ */
+function setup(options) {
+  const opts = options || {};
+  const apiKey = opts.apiKey || process.env.WEFLAYR_API_KEY;
+  if (typeof apiKey !== 'string' || !apiKey) {
+    throw new Error(
+      'weflayr.setup: `apiKey` is required (pass it explicitly or set WEFLAYR_API_KEY)'
+    );
+  }
+  options = { ...opts, apiKey };
+
+  if (options.captureMessageContent === false) {
+    process.env[CONTENT_CAPTURE_ENV] = 'false';
+  } else if (options.captureMessageContent === true) {
+    process.env[CONTENT_CAPTURE_ENV] = 'true';
+  }
+
+  _detachPreviousWeflayrProcessor();
+
+  const baseUrl = options.baseUrl || process.env.WEFLAYR_BASE_URL || DEFAULT_BASE_URL;
+
+  const exporter = buildExporter({
+    baseUrl,
+    apiKey: options.apiKey,
+    warnOnExportError: options.warnOnExportError !== false,
+  });
+
+  const processor = new WeflayrSpanProcessor({
+    exporter,
+    exportMode: options.exportMode || 'batch',
+    defaultTags: options.defaultTags || {},
+    mask: options.mask,
+  });
+
+  // Adopt an existing TracerProvider when there is one — e.g. the user already
+  // configured Datadog/Honeycomb/OTel, or called weflayr.setup() before.
+  // provider.register() silently refuses to override the proxy if another
+  // provider is already wired in, so naively creating a new provider would
+  // leave our processor attached to a dead one and we'd drop every LLM span.
+  const currentTracerProvider = _unwrapTracerProvider(trace.getTracerProvider());
+  let tracerProvider;
+  if (_attachProcessorToExistingProvider(currentTracerProvider, processor)) {
+    tracerProvider = currentTracerProvider;
+  } else {
+    tracerProvider = new NodeTracerProvider({
+      resource: resourceFromAttributes({
+        sdk_version: SDK_VERSION,
+        sdk_language: SDK_LANGUAGE,
+      }),
+      spanProcessors: [processor],
+    });
+    tracerProvider.register();
+  }
+
+  // beforeExit fires when the event loop empties on a clean exit, giving us a
+  // last async tick to drain buffered spans. It does NOT fire on process.exit()
+  // or uncaught fatals — callers handling those paths still need to call flush
+  // explicitly (e.g. in a finally) for the OTLP HTTP request to complete.
+  if (!_state.beforeExitListener) {
+    _state.beforeExitListener = async () => {
+      try {
+        await flush();
+      } catch {
+        // best-effort: process is already winding down.
+      }
+    };
+    process.on('beforeExit', _state.beforeExitListener);
+  }
+
+  _state.tracerProvider = tracerProvider;
+  _state.processor = processor;
+  debug(
+    'setup ready: baseUrl=%s exportMode=%s defaultTags=%d',
+    baseUrl,
+    options.exportMode || 'batch',
+    Object.keys(options.defaultTags || {}).length
+  );
+}
+
+async function flush() {
+  if (!_state.processor) return;
+  debug('flush: forcing exporter flush');
+  await _state.processor.forceFlush();
+}
+
+// Shut down + detach the prior weflayr processor — idempotency for setup().
+// Without this, calling setup() twice (key rotation, hot reload, tests that
+// reconfigure) would leave the first processor wired in alongside the new
+// one, double-exporting every span and leaking exporter HTTP pools.
+function _detachPreviousWeflayrProcessor() {
+  const previousProcessor = _state.processor;
+  if (!previousProcessor) return;
+  const tp = _state.tracerProvider;
+  const multi = tp && tp._activeSpanProcessor;
+  if (multi && Array.isArray(multi._spanProcessors)) {
+    multi._spanProcessors = multi._spanProcessors.filter(
+      (processor) => processor !== previousProcessor
+    );
+  }
+  try {
+    previousProcessor.shutdown();
+  } catch {
+    // best-effort cleanup.
+  }
+  _state.processor = null;
+}
+
+module.exports = { setup, flush, _state };