@getfoil/foil-js 0.4.0

package/src/otel.js

@@ -0,0 +1,610 @@
+/**
+ * Foil OpenTelemetry Integration
+ *
+ * Provides a SpanProcessor that exports OpenTelemetry spans to Foil's OTLP endpoint.
+ * This enables automatic instrumentation of LLM calls using OpenLLMetry or other
+ * OpenTelemetry instrumentations.
+ *
+ * Usage:
+ * ```javascript
+ * const { FoilSpanProcessor, Foil } = require('@foil/foil-js/otel');
+ * const { NodeTracerProvider } = require('@opentelemetry/sdk-trace-node');
+ *
+ * // Option 1: Use FoilSpanProcessor directly
+ * const provider = new NodeTracerProvider();
+ * provider.addSpanProcessor(new FoilSpanProcessor({ apiKey: 'sk_live_...' }));
+ * provider.register();
+ *
+ * // Option 2: Use Foil.init() convenience method
+ * Foil.init({ apiKey: 'sk_live_...' });
+ * ```
+ */
+
+const axios = require('axios');
+
+// Debug logging
+const isDebugEnabled = () => process.env.FOIL_DEBUG === 'true';
+
+/**
+ * Default Foil OTLP endpoint
+ */
+const DEFAULT_ENDPOINT = 'https://api.getfoil.ai/api/otlp/v1/traces';
+
+/**
+ * FoilSpanProcessor implements the OpenTelemetry SpanProcessor interface.
+ * It batches completed spans and exports them to Foil's OTLP endpoint.
+ *
+ * @implements {SpanProcessor}
+ */
+class FoilSpanProcessor {
+  /**
+   * Create a new FoilSpanProcessor
+   * @param {Object} options - Configuration options
+   * @param {string} options.apiKey - Foil API key (required)
+   * @param {string} [options.endpoint] - Custom OTLP endpoint URL
+   * @param {number} [options.maxBatchSize=100] - Maximum spans per batch
+   * @param {number} [options.scheduledDelayMs=5000] - Batch export interval in milliseconds
+   * @param {number} [options.exportTimeoutMs=30000] - Export request timeout in milliseconds
+   * @param {boolean} [options.debug] - Enable debug logging
+   */
+  constructor(options = {}) {
+    if (!options.apiKey) {
+      throw new Error('Foil API key is required. Pass { apiKey: "sk_live_..." }');
+    }
+
+    this.apiKey = options.apiKey;
+    this.endpoint = options.endpoint || process.env.FOIL_OTLP_ENDPOINT || DEFAULT_ENDPOINT;
+    this.maxBatchSize = options.maxBatchSize || 100;
+    this.scheduledDelayMs = options.scheduledDelayMs || 5000;
+    this.exportTimeoutMs = options.exportTimeoutMs || 30000;
+    this.debug = options.debug || isDebugEnabled();
+
+    // Pending spans waiting to be exported
+    this._pendingSpans = [];
+
+    // Export timer
+    this._timer = null;
+
+    // Track if we've been shutdown
+    this._shutdown = false;
+
+    // Start the export timer
+    this._startTimer();
+
+    if (this.debug) {
+      console.log('[Foil] SpanProcessor initialized', {
+        endpoint: this.endpoint,
+        maxBatchSize: this.maxBatchSize,
+        scheduledDelayMs: this.scheduledDelayMs,
+      });
+    }
+  }
+
+  /**
+   * Called when a span is started. We don't need to do anything here
+   * since we only export completed spans.
+   * @param {Span} span - The span that was started
+   * @param {Context} parentContext - The parent context
+   */
+  onStart(span, parentContext) {
+    // No-op: we only export on span end
+  }
+
+  /**
+   * Called when a span is ended. We collect the span for batch export.
+   * @param {ReadableSpan} span - The completed span
+   */
+  onEnd(span) {
+    if (this._shutdown) {
+      return;
+    }
+
+    // Convert OTEL span to OTLP format
+    const otlpSpan = this._convertToOTLP(span);
+    this._pendingSpans.push(otlpSpan);
+
+    if (this.debug) {
+      console.log('[Foil] Span ended', {
+        name: span.name,
+        traceId: span.spanContext().traceId,
+        spanId: span.spanContext().spanId,
+        pendingCount: this._pendingSpans.length,
+      });
+    }
+
+    // Export immediately if batch is full
+    if (this._pendingSpans.length >= this.maxBatchSize) {
+      this._export();
+    }
+  }
+
+  /**
+   * Force flush any pending spans
+   * @returns {Promise<void>}
+   */
+  async forceFlush() {
+    if (this._pendingSpans.length > 0) {
+      await this._export();
+    }
+  }
+
+  /**
+   * Shutdown the processor and flush any remaining spans
+   * @returns {Promise<void>}
+   */
+  async shutdown() {
+    this._shutdown = true;
+
+    // Stop the timer
+    if (this._timer) {
+      clearInterval(this._timer);
+      this._timer = null;
+    }
+
+    // Flush remaining spans
+    await this.forceFlush();
+
+    if (this.debug) {
+      console.log('[Foil] SpanProcessor shutdown complete');
+    }
+  }
+
+  /**
+   * Start the batch export timer
+   * @private
+   */
+  _startTimer() {
+    this._timer = setInterval(() => {
+      if (this._pendingSpans.length > 0) {
+        this._export();
+      }
+    }, this.scheduledDelayMs);
+
+    // Don't prevent process from exiting
+    if (this._timer.unref) {
+      this._timer.unref();
+    }
+  }
+
+  /**
+   * Convert an OpenTelemetry ReadableSpan to OTLP JSON format
+   * @param {ReadableSpan} span - The OTEL span
+   * @returns {Object} OTLP span format
+   * @private
+   */
+  _convertToOTLP(span) {
+    const spanContext = span.spanContext();
+
+    // Convert attributes to OTLP format
+    const attributes = [];
+    if (span.attributes) {
+      for (const [key, value] of Object.entries(span.attributes)) {
+        attributes.push({
+          key,
+          value: this._convertAttributeValue(value),
+        });
+      }
+    }
+
+    // Convert events to OTLP format
+    const events = (span.events || []).map((event) => ({
+      timeUnixNano: String(this._hrTimeToNanos(event.time)),
+      name: event.name,
+      attributes: (event.attributes ? Object.entries(event.attributes) : []).map(([key, value]) => ({
+        key,
+        value: this._convertAttributeValue(value),
+      })),
+    }));
+
+    // Convert links to OTLP format
+    const links = (span.links || []).map((link) => ({
+      traceId: link.context.traceId,
+      spanId: link.context.spanId,
+      traceState: link.context.traceState?.serialize() || '',
+      attributes: (link.attributes ? Object.entries(link.attributes) : []).map(([key, value]) => ({
+        key,
+        value: this._convertAttributeValue(value),
+      })),
+    }));
+
+    return {
+      traceId: spanContext.traceId,
+      spanId: spanContext.spanId,
+      parentSpanId: span.parentSpanId || '',
+      traceState: spanContext.traceState?.serialize() || '',
+      name: span.name,
+      kind: span.kind || 0,
+      startTimeUnixNano: String(this._hrTimeToNanos(span.startTime)),
+      endTimeUnixNano: String(this._hrTimeToNanos(span.endTime)),
+      attributes,
+      droppedAttributesCount: span.droppedAttributesCount || 0,
+      events,
+      droppedEventsCount: span.droppedEventsCount || 0,
+      links,
+      droppedLinksCount: span.droppedLinksCount || 0,
+      status: {
+        code: span.status?.code || 0,
+        message: span.status?.message || '',
+      },
+    };
+  }
+
+  /**
+   * Convert an attribute value to OTLP format
+   * @param {any} value - The attribute value
+   * @returns {Object} OTLP attribute value
+   * @private
+   */
+  _convertAttributeValue(value) {
+    if (typeof value === 'string') {
+      return { stringValue: value };
+    }
+    if (typeof value === 'boolean') {
+      return { boolValue: value };
+    }
+    if (typeof value === 'number') {
+      if (Number.isInteger(value)) {
+        return { intValue: String(value) };
+      }
+      return { doubleValue: value };
+    }
+    if (Array.isArray(value)) {
+      return {
+        arrayValue: {
+          values: value.map((v) => this._convertAttributeValue(v)),
+        },
+      };
+    }
+    // Fallback: convert to string
+    return { stringValue: String(value) };
+  }
+
+  /**
+   * Convert OTEL HrTime [seconds, nanoseconds] to nanoseconds BigInt
+   * @param {[number, number]} hrTime - High resolution time
+   * @returns {bigint} Nanoseconds since epoch
+   * @private
+   */
+  _hrTimeToNanos(hrTime) {
+    if (!hrTime || !Array.isArray(hrTime)) {
+      return BigInt(Date.now()) * BigInt(1000000);
+    }
+    const [seconds, nanos] = hrTime;
+    return BigInt(seconds) * BigInt(1000000000) + BigInt(nanos);
+  }
+
+  /**
+   * Export pending spans to Foil
+   * @returns {Promise<void>}
+   * @private
+   */
+  async _export() {
+    if (this._pendingSpans.length === 0) {
+      return;
+    }
+
+    // Take the current batch and clear pending
+    const batch = this._pendingSpans.splice(0, this.maxBatchSize);
+
+    if (this.debug) {
+      console.log('[Foil] Exporting spans', { count: batch.length });
+    }
+
+    // Build OTLP request
+    const request = {
+      resourceSpans: [
+        {
+          resource: {
+            attributes: [
+              {
+                key: 'service.name',
+                value: { stringValue: process.env.OTEL_SERVICE_NAME || 'foil-instrumented-app' },
+              },
+              {
+                key: 'telemetry.sdk.name',
+                value: { stringValue: '@foil/foil-js' },
+              },
+              {
+                key: 'telemetry.sdk.language',
+                value: { stringValue: 'nodejs' },
+              },
+            ],
+          },
+          scopeSpans: [
+            {
+              scope: {
+                name: '@foil/foil-js',
+                version: '0.4.0',
+              },
+              spans: batch,
+            },
+          ],
+        },
+      ],
+    };
+
+    try {
+      const response = await axios.post(this.endpoint, request, {
+        headers: {
+          'Content-Type': 'application/json',
+          Authorization: this.apiKey,
+        },
+        timeout: this.exportTimeoutMs,
+      });
+
+      if (this.debug) {
+        console.log('[Foil] Export successful', {
+          count: batch.length,
+          status: response.status,
+        });
+      }
+
+      // Check for partial success
+      if (response.data?.partialSuccess?.rejectedSpans > 0) {
+        console.warn('[Foil] Some spans were rejected', response.data.partialSuccess);
+      }
+    } catch (error) {
+      console.error('[Foil] Export failed', {
+        error: error.message,
+        count: batch.length,
+      });
+
+      // Re-queue spans on failure (up to a limit to prevent memory issues)
+      if (this._pendingSpans.length < this.maxBatchSize * 3) {
+        this._pendingSpans.unshift(...batch);
+      }
+    }
+  }
+}
+
+/**
+ * Foil convenience class for initializing OpenTelemetry tracing.
+ * Provides a simple way to set up Foil as the trace exporter.
+ */
+class Foil {
+  /**
+   * The global TracerProvider instance
+   * @type {TracerProvider|null}
+   */
+  static _provider = null;
+
+  /**
+   * The FoilSpanProcessor instance
+   * @type {FoilSpanProcessor|null}
+   */
+  static _processor = null;
+
+  /**
+   * Initialize Foil OpenTelemetry integration.
+   * This sets up a TracerProvider with FoilSpanProcessor and registers it globally.
+   *
+   * Note: This requires @opentelemetry/sdk-trace-node to be installed.
+   *
+   * @param {Object} options - Configuration options
+   * @param {string} options.apiKey - Foil API key (required)
+   * @param {string} [options.agentName] - Agent name for grouping traces in Foil
+   * @param {string} [options.endpoint] - Custom OTLP endpoint URL
+   * @param {boolean} [options.debug] - Enable debug logging
+   * @returns {Object} Object with provider and processor
+   *
+   * @example
+   * ```javascript
+   * const { Foil } = require('@foil/foil-js/otel');
+   *
+   * // Initialize with API key
+   * Foil.init({ apiKey: process.env.FOIL_API_KEY });
+   *
+   * // Now any OpenTelemetry instrumentation will export to Foil
+   * // e.g., OpenLLMetry for LLM calls
+   * ```
+   */
+  static init(options = {}) {
+    if (!options.apiKey) {
+      throw new Error('Foil API key is required. Pass { apiKey: "sk_live_..." }');
+    }
+
+    const debug = options.debug || isDebugEnabled();
+
+    // Load OpenTelemetry SDK
+    const { NodeTracerProvider } = require('@opentelemetry/sdk-trace-node');
+
+    // Set agent name as OTEL service name (used by transformer to create/lookup agent)
+    if (options.agentName) {
+      process.env.OTEL_SERVICE_NAME = options.agentName;
+    }
+
+    // Create the processor
+    Foil._processor = new FoilSpanProcessor({
+      apiKey: options.apiKey,
+      endpoint: options.endpoint,
+      debug,
+    });
+
+    // Create and configure the provider
+    Foil._provider = new NodeTracerProvider();
+    Foil._provider.addSpanProcessor(Foil._processor);
+    Foil._provider.register();
+
+    if (debug) {
+      console.log('[Foil] Initialized OpenTelemetry provider');
+    }
+
+    // Initialize OpenLLMetry (Traceloop) for automatic LLM instrumentation
+    // We disable their exporter since we use FoilSpanProcessor instead
+    try {
+      const Traceloop = require('@traceloop/node-server-sdk');
+      Traceloop.initialize({
+        disableBatch: true,
+        exporter: null, // Disable Traceloop's exporter, we use FoilSpanProcessor
+        silenceInitializationMessage: true,
+      });
+
+      if (debug) {
+        console.log('[Foil] Auto-instrumentation enabled for: OpenAI, Anthropic, Cohere, Bedrock, LangChain, etc.');
+      }
+    } catch (error) {
+      if (debug) {
+        console.log('[Foil] Note: Install @traceloop/node-server-sdk for auto-instrumentation');
+      }
+    }
+
+    if (debug) {
+      console.log('[Foil] Ready! All LLM calls will be automatically traced.', {
+        agentName: options.agentName || process.env.OTEL_SERVICE_NAME || 'default',
+      });
+    }
+
+    return {
+      provider: Foil._provider,
+      processor: Foil._processor,
+    };
+  }
+
+  /**
+   * Shutdown Foil and flush any pending spans
+   * @returns {Promise<void>}
+   */
+  static async shutdown() {
+    if (Foil._processor) {
+      await Foil._processor.shutdown();
+      Foil._processor = null;
+    }
+    if (Foil._provider) {
+      await Foil._provider.shutdown();
+      Foil._provider = null;
+    }
+  }
+
+  /**
+   * Force flush any pending spans
+   * @returns {Promise<void>}
+   */
+  static async flush() {
+    if (Foil._processor) {
+      await Foil._processor.forceFlush();
+    }
+  }
+}
+
+/**
+ * Attachment counter for unique indexing within a span
+ * Uses WeakMap to track per-span attachment counts
+ */
+const spanAttachmentCounts = new WeakMap();
+
+/**
+ * Add an attachment to the current active span.
+ * Attachments allow you to include additional context like images, code, text, or embedded content.
+ *
+ * @param {Object} attachment - The attachment to add
+ * @param {string} attachment.type - Type of attachment: 'image', 'code', 'text', or 'iframe'
+ * @param {string} attachment.value - The content or URL of the attachment
+ * @param {string} attachment.role - Whether this is 'input' or 'output'
+ * @param {string} [attachment.name] - Optional display name for the attachment
+ * @param {string} [attachment.language] - Language for code attachments (e.g., 'javascript', 'python')
+ *
+ * @example
+ * // Attach an input image
+ * addAttachment({ type: 'image', value: 'https://example.com/image.png', role: 'input' });
+ *
+ * // Attach generated code
+ * addAttachment({ type: 'code', value: 'console.log("hello")', role: 'output', language: 'javascript' });
+ *
+ * // Attach a document
+ * addAttachment({ type: 'text', value: 'Long document content...', role: 'input', name: 'context.txt' });
+ */
+function addAttachment(attachment) {
+  const api = require('@opentelemetry/api');
+  const span = api.trace.getActiveSpan();
+
+  if (!span) {
+    if (isDebugEnabled()) {
+      console.warn('[Foil] addAttachment called but no active span found');
+    }
+    return false;
+  }
+
+  // Validate attachment
+  const validTypes = ['image', 'code', 'text', 'iframe'];
+  if (!validTypes.includes(attachment.type)) {
+    console.warn(`[Foil] Invalid attachment type: ${attachment.type}. Must be one of: ${validTypes.join(', ')}`);
+    return false;
+  }
+
+  if (!attachment.value) {
+    console.warn('[Foil] Attachment value is required');
+    return false;
+  }
+
+  if (!['input', 'output'].includes(attachment.role)) {
+    console.warn('[Foil] Attachment role must be "input" or "output"');
+    return false;
+  }
+
+  // Get or initialize attachment count for this span
+  let count = spanAttachmentCounts.get(span) || 0;
+
+  // Set attributes on the span using Foil's attachment convention
+  span.setAttribute(`foil.attachment.${count}.type`, attachment.type);
+  span.setAttribute(`foil.attachment.${count}.value`, attachment.value);
+  span.setAttribute(`foil.attachment.${count}.role`, attachment.role);
+
+  if (attachment.name) {
+    span.setAttribute(`foil.attachment.${count}.name`, attachment.name);
+  }
+
+  if (attachment.language && attachment.type === 'code') {
+    span.setAttribute(`foil.attachment.${count}.language`, attachment.language);
+  }
+
+  // Increment counter
+  spanAttachmentCounts.set(span, count + 1);
+
+  if (isDebugEnabled()) {
+    console.log('[Foil] Attachment added', { index: count, type: attachment.type, role: attachment.role });
+  }
+
+  return true;
+}
+
+/**
+ * Convenience function to attach an image
+ * @param {string} url - Image URL
+ * @param {string} role - 'input' or 'output'
+ * @param {string} [name] - Optional display name
+ */
+function attachImage(url, role, name) {
+  return addAttachment({ type: 'image', value: url, role, name });
+}
+
+/**
+ * Convenience function to attach code
+ * @param {string} code - Code content
+ * @param {string} role - 'input' or 'output'
+ * @param {string} [language] - Programming language
+ * @param {string} [name] - Optional display name
+ */
+function attachCode(code, role, language, name) {
+  return addAttachment({ type: 'code', value: code, role, language, name });
+}
+
+/**
+ * Convenience function to attach text/document
+ * @param {string} text - Text content
+ * @param {string} role - 'input' or 'output'
+ * @param {string} [name] - Optional display name
+ */
+function attachText(text, role, name) {
+  return addAttachment({ type: 'text', value: text, role, name });
+}
+
+module.exports = {
+  FoilSpanProcessor,
+  Foil,
+  DEFAULT_ENDPOINT,
+  // Attachment helpers
+  addAttachment,
+  attachImage,
+  attachCode,
+  attachText,
+};