@logbrew/sdk 0.1.2 → 0.1.4

package/index.cjs

@@ -1,3 +1,8 @@
+const { buildCreateSupportTicketDraft } = require("./support-ticket.cjs");
+const { buildIssueStackHelpers } = require("./issue-stack.cjs");
+const { buildOpenTelemetryHelpers } = require("./opentelemetry.cjs");
+const { buildTraceContextHelpers } = require("./trace-context.cjs");
+
 const SEVERITY_ALIASES = new Map([
   ["trace", "info"],
   ["debug", "info"],
@@ -26,15 +31,54 @@ const WINSTON_RESERVED_FIELDS = new Set(["level", "message", "timestamp", "time"
 const TRACEPARENT_PATTERN = /^([0-9a-fA-F]{2})-([0-9a-fA-F]{32})-([0-9a-fA-F]{16})-([0-9a-fA-F]{2})$/u;
 const ZERO_TRACE_ID = "00000000000000000000000000000000";
 const ZERO_SPAN_ID = "0000000000000000";
-
+const DEFAULT_MAX_QUEUE_SIZE = 1000;
+const DEFAULT_MAX_QUEUE_BYTES = 4 * 1024 * 1024;
+const DEFAULT_MAX_BATCH_EVENTS = 100;
+const DEFAULT_MAX_BATCH_BYTES = 256 * 1024;
+const DEFAULT_DELIVERY_INTERVAL_MS = 5000;
+const MAX_DELIVERY_INTERVAL_MS = 60 * 1000;
+const DEFAULT_DELIVERY_QUEUE_THRESHOLD = 50;
+const DELIVERY_HEALTH_SCHEMA_VERSION = 1;
+const EVENT_QUEUE_FACTORY = Symbol.for("@logbrew/sdk.eventQueueFactory");
+const MAX_ERROR_CAUSES = 5;
+const BUILTIN_ERROR_NAMES = new Set([
+  "AggregateError",
+  "Error",
+  "EvalError",
+  "RangeError",
+  "ReferenceError",
+  "SyntaxError",
+  "TypeError",
+  "URIError"
+]);
+const MAX_SPAN_EVENTS = 8;
+const MAX_SPAN_LINKS = 8;
+const EVENT_VALIDATORS = new Map([
+  ["release", validateRelease],
+  ["environment", validateEnvironment],
+  ["issue", validateIssue],
+  ["log", validateLog],
+  ["span", validateSpan],
+  ["action", validateAction],
+  ["metric", validateMetric]
+]);
 class SdkError extends Error {
-  constructor(code, message) {
+  constructor(code, message, details = {}) {
     super(message);
     this.name = "SdkError";
     this.code = code;
+    const retryAfterMs = retryAfterMsOrUndefined(details?.retryAfterMs);
+    if (retryAfterMs !== undefined) {
+      this.retryAfterMs = retryAfterMs;
+    }
+    if (details?.retryable === true) {
+      this.retryable = true;
+    }
   }
 }
 
+const { javascriptStackFrames, validateIssueStackFrames } = buildIssueStackHelpers({ SdkError });
+
 class TransportError extends Error {
   constructor(code, message, retryable = false) {
     super(message);
@@ -74,48 +118,296 @@ class RecordingTransport {
       throw next;
     }
 
-    return { statusCode: next.statusCode, attempts: 1 };
+    const retryAfterMs = retryAfterMsOrUndefined(next.retryAfterMs);
+    return retryAfterMs === undefined
+      ? { statusCode: next.statusCode, attempts: 1 }
+      : { statusCode: next.statusCode, attempts: 1, retryAfterMs };
   }
 }
 
 class LogBrewClient {
-  static create({ apiKey, sdkName, sdkVersion, maxRetries = 2, eventFilter }) {
+  static create({
+    apiKey,
+    sdkName,
+    sdkVersion,
+    maxRetries = 2,
+    eventFilter,
+    maxQueueSize = DEFAULT_MAX_QUEUE_SIZE,
+    maxQueueBytes = DEFAULT_MAX_QUEUE_BYTES,
+    maxBatchEvents = DEFAULT_MAX_BATCH_EVENTS,
+    maxBatchBytes = DEFAULT_MAX_BATCH_BYTES,
+    onEventDropped,
+    eventStore,
+    [EVENT_QUEUE_FACTORY]: eventQueueFactory,
+    transport,
+    automaticDelivery = transport !== undefined,
+    deliveryIntervalMs = DEFAULT_DELIVERY_INTERVAL_MS,
+    deliveryQueueThreshold = Math.min(DEFAULT_DELIVERY_QUEUE_THRESHOLD, maxQueueSize)
+  }) {
     requireNonEmpty("apiKey", apiKey);
     requireNonEmpty("sdkName", sdkName);
     requireNonEmpty("sdkVersion", sdkVersion);
+    requireNonNegativeInteger("maxRetries", maxRetries);
     if (eventFilter !== undefined && typeof eventFilter !== "function") {
       throw new SdkError("validation_error", "eventFilter must be a function");
     }
+    requirePositiveInteger("maxQueueSize", maxQueueSize);
+    requirePositiveInteger("maxQueueBytes", maxQueueBytes);
+    requirePositiveInteger("maxBatchEvents", maxBatchEvents);
+    requirePositiveInteger("maxBatchBytes", maxBatchBytes);
+    if (onEventDropped !== undefined && typeof onEventDropped !== "function") {
+      throw new SdkError("validation_error", "onEventDropped must be a function");
+    }
+    validateEventStore(eventStore);
+    if (eventQueueFactory !== undefined && typeof eventQueueFactory !== "function") {
+      throw new SdkError("validation_error", "event queue factory must be a function");
+    }
+    if (eventStore !== undefined && eventQueueFactory !== undefined) {
+      throw new SdkError("validation_error", "eventStore and event queue factory are mutually exclusive");
+    }
+    validateTransport(transport);
+    if (typeof automaticDelivery !== "boolean") {
+      throw new SdkError("validation_error", "automaticDelivery must be a boolean");
+    }
+    if (automaticDelivery && transport === undefined) {
+      throw new SdkError("validation_error", "automaticDelivery requires transport");
+    }
+    requirePositiveInteger("deliveryIntervalMs", deliveryIntervalMs);
+    if (deliveryIntervalMs > MAX_DELIVERY_INTERVAL_MS) {
+      throw new SdkError("validation_error", `deliveryIntervalMs must be at most ${MAX_DELIVERY_INTERVAL_MS}`);
+    }
+    requirePositiveInteger("deliveryQueueThreshold", deliveryQueueThreshold);
+    if (deliveryQueueThreshold > maxQueueSize) {
+      throw new SdkError("validation_error", "deliveryQueueThreshold must not exceed maxQueueSize");
+    }
 
     return new LogBrewClient({
       apiKey,
+      automaticDelivery,
+      deliveryIntervalMs,
+      deliveryQueueThreshold,
+      eventStore,
+      eventQueueFactory,
       eventFilter,
+      maxBatchBytes,
+      maxBatchEvents,
+      maxQueueBytes,
+      maxQueueSize,
+      onEventDropped,
       sdk: {
         name: sdkName,
         language: "javascript",
         version: sdkVersion
       },
-      maxRetries
+      maxRetries,
+      transport
     });
   }
 
-  constructor({ apiKey, sdk, maxRetries, eventFilter }) {
+  constructor({
+    apiKey,
+    sdk,
+    maxRetries,
+    eventFilter,
+    maxBatchBytes,
+    maxBatchEvents,
+    maxQueueBytes,
+    maxQueueSize,
+    onEventDropped,
+    eventStore,
+    eventQueueFactory,
+    transport,
+    automaticDelivery,
+    deliveryIntervalMs,
+    deliveryQueueThreshold
+  }) {
     this.apiKey = apiKey;
+    this.automaticDelivery = automaticDelivery;
+    this.deliveryIntervalMs = deliveryIntervalMs;
+    this.deliveryQueueThreshold = deliveryQueueThreshold;
     this.eventFilter = eventFilter;
+    this.maxBatchBytes = maxBatchBytes;
+    this.maxBatchEvents = maxBatchEvents;
+    this.maxQueueBytes = maxQueueBytes;
+    this.maxQueueSize = maxQueueSize;
+    this.onEventDropped = onEventDropped;
+    this.transport = transport;
     this.sdk = sdk;
     this.maxRetries = maxRetries;
-    this.events = [];
+    this.batchPrefix = `{"sdk":${JSON.stringify(this.sdk)},"events":[`;
+    this.batchPrefixBytes = utf8ByteLength(this.batchPrefix);
+    this.batchSuffix = "]}";
+    this.batchSuffixBytes = utf8ByteLength(this.batchSuffix);
+    const ownsEventStore = eventQueueFactory !== undefined;
+    const resolvedEventStore = ownsEventStore
+      ? createEventStoreFromQueueFactory(eventQueueFactory, {
+          batchPrefixBytes: this.batchPrefixBytes,
+          batchSuffixBytes: this.batchSuffixBytes,
+          maxBatchBytes,
+          maxQueueBytes,
+          maxQueueSize
+        })
+      : eventStore;
+    this.eventStore = resolvedEventStore;
+    let recovered;
+    try {
+      recovered = loadStoredEvents({
+        batchPrefixBytes: this.batchPrefixBytes,
+        batchSuffixBytes: this.batchSuffixBytes,
+        eventStore: resolvedEventStore,
+        maxBatchBytes,
+        maxQueueBytes,
+        maxQueueSize
+      });
+    } catch (error) {
+      if (ownsEventStore) {
+        try {
+          requireSynchronousStoreResult("close", resolvedEventStore.close());
+        } catch {
+          // Preserve the queue construction or recovery failure.
+        }
+      }
+      throw error;
+    }
+    this.events = recovered.events;
+    this.serializedEvents = recovered.serializedEvents;
+    this.serializedEventBytes = recovered.serializedEventBytes;
+    this.queuedEventBytes = recovered.queuedEventBytes;
+    this.operationTail = Promise.resolve();
+    this.pendingOperations = 0;
+    this.closing = false;
     this.closed = false;
+    this.droppedEventCount = 0;
+    this.droppedEventsByReason = {
+      event_too_large: 0,
+      queue_bytes_overflow: 0,
+      queue_overflow: 0
+    };
+    this.lastDropReason = "none";
+    this.storage = resolvedEventStore ? "persistent" : "memory";
+    this.hydratedEventCount = recovered.events.length;
+    this.hydratedEventBytes = recovered.queuedEventBytes;
+    this.deliveryTimer = undefined;
+    this.automaticFlushActive = false;
+    this.automaticFlushPending = false;
+    this.deliveryInFlight = false;
+    this.lastDeliveryOutcome = "idle";
+    this.automaticPauseReason = "none";
+    this.consecutiveDeliveryFailures = 0;
+    this.retryDelayMs = 0;
+    this.successfulFlushCount = 0;
+    this.failedFlushCount = 0;
+    this.deliveryAttemptCount = 0;
+    this.acceptedBatchCount = 0;
+    this.acceptedEventCount = 0;
+    this.lastStatusClass = "none";
+    this.lastAttemptAtUnixMs = 0;
+    this.lastAcceptedAtUnixMs = 0;
+    this.lastDroppedAtUnixMs = 0;
+    this.failedBatch = undefined;
+    this.#scheduleAutomaticDelivery();
   }
 
   pendingEvents() {
     return this.events.length;
   }
 
+  pendingBytes() {
+    return this.queuedEventBytes;
+  }
+
+  droppedEvents() {
+    return this.droppedEventCount;
+  }
+
+  deliveryHealth() {
+    const droppedByReason = Object.freeze({ ...this.droppedEventsByReason });
+    return Object.freeze({
+      schemaVersion: DELIVERY_HEALTH_SCHEMA_VERSION,
+      automaticDelivery: this.automaticDelivery,
+      lifecycle: this.closed ? "closed" : this.closing ? "shutting_down" : "active",
+      deliveryState: this.#deliveryState(),
+      storage: this.storage,
+      queueEvents: this.events.length,
+      queueBytes: this.queuedEventBytes,
+      hydratedEvents: this.hydratedEventCount,
+      hydratedBytes: this.hydratedEventBytes,
+      droppedEvents: this.droppedEventCount,
+      droppedByReason,
+      lastDropReason: this.lastDropReason,
+      scheduled: this.deliveryTimer !== undefined,
+      inFlight: this.deliveryInFlight,
+      coalesced: this.automaticFlushPending,
+      pendingOperations: this.pendingOperations,
+      lastOutcome: this.lastDeliveryOutcome,
+      lastStatusClass: this.lastStatusClass,
+      pausedReason: this.automaticPauseReason,
+      consecutiveFailures: this.consecutiveDeliveryFailures,
+      retryDelayMs: this.retryDelayMs,
+      flushes: this.successfulFlushCount,
+      failures: this.failedFlushCount,
+      attempts: this.deliveryAttemptCount,
+      batches: this.acceptedBatchCount,
+      acceptedEvents: this.acceptedEventCount,
+      lastAttemptAtUnixMs: this.lastAttemptAtUnixMs,
+      lastAcceptedAtUnixMs: this.lastAcceptedAtUnixMs,
+      lastDroppedAtUnixMs: this.lastDroppedAtUnixMs
+    });
+  }
+
+  #deliveryState() {
+    if (this.deliveryInFlight) {
+      return "in_flight";
+    }
+    if (this.retryDelayMs > 0) {
+      return "retrying";
+    }
+    if (this.automaticPauseReason !== "none") {
+      return "paused";
+    }
+    if (this.events.length > 0) {
+      return this.deliveryTimer !== undefined ? "scheduled" : "queued";
+    }
+    if (this.lastDeliveryOutcome === "accepted") {
+      return "accepted";
+    }
+    if (this.lastDeliveryOutcome === "failed") {
+      return "failed";
+    }
+    if (this.droppedEventCount > 0) {
+      return "dropped";
+    }
+    return "idle";
+  }
+
   previewJson() {
     return JSON.stringify({ sdk: this.sdk, events: this.events }, null, 2);
   }
 
+  purgePendingEvents() {
+    if (this.closed) {
+      throw new SdkError("shutdown_error", "client is already shut down");
+    }
+    if (this.closing) {
+      throw new SdkError("shutdown_error", "client is shutting down");
+    }
+    if (this.pendingOperations > 0 || this.automaticFlushActive) {
+      throw new SdkError("persistence_error", "cannot purge while a delivery operation is active");
+    }
+    const purgedEvents = this.events.length;
+    if (this.eventStore) {
+      requireSynchronousStoreResult("purge", this.eventStore.purge());
+    }
+    this.#clearDeliveryTimer();
+    this.automaticFlushPending = false;
+    this.failedBatch = undefined;
+    this.events.splice(0, this.events.length);
+    this.serializedEvents.splice(0, this.serializedEvents.length);
+    this.serializedEventBytes.splice(0, this.serializedEventBytes.length);
+    this.queuedEventBytes = 0;
+    return purgedEvents;
+  }
+
   release(id, timestamp, attributes) {
     this.#pushEvent("release", id, timestamp, validateRelease(attributes));
   }
@@ -148,64 +440,420 @@ class LogBrewClient {
     if (this.closed) {
       throw new SdkError("shutdown_error", "client is already shut down");
     }
-    return this.#flushInternal(transport);
+    if (this.closing) {
+      throw new SdkError("shutdown_error", "client is shutting down");
+    }
+    const resolvedTransport = this.#resolveTransport(transport);
+    const controlsAutomaticDelivery = this.automaticDelivery && resolvedTransport === this.transport;
+    this.#clearDeliveryTimer();
+    return this.#runSerialized(async () => {
+      this.#clearDeliveryTimer();
+      try {
+        const response = await this.#flushWithHealth(resolvedTransport);
+        if (controlsAutomaticDelivery) {
+          this.#recordAutomaticSuccess();
+        }
+        return response;
+      } catch (error) {
+        if (controlsAutomaticDelivery) {
+          this.#recordAutomaticFailure(error);
+        }
+        throw error;
+      } finally {
+        if (this.automaticDelivery && !this.closed && !this.closing) {
+          this.#resumeAutomaticDelivery();
+        }
+      }
+    });
   }
 
   async shutdown(transport) {
     if (this.closed) {
       throw new SdkError("shutdown_error", "client is already shut down");
     }
-    const response = await this.#flushInternal(transport);
-    this.closed = true;
-    return response;
+    if (this.closing) {
+      throw new SdkError("shutdown_error", "client is shutting down");
+    }
+    const resolvedTransport = this.#resolveTransport(transport);
+    const controlsAutomaticDelivery = this.automaticDelivery && resolvedTransport === this.transport;
+    this.#clearDeliveryTimer();
+    this.automaticFlushPending = false;
+    this.closing = true;
+    try {
+      const response = await this.#runSerialized(() => this.#flushWithHealth(resolvedTransport));
+      if (controlsAutomaticDelivery) {
+        this.#recordAutomaticSuccess();
+      }
+      if (this.eventStore) {
+        try {
+          requireSynchronousStoreResult("close", this.eventStore.close());
+        } catch (error) {
+          this.closed = true;
+          throw error;
+        }
+      }
+      this.closed = true;
+      return response;
+    } catch (error) {
+      if (!this.closed) {
+        this.closing = false;
+        if (controlsAutomaticDelivery) {
+          this.#recordAutomaticFailure(error);
+        }
+        this.#resumeAutomaticDelivery();
+      }
+      throw error;
+    }
   }
 
   #pushEvent(eventType, id, timestamp, attributes) {
     if (this.closed) {
       throw new SdkError("shutdown_error", "client is already shut down");
     }
+    if (this.closing) {
+      throw new SdkError("shutdown_error", "client is shutting down");
+    }
     requireNonEmpty("event id", id);
     requireTimestamp(timestamp);
     const event = { type: eventType, id, timestamp, attributes };
     if (this.eventFilter && this.eventFilter(cloneEvent(event)) === false) {
       return;
     }
+    const serializedEvent = JSON.stringify(event);
+    const eventBytes = utf8ByteLength(serializedEvent);
+    if (this.batchPrefixBytes + eventBytes + this.batchSuffixBytes > this.maxBatchBytes) {
+      this.#recordDroppedEvent(event, "event_too_large");
+      return;
+    }
+    if (this.events.length >= this.maxQueueSize) {
+      this.#recordDroppedEvent(event, "queue_overflow");
+      return;
+    }
+    if (this.queuedEventBytes + eventBytes > this.maxQueueBytes) {
+      this.#recordDroppedEvent(event, "queue_bytes_overflow");
+      return;
+    }
+    if (this.eventStore) {
+      requireSynchronousStoreResult("append", this.eventStore.append({
+        event: cloneEvent(event),
+        eventBytes,
+        serializedEvent
+      }));
+    }
     this.events.push(event);
+    this.serializedEvents.push(serializedEvent);
+    this.serializedEventBytes.push(eventBytes);
+    this.queuedEventBytes += eventBytes;
+    this.#scheduleAutomaticDelivery();
+  }
+
+  #recordDroppedEvent(event, reason) {
+    this.droppedEventCount = incrementBounded(this.droppedEventCount);
+    this.droppedEventsByReason[reason] = incrementBounded(this.droppedEventsByReason[reason]);
+    this.lastDropReason = reason;
+    this.lastDroppedAtUnixMs = nextBoundedTimestamp(this.lastDroppedAtUnixMs);
+    if (!this.onEventDropped) {
+      return;
+    }
+    try {
+      this.onEventDropped({
+        droppedEvents: this.droppedEventCount,
+        eventId: event.id,
+        eventType: event.type,
+        reason
+      });
+    } catch {
+      // Drop callbacks are advisory and must not interrupt application logging.
+    }
+  }
+
+  #runSerialized(operation) {
+    this.pendingOperations = incrementBounded(this.pendingOperations);
+    const result = this.operationTail.then(operation).finally(() => {
+      this.pendingOperations = Math.max(0, this.pendingOperations - 1);
+    });
+    this.operationTail = result.then(
+      () => undefined,
+      () => undefined
+    );
+    return result;
+  }
+
+  #resolveTransport(transport) {
+    const resolved = transport ?? this.transport;
+    if (resolved === undefined) {
+      throw new SdkError("validation_error", "flush and shutdown require transport");
+    }
+    validateTransport(resolved);
+    return resolved;
+  }
+
+  async #flushWithHealth(transport) {
+    this.deliveryInFlight = true;
+    try {
+      const response = await this.#flushSnapshot(transport);
+      this.successfulFlushCount = incrementBounded(this.successfulFlushCount);
+      this.lastDeliveryOutcome = response.batches === 0 ? "empty" : "accepted";
+      return response;
+    } catch (error) {
+      this.failedFlushCount = incrementBounded(this.failedFlushCount);
+      this.lastDeliveryOutcome = "failed";
+      throw error;
+    } finally {
+      this.deliveryInFlight = false;
+    }
+  }
+
+  #scheduleAutomaticDelivery() {
+    if (!this.automaticDelivery || this.closed || this.closing || this.events.length === 0 || this.automaticPauseReason !== "none") {
+      return;
+    }
+    if (this.automaticFlushActive) {
+      this.automaticFlushPending = true;
+      return;
+    }
+    if (this.retryDelayMs > 0) {
+      this.#armAutomaticDeliveryTimer(this.retryDelayMs);
+      return;
+    }
+    if (this.events.length >= this.deliveryQueueThreshold) {
+      this.#requestAutomaticFlush();
+      return;
+    }
+    this.#armAutomaticDeliveryTimer();
+  }
+
+  #armAutomaticDeliveryTimer(delayMs = this.deliveryIntervalMs) {
+    if (!this.automaticDelivery || this.closed || this.closing || this.events.length === 0 || this.automaticPauseReason !== "none") {
+      return;
+    }
+    if (this.deliveryTimer !== undefined) {
+      return;
+    }
+    const timer = setTimeout(() => {
+      if (this.deliveryTimer !== timer) {
+        return;
+      }
+      this.deliveryTimer = undefined;
+      this.retryDelayMs = 0;
+      this.#requestAutomaticFlush();
+    }, delayMs);
+    this.deliveryTimer = timer;
+    if (timer && typeof timer === "object" && typeof timer.unref === "function") {
+      timer.unref();
+    }
+  }
+
+  #clearDeliveryTimer() {
+    if (this.deliveryTimer === undefined) {
+      return;
+    }
+    globalThis.clearTimeout(this.deliveryTimer);
+    this.deliveryTimer = undefined;
+  }
+
+  #requestAutomaticFlush() {
+    if (!this.automaticDelivery || this.closed || this.closing || this.events.length === 0 || this.automaticPauseReason !== "none") {
+      return;
+    }
+    this.#clearDeliveryTimer();
+    if (this.automaticFlushActive) {
+      this.automaticFlushPending = true;
+      return;
+    }
+    this.automaticFlushActive = true;
+    void Promise.resolve().then(() => this.#runAutomaticFlush());
+  }
+
+  async #runAutomaticFlush() {
+    if (this.closed || this.closing) {
+      this.automaticFlushActive = false;
+      this.automaticFlushPending = false;
+      return;
+    }
+    let succeeded = false;
+    try {
+      await this.#runSerialized(() => this.#flushWithHealth(this.transport));
+      this.#recordAutomaticSuccess();
+      succeeded = true;
+    } catch (error) {
+      this.#recordAutomaticFailure(error);
+    } finally {
+      this.automaticFlushActive = false;
+      if (this.closed || this.closing) {
+        this.automaticFlushPending = false;
+      } else {
+        const drainCoalesced = succeeded && this.automaticFlushPending && this.events.length > 0;
+        this.automaticFlushPending = false;
+        if (drainCoalesced) {
+          this.#requestAutomaticFlush();
+        } else if (!succeeded) {
+          this.#resumeAutomaticDelivery();
+        } else {
+          this.#scheduleAutomaticDelivery();
+        }
+      }
+    }
   }
 
