apitally 0.25.7 → 1.0.0-alpha.1

package/dist/spanExporter.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/spanExporter.ts"],"sourcesContent":["import type { Attributes } from \"@opentelemetry/api\";\nimport { SpanKind } from \"@opentelemetry/api\";\nimport type { ExportResult } from \"@opentelemetry/core\";\nimport { ProtobufTraceSerializer } from \"@opentelemetry/otlp-transformer\";\nimport { type Resource, resourceFromAttributes } from \"@opentelemetry/resources\";\nimport type { ReadableSpan, SpanExporter } from \"@opentelemetry/sdk-trace-base\";\nimport { BODY_TOO_LARGE, BODY_TOO_LARGE_BUFFER, MAX_BODY_SIZE } from \"./bodyCapture.js\";\nimport { type BodyMaskingCallback, DEFAULT_ENV } from \"./config.js\";\nimport { serializeInChunksToSpool } from \"./exportSerialization.js\";\nimport { logWarning } from \"./logger.js\";\nimport { REDACTED, type Redaction } from \"./redaction.js\";\nimport { copySpan, type SpanCopy } from \"./spanProcessor.js\";\nimport type { Spool } from \"./spool.js\";\n\nconst QUERY_ATTRIBUTES = new Set([\"url.query\", \"url.full\", \"http.target\", \"http.url\"]);\nconst REQUEST_HEADER_ATTRIBUTE_PREFIX = \"http.request.header.\";\nconst RESPONSE_HEADER_ATTRIBUTE_PREFIX = \"http.response.header.\";\nconst DEPLOYMENT_ENVIRONMENT_NAME = \"deployment.environment.name\";\nconst SERVICE_INSTANCE_ID = \"service.instance.id\";\n\nexport interface ApitallySpanExporterOptions {\n  redaction: Redaction;\n  env: string;\n  instanceId: string;\n  spool: Spool;\n  maskRequestBody?: BodyMaskingCallback;\n  maskResponseBody?: BodyMaskingCallback;\n}\n\n// Export copies receive transport attributes, captured data, and redaction\n// without mutating the original spans.\nexport class ApitallySpanExporter implements SpanExporter {\n  private readonly redaction: Redaction;\n  private readonly env: string;\n  private readonly instanceId: string;\n  private readonly spool: Spool;\n  private readonly maskRequestBody?: BodyMaskingCallback;\n  private readonly maskResponseBody?: BodyMaskingCallback;\n\n  constructor(options: ApitallySpanExporterOptions) {\n    this.redaction = options.redaction;\n    this.env = options.env;\n    this.instanceId = options.instanceId;\n    this.spool = options.spool;\n    this.maskRequestBody = options.maskRequestBody;\n    this.maskResponseBody = options.maskResponseBody;\n  }\n\n  export(spans: ReadableSpan[], resultCallback: (result: ExportResult) => void): void {\n    // Rewritten resources are shared across the batch: the serializer groups\n    // resourceSpans by object identity, never by attribute equality.\n    const rewrittenResources = new Map<Resource, Resource>();\n    const exportCopies: ReadableSpan[] = [];\n    for (const span of spans) {\n      try {\n        exportCopies.push(this.buildExportCopy(span, rewrittenResources));\n      } catch {\n        // A span that failed redaction must never leave the process.\n        logWarning(\"Failed to prepare a span for export to Apitally, so the span was dropped\");\n      }\n    }\n    serializeInChunksToSpool(\n      exportCopies,\n      (chunk) => ProtobufTraceSerializer.serializeRequest(chunk),\n      this.spool,\n      \"traces\",\n      resultCallback,\n    );\n  }\n\n  forceFlush(): Promise<void> {\n    return Promise.resolve();\n  }\n\n  shutdown(): Promise<void> {\n    return Promise.resolve();\n  }\n\n  private buildExportCopy(\n    span: ReadableSpan,\n    rewrittenResources: Map<Resource, Resource>,\n  ): ReadableSpan {\n    const data = (span as SpanCopy).apitallyData;\n    const stash = data?.stash;\n    // The record is applied last: a transport-observed value wins over anything\n    // the producing instrumentation set for the same key.\n    const attributes: Record<string, unknown> = {\n      ...span.attributes,\n      ...data?.record?.attributes,\n    };\n    this.redactQueryAndHeaderAttributes(attributes);\n    if (stash?.requestHeaders) {\n      writeCapturedHeaderAttributes(\n        attributes,\n        REQUEST_HEADER_ATTRIBUTE_PREFIX,\n        stash.requestHeaders,\n        this.redaction,\n      );\n    }\n    if (stash?.responseHeaders) {\n      writeCapturedHeaderAttributes(\n        attributes,\n        RESPONSE_HEADER_ATTRIBUTE_PREFIX,\n        stash.responseHeaders,\n        this.redaction,\n      );\n    }\n    const copy = copySpan(span);\n    copy.attributes = attributes as Attributes;\n    copy.resource = this.resolveExportResource(span.resource, rewrittenResources);\n    if (data?.demoteToInternal) {\n      copy.kind = SpanKind.INTERNAL;\n    }\n    if (stash && (stash.requestBody !== undefined || stash.responseBody !== undefined)) {\n      // Mask callbacks receive the redacted export copy with captured headers\n      // attached, but without body attributes.\n      const snapshot = copySpan(copy);\n      snapshot.attributes = { ...attributes } as Attributes;\n      if (stash.requestBody !== undefined) {\n        attributes[\"apitally.request.body\"] = this.processBody(\n          snapshot,\n          stash.requestBody,\n          this.maskRequestBody,\n          \"maskRequestBody\",\n        );\n      }\n      if (stash.responseBody !== undefined) {\n        attributes[\"apitally.response.body\"] = this.processBody(\n          snapshot,\n          stash.responseBody,\n          this.maskResponseBody,\n          \"maskResponseBody\",\n        );\n      }\n    }\n    return copy;\n  }\n\n  // OpenTelemetry HTTP instrumentations leave query and header attributes raw.\n  // Both legacy and stable HTTP attribute names are redacted before export.\n  private redactQueryAndHeaderAttributes(attributes: Record<string, unknown>): void {\n    for (const [key, value] of Object.entries(attributes)) {\n      if (QUERY_ATTRIBUTES.has(key) && typeof value === \"string\") {\n        attributes[key] = this.redaction.redactQueryParams(value, key === \"url.query\");\n      } else if (\n        key.startsWith(REQUEST_HEADER_ATTRIBUTE_PREFIX) ||\n        key.startsWith(RESPONSE_HEADER_ATTRIBUTE_PREFIX)\n      ) {\n        const headerName = key.slice(\n          key.startsWith(REQUEST_HEADER_ATTRIBUTE_PREFIX)\n            ? REQUEST_HEADER_ATTRIBUTE_PREFIX.length\n            : RESPONSE_HEADER_ATTRIBUTE_PREFIX.length,\n        );\n        attributes[key] = this.redaction.redactHeaderValue(headerName, value);\n      }\n    }\n  }\n\n  // Bodies are masked, parsed, field-redacted, and serialized in that order.\n  // Masking failures redact the entire body.\n  private processBody(\n    snapshot: ReadableSpan,\n    body: Buffer,\n    maskCallback: BodyMaskingCallback | undefined,\n    optionName: string,\n  ): string | Buffer {\n    if (body.equals(BODY_TOO_LARGE_BUFFER)) {\n      return BODY_TOO_LARGE;\n    }\n    let processed = body;\n    if (maskCallback) {\n      let masked: unknown;\n      try {\n        masked = maskCallback(body, snapshot);\n      } catch {\n        logWarning(\n          `The Apitally ${optionName} callback threw an error, so the body was replaced with ${REDACTED}`,\n        );\n        return REDACTED;\n      }\n      if (masked === null || masked === undefined) {\n        return REDACTED;\n      }\n      if (!Buffer.isBuffer(masked)) {\n        logWarning(\n          `The Apitally ${optionName} callback returned an invalid value, so the body was replaced with ${REDACTED}. Mask callbacks must synchronously return a Buffer or null.`,\n        );\n        return REDACTED;\n      }\n      if (masked.length > MAX_BODY_SIZE) {\n        return BODY_TOO_LARGE;\n      }\n      processed = masked;\n    }\n    return this.redaction.redactBody(processed);\n  }\n\n  // Export resources must carry Apitally's process identity and match Apitally-Env.\n  // Rewrites apply only to Apitally's copies.\n  private resolveExportResource(\n    resource: Resource,\n    rewrittenResources: Map<Resource, Resource>,\n  ): Resource {\n    const resourceEnv = resource.attributes[DEPLOYMENT_ENVIRONMENT_NAME];\n    const resourceInstanceId = resource.attributes[SERVICE_INSTANCE_ID];\n    const envDiffers = typeof resourceEnv === \"string\" && resourceEnv !== this.env;\n    const envMissing = resourceEnv === undefined && this.env !== DEFAULT_ENV;\n    const instanceIdDiffers = resourceInstanceId !== this.instanceId;\n    if (!envDiffers && !envMissing && !instanceIdDiffers) {\n      return resource;\n    }\n    const existing = rewrittenResources.get(resource);\n    if (existing) {\n      return existing;\n    }\n    if (envDiffers) {\n      logWarning(\n        `The tracer provider's resource sets deployment.environment.name to \"${resourceEnv}\", which differs from the Apitally env \"${this.env}\". Spans are exported to Apitally with the env \"${this.env}\".`,\n      );\n    }\n    const attributes: Attributes = {\n      ...resource.attributes,\n      [SERVICE_INSTANCE_ID]: this.instanceId,\n    };\n    if (envDiffers || envMissing) {\n      attributes[DEPLOYMENT_ENVIRONMENT_NAME] = this.env;\n    }\n    const rewritten = resourceFromAttributes(attributes);\n    rewrittenResources.set(resource, rewritten);\n    return rewritten;\n  }\n}\n\nfunction writeCapturedHeaderAttributes(\n  attributes: Record<string, unknown>,\n  prefix: string,\n  headers: Record<string, string | string[]>,\n  redaction: Redaction,\n): void {\n  for (const [name, values] of Object.entries(headers)) {\n    const redactedValues = redaction.redactHeaderValue(name, values);\n    attributes[prefix + name] = Array.isArray(redactedValues) ? redactedValues : [redactedValues];\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/spanExporter.d.cts

