@databricks/appkit 0.1.5 → 0.3.0

package/dist/stream/arrow-stream-processor.js

@@ -1,4 +1,11 @@
+import { createLogger } from "../logging/logger.js";
+import { ExecutionError } from "../errors/execution.js";
+import { ValidationError } from "../errors/validation.js";
+import { init_errors } from "../errors/index.js";
+
 //#region src/stream/arrow-stream-processor.ts
+init_errors();
+const logger = createLogger("stream:arrow");
 const BACKOFF_MULTIPLIER = 1e3;
 var ArrowStreamProcessor = class ArrowStreamProcessor {
 	static {
@@ -38,7 +45,7 @@ var ArrowStreamProcessor = class ArrowStreamProcessor {
 	* @returns Raw concatenated IPC bytes with schema
 	*/
 	async processChunks(chunks, schema, signal) {
-		if (chunks.length === 0) throw new Error("No Arrow chunks provided");
+		if (chunks.length === 0) throw ValidationError.missingField("chunks");
 		const buffers = await this.downloadChunksRaw(chunks, signal);
 		return {
 			data: this.concatenateBuffers(buffers),
@@ -74,30 +81,30 @@ var ArrowStreamProcessor = class ArrowStreamProcessor {
 			try {
 				const externalLink = chunk.external_link;
 				if (!externalLink) {
-					console.error("External link is required", chunk);
+					logger.error("External link is required for chunk: %O", chunk);
 					continue;
 				}
 				const response = await fetch(externalLink, { signal: combinedSignal });
-				if (!response.ok) throw new Error(`Failed to download chunk ${chunk.chunk_index}: ${response.status} ${response.statusText}`);
+				if (!response.ok) throw ExecutionError.statementFailed(`Failed to download chunk ${chunk.chunk_index}: ${response.status} ${response.statusText}`);
 				const arrayBuffer = await response.arrayBuffer();
 				return new Uint8Array(arrayBuffer);
 			} catch (error) {
 				lastError = error;
 				if (timeoutController.signal.aborted) lastError = /* @__PURE__ */ new Error(`Chunk ${chunk.chunk_index} download timed out after ${this.options.timeout}ms`);
-				if (signal?.aborted) throw new Error("Arrow stream processing was aborted");
+				if (signal?.aborted) throw ExecutionError.canceled();
 				if (attempt < this.options.retries - 1) await this.delay(2 ** attempt * BACKOFF_MULTIPLIER);
 			} finally {
 				clearTimeout(timeoutId);
 			}
 		}
-		throw new Error(`Failed to download chunk ${chunk.chunk_index} after ${this.options.retries} attempts: ${lastError?.message}`);
+		throw ExecutionError.statementFailed(`Failed to download chunk ${chunk.chunk_index} after ${this.options.retries} attempts: ${lastError?.message}`);
 	}
 	/**
 	* Concatenate multiple Uint8Array buffers into a single buffer.
 	* Pre-allocates the result array for efficiency.
 	*/
 	concatenateBuffers(buffers) {
-		if (buffers.length === 0) throw new Error("No buffers to concatenate");
+		if (buffers.length === 0) throw ValidationError.missingField("buffers");
 		if (buffers.length === 1) return buffers[0];
 		const totalLength = buffers.reduce((sum, buf) => sum + buf.length, 0);
 		const result = new Uint8Array(totalLength);

package/dist/stream/arrow-stream-processor.js.map

@@ -1 +1 @@
-{"version":3,"file":"arrow-stream-processor.js","names":[],"sources":["../../src/stream/arrow-stream-processor.ts"],"sourcesContent":["import type { sql } from \"@databricks/sdk-experimental\";\n\ntype ResultManifest = sql.ResultManifest;\ntype ExternalLink = sql.ExternalLink;\n\nexport interface ArrowStreamOptions {\n  maxConcurrentDownloads: number;\n  timeout: number;\n  retries: number;\n}\n\n/**\n * Result from zero-copy Arrow chunk processing.\n * Contains raw IPC bytes without server-side parsing.\n */\nexport interface ArrowRawResult {\n  /** Concatenated raw Arrow IPC bytes */\n  data: Uint8Array;\n  /** Schema from Databricks manifest (not parsed from Arrow) */\n  schema: ResultManifest[\"schema\"];\n}\n\nconst BACKOFF_MULTIPLIER = 1000;\n\nexport class ArrowStreamProcessor {\n  static readonly DEFAULT_MAX_CONCURRENT_DOWNLOADS = 5;\n  static readonly DEFAULT_TIMEOUT = 30000;\n  static readonly DEFAULT_RETRIES = 3;\n\n  constructor(\n    private options: ArrowStreamOptions = {\n      maxConcurrentDownloads:\n        ArrowStreamProcessor.DEFAULT_MAX_CONCURRENT_DOWNLOADS,\n      timeout: ArrowStreamProcessor.DEFAULT_TIMEOUT,\n      retries: ArrowStreamProcessor.DEFAULT_RETRIES,\n    },\n  ) {\n    this.options = {\n      maxConcurrentDownloads:\n        options.maxConcurrentDownloads ??\n        ArrowStreamProcessor.DEFAULT_MAX_CONCURRENT_DOWNLOADS,\n      timeout: options.timeout ?? ArrowStreamProcessor.DEFAULT_TIMEOUT,\n      retries: options.retries ?? ArrowStreamProcessor.DEFAULT_RETRIES,\n    };\n  }\n\n  /**\n   * Process Arrow chunks using zero-copy proxy pattern.\n   *\n   * Downloads raw IPC bytes from external links and concatenates them\n   * without parsing into Arrow Tables on the server. This reduces:\n   * - Memory usage by ~50% (no parsed Table representation)\n   * - CPU usage (no tableFromIPC/tableToIPC calls)\n   *\n   * The client is responsible for parsing the IPC bytes.\n   *\n   * @param chunks - External links to Arrow IPC data\n   * @param schema - Schema from Databricks manifest\n   * @param signal - Optional abort signal\n   * @returns Raw concatenated IPC bytes with schema\n   */\n  async processChunks(\n    chunks: ExternalLink[],\n    schema: ResultManifest[\"schema\"],\n    signal?: AbortSignal,\n  ): Promise<ArrowRawResult> {\n    if (chunks.length === 0) {\n      throw new Error(\"No Arrow chunks provided\");\n    }\n\n    const buffers = await this.downloadChunksRaw(chunks, signal);\n    const data = this.concatenateBuffers(buffers);\n\n    return { data, schema };\n  }\n\n  /**\n   * Download all chunks as raw bytes with concurrency control.\n   */\n  private async downloadChunksRaw(\n    chunks: ExternalLink[],\n    signal?: AbortSignal,\n  ): Promise<Uint8Array[]> {\n    const semaphore = new Semaphore(this.options.maxConcurrentDownloads);\n\n    const downloadPromises = chunks.map(async (chunk) => {\n      await semaphore.acquire();\n      try {\n        return await this.downloadChunkRaw(chunk, signal);\n      } finally {\n        semaphore.release();\n      }\n    });\n\n    return Promise.all(downloadPromises);\n  }\n\n  /**\n   * Download a single chunk as raw bytes with retry logic.\n   */\n  private async downloadChunkRaw(\n    chunk: ExternalLink,\n    signal?: AbortSignal,\n  ): Promise<Uint8Array> {\n    let lastError: Error | null = null;\n\n    for (let attempt = 0; attempt < this.options.retries; attempt++) {\n      const timeoutController = new AbortController();\n      const timeoutId = setTimeout(() => {\n        timeoutController.abort();\n      }, this.options.timeout);\n\n      const combinedSignal = signal\n        ? this.combineAbortSignals(signal, timeoutController.signal)\n        : timeoutController.signal;\n\n      try {\n        const externalLink = chunk.external_link;\n        if (!externalLink) {\n          console.error(\"External link is required\", chunk);\n          continue;\n        }\n\n        const response = await fetch(externalLink, {\n          signal: combinedSignal,\n        });\n\n        if (!response.ok) {\n          throw new Error(\n            `Failed to download chunk ${chunk.chunk_index}: ${response.status} ${response.statusText}`,\n          );\n        }\n\n        const arrayBuffer = await response.arrayBuffer();\n        return new Uint8Array(arrayBuffer);\n      } catch (error) {\n        lastError = error as Error;\n\n        if (timeoutController.signal.aborted) {\n          lastError = new Error(\n            `Chunk ${chunk.chunk_index} download timed out after ${this.options.timeout}ms`,\n          );\n        }\n\n        if (signal?.aborted) {\n          throw new Error(\"Arrow stream processing was aborted\");\n        }\n\n        if (attempt < this.options.retries - 1) {\n          await this.delay(2 ** attempt * BACKOFF_MULTIPLIER);\n        }\n      } finally {\n        clearTimeout(timeoutId);\n      }\n    }\n\n    throw new Error(\n      `Failed to download chunk ${chunk.chunk_index} after ${this.options.retries} attempts: ${lastError?.message}`,\n    );\n  }\n\n  /**\n   * Concatenate multiple Uint8Array buffers into a single buffer.\n   * Pre-allocates the result array for efficiency.\n   */\n  private concatenateBuffers(buffers: Uint8Array[]): Uint8Array {\n    if (buffers.length === 0) {\n      throw new Error(\"No buffers to concatenate\");\n    }\n\n    if (buffers.length === 1) {\n      return buffers[0];\n    }\n\n    const totalLength = buffers.reduce((sum, buf) => sum + buf.length, 0);\n    const result = new Uint8Array(totalLength);\n\n    let offset = 0;\n    for (const buffer of buffers) {\n      result.set(buffer, offset);\n      offset += buffer.length;\n    }\n\n    return result;\n  }\n\n  /**\n   * Combines multiple AbortSignals into one.\n   * The combined signal aborts when any of the input signals abort.\n   */\n  private combineAbortSignals(...signals: AbortSignal[]): AbortSignal {\n    const controller = new AbortController();\n\n    for (const signal of signals) {\n      if (signal.aborted) {\n        controller.abort();\n        return controller.signal;\n      }\n      signal.addEventListener(\"abort\", () => controller.abort(), {\n        once: true,\n      });\n    }\n\n    return controller.signal;\n  }\n\n  private delay(ms: number): Promise<void> {\n    return new Promise((resolve) => setTimeout(resolve, ms));\n  }\n}\n\nclass Semaphore {\n  private permits: number;\n  private waiting: (() => void)[] = [];\n\n  constructor(permits: number) {\n    this.permits = permits;\n  }\n\n  async acquire(): Promise<void> {\n    if (this.permits > 0) {\n      this.permits--;\n      return;\n    }\n\n    return new Promise<void>((resolve) => {\n      this.waiting.push(resolve);\n    });\n  }\n\n  release(): void {\n    if (this.waiting.length > 0) {\n      const next = this.waiting.shift();\n\n      if (next) {\n        next();\n      }\n    } else {\n      this.permits++;\n    }\n  }\n}\n"],"mappings":"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"}
+{"version":3,"file":"arrow-stream-processor.js","names":[],"sources":["../../src/stream/arrow-stream-processor.ts"],"sourcesContent":["import type { sql } from \"@databricks/sdk-experimental\";\nimport { ExecutionError, ValidationError } from \"../errors\";\nimport { createLogger } from \"../logging/logger\";\n\nconst logger = createLogger(\"stream:arrow\");\n\ntype ResultManifest = sql.ResultManifest;\ntype ExternalLink = sql.ExternalLink;\n\nexport interface ArrowStreamOptions {\n  maxConcurrentDownloads: number;\n  timeout: number;\n  retries: number;\n}\n\n/**\n * Result from zero-copy Arrow chunk processing.\n * Contains raw IPC bytes without server-side parsing.\n */\nexport interface ArrowRawResult {\n  /** Concatenated raw Arrow IPC bytes */\n  data: Uint8Array;\n  /** Schema from Databricks manifest (not parsed from Arrow) */\n  schema: ResultManifest[\"schema\"];\n}\n\nconst BACKOFF_MULTIPLIER = 1000;\n\nexport class ArrowStreamProcessor {\n  static readonly DEFAULT_MAX_CONCURRENT_DOWNLOADS = 5;\n  static readonly DEFAULT_TIMEOUT = 30000;\n  static readonly DEFAULT_RETRIES = 3;\n\n  constructor(\n    private options: ArrowStreamOptions = {\n      maxConcurrentDownloads:\n        ArrowStreamProcessor.DEFAULT_MAX_CONCURRENT_DOWNLOADS,\n      timeout: ArrowStreamProcessor.DEFAULT_TIMEOUT,\n      retries: ArrowStreamProcessor.DEFAULT_RETRIES,\n    },\n  ) {\n    this.options = {\n      maxConcurrentDownloads:\n        options.maxConcurrentDownloads ??\n        ArrowStreamProcessor.DEFAULT_MAX_CONCURRENT_DOWNLOADS,\n      timeout: options.timeout ?? ArrowStreamProcessor.DEFAULT_TIMEOUT,\n      retries: options.retries ?? ArrowStreamProcessor.DEFAULT_RETRIES,\n    };\n  }\n\n  /**\n   * Process Arrow chunks using zero-copy proxy pattern.\n   *\n   * Downloads raw IPC bytes from external links and concatenates them\n   * without parsing into Arrow Tables on the server. This reduces:\n   * - Memory usage by ~50% (no parsed Table representation)\n   * - CPU usage (no tableFromIPC/tableToIPC calls)\n   *\n   * The client is responsible for parsing the IPC bytes.\n   *\n   * @param chunks - External links to Arrow IPC data\n   * @param schema - Schema from Databricks manifest\n   * @param signal - Optional abort signal\n   * @returns Raw concatenated IPC bytes with schema\n   */\n  async processChunks(\n    chunks: ExternalLink[],\n    schema: ResultManifest[\"schema\"],\n    signal?: AbortSignal,\n  ): Promise<ArrowRawResult> {\n    if (chunks.length === 0) {\n      throw ValidationError.missingField(\"chunks\");\n    }\n\n    const buffers = await this.downloadChunksRaw(chunks, signal);\n    const data = this.concatenateBuffers(buffers);\n\n    return { data, schema };\n  }\n\n  /**\n   * Download all chunks as raw bytes with concurrency control.\n   */\n  private async downloadChunksRaw(\n    chunks: ExternalLink[],\n    signal?: AbortSignal,\n  ): Promise<Uint8Array[]> {\n    const semaphore = new Semaphore(this.options.maxConcurrentDownloads);\n\n    const downloadPromises = chunks.map(async (chunk) => {\n      await semaphore.acquire();\n      try {\n        return await this.downloadChunkRaw(chunk, signal);\n      } finally {\n        semaphore.release();\n      }\n    });\n\n    return Promise.all(downloadPromises);\n  }\n\n  /**\n   * Download a single chunk as raw bytes with retry logic.\n   */\n  private async downloadChunkRaw(\n    chunk: ExternalLink,\n    signal?: AbortSignal,\n  ): Promise<Uint8Array> {\n    let lastError: Error | null = null;\n\n    for (let attempt = 0; attempt < this.options.retries; attempt++) {\n      const timeoutController = new AbortController();\n      const timeoutId = setTimeout(() => {\n        timeoutController.abort();\n      }, this.options.timeout);\n\n      const combinedSignal = signal\n        ? this.combineAbortSignals(signal, timeoutController.signal)\n        : timeoutController.signal;\n\n      try {\n        const externalLink = chunk.external_link;\n        if (!externalLink) {\n          logger.error(\"External link is required for chunk: %O\", chunk);\n          continue;\n        }\n\n        const response = await fetch(externalLink, {\n          signal: combinedSignal,\n        });\n\n        if (!response.ok) {\n          throw ExecutionError.statementFailed(\n            `Failed to download chunk ${chunk.chunk_index}: ${response.status} ${response.statusText}`,\n          );\n        }\n\n        const arrayBuffer = await response.arrayBuffer();\n        return new Uint8Array(arrayBuffer);\n      } catch (error) {\n        lastError = error as Error;\n\n        if (timeoutController.signal.aborted) {\n          lastError = new Error(\n            `Chunk ${chunk.chunk_index} download timed out after ${this.options.timeout}ms`,\n          );\n        }\n\n        if (signal?.aborted) {\n          throw ExecutionError.canceled();\n        }\n\n        if (attempt < this.options.retries - 1) {\n          await this.delay(2 ** attempt * BACKOFF_MULTIPLIER);\n        }\n      } finally {\n        clearTimeout(timeoutId);\n      }\n    }\n\n    throw ExecutionError.statementFailed(\n      `Failed to download chunk ${chunk.chunk_index} after ${this.options.retries} attempts: ${lastError?.message}`,\n    );\n  }\n\n  /**\n   * Concatenate multiple Uint8Array buffers into a single buffer.\n   * Pre-allocates the result array for efficiency.\n   */\n  private concatenateBuffers(buffers: Uint8Array[]): Uint8Array {\n    if (buffers.length === 0) {\n      throw ValidationError.missingField(\"buffers\");\n    }\n\n    if (buffers.length === 1) {\n      return buffers[0];\n    }\n\n    const totalLength = buffers.reduce((sum, buf) => sum + buf.length, 0);\n    const result = new Uint8Array(totalLength);\n\n    let offset = 0;\n    for (const buffer of buffers) {\n      result.set(buffer, offset);\n      offset += buffer.length;\n    }\n\n    return result;\n  }\n\n  /**\n   * Combines multiple AbortSignals into one.\n   * The combined signal aborts when any of the input signals abort.\n   */\n  private combineAbortSignals(...signals: AbortSignal[]): AbortSignal {\n    const controller = new AbortController();\n\n    for (const signal of signals) {\n      if (signal.aborted) {\n        controller.abort();\n        return controller.signal;\n      }\n      signal.addEventListener(\"abort\", () => controller.abort(), {\n        once: true,\n      });\n    }\n\n    return controller.signal;\n  }\n\n  private delay(ms: number): Promise<void> {\n    return new Promise((resolve) => setTimeout(resolve, ms));\n  }\n}\n\nclass Semaphore {\n  private permits: number;\n  private waiting: (() => void)[] = [];\n\n  constructor(permits: number) {\n    this.permits = permits;\n  }\n\n  async acquire(): Promise<void> {\n    if (this.permits > 0) {\n      this.permits--;\n      return;\n    }\n\n    return new Promise<void>((resolve) => {\n      this.waiting.push(resolve);\n    });\n  }\n\n  release(): void {\n    if (this.waiting.length > 0) {\n      const next = this.waiting.shift();\n\n      if (next) {\n        next();\n      }\n    } else {\n      this.permits++;\n    }\n  }\n}\n"],"mappings":"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"}

package/dist/stream/buffers.js

@@ -1,7 +1,11 @@
+import { ValidationError } from "../errors/validation.js";
+import { init_errors } from "../errors/index.js";
+
 //#region src/stream/buffers.ts
+init_errors();
 var RingBuffer = class {
 	constructor(capacity, keyExtractor) {
-		if (capacity <= 0) throw new Error("Capacity must be greater than 0");
+		if (capacity <= 0) throw ValidationError.invalidValue("capacity", capacity, "greater than 0");
 		this.capacity = capacity;
 		this.buffer = new Array(capacity).fill(null);
 		this.writeIndex = 0;

package/dist/stream/buffers.js.map

@@ -1 +1 @@
-{"version":3,"file":"buffers.js","names":[],"sources":["../../src/stream/buffers.ts"],"sourcesContent":["import type { BufferedEvent } from \"./types\";\n\n// generic ring buffer implementation\nexport class RingBuffer<T> {\n  public buffer: (T | null)[];\n  public capacity: number;\n  private writeIndex: number;\n  private size: number;\n  private keyExtractor: (item: T) => string;\n  private keyIndex: Map<string, number>;\n\n  constructor(capacity: number, keyExtractor: (item: T) => string) {\n    if (capacity <= 0) {\n      throw new Error(\"Capacity must be greater than 0\");\n    }\n\n    this.capacity = capacity;\n    this.buffer = new Array(capacity).fill(null);\n    this.writeIndex = 0;\n    this.size = 0;\n    this.keyExtractor = keyExtractor;\n    this.keyIndex = new Map();\n  }\n\n  // add an item to the buffer\n  add(item: T): void {\n    const key = this.keyExtractor(item);\n\n    // check if item already exists\n    const existingIndex = this.keyIndex.get(key);\n    if (existingIndex !== undefined) {\n      // update existing item\n      this.buffer[existingIndex] = item;\n      return;\n    }\n\n    // evict least recently used item if at capacity\n    const evicted = this.buffer[this.writeIndex];\n    if (evicted !== null) {\n      const evictedKey = this.keyExtractor(evicted);\n      this.keyIndex.delete(evictedKey);\n    }\n\n    // add new item\n    this.buffer[this.writeIndex] = item;\n    this.keyIndex.set(key, this.writeIndex);\n\n    // update write index and size\n    this.writeIndex = (this.writeIndex + 1) % this.capacity;\n    this.size = Math.min(this.size + 1, this.capacity);\n  }\n\n  // get an item from the buffer\n  get(key: string): T | null {\n    const index = this.keyIndex.get(key);\n    if (index === undefined) return null;\n\n    return this.buffer[index];\n  }\n\n  // check if an item exists in the buffer\n  has(key: string): boolean {\n    return this.keyIndex.has(key);\n  }\n\n  // remove an item from the buffer\n  remove(key: string): void {\n    const index = this.keyIndex.get(key);\n    if (index === undefined) return;\n\n    // remove item from buffer\n    this.buffer[index] = null;\n    this.keyIndex.delete(key);\n\n    // update size\n    this.size = Math.max(this.size - 1, 0);\n  }\n\n  // get all items from the buffer\n  getAll(): T[] {\n    const result: T[] = [];\n\n    // iterate over buffer in order of insertion\n    for (let i = 0; i < this.size; i++) {\n      // calculate index of item in buffer\n      const index =\n        (this.writeIndex - this.size + i + this.capacity) % this.capacity;\n      // add item to result if not null\n      const item = this.buffer[index];\n      if (item !== null) {\n        result.push(item);\n      }\n    }\n    return result;\n  }\n\n  // get the size of the buffer\n  getSize(): number {\n    return this.size;\n  }\n\n  // clear the buffer\n  clear(): void {\n    this.buffer = new Array(this.capacity).fill(null);\n    this.keyIndex.clear();\n    this.writeIndex = 0;\n    this.size = 0;\n  }\n}\n\n// event ring buffer implementation\nexport class EventRingBuffer {\n  private buffer: RingBuffer<BufferedEvent>;\n\n  constructor(capacity: number = 100) {\n    this.buffer = new RingBuffer<BufferedEvent>(capacity, (event) => event.id);\n  }\n\n  // add an event to the buffer\n  add(event: BufferedEvent): void {\n    this.buffer.add(event);\n  }\n\n  // check if an event exists in the buffer\n  has(eventId: string): boolean {\n    return this.buffer.has(eventId);\n  }\n\n  // get all events since a given event id\n  getEventsSince(lastEventId: string): BufferedEvent[] {\n    const allEvents = this.buffer.getAll();\n    const result: BufferedEvent[] = [];\n    // flag to track if we've found the last event\n    let foundLastEvent = false;\n\n    // iterate over all events\n    for (const event of allEvents) {\n      // if found, add to result\n      if (foundLastEvent) {\n        result.push(event);\n        // if not found, check if it's the last event\n      } else if (event.id === lastEventId) {\n        foundLastEvent = true;\n      }\n    }\n    return result;\n  }\n\n  clear(): void {\n    this.buffer.clear();\n  }\n}\n"],"mappings":";AAGA,IAAa,aAAb,MAA2B;CAQzB,YAAY,UAAkB,cAAmC;AAC/D,MAAI,YAAY,EACd,OAAM,IAAI,MAAM,kCAAkC;AAGpD,OAAK,WAAW;AAChB,OAAK,SAAS,IAAI,MAAM,SAAS,CAAC,KAAK,KAAK;AAC5C,OAAK,aAAa;AAClB,OAAK,OAAO;AACZ,OAAK,eAAe;AACpB,OAAK,2BAAW,IAAI,KAAK;;CAI3B,IAAI,MAAe;EACjB,MAAM,MAAM,KAAK,aAAa,KAAK;EAGnC,MAAM,gBAAgB,KAAK,SAAS,IAAI,IAAI;AAC5C,MAAI,kBAAkB,QAAW;AAE/B,QAAK,OAAO,iBAAiB;AAC7B;;EAIF,MAAM,UAAU,KAAK,OAAO,KAAK;AACjC,MAAI,YAAY,MAAM;GACpB,MAAM,aAAa,KAAK,aAAa,QAAQ;AAC7C,QAAK,SAAS,OAAO,WAAW;;AAIlC,OAAK,OAAO,KAAK,cAAc;AAC/B,OAAK,SAAS,IAAI,KAAK,KAAK,WAAW;AAGvC,OAAK,cAAc,KAAK,aAAa,KAAK,KAAK;AAC/C,OAAK,OAAO,KAAK,IAAI,KAAK,OAAO,GAAG,KAAK,SAAS;;CAIpD,IAAI,KAAuB;EACzB,MAAM,QAAQ,KAAK,SAAS,IAAI,IAAI;AACpC,MAAI,UAAU,OAAW,QAAO;AAEhC,SAAO,KAAK,OAAO;;CAIrB,IAAI,KAAsB;AACxB,SAAO,KAAK,SAAS,IAAI,IAAI;;CAI/B,OAAO,KAAmB;EACxB,MAAM,QAAQ,KAAK,SAAS,IAAI,IAAI;AACpC,MAAI,UAAU,OAAW;AAGzB,OAAK,OAAO,SAAS;AACrB,OAAK,SAAS,OAAO,IAAI;AAGzB,OAAK,OAAO,KAAK,IAAI,KAAK,OAAO,GAAG,EAAE;;CAIxC,SAAc;EACZ,MAAM,SAAc,EAAE;AAGtB,OAAK,IAAI,IAAI,GAAG,IAAI,KAAK,MAAM,KAAK;GAElC,MAAM,SACH,KAAK,aAAa,KAAK,OAAO,IAAI,KAAK,YAAY,KAAK;GAE3D,MAAM,OAAO,KAAK,OAAO;AACzB,OAAI,SAAS,KACX,QAAO,KAAK,KAAK;;AAGrB,SAAO;;CAIT,UAAkB;AAChB,SAAO,KAAK;;CAId,QAAc;AACZ,OAAK,SAAS,IAAI,MAAM,KAAK,SAAS,CAAC,KAAK,KAAK;AACjD,OAAK,SAAS,OAAO;AACrB,OAAK,aAAa;AAClB,OAAK,OAAO;;;AAKhB,IAAa,kBAAb,MAA6B;CAG3B,YAAY,WAAmB,KAAK;AAClC,OAAK,SAAS,IAAI,WAA0B,WAAW,UAAU,MAAM,GAAG;;CAI5E,IAAI,OAA4B;AAC9B,OAAK,OAAO,IAAI,MAAM;;CAIxB,IAAI,SAA0B;AAC5B,SAAO,KAAK,OAAO,IAAI,QAAQ;;CAIjC,eAAe,aAAsC;EACnD,MAAM,YAAY,KAAK,OAAO,QAAQ;EACtC,MAAM,SAA0B,EAAE;EAElC,IAAI,iBAAiB;AAGrB,OAAK,MAAM,SAAS,UAElB,KAAI,eACF,QAAO,KAAK,MAAM;WAET,MAAM,OAAO,YACtB,kBAAiB;AAGrB,SAAO;;CAGT,QAAc;AACZ,OAAK,OAAO,OAAO"}
+{"version":3,"file":"buffers.js","names":[],"sources":["../../src/stream/buffers.ts"],"sourcesContent":["import { ValidationError } from \"../errors\";\nimport type { BufferedEvent } from \"./types\";\n\n// generic ring buffer implementation\nexport class RingBuffer<T> {\n  public buffer: (T | null)[];\n  public capacity: number;\n  private writeIndex: number;\n  private size: number;\n  private keyExtractor: (item: T) => string;\n  private keyIndex: Map<string, number>;\n\n  constructor(capacity: number, keyExtractor: (item: T) => string) {\n    if (capacity <= 0) {\n      throw ValidationError.invalidValue(\n        \"capacity\",\n        capacity,\n        \"greater than 0\",\n      );\n    }\n\n    this.capacity = capacity;\n    this.buffer = new Array(capacity).fill(null);\n    this.writeIndex = 0;\n    this.size = 0;\n    this.keyExtractor = keyExtractor;\n    this.keyIndex = new Map();\n  }\n\n  // add an item to the buffer\n  add(item: T): void {\n    const key = this.keyExtractor(item);\n\n    // check if item already exists\n    const existingIndex = this.keyIndex.get(key);\n    if (existingIndex !== undefined) {\n      // update existing item\n      this.buffer[existingIndex] = item;\n      return;\n    }\n\n    // evict least recently used item if at capacity\n    const evicted = this.buffer[this.writeIndex];\n    if (evicted !== null) {\n      const evictedKey = this.keyExtractor(evicted);\n      this.keyIndex.delete(evictedKey);\n    }\n\n    // add new item\n    this.buffer[this.writeIndex] = item;\n    this.keyIndex.set(key, this.writeIndex);\n\n    // update write index and size\n    this.writeIndex = (this.writeIndex + 1) % this.capacity;\n    this.size = Math.min(this.size + 1, this.capacity);\n  }\n\n  // get an item from the buffer\n  get(key: string): T | null {\n    const index = this.keyIndex.get(key);\n    if (index === undefined) return null;\n\n    return this.buffer[index];\n  }\n\n  // check if an item exists in the buffer\n  has(key: string): boolean {\n    return this.keyIndex.has(key);\n  }\n\n  // remove an item from the buffer\n  remove(key: string): void {\n    const index = this.keyIndex.get(key);\n    if (index === undefined) return;\n\n    // remove item from buffer\n    this.buffer[index] = null;\n    this.keyIndex.delete(key);\n\n    // update size\n    this.size = Math.max(this.size - 1, 0);\n  }\n\n  // get all items from the buffer\n  getAll(): T[] {\n    const result: T[] = [];\n\n    // iterate over buffer in order of insertion\n    for (let i = 0; i < this.size; i++) {\n      // calculate index of item in buffer\n      const index =\n        (this.writeIndex - this.size + i + this.capacity) % this.capacity;\n      // add item to result if not null\n      const item = this.buffer[index];\n      if (item !== null) {\n        result.push(item);\n      }\n    }\n    return result;\n  }\n\n  // get the size of the buffer\n  getSize(): number {\n    return this.size;\n  }\n\n  // clear the buffer\n  clear(): void {\n    this.buffer = new Array(this.capacity).fill(null);\n    this.keyIndex.clear();\n    this.writeIndex = 0;\n    this.size = 0;\n  }\n}\n\n// event ring buffer implementation\nexport class EventRingBuffer {\n  private buffer: RingBuffer<BufferedEvent>;\n\n  constructor(capacity: number = 100) {\n    this.buffer = new RingBuffer<BufferedEvent>(capacity, (event) => event.id);\n  }\n\n  // add an event to the buffer\n  add(event: BufferedEvent): void {\n    this.buffer.add(event);\n  }\n\n  // check if an event exists in the buffer\n  has(eventId: string): boolean {\n    return this.buffer.has(eventId);\n  }\n\n  // get all events since a given event id\n  getEventsSince(lastEventId: string): BufferedEvent[] {\n    const allEvents = this.buffer.getAll();\n    const result: BufferedEvent[] = [];\n    // flag to track if we've found the last event\n    let foundLastEvent = false;\n\n    // iterate over all events\n    for (const event of allEvents) {\n      // if found, add to result\n      if (foundLastEvent) {\n        result.push(event);\n        // if not found, check if it's the last event\n      } else if (event.id === lastEventId) {\n        foundLastEvent = true;\n      }\n    }\n    return result;\n  }\n\n  clear(): void {\n    this.buffer.clear();\n  }\n}\n"],"mappings":";;;;aAA4C;AAI5C,IAAa,aAAb,MAA2B;CAQzB,YAAY,UAAkB,cAAmC;AAC/D,MAAI,YAAY,EACd,OAAM,gBAAgB,aACpB,YACA,UACA,iBACD;AAGH,OAAK,WAAW;AAChB,OAAK,SAAS,IAAI,MAAM,SAAS,CAAC,KAAK,KAAK;AAC5C,OAAK,aAAa;AAClB,OAAK,OAAO;AACZ,OAAK,eAAe;AACpB,OAAK,2BAAW,IAAI,KAAK;;CAI3B,IAAI,MAAe;EACjB,MAAM,MAAM,KAAK,aAAa,KAAK;EAGnC,MAAM,gBAAgB,KAAK,SAAS,IAAI,IAAI;AAC5C,MAAI,kBAAkB,QAAW;AAE/B,QAAK,OAAO,iBAAiB;AAC7B;;EAIF,MAAM,UAAU,KAAK,OAAO,KAAK;AACjC,MAAI,YAAY,MAAM;GACpB,MAAM,aAAa,KAAK,aAAa,QAAQ;AAC7C,QAAK,SAAS,OAAO,WAAW;;AAIlC,OAAK,OAAO,KAAK,cAAc;AAC/B,OAAK,SAAS,IAAI,KAAK,KAAK,WAAW;AAGvC,OAAK,cAAc,KAAK,aAAa,KAAK,KAAK;AAC/C,OAAK,OAAO,KAAK,IAAI,KAAK,OAAO,GAAG,KAAK,SAAS;;CAIpD,IAAI,KAAuB;EACzB,MAAM,QAAQ,KAAK,SAAS,IAAI,IAAI;AACpC,MAAI,UAAU,OAAW,QAAO;AAEhC,SAAO,KAAK,OAAO;;CAIrB,IAAI,KAAsB;AACxB,SAAO,KAAK,SAAS,IAAI,IAAI;;CAI/B,OAAO,KAAmB;EACxB,MAAM,QAAQ,KAAK,SAAS,IAAI,IAAI;AACpC,MAAI,UAAU,OAAW;AAGzB,OAAK,OAAO,SAAS;AACrB,OAAK,SAAS,OAAO,IAAI;AAGzB,OAAK,OAAO,KAAK,IAAI,KAAK,OAAO,GAAG,EAAE;;CAIxC,SAAc;EACZ,MAAM,SAAc,EAAE;AAGtB,OAAK,IAAI,IAAI,GAAG,IAAI,KAAK,MAAM,KAAK;GAElC,MAAM,SACH,KAAK,aAAa,KAAK,OAAO,IAAI,KAAK,YAAY,KAAK;GAE3D,MAAM,OAAO,KAAK,OAAO;AACzB,OAAI,SAAS,KACX,QAAO,KAAK,KAAK;;AAGrB,SAAO;;CAIT,UAAkB;AAChB,SAAO,KAAK;;CAId,QAAc;AACZ,OAAK,SAAS,IAAI,MAAM,KAAK,SAAS,CAAC,KAAK,KAAK;AACjD,OAAK,SAAS,OAAO;AACrB,OAAK,aAAa;AAClB,OAAK,OAAO;;;AAKhB,IAAa,kBAAb,MAA6B;CAG3B,YAAY,WAAmB,KAAK;AAClC,OAAK,SAAS,IAAI,WAA0B,WAAW,UAAU,MAAM,GAAG;;CAI5E,IAAI,OAA4B;AAC9B,OAAK,OAAO,IAAI,MAAM;;CAIxB,IAAI,SAA0B;AAC5B,SAAO,KAAK,OAAO,IAAI,QAAQ;;CAIjC,eAAe,aAAsC;EACnD,MAAM,YAAY,KAAK,OAAO,QAAQ;EACtC,MAAM,SAA0B,EAAE;EAElC,IAAI,iBAAiB;AAGrB,OAAK,MAAM,SAAS,UAElB,KAAI,eACF,QAAO,KAAK,MAAM;WAET,MAAM,OAAO,YACtB,kBAAiB;AAGrB,SAAO;;CAGT,QAAc;AACZ,OAAK,OAAO,OAAO"}

package/dist/stream/stream-manager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"stream-manager.d.ts","names":[],"sources":["../../src/stream/stream-manager.ts"],"sourcesContent":[],"mappings":";;;;cAUa,aAAA;;;EAAA,QAAA,SAAa;EAAA,QAAA,YAAA;UAOF,SAAA;aAYf,CAAA,OAAA,CAAA,EAZe,YAYf;QACa,CAAA,GAAA,EADb,YACa,EAAA,OAAA,EAAA,CAAA,MAAA,EAAA,WAAA,EAAA,GAAgB,cAAhB,CAAA,GAAA,EAAA,IAAA,EAAA,OAAA,CAAA,EAAA,OAAA,CAAA,EACR,YADQ,CAAA,EAEjB,OAFiB,CAAA,IAAA,CAAA;UAAgB,CAAA,CAAA,EAAA,IAAA;gBACxB,CAAA,CAAA,EAAA,MAAA;UACT,uBAAA;EAAO,QAAA,gBAAA"}
+{"version":3,"file":"stream-manager.d.ts","names":[],"sources":["../../src/stream/stream-manager.ts"],"sourcesContent":[],"mappings":";;;;cAWa,aAAA;;;EAAA,QAAA,SAAa;EAAA,QAAA,YAAA;UAOF,SAAA;aAYf,CAAA,OAAA,CAAA,EAZe,YAYf;QACa,CAAA,GAAA,EADb,YACa,EAAA,OAAA,EAAA,CAAA,MAAA,EAAA,WAAA,EAAA,GAAgB,cAAhB,CAAA,GAAA,EAAA,IAAA,EAAA,OAAA,CAAA,EAAA,OAAA,CAAA,EACR,YADQ,CAAA,EAEjB,OAFiB,CAAA,IAAA,CAAA;UAAgB,CAAA,CAAA,EAAA,IAAA;gBACxB,CAAA,CAAA,EAAA,MAAA;UACT,uBAAA;EAAO,QAAA,gBAAA"}

package/dist/stream/stream-manager.js

@@ -5,6 +5,7 @@ import { StreamValidator } from "./validator.js";
 import { SSEWriter } from "./sse-writer.js";
 import { StreamRegistry } from "./stream-registry.js";
 import { randomUUID } from "node:crypto";
+import { context } from "@opentelemetry/api";
 
 //#region src/stream/stream-manager.ts
 var StreamManager = class {
@@ -15,8 +16,9 @@ var StreamManager = class {
 		this.bufferTTL = options?.bufferTTL ?? streamDefaults.bufferTTL;
 		this.activeOperations = /* @__PURE__ */ new Set();
 	}
-	stream(res, handler, options) {
+	async stream(res, handler, options) {
 		const { streamId } = options || {};
+		if (res.writableEnded || res.destroyed) return;
 		this.sseWriter.setupHeaders(res);
 		if (streamId && StreamValidator.validateStreamId(streamId)) {
 			const existingStream = this.streamRegistry.get(streamId);
@@ -73,10 +75,16 @@ var StreamManager = class {
 	}
 	async _createNewStream(res, handler, options) {
 		const streamId = options?.streamId ?? randomUUID();
+		if (res.writableEnded || res.destroyed) return;
 		const abortController = new AbortController();
 		const eventBuffer = new EventRingBuffer(options?.bufferSize ?? streamDefaults.bufferSize);
 		const combinedSignal = this._combineSignals(abortController.signal, options?.userSignal);
 		const heartbeat = this.sseWriter.startHeartbeat(res, combinedSignal);
+		const traceContext = context.active();
+		if (res.writableEnded || res.destroyed) {
+			clearInterval(heartbeat);
+			return;
+		}
 		const streamEntry = {
 			streamId,
 			generator: handler(combinedSignal),
@@ -84,7 +92,8 @@ var StreamManager = class {
 			clients: new Set([res]),
 			isCompleted: false,
 			lastAccess: Date.now(),
-			abortController
+			abortController,
+			traceContext
 		};
 		this.streamRegistry.add(streamEntry);
 		const streamOperation = {
@@ -103,45 +112,47 @@ var StreamManager = class {
 		this.activeOperations.delete(streamOperation);
 	}
 	async _processGeneratorInBackground(streamEntry) {
-		try {
-			for await (const event of streamEntry.generator) {
-				if (streamEntry.abortController.signal.aborted) break;
-				const eventId = randomUUID();
-				const eventData = JSON.stringify(event);
-				if (eventData.length > this.maxEventSize) {
-					const errorMsg = `Event exceeds max size of ${this.maxEventSize} bytes`;
-					const errorCode = SSEErrorCode.INVALID_REQUEST;
-					this._broadcastErrorToClients(streamEntry, eventId, errorMsg, errorCode);
-					continue;
+		return context.with(streamEntry.traceContext, async () => {
+			try {
+				for await (const event of streamEntry.generator) {
+					if (streamEntry.abortController.signal.aborted) break;
+					const eventId = randomUUID();
+					const eventData = JSON.stringify(event);
+					if (eventData.length > this.maxEventSize) {
+						const errorMsg = `Event exceeds max size of ${this.maxEventSize} bytes`;
+						const errorCode = SSEErrorCode.INVALID_REQUEST;
+						this._broadcastErrorToClients(streamEntry, eventId, errorMsg, errorCode);
+						continue;
+					}
+					streamEntry.eventBuffer.add({
+						id: eventId,
+						type: event.type,
+						data: eventData,
+						timestamp: Date.now()
+					});
+					this._broadcastEventsToClients(streamEntry, eventId, event);
+					streamEntry.lastAccess = Date.now();
 				}
+				streamEntry.isCompleted = true;
+				this._closeAllClients(streamEntry);
+				this._cleanupStream(streamEntry);
+			} catch (error) {
+				const errorMsg = error instanceof Error ? error.message : "Internal server error";
+				const errorEventId = randomUUID();
+				const errorCode = this._categorizeError(error);
 				streamEntry.eventBuffer.add({
-					id: eventId,
-					type: event.type,
-					data: eventData,
+					id: errorEventId,
+					type: "error",
+					data: JSON.stringify({
+						error: errorMsg,
+						code: errorCode
+					}),
 					timestamp: Date.now()
 				});
-				this._broadcastEventsToClients(streamEntry, eventId, event);
-				streamEntry.lastAccess = Date.now();
+				this._broadcastErrorToClients(streamEntry, errorEventId, errorMsg, errorCode, true);
+				streamEntry.isCompleted = true;
 			}
-			streamEntry.isCompleted = true;
-			this._closeAllClients(streamEntry);
-			this._cleanupStream(streamEntry);
-		} catch (error) {
-			const errorMsg = error instanceof Error ? error.message : "Internal server error";
-			const errorEventId = randomUUID();
-			const errorCode = this._categorizeError(error);
-			streamEntry.eventBuffer.add({
-				id: errorEventId,
-				type: "error",
-				data: JSON.stringify({
-					error: errorMsg,
-					code: errorCode
-				}),
-				timestamp: Date.now()
-			});
-			this._broadcastErrorToClients(streamEntry, errorEventId, errorMsg, errorCode, true);
-			streamEntry.isCompleted = true;
-		}
+		});
 	}
 	_combineSignals(internalSignal, userSignal) {
 		if (!userSignal) return internalSignal || new AbortController().signal;

package/dist/stream/stream-manager.js.map

@@ -1 +1 @@
-{"version":3,"file":"stream-manager.js","names":[],"sources":["../../src/stream/stream-manager.ts"],"sourcesContent":["import { randomUUID } from \"node:crypto\";\nimport type { IAppResponse, StreamConfig } from \"shared\";\nimport { EventRingBuffer } from \"./buffers\";\nimport { streamDefaults } from \"./defaults\";\nimport { SSEWriter } from \"./sse-writer\";\nimport { StreamRegistry } from \"./stream-registry\";\nimport { SSEErrorCode, type StreamEntry, type StreamOperation } from \"./types\";\nimport { StreamValidator } from \"./validator\";\n\n// main entry point for Server-Sent events streaming\nexport class StreamManager {\n  private activeOperations: Set<StreamOperation>;\n  private streamRegistry: StreamRegistry;\n  private sseWriter: SSEWriter;\n  private maxEventSize: number;\n  private bufferTTL: number;\n\n  constructor(options?: StreamConfig) {\n    this.streamRegistry = new StreamRegistry(\n      options?.maxActiveStreams ?? streamDefaults.maxActiveStreams,\n    );\n    this.sseWriter = new SSEWriter();\n    this.maxEventSize = options?.maxEventSize ?? streamDefaults.maxEventSize;\n    this.bufferTTL = options?.bufferTTL ?? streamDefaults.bufferTTL;\n    this.activeOperations = new Set();\n  }\n\n  // main streaming method - handles new connection and reconnection\n  stream(\n    res: IAppResponse,\n    handler: (signal: AbortSignal) => AsyncGenerator<any, void, unknown>,\n    options?: StreamConfig,\n  ): Promise<void> {\n    const { streamId } = options || {};\n\n    // setup SSE headers\n    this.sseWriter.setupHeaders(res);\n\n    // handle reconnection\n    if (streamId && StreamValidator.validateStreamId(streamId)) {\n      const existingStream = this.streamRegistry.get(streamId);\n      // if stream exists, attach to it\n      if (existingStream) {\n        return this._attachToExistingStream(res, existingStream, options);\n      }\n    }\n\n    // if stream does not exist, create a new one\n    return this._createNewStream(res, handler, options);\n  }\n\n  // abort all active operations\n  abortAll(): void {\n    this.activeOperations.forEach((operation) => {\n      if (operation.heartbeat) clearInterval(operation.heartbeat);\n      operation.controller.abort(\"Server shutdown\");\n    });\n    this.activeOperations.clear();\n    this.streamRegistry.clear();\n  }\n\n  // get the number of active operations\n  getActiveCount(): number {\n    return this.activeOperations.size;\n  }\n\n  // attach to existing stream\n  private async _attachToExistingStream(\n    res: IAppResponse,\n    streamEntry: StreamEntry,\n    options?: StreamConfig,\n  ): Promise<void> {\n    // handle reconnection - replay missed events\n    const lastEventId = res.req?.headers[\"last-event-id\"];\n\n    if (StreamValidator.validateEventId(lastEventId)) {\n      // cast to string after validation\n      const validEventId = lastEventId as string;\n      if (streamEntry.eventBuffer.has(validEventId)) {\n        const missedEvents =\n          streamEntry.eventBuffer.getEventsSince(validEventId);\n        // broadcast missed events to client\n        for (const event of missedEvents) {\n          if (options?.userSignal?.aborted) break;\n          this.sseWriter.writeBufferedEvent(res, event);\n        }\n      } else {\n        // buffer overflow - send warning\n        this.sseWriter.writeBufferOverflowWarning(res, validEventId);\n      }\n    }\n\n    // add client to stream entry\n    streamEntry.clients.add(res);\n    streamEntry.lastAccess = Date.now();\n\n    // start heartbeat\n    const combinedSignal = this._combineSignals(\n      streamEntry.abortController.signal,\n      options?.userSignal,\n    );\n    const heartbeat = this.sseWriter.startHeartbeat(res, combinedSignal);\n\n    // track operation\n    const streamOperation: StreamOperation = {\n      controller: streamEntry.abortController,\n      type: \"stream\",\n      heartbeat,\n    };\n    this.activeOperations.add(streamOperation);\n\n    // handle client disconnect\n    res.on(\"close\", () => {\n      clearInterval(heartbeat);\n      streamEntry.clients.delete(res);\n      this.activeOperations.delete(streamOperation);\n\n      // cleanup if stream is completed and no clients are connected\n      if (streamEntry.isCompleted && streamEntry.clients.size === 0) {\n        setTimeout(() => {\n          if (streamEntry.clients.size === 0) {\n            this.streamRegistry.remove(streamEntry.streamId);\n          }\n        }, this.bufferTTL);\n      }\n    });\n\n    // if stream is completed, close connection\n    if (streamEntry.isCompleted) {\n      res.end();\n      // cleanup operation\n      this.activeOperations.delete(streamOperation);\n      clearInterval(heartbeat);\n    }\n  }\n  private async _createNewStream(\n    res: IAppResponse,\n    handler: (signal: AbortSignal) => AsyncGenerator<any, void, unknown>,\n    options?: StreamConfig,\n  ): Promise<void> {\n    const streamId = options?.streamId ?? randomUUID();\n    const abortController = new AbortController();\n\n    // create event buffer\n    const eventBuffer = new EventRingBuffer(\n      options?.bufferSize ?? streamDefaults.bufferSize,\n    );\n\n    // setup signals and heartbeat\n    const combinedSignal = this._combineSignals(\n      abortController.signal,\n      options?.userSignal,\n    );\n    const heartbeat = this.sseWriter.startHeartbeat(res, combinedSignal);\n\n    // create stream entry\n    const streamEntry: StreamEntry = {\n      streamId,\n      generator: handler(combinedSignal),\n      eventBuffer,\n      clients: new Set([res]),\n      isCompleted: false,\n      lastAccess: Date.now(),\n      abortController,\n    };\n    this.streamRegistry.add(streamEntry);\n\n    // track operation\n    const streamOperation: StreamOperation = {\n      controller: abortController,\n      type: \"stream\",\n      heartbeat,\n    };\n    this.activeOperations.add(streamOperation);\n\n    // handle client disconnect\n    res.on(\"close\", () => {\n      clearInterval(heartbeat);\n      this.activeOperations.delete(streamOperation);\n      streamEntry.clients.delete(res);\n    });\n\n    await this._processGeneratorInBackground(streamEntry);\n\n    // cleanup\n    clearInterval(heartbeat);\n    this.activeOperations.delete(streamOperation);\n  }\n\n  private async _processGeneratorInBackground(\n    streamEntry: StreamEntry,\n  ): Promise<void> {\n    try {\n      // retrieve all events from generator\n      for await (const event of streamEntry.generator) {\n        if (streamEntry.abortController.signal.aborted) break;\n        const eventId = randomUUID();\n        const eventData = JSON.stringify(event);\n\n        // validate event size\n        if (eventData.length > this.maxEventSize) {\n          const errorMsg = `Event exceeds max size of ${this.maxEventSize} bytes`;\n          const errorCode = SSEErrorCode.INVALID_REQUEST;\n          // broadcast error to all connected clients\n          this._broadcastErrorToClients(\n            streamEntry,\n            eventId,\n            errorMsg,\n            errorCode,\n          );\n          continue;\n        }\n\n        // buffer event for reconnection\n        streamEntry.eventBuffer.add({\n          id: eventId,\n          type: event.type,\n          data: eventData,\n          timestamp: Date.now(),\n        });\n\n        // broadcast to all connected clients\n        this._broadcastEventsToClients(streamEntry, eventId, event);\n        streamEntry.lastAccess = Date.now();\n      }\n\n      streamEntry.isCompleted = true;\n\n      // close all clients\n      this._closeAllClients(streamEntry);\n\n      // cleanup if no clients are connected\n      this._cleanupStream(streamEntry);\n    } catch (error) {\n      const errorMsg =\n        error instanceof Error ? error.message : \"Internal server error\";\n      const errorEventId = randomUUID();\n      const errorCode = this._categorizeError(error);\n\n      // buffer error event\n      streamEntry.eventBuffer.add({\n        id: errorEventId,\n        type: \"error\",\n        data: JSON.stringify({ error: errorMsg, code: errorCode }),\n        timestamp: Date.now(),\n      });\n\n      // send error event to all connected clients\n      this._broadcastErrorToClients(\n        streamEntry,\n        errorEventId,\n        errorMsg,\n        errorCode,\n        true,\n      );\n      streamEntry.isCompleted = true;\n    }\n  }\n\n  private _combineSignals(\n    internalSignal?: AbortSignal,\n    userSignal?: AbortSignal,\n  ): AbortSignal {\n    if (!userSignal) return internalSignal || new AbortController().signal;\n\n    const signals = [internalSignal, userSignal].filter(\n      Boolean,\n    ) as AbortSignal[];\n    const controller = new AbortController();\n\n    signals.forEach((signal) => {\n      if (signal?.aborted) {\n        controller.abort(signal.reason);\n        return;\n      }\n\n      signal?.addEventListener(\n        \"abort\",\n        () => {\n          controller.abort(signal.reason);\n        },\n        { once: true },\n      );\n    });\n    return controller.signal;\n  }\n\n  // broadcast events to all connected clients\n  private _broadcastEventsToClients(\n    streamEntry: StreamEntry,\n    eventId: string,\n    event: any,\n  ): void {\n    for (const client of streamEntry.clients) {\n      if (!client.writableEnded) {\n        this.sseWriter.writeEvent(client, eventId, event);\n      }\n    }\n  }\n\n  // broadcast error to all connected clients\n  private _broadcastErrorToClients(\n    streamEntry: StreamEntry,\n    eventId: string,\n    errorMessage: string,\n    errorCode: SSEErrorCode,\n    closeClients: boolean = false,\n  ): void {\n    for (const client of streamEntry.clients) {\n      if (!client.writableEnded) {\n        this.sseWriter.writeError(client, eventId, errorMessage, errorCode);\n        if (closeClients) {\n          client.end();\n        }\n      }\n    }\n  }\n\n  // close all connected clients\n  private _closeAllClients(streamEntry: StreamEntry): void {\n    for (const client of streamEntry.clients) {\n      if (!client.writableEnded) {\n        client.end();\n      }\n    }\n  }\n\n  // cleanup stream if no clients are connected\n  private _cleanupStream(streamEntry: StreamEntry): void {\n    if (streamEntry.clients.size === 0) {\n      setTimeout(() => {\n        if (streamEntry.clients.size === 0) {\n          this.streamRegistry.remove(streamEntry.streamId);\n        }\n      }, this.bufferTTL);\n    }\n  }\n\n  private _categorizeError(error: unknown): SSEErrorCode {\n    if (error instanceof Error) {\n      const message = error.message.toLowerCase();\n      if (message.includes(\"timeout\") || message.includes(\"timed out\")) {\n        return SSEErrorCode.TIMEOUT;\n      }\n\n      if (message.includes(\"unavailable\") || message.includes(\"econnrefused\")) {\n        return SSEErrorCode.TEMPORARY_UNAVAILABLE;\n      }\n\n      if (error.name === \"AbortError\") {\n        return SSEErrorCode.STREAM_ABORTED;\n      }\n    }\n\n    return SSEErrorCode.INTERNAL_ERROR;\n  }\n}\n"],"mappings":"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"}
+{"version":3,"file":"stream-manager.js","names":[],"sources":["../../src/stream/stream-manager.ts"],"sourcesContent":["import { randomUUID } from \"node:crypto\";\nimport { context } from \"@opentelemetry/api\";\nimport type { IAppResponse, StreamConfig } from \"shared\";\nimport { EventRingBuffer } from \"./buffers\";\nimport { streamDefaults } from \"./defaults\";\nimport { SSEWriter } from \"./sse-writer\";\nimport { StreamRegistry } from \"./stream-registry\";\nimport { SSEErrorCode, type StreamEntry, type StreamOperation } from \"./types\";\nimport { StreamValidator } from \"./validator\";\n\n// main entry point for Server-Sent events streaming\nexport class StreamManager {\n  private activeOperations: Set<StreamOperation>;\n  private streamRegistry: StreamRegistry;\n  private sseWriter: SSEWriter;\n  private maxEventSize: number;\n  private bufferTTL: number;\n\n  constructor(options?: StreamConfig) {\n    this.streamRegistry = new StreamRegistry(\n      options?.maxActiveStreams ?? streamDefaults.maxActiveStreams,\n    );\n    this.sseWriter = new SSEWriter();\n    this.maxEventSize = options?.maxEventSize ?? streamDefaults.maxEventSize;\n    this.bufferTTL = options?.bufferTTL ?? streamDefaults.bufferTTL;\n    this.activeOperations = new Set();\n  }\n\n  // main streaming method - handles new connection and reconnection\n  async stream(\n    res: IAppResponse,\n    handler: (signal: AbortSignal) => AsyncGenerator<any, void, unknown>,\n    options?: StreamConfig,\n  ): Promise<void> {\n    const { streamId } = options || {};\n\n    // check if response is already closed\n    if (res.writableEnded || res.destroyed) {\n      return;\n    }\n\n    // setup SSE headers\n    this.sseWriter.setupHeaders(res);\n\n    // handle reconnection\n    if (streamId && StreamValidator.validateStreamId(streamId)) {\n      const existingStream = this.streamRegistry.get(streamId);\n      // if stream exists, attach to it\n      if (existingStream) {\n        return this._attachToExistingStream(res, existingStream, options);\n      }\n    }\n\n    // if stream does not exist, create a new one\n    return this._createNewStream(res, handler, options);\n  }\n\n  // abort all active operations\n  abortAll(): void {\n    this.activeOperations.forEach((operation) => {\n      if (operation.heartbeat) clearInterval(operation.heartbeat);\n      operation.controller.abort(\"Server shutdown\");\n    });\n    this.activeOperations.clear();\n    this.streamRegistry.clear();\n  }\n\n  // get the number of active operations\n  getActiveCount(): number {\n    return this.activeOperations.size;\n  }\n\n  // attach to existing stream\n  private async _attachToExistingStream(\n    res: IAppResponse,\n    streamEntry: StreamEntry,\n    options?: StreamConfig,\n  ): Promise<void> {\n    // handle reconnection - replay missed events\n    const lastEventId = res.req?.headers[\"last-event-id\"];\n\n    if (StreamValidator.validateEventId(lastEventId)) {\n      // cast to string after validation\n      const validEventId = lastEventId as string;\n      if (streamEntry.eventBuffer.has(validEventId)) {\n        const missedEvents =\n          streamEntry.eventBuffer.getEventsSince(validEventId);\n        // broadcast missed events to client\n        for (const event of missedEvents) {\n          if (options?.userSignal?.aborted) break;\n          this.sseWriter.writeBufferedEvent(res, event);\n        }\n      } else {\n        // buffer overflow - send warning\n        this.sseWriter.writeBufferOverflowWarning(res, validEventId);\n      }\n    }\n\n    // add client to stream entry\n    streamEntry.clients.add(res);\n    streamEntry.lastAccess = Date.now();\n\n    // start heartbeat\n    const combinedSignal = this._combineSignals(\n      streamEntry.abortController.signal,\n      options?.userSignal,\n    );\n    const heartbeat = this.sseWriter.startHeartbeat(res, combinedSignal);\n\n    // track operation\n    const streamOperation: StreamOperation = {\n      controller: streamEntry.abortController,\n      type: \"stream\",\n      heartbeat,\n    };\n    this.activeOperations.add(streamOperation);\n\n    // handle client disconnect\n    res.on(\"close\", () => {\n      clearInterval(heartbeat);\n      streamEntry.clients.delete(res);\n      this.activeOperations.delete(streamOperation);\n\n      // cleanup if stream is completed and no clients are connected\n      if (streamEntry.isCompleted && streamEntry.clients.size === 0) {\n        setTimeout(() => {\n          if (streamEntry.clients.size === 0) {\n            this.streamRegistry.remove(streamEntry.streamId);\n          }\n        }, this.bufferTTL);\n      }\n    });\n\n    // if stream is completed, close connection\n    if (streamEntry.isCompleted) {\n      res.end();\n      // cleanup operation\n      this.activeOperations.delete(streamOperation);\n      clearInterval(heartbeat);\n    }\n  }\n  private async _createNewStream(\n    res: IAppResponse,\n    handler: (signal: AbortSignal) => AsyncGenerator<any, void, unknown>,\n    options?: StreamConfig,\n  ): Promise<void> {\n    const streamId = options?.streamId ?? randomUUID();\n\n    // abort stream if response is closed\n    if (res.writableEnded || res.destroyed) {\n      return;\n    }\n\n    const abortController = new AbortController();\n\n    // create event buffer\n    const eventBuffer = new EventRingBuffer(\n      options?.bufferSize ?? streamDefaults.bufferSize,\n    );\n\n    // setup signals and heartbeat\n    const combinedSignal = this._combineSignals(\n      abortController.signal,\n      options?.userSignal,\n    );\n    const heartbeat = this.sseWriter.startHeartbeat(res, combinedSignal);\n\n    // capture the current trace context at stream creation time\n    const traceContext = context.active();\n\n    // abort stream if response is closed\n    if (res.writableEnded || res.destroyed) {\n      clearInterval(heartbeat);\n      return;\n    }\n\n    // create stream entry\n    const streamEntry: StreamEntry = {\n      streamId,\n      generator: handler(combinedSignal),\n      eventBuffer,\n      clients: new Set([res]),\n      isCompleted: false,\n      lastAccess: Date.now(),\n      abortController,\n      traceContext,\n    };\n    this.streamRegistry.add(streamEntry);\n\n    // track operation\n    const streamOperation: StreamOperation = {\n      controller: abortController,\n      type: \"stream\",\n      heartbeat,\n    };\n    this.activeOperations.add(streamOperation);\n\n    res.on(\"close\", () => {\n      clearInterval(heartbeat);\n      this.activeOperations.delete(streamOperation);\n      streamEntry.clients.delete(res);\n    });\n\n    await this._processGeneratorInBackground(streamEntry);\n\n    // cleanup\n    clearInterval(heartbeat);\n    this.activeOperations.delete(streamOperation);\n  }\n\n  private async _processGeneratorInBackground(\n    streamEntry: StreamEntry,\n  ): Promise<void> {\n    // run the entire generator processing within the captured trace context\n    return context.with(streamEntry.traceContext, async () => {\n      try {\n        // retrieve all events from generator\n        for await (const event of streamEntry.generator) {\n          if (streamEntry.abortController.signal.aborted) break;\n          const eventId = randomUUID();\n          const eventData = JSON.stringify(event);\n\n          // validate event size\n          if (eventData.length > this.maxEventSize) {\n            const errorMsg = `Event exceeds max size of ${this.maxEventSize} bytes`;\n            const errorCode = SSEErrorCode.INVALID_REQUEST;\n            // broadcast error to all connected clients\n            this._broadcastErrorToClients(\n              streamEntry,\n              eventId,\n              errorMsg,\n              errorCode,\n            );\n            continue;\n          }\n\n          // buffer event for reconnection\n          streamEntry.eventBuffer.add({\n            id: eventId,\n            type: event.type,\n            data: eventData,\n            timestamp: Date.now(),\n          });\n\n          // broadcast to all connected clients\n          this._broadcastEventsToClients(streamEntry, eventId, event);\n          streamEntry.lastAccess = Date.now();\n        }\n\n        streamEntry.isCompleted = true;\n\n        // close all clients\n        this._closeAllClients(streamEntry);\n\n        // cleanup if no clients are connected\n        this._cleanupStream(streamEntry);\n      } catch (error) {\n        const errorMsg =\n          error instanceof Error ? error.message : \"Internal server error\";\n        const errorEventId = randomUUID();\n        const errorCode = this._categorizeError(error);\n\n        // buffer error event\n        streamEntry.eventBuffer.add({\n          id: errorEventId,\n          type: \"error\",\n          data: JSON.stringify({ error: errorMsg, code: errorCode }),\n          timestamp: Date.now(),\n        });\n\n        // send error event to all connected clients\n        this._broadcastErrorToClients(\n          streamEntry,\n          errorEventId,\n          errorMsg,\n          errorCode,\n          true,\n        );\n        streamEntry.isCompleted = true;\n      }\n    });\n  }\n\n  private _combineSignals(\n    internalSignal?: AbortSignal,\n    userSignal?: AbortSignal,\n  ): AbortSignal {\n    if (!userSignal) return internalSignal || new AbortController().signal;\n\n    const signals = [internalSignal, userSignal].filter(\n      Boolean,\n    ) as AbortSignal[];\n    const controller = new AbortController();\n\n    signals.forEach((signal) => {\n      if (signal?.aborted) {\n        controller.abort(signal.reason);\n        return;\n      }\n\n      signal?.addEventListener(\n        \"abort\",\n        () => {\n          controller.abort(signal.reason);\n        },\n        { once: true },\n      );\n    });\n    return controller.signal;\n  }\n\n  // broadcast events to all connected clients\n  private _broadcastEventsToClients(\n    streamEntry: StreamEntry,\n    eventId: string,\n    event: any,\n  ): void {\n    for (const client of streamEntry.clients) {\n      if (!client.writableEnded) {\n        this.sseWriter.writeEvent(client, eventId, event);\n      }\n    }\n  }\n\n  // broadcast error to all connected clients\n  private _broadcastErrorToClients(\n    streamEntry: StreamEntry,\n    eventId: string,\n    errorMessage: string,\n    errorCode: SSEErrorCode,\n    closeClients: boolean = false,\n  ): void {\n    for (const client of streamEntry.clients) {\n      if (!client.writableEnded) {\n        this.sseWriter.writeError(client, eventId, errorMessage, errorCode);\n        if (closeClients) {\n          client.end();\n        }\n      }\n    }\n  }\n\n  // close all connected clients\n  private _closeAllClients(streamEntry: StreamEntry): void {\n    for (const client of streamEntry.clients) {\n      if (!client.writableEnded) {\n        client.end();\n      }\n    }\n  }\n\n  // cleanup stream if no clients are connected\n  private _cleanupStream(streamEntry: StreamEntry): void {\n    if (streamEntry.clients.size === 0) {\n      setTimeout(() => {\n        if (streamEntry.clients.size === 0) {\n          this.streamRegistry.remove(streamEntry.streamId);\n        }\n      }, this.bufferTTL);\n    }\n  }\n\n  private _categorizeError(error: unknown): SSEErrorCode {\n    if (error instanceof Error) {\n      const message = error.message.toLowerCase();\n      if (message.includes(\"timeout\") || message.includes(\"timed out\")) {\n        return SSEErrorCode.TIMEOUT;\n      }\n\n      if (message.includes(\"unavailable\") || message.includes(\"econnrefused\")) {\n        return SSEErrorCode.TEMPORARY_UNAVAILABLE;\n      }\n\n      if (error.name === \"AbortError\") {\n        return SSEErrorCode.STREAM_ABORTED;\n      }\n    }\n\n    return SSEErrorCode.INTERNAL_ERROR;\n  }\n}\n"],"mappings":"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"}

package/dist/stream/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","names":[],"sources":["../../src/stream/types.ts"],"sourcesContent":["import type { IAppResponse } from \"shared\";\nimport type { EventRingBuffer } from \"./buffers\";\n\nexport const SSEWarningCode = {\n  BUFFER_OVERFLOW_RESTART: \"BUFFER_OVERFLOW_RESTART\",\n} as const satisfies Record<string, string>;\n\nexport type SSEWarningCode =\n  (typeof SSEWarningCode)[keyof typeof SSEWarningCode];\n\nexport const SSEErrorCode = {\n  TEMPORARY_UNAVAILABLE: \"TEMPORARY_UNAVAILABLE\",\n  TIMEOUT: \"TIMEOUT\",\n  INTERNAL_ERROR: \"INTERNAL_ERROR\",\n  INVALID_REQUEST: \"INVALID_REQUEST\",\n  STREAM_ABORTED: \"STREAM_ABORTED\",\n  STREAM_EVICTED: \"STREAM_EVICTED\",\n} as const satisfies Record<string, string>;\n\nexport type SSEErrorCode = (typeof SSEErrorCode)[keyof typeof SSEErrorCode];\n\nexport interface SSEError {\n  error: string;\n  code: SSEErrorCode;\n}\n\nexport interface BufferedEvent {\n  id: string;\n  type: string;\n  data: string;\n  timestamp: number;\n}\n\nexport interface StreamEntry {\n  streamId: string;\n  generator: AsyncGenerator<any, void, unknown>;\n  eventBuffer: EventRingBuffer;\n  clients: Set<IAppResponse>;\n  isCompleted: boolean;\n  lastAccess: number;\n  abortController: AbortController;\n}\n\nexport interface BufferEntry {\n  buffer: EventRingBuffer;\n  lastAccess: number;\n}\n\nexport interface StreamOperation {\n  controller: AbortController;\n  type: \"query\" | \"stream\";\n  heartbeat?: NodeJS.Timeout;\n}\n"],"mappings":";AAGA,MAAa,iBAAiB,EAC5B,yBAAyB,2BAC1B;AAKD,MAAa,eAAe;CAC1B,uBAAuB;CACvB,SAAS;CACT,gBAAgB;CAChB,iBAAiB;CACjB,gBAAgB;CAChB,gBAAgB;CACjB"}
+{"version":3,"file":"types.js","names":[],"sources":["../../src/stream/types.ts"],"sourcesContent":["import type { Context } from \"@opentelemetry/api\";\nimport type { IAppResponse } from \"shared\";\nimport type { EventRingBuffer } from \"./buffers\";\n\nexport const SSEWarningCode = {\n  BUFFER_OVERFLOW_RESTART: \"BUFFER_OVERFLOW_RESTART\",\n} as const satisfies Record<string, string>;\n\nexport type SSEWarningCode =\n  (typeof SSEWarningCode)[keyof typeof SSEWarningCode];\n\nexport const SSEErrorCode = {\n  TEMPORARY_UNAVAILABLE: \"TEMPORARY_UNAVAILABLE\",\n  TIMEOUT: \"TIMEOUT\",\n  INTERNAL_ERROR: \"INTERNAL_ERROR\",\n  INVALID_REQUEST: \"INVALID_REQUEST\",\n  STREAM_ABORTED: \"STREAM_ABORTED\",\n  STREAM_EVICTED: \"STREAM_EVICTED\",\n} as const satisfies Record<string, string>;\n\nexport type SSEErrorCode = (typeof SSEErrorCode)[keyof typeof SSEErrorCode];\n\nexport interface SSEError {\n  error: string;\n  code: SSEErrorCode;\n}\n\nexport interface BufferedEvent {\n  id: string;\n  type: string;\n  data: string;\n  timestamp: number;\n}\n\nexport interface StreamEntry {\n  streamId: string;\n  generator: AsyncGenerator<any, void, unknown>;\n  eventBuffer: EventRingBuffer;\n  clients: Set<IAppResponse>;\n  isCompleted: boolean;\n  lastAccess: number;\n  abortController: AbortController;\n  traceContext: Context;\n}\n\nexport interface BufferEntry {\n  buffer: EventRingBuffer;\n  lastAccess: number;\n}\n\nexport interface StreamOperation {\n  controller: AbortController;\n  type: \"query\" | \"stream\";\n  heartbeat?: NodeJS.Timeout;\n}\n"],"mappings":";AAIA,MAAa,iBAAiB,EAC5B,yBAAyB,2BAC1B;AAKD,MAAa,eAAe;CAC1B,uBAAuB;CACvB,SAAS;CACT,gBAAgB;CAChB,iBAAiB;CACjB,gBAAgB;CAChB,gBAAgB;CACjB"}

package/dist/telemetry/index.d.ts

@@ -1,4 +1,4 @@
 import { ITelemetry, InstrumentConfig, TelemetryConfig } from "./types.js";
 import { Counter, Histogram, Span as Span$1, SpanStatusCode } from "@opentelemetry/api";
-import { SeverityNumber } from "@opentelemetry/api-logs";
-export { type Counter, type Histogram, SeverityNumber, type Span$1 as Span, SpanStatusCode };
+import { SeverityNumber as SeverityNumber$1 } from "@opentelemetry/api-logs";
+export { type Counter, type Histogram, SeverityNumber$1 as SeverityNumber, type Span$1 as Span, SpanStatusCode };

package/dist/telemetry/index.js

@@ -3,6 +3,6 @@ import { instrumentations } from "./instrumentations.js";
 import { TelemetryProvider } from "./telemetry-provider.js";
 import { TelemetryManager } from "./telemetry-manager.js";
 import { SpanKind, SpanStatusCode } from "@opentelemetry/api";
-import { SeverityNumber } from "@opentelemetry/api-logs";
+import { SeverityNumber as SeverityNumber$1 } from "@opentelemetry/api-logs";
 
-export { SeverityNumber, SpanKind, SpanStatusCode };
+export { SeverityNumber$1 as SeverityNumber, SpanKind, SpanStatusCode };

package/dist/telemetry/instrumentations.js

@@ -1,3 +1,4 @@
+import { shouldIgnoreRequest } from "../utils/path-exclusions.js";
 import { ExpressInstrumentation } from "@opentelemetry/instrumentation-express";
 import { HttpInstrumentation } from "@opentelemetry/instrumentation-http";
 
@@ -10,17 +11,20 @@ import { HttpInstrumentation } from "@opentelemetry/instrumentation-http";
 * the recommended approach is to register them once in a corresponding plugin constructor.
 */
 const instrumentations = {
-	http: new HttpInstrumentation({ applyCustomAttributesOnSpan(span, request) {
-		let spanName = null;
-		if (request.route) {
-			const fullPath = (request.baseUrl || "") + (request.url?.split("?")[0] || "");
-			if (fullPath) spanName = `${request.method} ${fullPath}`;
-		} else if (request.url) {
-			const path = request.url.split("?")[0];
-			spanName = `${request.method} ${path}`;
+	http: new HttpInstrumentation({
+		ignoreIncomingRequestHook: shouldIgnoreRequest,
+		applyCustomAttributesOnSpan(span, request) {
+			let spanName = null;
+			if (request.route) {
+				const fullPath = (request.baseUrl || "") + (request.url?.split("?")[0] || "");
+				if (fullPath) spanName = `${request.method} ${fullPath}`;
+			} else if (request.url) {
+				const path = request.url.split("?")[0];
+				spanName = `${request.method} ${path}`;
+			}
+			if (spanName) span.updateName(spanName);
 		}
-		if (spanName) span.updateName(spanName);
-	} }),
+	}),
 	express: new ExpressInstrumentation({ requestHook: (span, info) => {
 		const req = info.request;
 		if (info.layerType === "request_handler" && req.route) {

package/dist/telemetry/instrumentations.js.map

@@ -1 +1 @@
-{"version":3,"file":"instrumentations.js","names":[],"sources":["../../src/telemetry/instrumentations.ts"],"sourcesContent":["import { ExpressInstrumentation } from \"@opentelemetry/instrumentation-express\";\nimport { HttpInstrumentation } from \"@opentelemetry/instrumentation-http\";\nimport type { Instrumentation } from \"@opentelemetry/instrumentation\";\n\n/**\n * Registry of pre-configured instrumentations for common use cases.\n * These can be selectively registered by plugins that need them.\n *\n * While instrumentations are generally safe to re-register,\n * the recommended approach is to register them once in a corresponding plugin constructor.\n */\nexport const instrumentations: Record<string, Instrumentation> = {\n  http: new HttpInstrumentation({\n    applyCustomAttributesOnSpan(span: any, request: any) {\n      let spanName: string | null = null;\n\n      if (request.route) {\n        const baseUrl = request.baseUrl || \"\";\n        const url = request.url?.split(\"?\")[0] || \"\";\n        const fullPath = baseUrl + url;\n        if (fullPath) {\n          spanName = `${request.method} ${fullPath}`;\n        }\n      } else if (request.url) {\n        // No Express route (e.g., static assets) - use the raw URL path\n        // Remove query string for cleaner trace names\n        const path = request.url.split(\"?\")[0];\n        spanName = `${request.method} ${path}`;\n      }\n\n      if (spanName) {\n        span.updateName(spanName);\n      }\n    },\n  }),\n  express: new ExpressInstrumentation({\n    requestHook: (span: any, info: any) => {\n      const req = info.request;\n\n      // Only update span name for route handlers (layerType: request_handler)\n      // This ensures we're not renaming middleware spans\n      if (info.layerType === \"request_handler\" && req.route) {\n        // Combine baseUrl with url to get full path with actual parameter values\n        // e.g., baseUrl=\"/api/analytics\" + url=\"/query/spend_data\" = \"/api/analytics/query/spend_data\"\n        const baseUrl = req.baseUrl || \"\";\n        const url = req.url?.split(\"?\")[0] || \"\";\n        const fullPath = baseUrl + url;\n        if (fullPath) {\n          const spanName = `${req.method} ${fullPath}`;\n          span.updateName(spanName);\n        }\n      }\n    },\n  }),\n};\n"],"mappings":";;;;;;;;;;;AAWA,MAAa,mBAAoD;CAC/D,MAAM,IAAI,oBAAoB,EAC5B,4BAA4B,MAAW,SAAc;EACnD,IAAI,WAA0B;AAE9B,MAAI,QAAQ,OAAO;GAGjB,MAAM,YAFU,QAAQ,WAAW,OACvB,QAAQ,KAAK,MAAM,IAAI,CAAC,MAAM;AAE1C,OAAI,SACF,YAAW,GAAG,QAAQ,OAAO,GAAG;aAEzB,QAAQ,KAAK;GAGtB,MAAM,OAAO,QAAQ,IAAI,MAAM,IAAI,CAAC;AACpC,cAAW,GAAG,QAAQ,OAAO,GAAG;;AAGlC,MAAI,SACF,MAAK,WAAW,SAAS;IAG9B,CAAC;CACF,SAAS,IAAI,uBAAuB,EAClC,cAAc,MAAW,SAAc;EACrC,MAAM,MAAM,KAAK;AAIjB,MAAI,KAAK,cAAc,qBAAqB,IAAI,OAAO;GAKrD,MAAM,YAFU,IAAI,WAAW,OACnB,IAAI,KAAK,MAAM,IAAI,CAAC,MAAM;AAEtC,OAAI,UAAU;IACZ,MAAM,WAAW,GAAG,IAAI,OAAO,GAAG;AAClC,SAAK,WAAW,SAAS;;;IAIhC,CAAC;CACH"}
+{"version":3,"file":"instrumentations.js","names":[],"sources":["../../src/telemetry/instrumentations.ts"],"sourcesContent":["import type { Instrumentation } from \"@opentelemetry/instrumentation\";\nimport { ExpressInstrumentation } from \"@opentelemetry/instrumentation-express\";\nimport { HttpInstrumentation } from \"@opentelemetry/instrumentation-http\";\nimport { shouldIgnoreRequest } from \"../utils/path-exclusions\";\n\n/**\n * Registry of pre-configured instrumentations for common use cases.\n * These can be selectively registered by plugins that need them.\n *\n * While instrumentations are generally safe to re-register,\n * the recommended approach is to register them once in a corresponding plugin constructor.\n */\nexport const instrumentations: Record<string, Instrumentation> = {\n  http: new HttpInstrumentation({\n    // Filter out requests before creating spans - this is the most efficient approach\n    ignoreIncomingRequestHook: shouldIgnoreRequest,\n\n    applyCustomAttributesOnSpan(span: any, request: any) {\n      let spanName: string | null = null;\n\n      if (request.route) {\n        const baseUrl = request.baseUrl || \"\";\n        const url = request.url?.split(\"?\")[0] || \"\";\n        const fullPath = baseUrl + url;\n        if (fullPath) {\n          spanName = `${request.method} ${fullPath}`;\n        }\n      } else if (request.url) {\n        // No Express route (e.g., static assets) - use the raw URL path\n        // Remove query string for cleaner trace names\n        const path = request.url.split(\"?\")[0];\n        spanName = `${request.method} ${path}`;\n      }\n\n      if (spanName) {\n        span.updateName(spanName);\n      }\n    },\n  }),\n  express: new ExpressInstrumentation({\n    requestHook: (span: any, info: any) => {\n      const req = info.request;\n\n      // Only update span name for route handlers (layerType: request_handler)\n      // This ensures we're not renaming middleware spans\n      if (info.layerType === \"request_handler\" && req.route) {\n        // Combine baseUrl with url to get full path with actual parameter values\n        // e.g., baseUrl=\"/api/analytics\" + url=\"/query/spend_data\" = \"/api/analytics/query/spend_data\"\n        const baseUrl = req.baseUrl || \"\";\n        const url = req.url?.split(\"?\")[0] || \"\";\n        const fullPath = baseUrl + url;\n        if (fullPath) {\n          const spanName = `${req.method} ${fullPath}`;\n          span.updateName(spanName);\n        }\n      }\n    },\n  }),\n};\n"],"mappings":";;;;;;;;;;;;AAYA,MAAa,mBAAoD;CAC/D,MAAM,IAAI,oBAAoB;EAE5B,2BAA2B;EAE3B,4BAA4B,MAAW,SAAc;GACnD,IAAI,WAA0B;AAE9B,OAAI,QAAQ,OAAO;IAGjB,MAAM,YAFU,QAAQ,WAAW,OACvB,QAAQ,KAAK,MAAM,IAAI,CAAC,MAAM;AAE1C,QAAI,SACF,YAAW,GAAG,QAAQ,OAAO,GAAG;cAEzB,QAAQ,KAAK;IAGtB,MAAM,OAAO,QAAQ,IAAI,MAAM,IAAI,CAAC;AACpC,eAAW,GAAG,QAAQ,OAAO,GAAG;;AAGlC,OAAI,SACF,MAAK,WAAW,SAAS;;EAG9B,CAAC;CACF,SAAS,IAAI,uBAAuB,EAClC,cAAc,MAAW,SAAc;EACrC,MAAM,MAAM,KAAK;AAIjB,MAAI,KAAK,cAAc,qBAAqB,IAAI,OAAO;GAKrD,MAAM,YAFU,IAAI,WAAW,OACnB,IAAI,KAAK,MAAM,IAAI,CAAC,MAAM;AAEtC,OAAI,UAAU;IACZ,MAAM,WAAW,GAAG,IAAI,OAAO,GAAG;AAClC,SAAK,WAAW,SAAS;;;IAIhC,CAAC;CACH"}

package/dist/telemetry/telemetry-manager.js

@@ -1,4 +1,6 @@
+import { createLogger } from "../logging/logger.js";
 import { TelemetryProvider } from "./telemetry-provider.js";
+import { AppKitSampler } from "./trace-sampler.js";
 import { getNodeAutoInstrumentations } from "@opentelemetry/auto-instrumentations-node";
 import { OTLPLogExporter } from "@opentelemetry/exporter-logs-otlp-proto";
 import { OTLPMetricExporter } from "@opentelemetry/exporter-metrics-otlp-proto";
@@ -7,11 +9,11 @@ import { registerInstrumentations } from "@opentelemetry/instrumentation";
 import { detectResources, envDetector, hostDetector, processDetector, resourceFromAttributes } from "@opentelemetry/resources";
 import { BatchLogRecordProcessor } from "@opentelemetry/sdk-logs";
 import { PeriodicExportingMetricReader } from "@opentelemetry/sdk-metrics";
-import { AlwaysOnSampler } from "@opentelemetry/sdk-trace-base";
-import { ATTR_SERVICE_NAME, ATTR_SERVICE_VERSION } from "@opentelemetry/semantic-conventions";
 import { NodeSDK } from "@opentelemetry/sdk-node";
+import { ATTR_SERVICE_NAME, ATTR_SERVICE_VERSION } from "@opentelemetry/semantic-conventions";
 
 //#region src/telemetry/telemetry-manager.ts
+const logger = createLogger("telemetry");
 var TelemetryManager = class TelemetryManager {
 	static {
 		this.DEFAULT_EXPORT_INTERVAL_MS = 1e4;
@@ -44,7 +46,7 @@ var TelemetryManager = class TelemetryManager {
 			this.sdk = new NodeSDK({
 				resource: this.createResource(config),
 				autoDetectResources: false,
-				sampler: new AlwaysOnSampler(),
+				sampler: new AppKitSampler(),
 				traceExporter: new OTLPTraceExporter({ headers: config.headers }),
 				metricReaders: [new PeriodicExportingMetricReader({
 					exporter: new OTLPMetricExporter({ headers: config.headers }),
@@ -55,9 +57,9 @@ var TelemetryManager = class TelemetryManager {
 			});
 			this.sdk.start();
 			this.registerShutdown();
-			console.log("[Telemetry] Initialized successfully");
+			logger.debug("Initialized successfully");
 		} catch (error) {
-			console.error("[Telemetry] Failed to initialize:", error);
+			logger.error("Failed to initialize: %O", error);
 		}
 	}
 	/**
@@ -103,7 +105,7 @@ var TelemetryManager = class TelemetryManager {
 			await this.sdk.shutdown();
 			this.sdk = void 0;
 		} catch (error) {
-			console.error("[Telemetry] Error shutting down:", error);
+			logger.error("Error shutting down: %O", error);
 		}
 	}
 };

package/dist/telemetry/telemetry-manager.js.map

@@ -1 +1 @@
-{"version":3,"file":"telemetry-manager.js","names":[],"sources":["../../src/telemetry/telemetry-manager.ts"],"sourcesContent":["import type { TelemetryOptions } from \"shared\";\nimport { getNodeAutoInstrumentations } from \"@opentelemetry/auto-instrumentations-node\";\nimport { OTLPLogExporter } from \"@opentelemetry/exporter-logs-otlp-proto\";\nimport { OTLPMetricExporter } from \"@opentelemetry/exporter-metrics-otlp-proto\";\nimport { OTLPTraceExporter } from \"@opentelemetry/exporter-trace-otlp-proto\";\nimport {\n  type Instrumentation,\n  registerInstrumentations as otelRegisterInstrumentations,\n} from \"@opentelemetry/instrumentation\";\nimport {\n  detectResources,\n  envDetector,\n  hostDetector,\n  processDetector,\n  type Resource,\n  resourceFromAttributes,\n} from \"@opentelemetry/resources\";\nimport { BatchLogRecordProcessor } from \"@opentelemetry/sdk-logs\";\nimport { PeriodicExportingMetricReader } from \"@opentelemetry/sdk-metrics\";\nimport { AlwaysOnSampler } from \"@opentelemetry/sdk-trace-base\";\nimport {\n  ATTR_SERVICE_NAME,\n  ATTR_SERVICE_VERSION,\n} from \"@opentelemetry/semantic-conventions\";\nimport { TelemetryProvider } from \"./telemetry-provider\";\nimport type { TelemetryConfig } from \"./types\";\nimport { NodeSDK } from \"@opentelemetry/sdk-node\";\n\nexport class TelemetryManager {\n  private static readonly DEFAULT_EXPORT_INTERVAL_MS = 10000;\n  private static readonly DEFAULT_FALLBACK_APP_NAME = \"databricks-app\";\n\n  private static instance?: TelemetryManager;\n  private sdk?: NodeSDK;\n\n  /**\n   * Create a scoped telemetry provider for a specific plugin.\n   * The plugin's name will be used as the default tracer/meter name.\n   * @param pluginName - The name of the plugin to create scoped telemetry for\n   * @param telemetryConfig - The telemetry configuration for the plugin\n   * @returns A scoped telemetry instance for the plugin\n   */\n  static getProvider(\n    pluginName: string,\n    telemetryConfig?: TelemetryOptions,\n  ): TelemetryProvider {\n    const globalManager = TelemetryManager.getInstance();\n    return new TelemetryProvider(pluginName, globalManager, telemetryConfig);\n  }\n\n  private constructor() {}\n\n  static getInstance(): TelemetryManager {\n    if (!TelemetryManager.instance) {\n      TelemetryManager.instance = new TelemetryManager();\n    }\n    return TelemetryManager.instance;\n  }\n\n  static initialize(config: Partial<TelemetryConfig> = {}): void {\n    const instance = TelemetryManager.getInstance();\n    instance._initialize(config);\n  }\n\n  private _initialize(config: Partial<TelemetryConfig>): void {\n    if (this.sdk) return;\n\n    if (!process.env.OTEL_EXPORTER_OTLP_ENDPOINT) {\n      return;\n    }\n\n    try {\n      this.sdk = new NodeSDK({\n        resource: this.createResource(config),\n        autoDetectResources: false,\n        sampler: new AlwaysOnSampler(),\n        traceExporter: new OTLPTraceExporter({ headers: config.headers }),\n        metricReaders: [\n          new PeriodicExportingMetricReader({\n            exporter: new OTLPMetricExporter({ headers: config.headers }),\n            exportIntervalMillis:\n              config.exportIntervalMs ||\n              TelemetryManager.DEFAULT_EXPORT_INTERVAL_MS,\n          }),\n        ],\n        logRecordProcessors: [\n          new BatchLogRecordProcessor(\n            new OTLPLogExporter({ headers: config.headers }),\n          ),\n        ],\n        instrumentations: this.getDefaultInstrumentations(),\n      });\n\n      this.sdk.start();\n      this.registerShutdown();\n      console.log(\"[Telemetry] Initialized successfully\");\n    } catch (error) {\n      console.error(\"[Telemetry] Failed to initialize:\", error);\n    }\n  }\n\n  /**\n   * Register OpenTelemetry instrumentations.\n   * Can be called at any time, but recommended to call in plugin constructor.\n   * @param instrumentations - Array of OpenTelemetry instrumentations to register\n   */\n  registerInstrumentations(instrumentations: Instrumentation[]): void {\n    otelRegisterInstrumentations({\n      //  global providers set by NodeSDK.start()\n      instrumentations,\n    });\n  }\n\n  private createResource(config: Partial<TelemetryConfig>): Resource {\n    const serviceName =\n      config.serviceName ||\n      process.env.OTEL_SERVICE_NAME ||\n      process.env.DATABRICKS_APP_NAME ||\n      TelemetryManager.DEFAULT_FALLBACK_APP_NAME;\n    const initialResource = resourceFromAttributes({\n      [ATTR_SERVICE_NAME]: serviceName,\n      [ATTR_SERVICE_VERSION]: config.serviceVersion ?? undefined,\n    });\n    const detectedResource = detectResources({\n      detectors: [envDetector, hostDetector, processDetector],\n    });\n    return initialResource.merge(detectedResource);\n  }\n\n  private getDefaultInstrumentations(): Instrumentation[] {\n    return [\n      ...getNodeAutoInstrumentations({\n        //\n        // enabled as a part of the server plugin\n        //\n        \"@opentelemetry/instrumentation-http\": {\n          enabled: false,\n        },\n        \"@opentelemetry/instrumentation-express\": {\n          enabled: false,\n        },\n        //\n        // reduce noise\n        //\n        \"@opentelemetry/instrumentation-fs\": {\n          enabled: false,\n        },\n        \"@opentelemetry/instrumentation-dns\": {\n          enabled: false,\n        },\n        \"@opentelemetry/instrumentation-net\": {\n          enabled: false,\n        },\n      }),\n    ];\n  }\n\n  private registerShutdown() {\n    const shutdownFn = async () => {\n      await TelemetryManager.getInstance().shutdown();\n    };\n    process.once(\"SIGTERM\", shutdownFn);\n    process.once(\"SIGINT\", shutdownFn);\n  }\n\n  private async shutdown(): Promise<void> {\n    if (!this.sdk) {\n      return;\n    }\n\n    try {\n      await this.sdk.shutdown();\n      this.sdk = undefined;\n    } catch (error) {\n      console.error(\"[Telemetry] Error shutting down:\", error);\n    }\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;AA4BA,IAAa,mBAAb,MAAa,iBAAiB;;oCACyB;;;mCACD;;;;;;;;;CAYpD,OAAO,YACL,YACA,iBACmB;AAEnB,SAAO,IAAI,kBAAkB,YADP,iBAAiB,aAAa,EACI,gBAAgB;;CAG1E,AAAQ,cAAc;CAEtB,OAAO,cAAgC;AACrC,MAAI,CAAC,iBAAiB,SACpB,kBAAiB,WAAW,IAAI,kBAAkB;AAEpD,SAAO,iBAAiB;;CAG1B,OAAO,WAAW,SAAmC,EAAE,EAAQ;AAE7D,EADiB,iBAAiB,aAAa,CACtC,YAAY,OAAO;;CAG9B,AAAQ,YAAY,QAAwC;AAC1D,MAAI,KAAK,IAAK;AAEd,MAAI,CAAC,QAAQ,IAAI,4BACf;AAGF,MAAI;AACF,QAAK,MAAM,IAAI,QAAQ;IACrB,UAAU,KAAK,eAAe,OAAO;IACrC,qBAAqB;IACrB,SAAS,IAAI,iBAAiB;IAC9B,eAAe,IAAI,kBAAkB,EAAE,SAAS,OAAO,SAAS,CAAC;IACjE,eAAe,CACb,IAAI,8BAA8B;KAChC,UAAU,IAAI,mBAAmB,EAAE,SAAS,OAAO,SAAS,CAAC;KAC7D,sBACE,OAAO,oBACP,iBAAiB;KACpB,CAAC,CACH;IACD,qBAAqB,CACnB,IAAI,wBACF,IAAI,gBAAgB,EAAE,SAAS,OAAO,SAAS,CAAC,CACjD,CACF;IACD,kBAAkB,KAAK,4BAA4B;IACpD,CAAC;AAEF,QAAK,IAAI,OAAO;AAChB,QAAK,kBAAkB;AACvB,WAAQ,IAAI,uCAAuC;WAC5C,OAAO;AACd,WAAQ,MAAM,qCAAqC,MAAM;;;;;;;;CAS7D,yBAAyB,kBAA2C;AAClE,2BAA6B,EAE3B,kBACD,CAAC;;CAGJ,AAAQ,eAAe,QAA4C;EACjE,MAAM,cACJ,OAAO,eACP,QAAQ,IAAI,qBACZ,QAAQ,IAAI,uBACZ,iBAAiB;EACnB,MAAM,kBAAkB,uBAAuB;IAC5C,oBAAoB;IACpB,uBAAuB,OAAO,kBAAkB;GAClD,CAAC;EACF,MAAM,mBAAmB,gBAAgB,EACvC,WAAW;GAAC;GAAa;GAAc;GAAgB,EACxD,CAAC;AACF,SAAO,gBAAgB,MAAM,iBAAiB;;CAGhD,AAAQ,6BAAgD;AACtD,SAAO,CACL,GAAG,4BAA4B;GAI7B,uCAAuC,EACrC,SAAS,OACV;GACD,0CAA0C,EACxC,SAAS,OACV;GAID,qCAAqC,EACnC,SAAS,OACV;GACD,sCAAsC,EACpC,SAAS,OACV;GACD,sCAAsC,EACpC,SAAS,OACV;GACF,CAAC,CACH;;CAGH,AAAQ,mBAAmB;EACzB,MAAM,aAAa,YAAY;AAC7B,SAAM,iBAAiB,aAAa,CAAC,UAAU;;AAEjD,UAAQ,KAAK,WAAW,WAAW;AACnC,UAAQ,KAAK,UAAU,WAAW;;CAGpC,MAAc,WAA0B;AACtC,MAAI,CAAC,KAAK,IACR;AAGF,MAAI;AACF,SAAM,KAAK,IAAI,UAAU;AACzB,QAAK,MAAM;WACJ,OAAO;AACd,WAAQ,MAAM,oCAAoC,MAAM"}
+{"version":3,"file":"telemetry-manager.js","names":[],"sources":["../../src/telemetry/telemetry-manager.ts"],"sourcesContent":["import { getNodeAutoInstrumentations } from \"@opentelemetry/auto-instrumentations-node\";\nimport { OTLPLogExporter } from \"@opentelemetry/exporter-logs-otlp-proto\";\nimport { OTLPMetricExporter } from \"@opentelemetry/exporter-metrics-otlp-proto\";\nimport { OTLPTraceExporter } from \"@opentelemetry/exporter-trace-otlp-proto\";\nimport {\n  type Instrumentation,\n  registerInstrumentations as otelRegisterInstrumentations,\n} from \"@opentelemetry/instrumentation\";\nimport {\n  detectResources,\n  envDetector,\n  hostDetector,\n  processDetector,\n  type Resource,\n  resourceFromAttributes,\n} from \"@opentelemetry/resources\";\nimport { BatchLogRecordProcessor } from \"@opentelemetry/sdk-logs\";\nimport { PeriodicExportingMetricReader } from \"@opentelemetry/sdk-metrics\";\nimport { NodeSDK } from \"@opentelemetry/sdk-node\";\nimport {\n  ATTR_SERVICE_NAME,\n  ATTR_SERVICE_VERSION,\n} from \"@opentelemetry/semantic-conventions\";\nimport type { TelemetryOptions } from \"shared\";\nimport { createLogger } from \"../logging/logger\";\nimport { TelemetryProvider } from \"./telemetry-provider\";\nimport { AppKitSampler } from \"./trace-sampler\";\nimport type { TelemetryConfig } from \"./types\";\n\nconst logger = createLogger(\"telemetry\");\n\nexport class TelemetryManager {\n  private static readonly DEFAULT_EXPORT_INTERVAL_MS = 10000;\n  private static readonly DEFAULT_FALLBACK_APP_NAME = \"databricks-app\";\n\n  private static instance?: TelemetryManager;\n  private sdk?: NodeSDK;\n\n  /**\n   * Create a scoped telemetry provider for a specific plugin.\n   * The plugin's name will be used as the default tracer/meter name.\n   * @param pluginName - The name of the plugin to create scoped telemetry for\n   * @param telemetryConfig - The telemetry configuration for the plugin\n   * @returns A scoped telemetry instance for the plugin\n   */\n  static getProvider(\n    pluginName: string,\n    telemetryConfig?: TelemetryOptions,\n  ): TelemetryProvider {\n    const globalManager = TelemetryManager.getInstance();\n    return new TelemetryProvider(pluginName, globalManager, telemetryConfig);\n  }\n\n  private constructor() {}\n\n  static getInstance(): TelemetryManager {\n    if (!TelemetryManager.instance) {\n      TelemetryManager.instance = new TelemetryManager();\n    }\n    return TelemetryManager.instance;\n  }\n\n  static initialize(config: Partial<TelemetryConfig> = {}): void {\n    const instance = TelemetryManager.getInstance();\n    instance._initialize(config);\n  }\n\n  private _initialize(config: Partial<TelemetryConfig>): void {\n    if (this.sdk) return;\n\n    if (!process.env.OTEL_EXPORTER_OTLP_ENDPOINT) {\n      return;\n    }\n\n    try {\n      this.sdk = new NodeSDK({\n        resource: this.createResource(config),\n        autoDetectResources: false,\n        sampler: new AppKitSampler(),\n        traceExporter: new OTLPTraceExporter({ headers: config.headers }),\n        metricReaders: [\n          new PeriodicExportingMetricReader({\n            exporter: new OTLPMetricExporter({ headers: config.headers }),\n            exportIntervalMillis:\n              config.exportIntervalMs ||\n              TelemetryManager.DEFAULT_EXPORT_INTERVAL_MS,\n          }),\n        ],\n        logRecordProcessors: [\n          new BatchLogRecordProcessor(\n            new OTLPLogExporter({ headers: config.headers }),\n          ),\n        ],\n        instrumentations: this.getDefaultInstrumentations(),\n      });\n\n      this.sdk.start();\n      this.registerShutdown();\n      logger.debug(\"Initialized successfully\");\n    } catch (error) {\n      logger.error(\"Failed to initialize: %O\", error);\n    }\n  }\n\n  /**\n   * Register OpenTelemetry instrumentations.\n   * Can be called at any time, but recommended to call in plugin constructor.\n   * @param instrumentations - Array of OpenTelemetry instrumentations to register\n   */\n  registerInstrumentations(instrumentations: Instrumentation[]): void {\n    otelRegisterInstrumentations({\n      //  global providers set by NodeSDK.start()\n      instrumentations,\n    });\n  }\n\n  private createResource(config: Partial<TelemetryConfig>): Resource {\n    const serviceName =\n      config.serviceName ||\n      process.env.OTEL_SERVICE_NAME ||\n      process.env.DATABRICKS_APP_NAME ||\n      TelemetryManager.DEFAULT_FALLBACK_APP_NAME;\n    const initialResource = resourceFromAttributes({\n      [ATTR_SERVICE_NAME]: serviceName,\n      [ATTR_SERVICE_VERSION]: config.serviceVersion ?? undefined,\n    });\n    const detectedResource = detectResources({\n      detectors: [envDetector, hostDetector, processDetector],\n    });\n    return initialResource.merge(detectedResource);\n  }\n\n  private getDefaultInstrumentations(): Instrumentation[] {\n    return [\n      ...getNodeAutoInstrumentations({\n        //\n        // enabled as a part of the server plugin\n        //\n        \"@opentelemetry/instrumentation-http\": {\n          enabled: false,\n        },\n        \"@opentelemetry/instrumentation-express\": {\n          enabled: false,\n        },\n        //\n        // reduce noise\n        //\n        \"@opentelemetry/instrumentation-fs\": {\n          enabled: false,\n        },\n        \"@opentelemetry/instrumentation-dns\": {\n          enabled: false,\n        },\n        \"@opentelemetry/instrumentation-net\": {\n          enabled: false,\n        },\n      }),\n    ];\n  }\n\n  private registerShutdown() {\n    const shutdownFn = async () => {\n      await TelemetryManager.getInstance().shutdown();\n    };\n    process.once(\"SIGTERM\", shutdownFn);\n    process.once(\"SIGINT\", shutdownFn);\n  }\n\n  private async shutdown(): Promise<void> {\n    if (!this.sdk) {\n      return;\n    }\n\n    try {\n      await this.sdk.shutdown();\n      this.sdk = undefined;\n    } catch (error) {\n      logger.error(\"Error shutting down: %O\", error);\n    }\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;AA6BA,MAAM,SAAS,aAAa,YAAY;AAExC,IAAa,mBAAb,MAAa,iBAAiB;;oCACyB;;;mCACD;;;;;;;;;CAYpD,OAAO,YACL,YACA,iBACmB;AAEnB,SAAO,IAAI,kBAAkB,YADP,iBAAiB,aAAa,EACI,gBAAgB;;CAG1E,AAAQ,cAAc;CAEtB,OAAO,cAAgC;AACrC,MAAI,CAAC,iBAAiB,SACpB,kBAAiB,WAAW,IAAI,kBAAkB;AAEpD,SAAO,iBAAiB;;CAG1B,OAAO,WAAW,SAAmC,EAAE,EAAQ;AAE7D,EADiB,iBAAiB,aAAa,CACtC,YAAY,OAAO;;CAG9B,AAAQ,YAAY,QAAwC;AAC1D,MAAI,KAAK,IAAK;AAEd,MAAI,CAAC,QAAQ,IAAI,4BACf;AAGF,MAAI;AACF,QAAK,MAAM,IAAI,QAAQ;IACrB,UAAU,KAAK,eAAe,OAAO;IACrC,qBAAqB;IACrB,SAAS,IAAI,eAAe;IAC5B,eAAe,IAAI,kBAAkB,EAAE,SAAS,OAAO,SAAS,CAAC;IACjE,eAAe,CACb,IAAI,8BAA8B;KAChC,UAAU,IAAI,mBAAmB,EAAE,SAAS,OAAO,SAAS,CAAC;KAC7D,sBACE,OAAO,oBACP,iBAAiB;KACpB,CAAC,CACH;IACD,qBAAqB,CACnB,IAAI,wBACF,IAAI,gBAAgB,EAAE,SAAS,OAAO,SAAS,CAAC,CACjD,CACF;IACD,kBAAkB,KAAK,4BAA4B;IACpD,CAAC;AAEF,QAAK,IAAI,OAAO;AAChB,QAAK,kBAAkB;AACvB,UAAO,MAAM,2BAA2B;WACjC,OAAO;AACd,UAAO,MAAM,4BAA4B,MAAM;;;;;;;;CASnD,yBAAyB,kBAA2C;AAClE,2BAA6B,EAE3B,kBACD,CAAC;;CAGJ,AAAQ,eAAe,QAA4C;EACjE,MAAM,cACJ,OAAO,eACP,QAAQ,IAAI,qBACZ,QAAQ,IAAI,uBACZ,iBAAiB;EACnB,MAAM,kBAAkB,uBAAuB;IAC5C,oBAAoB;IACpB,uBAAuB,OAAO,kBAAkB;GAClD,CAAC;EACF,MAAM,mBAAmB,gBAAgB,EACvC,WAAW;GAAC;GAAa;GAAc;GAAgB,EACxD,CAAC;AACF,SAAO,gBAAgB,MAAM,iBAAiB;;CAGhD,AAAQ,6BAAgD;AACtD,SAAO,CACL,GAAG,4BAA4B;GAI7B,uCAAuC,EACrC,SAAS,OACV;GACD,0CAA0C,EACxC,SAAS,OACV;GAID,qCAAqC,EACnC,SAAS,OACV;GACD,sCAAsC,EACpC,SAAS,OACV;GACD,sCAAsC,EACpC,SAAS,OACV;GACF,CAAC,CACH;;CAGH,AAAQ,mBAAmB;EACzB,MAAM,aAAa,YAAY;AAC7B,SAAM,iBAAiB,aAAa,CAAC,UAAU;;AAEjD,UAAQ,KAAK,WAAW,WAAW;AACnC,UAAQ,KAAK,UAAU,WAAW;;CAGpC,MAAc,WAA0B;AACtC,MAAI,CAAC,KAAK,IACR;AAGF,MAAI;AACF,SAAM,KAAK,IAAI,UAAU;AACzB,QAAK,MAAM;WACJ,OAAO;AACd,UAAO,MAAM,2BAA2B,MAAM"}

package/dist/telemetry/trace-sampler.js

@@ -0,0 +1,33 @@
+import { shouldExcludePath } from "../utils/path-exclusions.js";
+import { SamplingDecision } from "@opentelemetry/sdk-trace-base";
+
+//#region src/telemetry/trace-sampler.ts
+/**
+* Custom sampler that filters out asset requests and other noise.
+*
+* This acts as a secondary filter after HttpInstrumentation.ignoreIncomingRequestHook.
+* It catches any spans that slip through the primary filter.
+*/
+var AppKitSampler = class {
+	shouldSample(_context, _traceId, spanName, _spanKind, attributes, _links) {
+		const httpTarget = attributes["http.target"];
+		const httpRoute = attributes["http.route"];
+		const httpUrl = attributes["http.url"];
+		let path = httpTarget || httpRoute;
+		if (!path && httpUrl) try {
+			path = new URL(httpUrl).pathname;
+		} catch {
+			path = httpUrl;
+		}
+		if (!path) path = spanName;
+		if (shouldExcludePath(path)) return { decision: SamplingDecision.NOT_RECORD };
+		return { decision: SamplingDecision.RECORD_AND_SAMPLED };
+	}
+	toString() {
+		return "AppKitSampler";
+	}
+};
+
+//#endregion
+export { AppKitSampler };
+//# sourceMappingURL=trace-sampler.js.map

package/dist/telemetry/trace-sampler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace-sampler.js","names":[],"sources":["../../src/telemetry/trace-sampler.ts"],"sourcesContent":["import type { Attributes, Context, Link } from \"@opentelemetry/api\";\nimport type { Sampler, SamplingResult } from \"@opentelemetry/sdk-trace-base\";\nimport { SamplingDecision } from \"@opentelemetry/sdk-trace-base\";\nimport { shouldExcludePath } from \"../utils/path-exclusions\";\n\n/**\n * Custom sampler that filters out asset requests and other noise.\n *\n * This acts as a secondary filter after HttpInstrumentation.ignoreIncomingRequestHook.\n * It catches any spans that slip through the primary filter.\n */\nexport class AppKitSampler implements Sampler {\n  shouldSample(\n    _context: Context,\n    _traceId: string,\n    spanName: string,\n    _spanKind: number,\n    attributes: Attributes,\n    _links: Link[],\n  ): SamplingResult {\n    // Check if this is an HTTP request span\n    const httpTarget = attributes[\"http.target\"] as string | undefined;\n    const httpRoute = attributes[\"http.route\"] as string | undefined;\n    const httpUrl = attributes[\"http.url\"] as string | undefined;\n\n    // Try to extract path from various attributes\n    let path = httpTarget || httpRoute;\n    if (!path && httpUrl) {\n      try {\n        path = new URL(httpUrl).pathname;\n      } catch {\n        // Not a valid URL, use as-is\n        path = httpUrl;\n      }\n    }\n    if (!path) {\n      path = spanName;\n    }\n\n    // Check if path should be excluded\n    if (shouldExcludePath(path)) {\n      return {\n        decision: SamplingDecision.NOT_RECORD,\n      };\n    }\n\n    // For all other requests, record and sample\n    return {\n      decision: SamplingDecision.RECORD_AND_SAMPLED,\n    };\n  }\n\n  toString(): string {\n    return \"AppKitSampler\";\n  }\n}\n"],"mappings":";;;;;;;;;;AAWA,IAAa,gBAAb,MAA8C;CAC5C,aACE,UACA,UACA,UACA,WACA,YACA,QACgB;EAEhB,MAAM,aAAa,WAAW;EAC9B,MAAM,YAAY,WAAW;EAC7B,MAAM,UAAU,WAAW;EAG3B,IAAI,OAAO,cAAc;AACzB,MAAI,CAAC,QAAQ,QACX,KAAI;AACF,UAAO,IAAI,IAAI,QAAQ,CAAC;UAClB;AAEN,UAAO;;AAGX,MAAI,CAAC,KACH,QAAO;AAIT,MAAI,kBAAkB,KAAK,CACzB,QAAO,EACL,UAAU,iBAAiB,YAC5B;AAIH,SAAO,EACL,UAAU,iBAAiB,oBAC5B;;CAGH,WAAmB;AACjB,SAAO"}

package/dist/type-generator/index.js

@@ -1,9 +1,11 @@
+import { createLogger } from "../logging/logger.js";
 import { generateQueriesFromDescribe } from "./query-registry.js";
 import fs from "node:fs";
 import dotenv from "dotenv";
 
 //#region src/type-generator/index.ts
 dotenv.config();
+const logger = createLogger("type-generator");
 /**
 * Generate type declarations for QueryRegistry
 * Create the d.ts file from the plugin routes and query schemas
@@ -33,12 +35,12 @@ declare module "@databricks/appkit-ui/react" {
 */
 async function generateFromEntryPoint(options) {
 	const { outFile, queryFolder, warehouseId, noCache } = options;
-	console.log("\n[AppKit] Starting type generation...\n");
+	logger.debug("Starting type generation...");
 	let queryRegistry = [];
 	if (queryFolder) queryRegistry = await generateQueriesFromDescribe(queryFolder, warehouseId, { noCache });
 	const typeDeclarations = generateTypeDeclarations(queryRegistry);
 	fs.writeFileSync(outFile, typeDeclarations, "utf-8");
-	console.log("\n[AppKit] Type generation complete!\n");
+	logger.debug("Type generation complete!");
 }
 
 //#endregion