-  async #flushInternal(transport) {
-    if (this.events.length === 0) {
-      return { statusCode: 204, attempts: 0 };
+  async #flushSnapshot(transport) {
+    let remainingEvents = this.events.length;
+    if (remainingEvents === 0) {
+      return { statusCode: 204, attempts: 0, batches: 0 };
     }
 
-    const body = this.previewJson();
+    let attempts = 0;
+    let batches = 0;
+    let statusCode = 204;
+    while (remainingEvents > 0) {
+      const batch = this.failedBatch ?? this.#nextBatch(Math.min(remainingEvents, this.maxBatchEvents));
+      let response;
+      try {
+        response = await this.#sendBatch(transport, batch.body);
+      } catch (error) {
+        this.failedBatch ??= Object.freeze({ body: batch.body, eventsCount: batch.eventsCount });
+        throw error;
+      }
+      this.failedBatch = undefined;
+      this.#acknowledge(batch.eventsCount);
+      this.acceptedBatchCount = incrementBounded(this.acceptedBatchCount);
+      remainingEvents -= batch.eventsCount;
+      attempts += response.attempts;
+      batches += 1;
+      statusCode = response.statusCode;
+    }
+
+    return { statusCode, attempts, batches };
+  }
+
+  #nextBatch(maxEvents) {
+    let bodyBytes = this.batchPrefixBytes + this.batchSuffixBytes;
+    let eventsCount = 0;
+    for (let index = 0; index < maxEvents; index += 1) {
+      const separatorBytes = eventsCount === 0 ? 0 : 1;
+      const nextBodyBytes = bodyBytes + separatorBytes + this.serializedEventBytes[index];
+      if (nextBodyBytes > this.maxBatchBytes) {
+        break;
+      }
+      bodyBytes = nextBodyBytes;
+      eventsCount += 1;
+    }
+    if (eventsCount === 0) {
+      throw new SdkError("transport_error", "queued event cannot fit the configured batch byte limit");
+    }
+    return {
+      body: `${this.batchPrefix}${this.serializedEvents.slice(0, eventsCount).join(",")}${this.batchSuffix}`,
+      eventsCount
+    };
+  }
+
+  #acknowledge(eventsCount) {
+    if (this.eventStore) {
+      requireSynchronousStoreResult("acknowledge", this.eventStore.acknowledge(eventsCount));
+    }
+    let acknowledgedBytes = 0;
+    for (let index = 0; index < eventsCount; index += 1) {
+      acknowledgedBytes += this.serializedEventBytes[index];
+    }
+    this.events.splice(0, eventsCount);
+    this.serializedEvents.splice(0, eventsCount);
+    this.serializedEventBytes.splice(0, eventsCount);
+    this.queuedEventBytes -= acknowledgedBytes;
+    this.acceptedEventCount = addBounded(this.acceptedEventCount, eventsCount);
+    this.lastAcceptedAtUnixMs = nextBoundedTimestamp(Math.max(
+      this.lastAcceptedAtUnixMs,
+      this.lastAttemptAtUnixMs
+    ));
+  }
+
+  #recordAutomaticSuccess() {
+    this.automaticPauseReason = "none";
+    this.consecutiveDeliveryFailures = 0;
+    this.retryDelayMs = 0;
+  }
+
+  #recordAutomaticFailure(error) {
+    this.consecutiveDeliveryFailures = incrementBounded(this.consecutiveDeliveryFailures);
+    this.retryDelayMs = 0;
+    if (error instanceof SdkError && error.code === "unauthenticated") {
+      this.automaticPauseReason = "authentication";
+      return;
+    }
+    if (error instanceof SdkError && error.code === "rate_limited") {
+      this.automaticPauseReason = "rate_limit";
+      return;
+    }
+    if (error instanceof SdkError && error.retryable === true) {
+      this.automaticPauseReason = "none";
+      this.retryDelayMs = automaticRetryDelayMs(this.deliveryIntervalMs, this.consecutiveDeliveryFailures);
+      return;
+    }
+    this.automaticPauseReason = "non_retryable";
+  }
+
+  #resumeAutomaticDelivery() {
+    if (this.automaticPauseReason !== "none") {
+      return;
+    }
+    if (this.retryDelayMs > 0) {
+      this.#armAutomaticDeliveryTimer(this.retryDelayMs);
+      return;
+    }
+    this.#scheduleAutomaticDelivery();
+  }
+
+  async #sendBatch(transport, body) {
     const maxAttempts = this.maxRetries + 1;
     let attempts = 0;
 
     while (attempts < maxAttempts) {
       attempts += 1;
+      this.deliveryAttemptCount = incrementBounded(this.deliveryAttemptCount);
+      this.lastAttemptAtUnixMs = nextBoundedTimestamp(this.lastAttemptAtUnixMs);
+      this.lastStatusClass = "transport_error";
       try {
         const response = await transport.send(this.apiKey, body);
+        if (
+          !response
+          || Array.isArray(response)
+          || typeof response !== "object"
+          || !Number.isSafeInteger(response.statusCode)
+          || response.statusCode < 100
+          || response.statusCode > 599
+        ) {
+          this.lastStatusClass = "invalid_response";
+          throw new SdkError("transport_error", "invalid transport response");
+        }
+        this.lastStatusClass = statusClass(response.statusCode);
         if (response.statusCode === 401) {
           throw new SdkError("unauthenticated", "transport rejected the API key");
         }
+        if (response.statusCode === 429) {
+          throw new SdkError("rate_limited", "transport rate limited the batch", {
+            retryAfterMs: response.retryAfterMs
+          });
+        }
         if (response.statusCode >= 200 && response.statusCode < 300) {
-          this.events = [];
           return { statusCode: response.statusCode, attempts };
         }
-        if (response.statusCode >= 500 && attempts < maxAttempts) {
+        const retryableStatus = response.statusCode === 408 || response.statusCode >= 500;
+        if (retryableStatus && attempts < maxAttempts) {
           continue;
         }
-        throw new SdkError("transport_error", `unexpected transport status ${response.statusCode}`);
+        throw new SdkError("transport_error", `unexpected transport status ${response.statusCode}`, {
+          retryable: retryableStatus
+        });
       } catch (error) {
         if (error instanceof SdkError) {
           throw error;
         }
         if (error instanceof TransportError && error.retryable && attempts < maxAttempts) {
+          this.lastStatusClass = "network_error";
           continue;
         }
         if (error instanceof TransportError) {
-          throw new SdkError(error.code, error.message);
+          this.lastStatusClass = "network_error";
+          throw new SdkError(error.code, error.message, { retryable: error.retryable });
         }
         throw error;
       }
@@ -215,6 +863,256 @@ class LogBrewClient {
   }
 }
 
+function automaticRetryDelayMs(deliveryIntervalMs, consecutiveFailures) {
+  const exponent = Math.min(consecutiveFailures - 1, 30);
+  const maximumDelay = Math.min(MAX_DELIVERY_INTERVAL_MS, deliveryIntervalMs * (2 ** exponent));
+  const minimumDelay = Math.ceil(maximumDelay / 2);
+  return minimumDelay + Math.floor(Math.random() * (maximumDelay - minimumDelay + 1));
+}
+
+function statusClass(statusCode) {
+  if (statusCode >= 200 && statusCode < 300) {
+    return "success";
+  }
+  if (statusCode >= 400 && statusCode < 500) {
+    return "client_error";
+  }
+  if (statusCode >= 500) {
+    return "server_error";
+  }
+  return "other_status";
+}
+
+function nextBoundedTimestamp(previous) {
+  const now = Date.now();
+  if (!Number.isFinite(now)) {
+    return previous;
+  }
+  const bounded = Math.min(Number.MAX_SAFE_INTEGER, Math.max(0, Math.floor(now)));
+  return Math.max(previous, bounded);
+}
+
+function addBounded(current, increment) {
+  return Math.min(Number.MAX_SAFE_INTEGER, current + increment);
+}
+
+function utf8ByteLength(value) {
+  let bytes = 0;
+  for (let index = 0; index < value.length; index += 1) {
+    const codeUnit = value.charCodeAt(index);
+    if (codeUnit < 0x80) {
+      bytes += 1;
+    } else if (codeUnit < 0x800) {
+      bytes += 2;
+    } else if (codeUnit >= 0xd800 && codeUnit <= 0xdbff && index + 1 < value.length) {
+      const nextCodeUnit = value.charCodeAt(index + 1);
+      if (nextCodeUnit >= 0xdc00 && nextCodeUnit <= 0xdfff) {
+        bytes += 4;
+        index += 1;
+      } else {
+        bytes += 3;
+      }
+    } else {
+      bytes += 3;
+    }
+  }
+  return bytes;
+}
+
+function incrementBounded(value) {
+  return value >= Number.MAX_SAFE_INTEGER ? Number.MAX_SAFE_INTEGER : value + 1;
+}
+
+function validateTransport(transport) {
+  if (transport === undefined) {
+    return;
+  }
+  if (!transport || Array.isArray(transport) || typeof transport !== "object" || typeof transport.send !== "function") {
+    throw new SdkError("validation_error", "transport.send must be a function");
+  }
+}
+
+function validateEventStore(eventStore) {
+  if (eventStore === undefined) {
+    return;
+  }
+  if (!eventStore || Array.isArray(eventStore) || typeof eventStore !== "object") {
+    throw new SdkError("validation_error", "eventStore must be an object");
+  }
+  for (const method of ["load", "append", "acknowledge", "purge", "close"]) {
+    if (typeof eventStore[method] !== "function") {
+      throw new SdkError("validation_error", `eventStore.${method} must be a function`);
+    }
+  }
+}
+
+function createEventStoreFromQueueFactory(eventQueueFactory, config) {
+  const queue = eventQueueFactory({
+    ...config,
+    restoreEvent: restoreStoredEvent
+  });
+  validateEventQueue(queue);
+  return {
+    load() {
+      const events = queue.events();
+      const count = queue.length();
+      if (!Array.isArray(events) || events.length !== count) {
+        throw invalidStoredRecord();
+      }
+      return events.map((event, index) => ({
+        event,
+        eventBytes: queue.eventBytesAt(index),
+        serializedEvent: queue.serializedAt(index)
+      }));
+    },
+    append(record) {
+      return queue.append({
+        event: record.event,
+        byteCount: record.eventBytes,
+        serialized: record.serializedEvent
+      });
+    },
+    acknowledge(count) {
+      return queue.acknowledge(count);
+    },
+    purge() {
+      return queue.acknowledge(queue.length());
+    },
+    close() {
+      return queue.close();
+    }
+  };
+}
+
+function validateEventQueue(queue) {
+  const methods = [
+    "acknowledge",
+    "append",
+    "byteCount",
+    "close",
+    "eventBytesAt",
+    "events",
+    "length",
+    "serializedAt"
+  ];
+  if (!queue || Array.isArray(queue) || typeof queue !== "object" || methods.some((method) => typeof queue[method] !== "function")) {
+    throw new SdkError("validation_error", "event queue factory returned an invalid queue");
+  }
+}
+
+function restoreStoredEvent(serializedEvent) {
+  if (typeof serializedEvent !== "string" || serializedEvent === "") {
+    throw invalidStoredRecord();
+  }
+  let event;
+  try {
+    event = JSON.parse(serializedEvent);
+  } catch {
+    throw invalidStoredRecord();
+  }
+  return normalizeStoredRecord({
+    event,
+    eventBytes: utf8ByteLength(serializedEvent),
+    serializedEvent
+  }).event;
+}
+
+function requireSynchronousStoreResult(operation, result) {
+  if (result && typeof result.then === "function") {
+    throw new SdkError("persistence_error", `eventStore.${operation} must complete synchronously`);
+  }
+  return result;
+}
+
+function loadStoredEvents({
+  batchPrefixBytes,
+  batchSuffixBytes,
+  eventStore,
+  maxBatchBytes,
+  maxQueueBytes,
+  maxQueueSize
+}) {
+  if (!eventStore) {
+    return {
+      events: [],
+      queuedEventBytes: 0,
+      serializedEventBytes: [],
+      serializedEvents: []
+    };
+  }
+
+  const records = requireSynchronousStoreResult("load", eventStore.load());
+  if (!Array.isArray(records)) {
+    throw invalidStoredRecord();
+  }
+  if (records.length > maxQueueSize) {
+    throw new SdkError("persistence_error", "recovered event count exceeds maxQueueSize");
+  }
+
+  const events = [];
+  const serializedEvents = [];
+  const serializedEventBytes = [];
+  let queuedEventBytes = 0;
+  for (const record of records) {
+    const normalized = normalizeStoredRecord(record);
+    if (batchPrefixBytes + normalized.eventBytes + batchSuffixBytes > maxBatchBytes) {
+      throw new SdkError("persistence_error", "recovered event exceeds maxBatchBytes");
+    }
+    queuedEventBytes += normalized.eventBytes;
+    if (queuedEventBytes > maxQueueBytes) {
+      throw new SdkError("persistence_error", "recovered event bytes exceed maxQueueBytes");
+    }
+    events.push(normalized.event);
+    serializedEvents.push(normalized.serializedEvent);
+    serializedEventBytes.push(normalized.eventBytes);
+  }
+  return { events, queuedEventBytes, serializedEventBytes, serializedEvents };
+}
+
+function normalizeStoredRecord(record) {
+  try {
+    if (!record || Array.isArray(record) || typeof record !== "object") {
+      throw invalidStoredRecord();
+    }
+    const { event, eventBytes, serializedEvent } = record;
+    if (!event || Array.isArray(event) || typeof event !== "object") {
+      throw invalidStoredRecord();
+    }
+    const validator = EVENT_VALIDATORS.get(event.type);
+    if (!validator || !Number.isSafeInteger(eventBytes) || eventBytes <= 0 || typeof serializedEvent !== "string") {
+      throw invalidStoredRecord();
+    }
+    requireNonEmpty("event id", event.id);
+    requireTimestamp(event.timestamp);
+    if (!event.attributes || Array.isArray(event.attributes) || typeof event.attributes !== "object") {
+      throw invalidStoredRecord();
+    }
+    const normalizedEvent = {
+      type: event.type,
+      id: event.id,
+      timestamp: event.timestamp,
+      attributes: validator(event.attributes)
+    };
+    if (JSON.stringify(normalizedEvent) !== serializedEvent || utf8ByteLength(serializedEvent) !== eventBytes) {
+      throw invalidStoredRecord();
+    }
+    return {
+      event: cloneEvent(normalizedEvent),
+      eventBytes,
+      serializedEvent
+    };
+  } catch (error) {
+    if (error instanceof SdkError && error.code === "persistence_error") {
+      throw error;
+    }
+    throw invalidStoredRecord();
+  }
+}
+
+function invalidStoredRecord() {
+  return new SdkError("persistence_error", "event store returned an invalid record");
+}
+
 function installLogBrewConsoleCapture(config) {
   if (!config || typeof config !== "object") {
     throw new SdkError("validation_error", "console capture config must be an object");
@@ -352,6 +1250,197 @@ function logAttributesFromConsoleArgs(method, args, options = {}) {
   };
 }
 
+function createIssueAttributesFromError(error, options = {}) {
+  if (!options || Array.isArray(options) || typeof options !== "object") {
+    throw new SdkError("validation_error", "error issue options must be an object");
+  }
+  const details = errorDetails(error);
+  const stackFrames = javascriptStackFrames(details.stack, options.debugIdMap);
+  const frame = stackFrames[0] ?? null;
+  const source = stringOrUndefined(options.source) ?? "javascript.error";
+  const metadata = {
+    ...compactMetadata(options.metadata),
+    source,
+    errorName: details.name,
+    ...(details.message ? { errorMessage: details.message } : {}),
+    ...(frame ? {
+      errorFrameFile: frame.filename,
+      errorFrameLine: frame.line,
+      errorFrameColumn: frame.column
+    } : {}),
+    ...issueGroupingMetadata(source, details, frame, options.fingerprint),
+    ...errorCauseMetadata(error),
+    ...(stringOrUndefined(options.release) ? { release: options.release } : {}),
+    ...(stringOrUndefined(options.environment) ? { environment: options.environment } : {}),
+    ...(stringOrUndefined(options.service) ? { service: options.service } : {}),
+    ...(stringOrUndefined(options.runtime) ? { runtime: options.runtime } : {}),
+    ...(stringOrUndefined(options.platform) ? { platform: options.platform } : {}),
+    ...traceMetadata(options.trace),
+    ...releaseArtifactMetadata(frame),
+    ...(options.includeErrorStack === true && details.stack ? { errorStack: details.stack } : {})
+  };
+
+  return {
+    title: stringOrUndefined(options.title) ?? details.name,
+    level: normalizeSeverity("issue level", options.level ?? "error"),
+    ...(stringOrUndefined(options.message) ? { message: options.message } : details.message ? { message: details.message } : {}),
+    ...(stackFrames.length > 0 ? { stackFrames } : {}),
+    metadata: compactMetadata(metadata)
+  };
+}
+
+function errorDetails(error) {
+  if (error instanceof Error) {
+    return {
+      name: stringOrUndefined(error.name) ?? "Error",
+      message: stringOrUndefined(error.message),
+      stack: typeof error.stack === "string" && error.stack.trim() !== "" ? error.stack : undefined
+    };
+  }
+  if (error && typeof error === "object") {
+    const name = typeof error.name === "string" && error.name.trim() !== "" ? error.name : "Error";
+    const message = typeof error.message === "string" && error.message.trim() !== "" ? error.message : undefined;
+    const stack = typeof error.stack === "string" && error.stack.trim() !== "" ? error.stack : undefined;
+    return { name, message, stack };
+  }
+  if (typeof error === "string" && error.trim() !== "") {
+    return { name: "Error", message: error };
+  }
+  return { name: "Error" };
+}
+
+function issueGroupingMetadata(source, details, frame, fingerprint) {
+  const groupingKey = frame
+    ? `${source}:${details.name}:${frame.filename}`
+    : `${source}:${details.name}`;
+  const explicitFingerprint = issueFingerprintOrUndefined(fingerprint);
+  return {
+    issueGroupingKey: groupingKey,
+    issueGroupingSource: explicitFingerprint ? "explicit_fingerprint" : frame ? "error_type_and_frame" : "error_type",
+    ...(explicitFingerprint ? { issueFingerprint: explicitFingerprint } : {})
+  };
+}
+
+function issueFingerprintOrUndefined(value) {
+  if (value === undefined || value === null) {
+    return undefined;
+  }
+  if (typeof value !== "string" || value.trim() === "") {
+    throw new SdkError("validation_error", "issue fingerprint must be a non-empty string");
+  }
+  return value.trim();
+}
+
+function errorCauseMetadata(error) {
+  const state = {
+    items: [],
+    seen: new Set(),
+    sawExceptionGroup: false,
+    truncated: false
+  };
+  if (isObjectLike(error)) {
+    state.seen.add(error);
+    collectNestedErrorCauses(error, state);
+  }
+  if (state.items.length === 0) {
+    return {};
+  }
+  return {
+    errorCauseCount: state.items.length,
+    errorCauseTypes: state.items.map((item) => item.type).join(","),
+    errorCauseSources: state.items.map((item) => item.source).join(","),
+    ...(state.sawExceptionGroup ? { errorExceptionGroup: true } : {}),
+    ...(state.truncated ? { errorCauseTruncated: true } : {})
+  };
+}
+
+function collectNestedErrorCauses(parent, state) {
+  if (!isObjectLike(parent)) {
+    return;
+  }
+  if ("cause" in parent) {
+    collectErrorCause(parent.cause, "cause", state);
+  }
+  if (Array.isArray(parent.errors)) {
+    state.sawExceptionGroup = true;
+    for (const [index, child] of parent.errors.entries()) {
+      collectErrorCause(child, `errors[${index}]`, state);
+    }
+  }
+}
+
+function collectErrorCause(value, source, state) {
+  if (value === undefined || value === null) {
+    return;
+  }
+  if (state.items.length >= MAX_ERROR_CAUSES) {
+    state.truncated = true;
+    return;
+  }
+  if (isObjectLike(value)) {
+    if (state.seen.has(value)) {
+      state.truncated = true;
+      return;
+    }
+    state.seen.add(value);
+  }
+  state.items.push({
+    source,
+    type: errorCauseType(value)
+  });
+  collectNestedErrorCauses(value, state);
+}
+
+function errorCauseType(value) {
+  if (isObjectLike(value)) {
+    const constructorName = safeCauseTypeName(value.constructor?.name);
+    if (value instanceof Error) {
+      if (constructorName && constructorName !== "Error") {
+        return constructorName;
+      }
+      const builtinName = BUILTIN_ERROR_NAMES.has(value.name) ? value.name : undefined;
+      return builtinName ?? constructorName ?? "Error";
+    }
+    return constructorName ?? "Object";
+  }
+  return "NonError";
+}
+
+function safeCauseTypeName(value) {
+  return typeof value === "string" && /^[A-Za-z_$][A-Za-z0-9_$]{0,63}$/u.test(value) ? value : undefined;
+}
+
+function isObjectLike(value) {
+  return value !== null && (typeof value === "object" || typeof value === "function");
+}
+
+function traceMetadata(trace) {
+  if (trace === undefined || trace === null) {
+    return {};
+  }
+  const normalized = normalizeLogTraceContext(trace);
+  if (!normalized) {
+    return {};
+  }
+  return {
+    traceId: normalized.traceId,
+    spanId: normalized.spanId,
+    ...(normalized.parentSpanId ? { parentSpanId: normalized.parentSpanId } : {}),
+    ...(normalized.sampled !== undefined ? { sampled: normalized.sampled } : {})
+  };
+}
+
+function releaseArtifactMetadata(frame) {
+  if (!frame?.debugId) {
+    return {};
+  }
+  return {
+    releaseArtifactType: "sourcemap",
+    releaseArtifactCodeFile: frame.filename,
+    releaseArtifactDebugId: frame.debugId
+  };
+}
+
 function logbrewLevelFromConsoleMethod(method) {
   switch (method) {
     case "debug":
@@ -450,6 +1539,44 @@ function createTraceparentHeaders(input) {
   return { traceparent: createTraceparent(input) };
 }
 
+const {
+  createBaggage,
+  createTraceContextHeaders,
+  createTracestate,
+  parseBaggage,
+  parseTracestate
+} = buildTraceContextHelpers({
+  SdkError,
+  createTraceparent
+});
+
+const createSupportTicketDraft = buildCreateSupportTicketDraft({
+  SdkError,
+  requireAllowedValue,
+  requireNonEmpty,
+  requireTraceId
+});
+
+const {
+  createLogBrewOpenTelemetrySpanExporter,
+  createLogBrewOpenTelemetrySpanProcessor,
+  logbrewTraceContextFromCurrentOpenTelemetrySpan,
+  logbrewTraceContextFromOpenTelemetrySpan,
+  logbrewTraceContextFromOpenTelemetrySpanContext,
+  spanAttributesFromOpenTelemetryReadableSpan
+} = buildOpenTelemetryHelpers({
+  compactMetadata,
+  isMetadataValue,
+  LogBrewClient,
+  maxSpanEvents: MAX_SPAN_EVENTS,
+  maxSpanLinks: MAX_SPAN_LINKS,
+  requireNonEmpty,
+  requireSpanId,
+  requireTraceId,
+  SdkError,
+  stringOrUndefined
+});
+
 function spanAttributesFromTraceparent(traceparent, attributes) {
   if (!attributes || Array.isArray(attributes) || typeof attributes !== "object") {
     throw new SdkError("validation_error", "span attributes must be an object");
@@ -463,6 +1590,8 @@ function spanAttributesFromTraceparent(traceparent, attributes) {
       throw new SdkError("validation_error", "span durationMs must be non-negative");
     }
   }
+  const events = validateSpanEvents(attributes.events);
+  const links = validateSpanLinks(attributes.links);
 
   return {
     name: attributes.name,
@@ -471,6 +1600,8 @@ function spanAttributesFromTraceparent(traceparent, attributes) {
     parentSpanId: context.parentSpanId,
     status: attributes.status,
     ...(attributes.durationMs !== undefined ? { durationMs: attributes.durationMs } : {}),
+    ...(events !== undefined ? { events } : {}),
+    ...(links !== undefined ? { links } : {}),
     ...(attributes.metadata !== undefined ? { metadata: compactMetadata(attributes.metadata) } : {})
   };
 }
@@ -495,6 +1626,7 @@ function createLogBrewPinoDestination(config) {
     : () => new Date().toISOString();
   const eventIdPrefix = config.eventIdPrefix ?? "pino";
   const onError = typeof config.onError === "function" ? config.onError : () => {};
+  const traceProvider = typeof config.traceProvider === "function" ? config.traceProvider : null;
   const state = {
     captured: 0,
     pendingFlush: Promise.resolve(null)
@@ -513,7 +1645,8 @@ function createLogBrewPinoDestination(config) {
             logAttributesFromPinoRecord(record, {
               includeErrorStack,
               logger,
-              metadata
+              metadata,
+              trace: traceFromProvider(traceProvider, onError)
             })
           );
           if (flushOnWrite && transport) {
@@ -552,7 +1685,8 @@ function logAttributesFromPinoRecord(record, options = {}) {
   const metadata = {
     ...compactMetadata(options.metadata),
     pinoLevel: pinoLevelLabel(record.level),
-    ...pinoContextMetadata(record)
+    ...pinoContextMetadata(record),
+    ...traceMetadataFromLogContext(options.trace)
   };
   if (typeof record.level === "number" && Number.isFinite(record.level)) {
     metadata.pinoLevelNumber = record.level;
@@ -587,6 +1721,7 @@ function createLogBrewWinstonTransport(config) {
     : () => new Date().toISOString();
   const eventIdPrefix = config.eventIdPrefix ?? "winston";
   const onError = typeof config.onError === "function" ? config.onError : () => {};
+  const traceProvider = typeof config.traceProvider === "function" ? config.traceProvider : null;
   const state = {
     captured: 0,
     pendingFlush: Promise.resolve(null)
@@ -608,6 +1743,7 @@ function createLogBrewWinstonTransport(config) {
           onError,
           state,
           timestamp,
+          traceProvider,
           transport
         });
       } catch (error) {
@@ -663,7 +1799,8 @@ function captureWinstonInfo(config) {
     logAttributesFromWinstonInfo(config.info, {
       includeErrorStack: config.includeErrorStack,
       logger: config.logger,
-      metadata: config.metadata
+      metadata: config.metadata,
+      trace: traceFromProvider(config.traceProvider, config.onError)
     })
   );
   if (config.flushOnWrite && config.transport) {
@@ -683,7 +1820,8 @@ function logAttributesFromWinstonInfo(info, options = {}) {
   const metadata = {
     ...compactMetadata(options.metadata),
     winstonLevel: winstonLevelLabel(info.level),
-    ...winstonContextMetadata(info)
+    ...winstonContextMetadata(info),
+    ...traceMetadataFromLogContext(options.trace)
   };
   addWinstonErrorMetadata(metadata, info, options.includeErrorStack === true);
 
@@ -942,6 +2080,67 @@ function addPinoErrorMetadata(metadata, error, includeErrorStack) {
   }
 }
 
+function traceFromProvider(provider, onError) {
+  if (!provider) {
+    return undefined;
+  }
+  try {
+    return provider();
+  } catch (error) {
+    onError(error);
+    return undefined;
+  }
+}
+
+function traceMetadataFromLogContext(trace) {
+  const normalized = normalizeLogTraceContext(trace);
+  if (!normalized) {
+    return {};
+  }
+  return {
+    traceId: normalized.traceId,
+    spanId: normalized.spanId,
+    ...(normalized.parentSpanId !== undefined ? { parentSpanId: normalized.parentSpanId } : {}),
+    ...(normalized.sampled !== undefined ? { sampled: normalized.sampled } : {})
+  };
+}
+
+function normalizeLogTraceContext(trace) {
+  if (!trace || Array.isArray(trace) || typeof trace !== "object") {
+    return undefined;
+  }
+  const traceId = normalizeTraceId(trace.traceId);
+  const spanId = normalizeSpanId(trace.spanId);
+  if (!traceId || !spanId) {
+    return undefined;
+  }
+  const parentSpanId = normalizeSpanId(trace.parentSpanId);
+  return {
+    traceId,
+    spanId,
+    ...(parentSpanId !== undefined ? { parentSpanId } : {}),
+    ...(typeof trace.sampled === "boolean" ? { sampled: trace.sampled } : {})
+  };
+}
+
+function normalizeTraceId(traceId) {
+  try {
+    requireTraceId(traceId);
+  } catch {
+    return undefined;
+  }
+  return traceId.toLowerCase();
+}
+
+function normalizeSpanId(spanId) {
+  try {
+    requireSpanId("trace spanId", spanId);
+  } catch {
+    return undefined;
+  }
+  return spanId.toLowerCase();
+}
+
 function requireNonEmpty(label, value) {
   if (typeof value !== "string" || value.trim() === "") {
     throw new SdkError("validation_error", `${label} must be non-empty`);
@@ -964,6 +2163,25 @@ function requireFiniteNumber(label, value) {
   }
 }
 
+function requirePositiveInteger(label, value) {
+  if (!Number.isSafeInteger(value) || value <= 0) {
+    throw new SdkError("validation_error", `${label} must be a positive integer`);
+  }
+}
+
+function requireNonNegativeInteger(label, value) {
+  if (!Number.isSafeInteger(value) || value < 0) {
+    throw new SdkError("validation_error", `${label} must be a non-negative integer`);
+  }
+}
+
+function retryAfterMsOrUndefined(value) {
+  if (value === undefined) {
+    return undefined;
+  }
+  return Number.isSafeInteger(value) && value >= 0 ? value : undefined;
+}
+
 function requireTraceId(traceId) {
   if (typeof traceId !== "string" || !/^[0-9a-fA-F]{32}$/u.test(traceId)) {
     throw new SdkError("validation_error", "traceId must be 32 lowercase or uppercase hex characters");
@@ -1013,10 +2231,29 @@ function cloneMetadata(metadata) {
   return { ...metadata };
 }
 
+function cloneSpanEvents(events) {
+  return events.map((event) => event.metadata === undefined
+    ? { ...event }
+    : { ...event, metadata: { ...event.metadata } });
+}
+
+function cloneSpanLinks(links) {
+  return links.map((link) => link.metadata === undefined
+    ? { ...link }
+    : { ...link, metadata: { ...link.metadata } });
+}
+
 function cloneEvent(event) {
-  const attributes = event.attributes.metadata === undefined
-    ? { ...event.attributes }
-    : { ...event.attributes, metadata: { ...event.attributes.metadata } };
+  const attributes = { ...event.attributes };
+  if (event.attributes.metadata !== undefined) {
+    attributes.metadata = { ...event.attributes.metadata };
+  }
+  if (Array.isArray(event.attributes.events)) {
+    attributes.events = cloneSpanEvents(event.attributes.events);
+  }
+  if (Array.isArray(event.attributes.links)) {
+    attributes.links = cloneSpanLinks(event.attributes.links);
+  }
   return { ...event, attributes };
 }
 
@@ -1043,10 +2280,12 @@ function validateEnvironment(attributes) {
 function validateIssue(attributes) {
   requireNonEmpty("issue title", attributes.title);
   const level = normalizeSeverity("issue level", attributes.level);
+  const stackFrames = validateIssueStackFrames(attributes.stackFrames);
   return withMetadata({
     title: attributes.title,
     level,
-    ...(attributes.message !== undefined ? { message: attributes.message } : {})
+    ...(attributes.message !== undefined ? { message: attributes.message } : {}),
+    ...(stackFrames !== undefined ? { stackFrames } : {})
   }, attributes.metadata);
 }
 
@@ -1078,16 +2317,94 @@ function validateSpan(attributes) {
       throw new SdkError("validation_error", "span durationMs must be non-negative");
     }
   }
+  const events = validateSpanEvents(attributes.events);
+  const links = validateSpanLinks(attributes.links);
   return withMetadata({
     name: attributes.name,
     traceId: attributes.traceId,
     spanId: attributes.spanId,
     status: attributes.status,
     ...(attributes.parentSpanId !== undefined ? { parentSpanId: attributes.parentSpanId } : {}),
-    ...(attributes.durationMs !== undefined ? { durationMs: attributes.durationMs } : {})
+    ...(attributes.durationMs !== undefined ? { durationMs: attributes.durationMs } : {}),
+    ...(events !== undefined ? { events } : {}),
+    ...(links !== undefined ? { links } : {})
   }, attributes.metadata);
 }
 
+function validateSpanEvents(events) {
+  if (events === undefined) {
+    return undefined;
+  }
+  if (!Array.isArray(events)) {
+    throw new SdkError("validation_error", "span events must be an array");
+  }
+  if (events.length > MAX_SPAN_EVENTS) {
+    throw new SdkError("validation_error", `span events must contain at most ${MAX_SPAN_EVENTS} entries`);
+  }
+  if (events.length === 0) {
+    return undefined;
+  }
+
+  return events.map((event) => {
+    if (!event || Array.isArray(event) || typeof event !== "object") {
+      throw new SdkError("validation_error", "span event must be an object");
+    }
+    requireNonEmpty("span event name", event.name);
+    if (event.timestamp !== undefined) {
+      requireTimestamp(event.timestamp);
+    }
+    const summary = {
+      name: event.name,
+      ...(event.timestamp !== undefined ? { timestamp: event.timestamp } : {})
+    };
+    if (event.metadata !== undefined) {
+      const metadata = compactMetadata(event.metadata);
+      if (Object.keys(metadata).length > 0) {
+        summary.metadata = metadata;
+      }
+    }
+    return summary;
+  });
+}
+
+function validateSpanLinks(links) {
+  if (links === undefined) {
+    return undefined;
+  }
+  if (!Array.isArray(links)) {
+    throw new SdkError("validation_error", "span links must be an array");
+  }
+  if (links.length > MAX_SPAN_LINKS) {
+    throw new SdkError("validation_error", `span links must contain at most ${MAX_SPAN_LINKS} entries`);
+  }
+  if (links.length === 0) {
+    return undefined;
+  }
+
+  return links.map((link) => {
+    if (!link || Array.isArray(link) || typeof link !== "object") {
+      throw new SdkError("validation_error", "span link must be an object");
+    }
+    requireTraceId(link.traceId);
+    requireSpanId("span link spanId", link.spanId);
+    if (link.sampled !== undefined && typeof link.sampled !== "boolean") {
+      throw new SdkError("validation_error", "span link sampled must be a boolean");
+    }
+    const summary = {
+      traceId: link.traceId.toLowerCase(),
+      spanId: link.spanId.toLowerCase(),
+      ...(link.sampled !== undefined ? { sampled: link.sampled } : {})
+    };
+    if (link.metadata !== undefined) {
+      const metadata = compactMetadata(link.metadata);
+      if (Object.keys(metadata).length > 0) {
+        summary.metadata = metadata;
+      }
+    }
+    return summary;
+  });
+}
+
 function validateAction(attributes) {
   requireNonEmpty("action name", attributes.name);
   requireAllowedValue("action status", attributes.status, ACTION_STATUSES);
@@ -1317,21 +2634,34 @@ function formatConsoleArgument(value, includeErrorStack) {
 }
 
 module.exports = {
+  createBaggage,
+  createIssueAttributesFromError,
   createNetworkMilestoneAttributes,
   createProductActionAttributes,
+  createLogBrewOpenTelemetrySpanExporter,
+  createLogBrewOpenTelemetrySpanProcessor,
+  createSupportTicketDraft,
+  createTraceContextHeaders,
   createTraceparent,
   createTraceparentHeaders,
+  createTracestate,
   createLogBrewPinoDestination,
   createLogBrewWinstonTransport,
   installLogBrewConsoleCapture,
   LogBrewClient,
+  logbrewTraceContextFromCurrentOpenTelemetrySpan,
+  logbrewTraceContextFromOpenTelemetrySpan,
+  logbrewTraceContextFromOpenTelemetrySpanContext,
   logAttributesFromConsoleArgs,
   logAttributesFromPinoRecord,
   logAttributesFromWinstonInfo,
   logbrewLevelFromConsoleMethod,
+  parseBaggage,
   parseTraceparent,
+  parseTracestate,
   RecordingTransport,
   SdkError,
+  spanAttributesFromOpenTelemetryReadableSpan,
   spanAttributesFromTraceparent,
   TransportError
 };