@@ -0,0 +1,33 @@
+import { ExportResult } from '@opentelemetry/core';
+import { SpanExporter, ReadableSpan } from '@opentelemetry/sdk-trace-base';
+import { BodyMaskingCallback } from './config.cjs';
+import { Redaction } from './redaction.cjs';
+import { Spool } from './spool.cjs';
+import 'node:zlib';
+
+interface ApitallySpanExporterOptions {
+    redaction: Redaction;
+    env: string;
+    instanceId: string;
+    spool: Spool;
+    maskRequestBody?: BodyMaskingCallback;
+    maskResponseBody?: BodyMaskingCallback;
+}
+declare class ApitallySpanExporter implements SpanExporter {
+    private readonly redaction;
+    private readonly env;
+    private readonly instanceId;
+    private readonly spool;
+    private readonly maskRequestBody?;
+    private readonly maskResponseBody?;
+    constructor(options: ApitallySpanExporterOptions);
+    export(spans: ReadableSpan[], resultCallback: (result: ExportResult) => void): void;
+    forceFlush(): Promise<void>;
+    shutdown(): Promise<void>;
+    private buildExportCopy;
+    private redactQueryAndHeaderAttributes;
+    private processBody;
+    private resolveExportResource;
+}
+
+export { ApitallySpanExporter, type ApitallySpanExporterOptions };

package/dist/spanExporter.d.ts

@@ -0,0 +1,33 @@
+import { ExportResult } from '@opentelemetry/core';
+import { SpanExporter, ReadableSpan } from '@opentelemetry/sdk-trace-base';
+import { BodyMaskingCallback } from './config.js';
+import { Redaction } from './redaction.js';
+import { Spool } from './spool.js';
+import 'node:zlib';
+
+interface ApitallySpanExporterOptions {
+    redaction: Redaction;
+    env: string;
+    instanceId: string;
+    spool: Spool;
+    maskRequestBody?: BodyMaskingCallback;
+    maskResponseBody?: BodyMaskingCallback;
+}
+declare class ApitallySpanExporter implements SpanExporter {
+    private readonly redaction;
+    private readonly env;
+    private readonly instanceId;
+    private readonly spool;
+    private readonly maskRequestBody?;
+    private readonly maskResponseBody?;
+    constructor(options: ApitallySpanExporterOptions);
+    export(spans: ReadableSpan[], resultCallback: (result: ExportResult) => void): void;
+    forceFlush(): Promise<void>;
+    shutdown(): Promise<void>;
+    private buildExportCopy;
+    private redactQueryAndHeaderAttributes;
+    private processBody;
+    private resolveExportResource;
+}
+
+export { ApitallySpanExporter, type ApitallySpanExporterOptions };

package/dist/spanExporter.js

@@ -0,0 +1,194 @@
+import { SpanKind } from "@opentelemetry/api";
+import { ProtobufTraceSerializer } from "@opentelemetry/otlp-transformer";
+import { resourceFromAttributes } from "@opentelemetry/resources";
+import { BODY_TOO_LARGE, BODY_TOO_LARGE_BUFFER, MAX_BODY_SIZE } from "./bodyCapture.js";
+import { DEFAULT_ENV } from "./config.js";
+import { serializeInChunksToSpool } from "./exportSerialization.js";
+import { logWarning } from "./logger.js";
+import { REDACTED } from "./redaction.js";
+import { copySpan } from "./spanProcessor.js";
+const QUERY_ATTRIBUTES = /* @__PURE__ */ new Set(["url.query", "url.full", "http.target", "http.url"]);
+const REQUEST_HEADER_ATTRIBUTE_PREFIX = "http.request.header.";
+const RESPONSE_HEADER_ATTRIBUTE_PREFIX = "http.response.header.";
+const DEPLOYMENT_ENVIRONMENT_NAME = "deployment.environment.name";
+const SERVICE_INSTANCE_ID = "service.instance.id";
+class ApitallySpanExporter {
+  redaction;
+  env;
+  instanceId;
+  spool;
+  maskRequestBody;
+  maskResponseBody;
+  constructor(options) {
+    this.redaction = options.redaction;
+    this.env = options.env;
+    this.instanceId = options.instanceId;
+    this.spool = options.spool;
+    this.maskRequestBody = options.maskRequestBody;
+    this.maskResponseBody = options.maskResponseBody;
+  }
+  export(spans, resultCallback) {
+    const rewrittenResources = /* @__PURE__ */ new Map();
+    const exportCopies = [];
+    for (const span of spans) {
+      try {
+        exportCopies.push(this.buildExportCopy(span, rewrittenResources));
+      } catch {
+        logWarning("Failed to prepare a span for export to Apitally, so the span was dropped");
+      }
+    }
+    serializeInChunksToSpool(
+      exportCopies,
+      (chunk) => ProtobufTraceSerializer.serializeRequest(chunk),
+      this.spool,
+      "traces",
+      resultCallback
+    );
+  }
+  forceFlush() {
+    return Promise.resolve();
+  }
+  shutdown() {
+    return Promise.resolve();
+  }
+  buildExportCopy(span, rewrittenResources) {
+    const data = span.apitallyData;
+    const stash = data?.stash;
+    const attributes = {
+      ...span.attributes,
+      ...data?.record?.attributes
+    };
+    this.redactQueryAndHeaderAttributes(attributes);
+    if (stash?.requestHeaders) {
+      writeCapturedHeaderAttributes(
+        attributes,
+        REQUEST_HEADER_ATTRIBUTE_PREFIX,
+        stash.requestHeaders,
+        this.redaction
+      );
+    }
+    if (stash?.responseHeaders) {
+      writeCapturedHeaderAttributes(
+        attributes,
+        RESPONSE_HEADER_ATTRIBUTE_PREFIX,
+        stash.responseHeaders,
+        this.redaction
+      );
+    }
+    const copy = copySpan(span);
+    copy.attributes = attributes;
+    copy.resource = this.resolveExportResource(span.resource, rewrittenResources);
+    if (data?.demoteToInternal) {
+      copy.kind = SpanKind.INTERNAL;
+    }
+    if (stash && (stash.requestBody !== void 0 || stash.responseBody !== void 0)) {
+      const snapshot = copySpan(copy);
+      snapshot.attributes = { ...attributes };
+      if (stash.requestBody !== void 0) {
+        attributes["apitally.request.body"] = this.processBody(
+          snapshot,
+          stash.requestBody,
+          this.maskRequestBody,
+          "maskRequestBody"
+        );
+      }
+      if (stash.responseBody !== void 0) {
+        attributes["apitally.response.body"] = this.processBody(
+          snapshot,
+          stash.responseBody,
+          this.maskResponseBody,
+          "maskResponseBody"
+        );
+      }
+    }
+    return copy;
+  }
+  // OpenTelemetry HTTP instrumentations leave query and header attributes raw.
+  // Both legacy and stable HTTP attribute names are redacted before export.
+  redactQueryAndHeaderAttributes(attributes) {
+    for (const [key, value] of Object.entries(attributes)) {
+      if (QUERY_ATTRIBUTES.has(key) && typeof value === "string") {
+        attributes[key] = this.redaction.redactQueryParams(value, key === "url.query");
+      } else if (key.startsWith(REQUEST_HEADER_ATTRIBUTE_PREFIX) || key.startsWith(RESPONSE_HEADER_ATTRIBUTE_PREFIX)) {
+        const headerName = key.slice(
+          key.startsWith(REQUEST_HEADER_ATTRIBUTE_PREFIX) ? REQUEST_HEADER_ATTRIBUTE_PREFIX.length : RESPONSE_HEADER_ATTRIBUTE_PREFIX.length
+        );
+        attributes[key] = this.redaction.redactHeaderValue(headerName, value);
+      }
+    }
+  }
+  // Bodies are masked, parsed, field-redacted, and serialized in that order.
+  // Masking failures redact the entire body.
+  processBody(snapshot, body, maskCallback, optionName) {
+    if (body.equals(BODY_TOO_LARGE_BUFFER)) {
+      return BODY_TOO_LARGE;
+    }
+    let processed = body;
+    if (maskCallback) {
+      let masked;
+      try {
+        masked = maskCallback(body, snapshot);
+      } catch {
+        logWarning(
+          `The Apitally ${optionName} callback threw an error, so the body was replaced with ${REDACTED}`
+        );
+        return REDACTED;
+      }
+      if (masked === null || masked === void 0) {
+        return REDACTED;
+      }
+      if (!Buffer.isBuffer(masked)) {
+        logWarning(
+          `The Apitally ${optionName} callback returned an invalid value, so the body was replaced with ${REDACTED}. Mask callbacks must synchronously return a Buffer or null.`
+        );
+        return REDACTED;
+      }
+      if (masked.length > MAX_BODY_SIZE) {
+        return BODY_TOO_LARGE;
+      }
+      processed = masked;
+    }
+    return this.redaction.redactBody(processed);
+  }
+  // Export resources must carry Apitally's process identity and match Apitally-Env.
+  // Rewrites apply only to Apitally's copies.
+  resolveExportResource(resource, rewrittenResources) {
+    const resourceEnv = resource.attributes[DEPLOYMENT_ENVIRONMENT_NAME];
+    const resourceInstanceId = resource.attributes[SERVICE_INSTANCE_ID];
+    const envDiffers = typeof resourceEnv === "string" && resourceEnv !== this.env;
+    const envMissing = resourceEnv === void 0 && this.env !== DEFAULT_ENV;
+    const instanceIdDiffers = resourceInstanceId !== this.instanceId;
+    if (!envDiffers && !envMissing && !instanceIdDiffers) {
+      return resource;
+    }
+    const existing = rewrittenResources.get(resource);
+    if (existing) {
+      return existing;
+    }
+    if (envDiffers) {
+      logWarning(
+        `The tracer provider's resource sets deployment.environment.name to "${resourceEnv}", which differs from the Apitally env "${this.env}". Spans are exported to Apitally with the env "${this.env}".`
+      );
+    }
+    const attributes = {
+      ...resource.attributes,
+      [SERVICE_INSTANCE_ID]: this.instanceId
+    };
+    if (envDiffers || envMissing) {
+      attributes[DEPLOYMENT_ENVIRONMENT_NAME] = this.env;
+    }
+    const rewritten = resourceFromAttributes(attributes);
+    rewrittenResources.set(resource, rewritten);
+    return rewritten;
+  }
+}
+function writeCapturedHeaderAttributes(attributes, prefix, headers, redaction) {
+  for (const [name, values] of Object.entries(headers)) {
+    const redactedValues = redaction.redactHeaderValue(name, values);
+    attributes[prefix + name] = Array.isArray(redactedValues) ? redactedValues : [redactedValues];
+  }
+}
+export {
+  ApitallySpanExporter
+};
+//# sourceMappingURL=spanExporter.js.map

package/dist/spanExporter.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/spanExporter.ts"],"sourcesContent":["import type { Attributes } from \"@opentelemetry/api\";\nimport { SpanKind } from \"@opentelemetry/api\";\nimport type { ExportResult } from \"@opentelemetry/core\";\nimport { ProtobufTraceSerializer } from \"@opentelemetry/otlp-transformer\";\nimport { type Resource, resourceFromAttributes } from \"@opentelemetry/resources\";\nimport type { ReadableSpan, SpanExporter } from \"@opentelemetry/sdk-trace-base\";\nimport { BODY_TOO_LARGE, BODY_TOO_LARGE_BUFFER, MAX_BODY_SIZE } from \"./bodyCapture.js\";\nimport { type BodyMaskingCallback, DEFAULT_ENV } from \"./config.js\";\nimport { serializeInChunksToSpool } from \"./exportSerialization.js\";\nimport { logWarning } from \"./logger.js\";\nimport { REDACTED, type Redaction } from \"./redaction.js\";\nimport { copySpan, type SpanCopy } from \"./spanProcessor.js\";\nimport type { Spool } from \"./spool.js\";\n\nconst QUERY_ATTRIBUTES = new Set([\"url.query\", \"url.full\", \"http.target\", \"http.url\"]);\nconst REQUEST_HEADER_ATTRIBUTE_PREFIX = \"http.request.header.\";\nconst RESPONSE_HEADER_ATTRIBUTE_PREFIX = \"http.response.header.\";\nconst DEPLOYMENT_ENVIRONMENT_NAME = \"deployment.environment.name\";\nconst SERVICE_INSTANCE_ID = \"service.instance.id\";\n\nexport interface ApitallySpanExporterOptions {\n  redaction: Redaction;\n  env: string;\n  instanceId: string;\n  spool: Spool;\n  maskRequestBody?: BodyMaskingCallback;\n  maskResponseBody?: BodyMaskingCallback;\n}\n\n// Export copies receive transport attributes, captured data, and redaction\n// without mutating the original spans.\nexport class ApitallySpanExporter implements SpanExporter {\n  private readonly redaction: Redaction;\n  private readonly env: string;\n  private readonly instanceId: string;\n  private readonly spool: Spool;\n  private readonly maskRequestBody?: BodyMaskingCallback;\n  private readonly maskResponseBody?: BodyMaskingCallback;\n\n  constructor(options: ApitallySpanExporterOptions) {\n    this.redaction = options.redaction;\n    this.env = options.env;\n    this.instanceId = options.instanceId;\n    this.spool = options.spool;\n    this.maskRequestBody = options.maskRequestBody;\n    this.maskResponseBody = options.maskResponseBody;\n  }\n\n  export(spans: ReadableSpan[], resultCallback: (result: ExportResult) => void): void {\n    // Rewritten resources are shared across the batch: the serializer groups\n    // resourceSpans by object identity, never by attribute equality.\n    const rewrittenResources = new Map<Resource, Resource>();\n    const exportCopies: ReadableSpan[] = [];\n    for (const span of spans) {\n      try {\n        exportCopies.push(this.buildExportCopy(span, rewrittenResources));\n      } catch {\n        // A span that failed redaction must never leave the process.\n        logWarning(\"Failed to prepare a span for export to Apitally, so the span was dropped\");\n      }\n    }\n    serializeInChunksToSpool(\n      exportCopies,\n      (chunk) => ProtobufTraceSerializer.serializeRequest(chunk),\n      this.spool,\n      \"traces\",\n      resultCallback,\n    );\n  }\n\n  forceFlush(): Promise<void> {\n    return Promise.resolve();\n  }\n\n  shutdown(): Promise<void> {\n    return Promise.resolve();\n  }\n\n  private buildExportCopy(\n    span: ReadableSpan,\n    rewrittenResources: Map<Resource, Resource>,\n  ): ReadableSpan {\n    const data = (span as SpanCopy).apitallyData;\n    const stash = data?.stash;\n    // The record is applied last: a transport-observed value wins over anything\n    // the producing instrumentation set for the same key.\n    const attributes: Record<string, unknown> = {\n      ...span.attributes,\n      ...data?.record?.attributes,\n    };\n    this.redactQueryAndHeaderAttributes(attributes);\n    if (stash?.requestHeaders) {\n      writeCapturedHeaderAttributes(\n        attributes,\n        REQUEST_HEADER_ATTRIBUTE_PREFIX,\n        stash.requestHeaders,\n        this.redaction,\n      );\n    }\n    if (stash?.responseHeaders) {\n      writeCapturedHeaderAttributes(\n        attributes,\n        RESPONSE_HEADER_ATTRIBUTE_PREFIX,\n        stash.responseHeaders,\n        this.redaction,\n      );\n    }\n    const copy = copySpan(span);\n    copy.attributes = attributes as Attributes;\n    copy.resource = this.resolveExportResource(span.resource, rewrittenResources);\n    if (data?.demoteToInternal) {\n      copy.kind = SpanKind.INTERNAL;\n    }\n    if (stash && (stash.requestBody !== undefined || stash.responseBody !== undefined)) {\n      // Mask callbacks receive the redacted export copy with captured headers\n      // attached, but without body attributes.\n      const snapshot = copySpan(copy);\n      snapshot.attributes = { ...attributes } as Attributes;\n      if (stash.requestBody !== undefined) {\n        attributes[\"apitally.request.body\"] = this.processBody(\n          snapshot,\n          stash.requestBody,\n          this.maskRequestBody,\n          \"maskRequestBody\",\n        );\n      }\n      if (stash.responseBody !== undefined) {\n        attributes[\"apitally.response.body\"] = this.processBody(\n          snapshot,\n          stash.responseBody,\n          this.maskResponseBody,\n          \"maskResponseBody\",\n        );\n      }\n    }\n    return copy;\n  }\n\n  // OpenTelemetry HTTP instrumentations leave query and header attributes raw.\n  // Both legacy and stable HTTP attribute names are redacted before export.\n  private redactQueryAndHeaderAttributes(attributes: Record<string, unknown>): void {\n    for (const [key, value] of Object.entries(attributes)) {\n      if (QUERY_ATTRIBUTES.has(key) && typeof value === \"string\") {\n        attributes[key] = this.redaction.redactQueryParams(value, key === \"url.query\");\n      } else if (\n        key.startsWith(REQUEST_HEADER_ATTRIBUTE_PREFIX) ||\n        key.startsWith(RESPONSE_HEADER_ATTRIBUTE_PREFIX)\n      ) {\n        const headerName = key.slice(\n          key.startsWith(REQUEST_HEADER_ATTRIBUTE_PREFIX)\n            ? REQUEST_HEADER_ATTRIBUTE_PREFIX.length\n            : RESPONSE_HEADER_ATTRIBUTE_PREFIX.length,\n        );\n        attributes[key] = this.redaction.redactHeaderValue(headerName, value);\n      }\n    }\n  }\n\n  // Bodies are masked, parsed, field-redacted, and serialized in that order.\n  // Masking failures redact the entire body.\n  private processBody(\n    snapshot: ReadableSpan,\n    body: Buffer,\n    maskCallback: BodyMaskingCallback | undefined,\n    optionName: string,\n  ): string | Buffer {\n    if (body.equals(BODY_TOO_LARGE_BUFFER)) {\n      return BODY_TOO_LARGE;\n    }\n    let processed = body;\n    if (maskCallback) {\n      let masked: unknown;\n      try {\n        masked = maskCallback(body, snapshot);\n      } catch {\n        logWarning(\n          `The Apitally ${optionName} callback threw an error, so the body was replaced with ${REDACTED}`,\n        );\n        return REDACTED;\n      }\n      if (masked === null || masked === undefined) {\n        return REDACTED;\n      }\n      if (!Buffer.isBuffer(masked)) {\n        logWarning(\n          `The Apitally ${optionName} callback returned an invalid value, so the body was replaced with ${REDACTED}. Mask callbacks must synchronously return a Buffer or null.`,\n        );\n        return REDACTED;\n      }\n      if (masked.length > MAX_BODY_SIZE) {\n        return BODY_TOO_LARGE;\n      }\n      processed = masked;\n    }\n    return this.redaction.redactBody(processed);\n  }\n\n  // Export resources must carry Apitally's process identity and match Apitally-Env.\n  // Rewrites apply only to Apitally's copies.\n  private resolveExportResource(\n    resource: Resource,\n    rewrittenResources: Map<Resource, Resource>,\n  ): Resource {\n    const resourceEnv = resource.attributes[DEPLOYMENT_ENVIRONMENT_NAME];\n    const resourceInstanceId = resource.attributes[SERVICE_INSTANCE_ID];\n    const envDiffers = typeof resourceEnv === \"string\" && resourceEnv !== this.env;\n    const envMissing = resourceEnv === undefined && this.env !== DEFAULT_ENV;\n    const instanceIdDiffers = resourceInstanceId !== this.instanceId;\n    if (!envDiffers && !envMissing && !instanceIdDiffers) {\n      return resource;\n    }\n    const existing = rewrittenResources.get(resource);\n    if (existing) {\n      return existing;\n    }\n    if (envDiffers) {\n      logWarning(\n        `The tracer provider's resource sets deployment.environment.name to \"${resourceEnv}\", which differs from the Apitally env \"${this.env}\". Spans are exported to Apitally with the env \"${this.env}\".`,\n      );\n    }\n    const attributes: Attributes = {\n      ...resource.attributes,\n      [SERVICE_INSTANCE_ID]: this.instanceId,\n    };\n    if (envDiffers || envMissing) {\n      attributes[DEPLOYMENT_ENVIRONMENT_NAME] = this.env;\n    }\n    const rewritten = resourceFromAttributes(attributes);\n    rewrittenResources.set(resource, rewritten);\n    return rewritten;\n  }\n}\n\nfunction writeCapturedHeaderAttributes(\n  attributes: Record<string, unknown>,\n  prefix: string,\n  headers: Record<string, string | string[]>,\n  redaction: Redaction,\n): void {\n  for (const [name, values] of Object.entries(headers)) {\n    const redactedValues = redaction.redactHeaderValue(name, values);\n    attributes[prefix + name] = Array.isArray(redactedValues) ? redactedValues : [redactedValues];\n  }\n}\n"],"mappings":"AACA,SAAS,gBAAgB;AAEzB,SAAS,+BAA+B;AACxC,SAAwB,8BAA8B;AAEtD,SAAS,gBAAgB,uBAAuB,qBAAqB;AACrE,SAAmC,mBAAmB;AACtD,SAAS,gCAAgC;AACzC,SAAS,kBAAkB;AAC3B,SAAS,gBAAgC;AACzC,SAAS,gBAA+B;AAGxC,MAAM,mBAAmB,oBAAI,IAAI,CAAC,aAAa,YAAY,eAAe,UAAU,CAAC;AACrF,MAAM,kCAAkC;AACxC,MAAM,mCAAmC;AACzC,MAAM,8BAA8B;AACpC,MAAM,sBAAsB;AAarB,MAAM,qBAA6C;AAAA,EACvC;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EAEjB,YAAY,SAAsC;AAChD,SAAK,YAAY,QAAQ;AACzB,SAAK,MAAM,QAAQ;AACnB,SAAK,aAAa,QAAQ;AAC1B,SAAK,QAAQ,QAAQ;AACrB,SAAK,kBAAkB,QAAQ;AAC/B,SAAK,mBAAmB,QAAQ;AAAA,EAClC;AAAA,EAEA,OAAO,OAAuB,gBAAsD;AAGlF,UAAM,qBAAqB,oBAAI,IAAwB;AACvD,UAAM,eAA+B,CAAC;AACtC,eAAW,QAAQ,OAAO;AACxB,UAAI;AACF,qBAAa,KAAK,KAAK,gBAAgB,MAAM,kBAAkB,CAAC;AAAA,MAClE,QAAQ;AAEN,mBAAW,0EAA0E;AAAA,MACvF;AAAA,IACF;AACA;AAAA,MACE;AAAA,MACA,CAAC,UAAU,wBAAwB,iBAAiB,KAAK;AAAA,MACzD,KAAK;AAAA,MACL;AAAA,MACA;AAAA,IACF;AAAA,EACF;AAAA,EAEA,aAA4B;AAC1B,WAAO,QAAQ,QAAQ;AAAA,EACzB;AAAA,EAEA,WAA0B;AACxB,WAAO,QAAQ,QAAQ;AAAA,EACzB;AAAA,EAEQ,gBACN,MACA,oBACc;AACd,UAAM,OAAQ,KAAkB;AAChC,UAAM,QAAQ,MAAM;AAGpB,UAAM,aAAsC;AAAA,MAC1C,GAAG,KAAK;AAAA,MACR,GAAG,MAAM,QAAQ;AAAA,IACnB;AACA,SAAK,+BAA+B,UAAU;AAC9C,QAAI,OAAO,gBAAgB;AACzB;AAAA,QACE;AAAA,QACA;AAAA,QACA,MAAM;AAAA,QACN,KAAK;AAAA,MACP;AAAA,IACF;AACA,QAAI,OAAO,iBAAiB;AAC1B;AAAA,QACE;AAAA,QACA;AAAA,QACA,MAAM;AAAA,QACN,KAAK;AAAA,MACP;AAAA,IACF;AACA,UAAM,OAAO,SAAS,IAAI;AAC1B,SAAK,aAAa;AAClB,SAAK,WAAW,KAAK,sBAAsB,KAAK,UAAU,kBAAkB;AAC5E,QAAI,MAAM,kBAAkB;AAC1B,WAAK,OAAO,SAAS;AAAA,IACvB;AACA,QAAI,UAAU,MAAM,gBAAgB,UAAa,MAAM,iBAAiB,SAAY;AAGlF,YAAM,WAAW,SAAS,IAAI;AAC9B,eAAS,aAAa,EAAE,GAAG,WAAW;AACtC,UAAI,MAAM,gBAAgB,QAAW;AACnC,mBAAW,uBAAuB,IAAI,KAAK;AAAA,UACzC;AAAA,UACA,MAAM;AAAA,UACN,KAAK;AAAA,UACL;AAAA,QACF;AAAA,MACF;AACA,UAAI,MAAM,iBAAiB,QAAW;AACpC,mBAAW,wBAAwB,IAAI,KAAK;AAAA,UAC1C;AAAA,UACA,MAAM;AAAA,UACN,KAAK;AAAA,UACL;AAAA,QACF;AAAA,MACF;AAAA,IACF;AACA,WAAO;AAAA,EACT;AAAA;AAAA;AAAA,EAIQ,+BAA+B,YAA2C;AAChF,eAAW,CAAC,KAAK,KAAK,KAAK,OAAO,QAAQ,UAAU,GAAG;AACrD,UAAI,iBAAiB,IAAI,GAAG,KAAK,OAAO,UAAU,UAAU;AAC1D,mBAAW,GAAG,IAAI,KAAK,UAAU,kBAAkB,OAAO,QAAQ,WAAW;AAAA,MAC/E,WACE,IAAI,WAAW,+BAA+B,KAC9C,IAAI,WAAW,gCAAgC,GAC/C;AACA,cAAM,aAAa,IAAI;AAAA,UACrB,IAAI,WAAW,+BAA+B,IAC1C,gCAAgC,SAChC,iCAAiC;AAAA,QACvC;AACA,mBAAW,GAAG,IAAI,KAAK,UAAU,kBAAkB,YAAY,KAAK;AAAA,MACtE;AAAA,IACF;AAAA,EACF;AAAA;AAAA;AAAA,EAIQ,YACN,UACA,MACA,cACA,YACiB;AACjB,QAAI,KAAK,OAAO,qBAAqB,GAAG;AACtC,aAAO;AAAA,IACT;AACA,QAAI,YAAY;AAChB,QAAI,cAAc;AAChB,UAAI;AACJ,UAAI;AACF,iBAAS,aAAa,MAAM,QAAQ;AAAA,MACtC,QAAQ;AACN;AAAA,UACE,gBAAgB,UAAU,2DAA2D,QAAQ;AAAA,QAC/F;AACA,eAAO;AAAA,MACT;AACA,UAAI,WAAW,QAAQ,WAAW,QAAW;AAC3C,eAAO;AAAA,MACT;AACA,UAAI,CAAC,OAAO,SAAS,MAAM,GAAG;AAC5B;AAAA,UACE,gBAAgB,UAAU,sEAAsE,QAAQ;AAAA,QAC1G;AACA,eAAO;AAAA,MACT;AACA,UAAI,OAAO,SAAS,eAAe;AACjC,eAAO;AAAA,MACT;AACA,kBAAY;AAAA,IACd;AACA,WAAO,KAAK,UAAU,WAAW,SAAS;AAAA,EAC5C;AAAA;AAAA;AAAA,EAIQ,sBACN,UACA,oBACU;AACV,UAAM,cAAc,SAAS,WAAW,2BAA2B;AACnE,UAAM,qBAAqB,SAAS,WAAW,mBAAmB;AAClE,UAAM,aAAa,OAAO,gBAAgB,YAAY,gBAAgB,KAAK;AAC3E,UAAM,aAAa,gBAAgB,UAAa,KAAK,QAAQ;AAC7D,UAAM,oBAAoB,uBAAuB,KAAK;AACtD,QAAI,CAAC,cAAc,CAAC,cAAc,CAAC,mBAAmB;AACpD,aAAO;AAAA,IACT;AACA,UAAM,WAAW,mBAAmB,IAAI,QAAQ;AAChD,QAAI,UAAU;AACZ,aAAO;AAAA,IACT;AACA,QAAI,YAAY;AACd;AAAA,QACE,uEAAuE,WAAW,2CAA2C,KAAK,GAAG,mDAAmD,KAAK,GAAG;AAAA,MAClM;AAAA,IACF;AACA,UAAM,aAAyB;AAAA,MAC7B,GAAG,SAAS;AAAA,MACZ,CAAC,mBAAmB,GAAG,KAAK;AAAA,IAC9B;AACA,QAAI,cAAc,YAAY;AAC5B,iBAAW,2BAA2B,IAAI,KAAK;AAAA,IACjD;AACA,UAAM,YAAY,uBAAuB,UAAU;AACnD,uBAAmB,IAAI,UAAU,SAAS;AAC1C,WAAO;AAAA,EACT;AACF;AAEA,SAAS,8BACP,YACA,QACA,SACA,WACM;AACN,aAAW,CAAC,MAAM,MAAM,KAAK,OAAO,QAAQ,OAAO,GAAG;AACpD,UAAM,iBAAiB,UAAU,kBAAkB,MAAM,MAAM;AAC/D,eAAW,SAAS,IAAI,IAAI,MAAM,QAAQ,cAAc,IAAI,iBAAiB,CAAC,cAAc;AAAA,EAC9F;AACF;","names":[]}