@atrim/instrument-web 0.1.0

package/target/dist/index.d.ts

@@ -0,0 +1,413 @@
+import { WebTracerProvider } from '@opentelemetry/sdk-trace-web';
+import { InstrumentationConfig, ConfigLoader } from '@atrim/instrument-core';
+export { ConfigError, ConfigFileError, ConfigUrlError, ConfigValidationError, ExportError, InitializationError, InstrumentationConfig, PatternConfig, PatternMatcher, ShutdownError, clearPatternMatcher, getPatternMatcher, initializePatternMatcher, shouldInstrumentSpan } from '@atrim/instrument-core';
+import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
+import { Layer } from 'effect';
+import { SpanProcessor, ReadableSpan } from '@opentelemetry/sdk-trace-base';
+import { Context, Span } from '@opentelemetry/api';
+
+/**
+ * SDK Initializer for Browser
+ *
+ * Initializes the OpenTelemetry WebTracerProvider with:
+ * - Auto-instrumentation (fetch, XHR, document load, user interactions)
+ * - Pattern-based span filtering
+ * - OTLP HTTP export
+ */
+
+interface SdkInitializationOptions {
+    /**
+     * Service name (required for browser - no auto-detection)
+     * @example 'my-app-frontend'
+     */
+    serviceName: string;
+    /**
+     * Service version (optional)
+     * @example '1.0.0'
+     */
+    serviceVersion?: string;
+    /**
+     * Path to instrumentation.yaml file
+     * Note: Only works if file is publicly accessible
+     */
+    configPath?: string;
+    /**
+     * URL to remote instrumentation.yaml
+     * @example 'https://config.company.com/instrumentation.yaml'
+     */
+    configUrl?: string;
+    /**
+     * Inline configuration object (takes precedence over file/URL)
+     */
+    config?: InstrumentationConfig;
+    /**
+     * OTLP endpoint URL
+     * @default 'http://localhost:4318/v1/traces'
+     */
+    otlpEndpoint?: string;
+    /**
+     * OTLP HTTP headers
+     * @example { 'Authorization': 'Bearer token' }
+     */
+    otlpHeaders?: Record<string, string>;
+    /**
+     * Enable document load instrumentation
+     * @default true
+     */
+    enableDocumentLoad?: boolean;
+    /**
+     * Enable user interaction instrumentation
+     * @default true
+     */
+    enableUserInteraction?: boolean;
+    /**
+     * Enable fetch API instrumentation
+     * @default true
+     */
+    enableFetch?: boolean;
+    /**
+     * Enable XMLHttpRequest instrumentation
+     * @default true
+     */
+    enableXhr?: boolean;
+}
+/**
+ * Get the current SDK instance
+ *
+ * @returns WebTracerProvider instance or null if not initialized
+ */
+declare function getSdkInstance(): WebTracerProvider | null;
+/**
+ * Shutdown the SDK gracefully
+ *
+ * Flushes pending spans and releases resources
+ */
+declare function shutdownSdk(): Promise<void>;
+/**
+ * Reset the SDK instance (for testing)
+ *
+ * Does not shutdown - just clears the singleton
+ */
+declare function resetSdk(): void;
+
+/**
+ * Public API for @atrim/instrument-web
+ *
+ * Main initialization functions for browser instrumentation
+ */
+
+/**
+ * Initialize OpenTelemetry instrumentation for browser
+ *
+ * This is the main entry point for setting up tracing in browser applications.
+ * Call this function once at application startup, before any other code runs.
+ *
+ * @param options - Initialization options
+ * @returns WebTracerProvider instance
+ * @throws {Error} If initialization fails
+ *
+ * @example
+ * ```typescript
+ * import { initializeInstrumentation } from '@atrim/instrument-web'
+ *
+ * await initializeInstrumentation({
+ *   serviceName: 'my-app',
+ *   otlpEndpoint: 'http://localhost:4318/v1/traces'
+ * })
+ * ```
+ *
+ * @example With pattern-based filtering
+ * ```typescript
+ * await initializeInstrumentation({
+ *   serviceName: 'my-app',
+ *   configUrl: 'https://config.company.com/instrumentation.yaml'
+ * })
+ * ```
+ *
+ * @example Disable specific instrumentations
+ * ```typescript
+ * await initializeInstrumentation({
+ *   serviceName: 'my-app',
+ *   enableUserInteraction: false, // Disable click tracking
+ *   enableXhr: false // Disable XMLHttpRequest tracking
+ * })
+ * ```
+ */
+declare function initializeInstrumentation(options: SdkInitializationOptions): Promise<WebTracerProvider>;
+
+/**
+ * OTLP Exporter Factory for Browser
+ *
+ * Creates OTLP HTTP exporters for sending traces from the browser.
+ * Browser only supports HTTP/JSON protocol (no gRPC).
+ */
+
+interface OtlpExporterOptions {
+    /**
+     * OTLP endpoint URL
+     * Must end in /v1/traces for browser exporter
+     * @default 'http://localhost:4318/v1/traces'
+     */
+    endpoint?: string;
+    /**
+     * Custom HTTP headers (e.g., for authentication)
+     * @example { 'Authorization': 'Bearer token' }
+     */
+    headers?: Record<string, string>;
+    /**
+     * Request timeout in milliseconds
+     * @default 10000
+     */
+    timeout?: number;
+}
+/**
+ * Create an OTLP HTTP trace exporter for browser
+ *
+ * @param options - Exporter configuration options
+ * @returns OTLPTraceExporter instance
+ *
+ * @example
+ * ```typescript
+ * const exporter = createOtlpExporter({
+ *   endpoint: 'http://localhost:4318/v1/traces',
+ *   headers: { 'x-api-key': 'secret' }
+ * })
+ * ```
+ */
+declare function createOtlpExporter(options?: OtlpExporterOptions): OTLPTraceExporter;
+/**
+ * Get OTLP endpoint from environment or use default
+ *
+ * Checks in order:
+ * 1. import.meta.env.VITE_OTEL_EXPORTER_OTLP_ENDPOINT (Vite)
+ * 2. window.OTEL_EXPORTER_OTLP_ENDPOINT (runtime config)
+ * 3. Default: http://localhost:4318/v1/traces
+ *
+ * @returns OTLP endpoint URL
+ */
+declare function getOtlpEndpoint(): string;
+
+/**
+ * Browser configuration loader using Effect Platform
+ *
+ * Provides HttpClient layer for the core ConfigLoader service
+ * (No FileSystem in browser)
+ */
+
+/**
+ * Complete ConfigLoader layer with browser platform dependencies
+ *
+ * Provides:
+ * - ConfigLoader service
+ * - HttpClient (from FetchHttpClient)
+ * - No FileSystem (browser doesn't have filesystem access)
+ */
+declare const WebConfigLoaderLive: Layer.Layer<ConfigLoader, never, never>;
+/**
+ * Load configuration from URI (Promise-based convenience API)
+ *
+ * Automatically provides browser platform layers (HttpClient only)
+ *
+ * @param uri - Configuration URI (http://, https://, or relative path)
+ * @returns Promise that resolves to validated configuration
+ */
+declare function loadConfig(uri: string): Promise<InstrumentationConfig>;
+/**
+ * Load configuration from inline content (Promise-based convenience API)
+ *
+ * @param content - YAML string, JSON string, or plain object
+ * @returns Promise that resolves to validated configuration
+ */
+declare function loadConfigFromInline(content: string | unknown): Promise<InstrumentationConfig>;
+
+/**
+ * Pattern-Based Span Processor for Browser
+ *
+ * Filters spans based on patterns defined in instrumentation.yaml
+ * Re-uses pattern matching logic from @atrim/instrument-core
+ */
+
+/**
+ * Span processor that filters spans based on pattern matching
+ *
+ * This processor runs BEFORE export and drops spans that don't match
+ * the configured patterns in instrumentation.yaml.
+ *
+ * @example
+ * ```yaml
+ * # instrumentation.yaml
+ * instrumentation:
+ *   instrument_patterns:
+ *     - pattern: "^documentLoad"
+ *     - pattern: "^HTTP (GET|POST)"
+ *   ignore_patterns:
+ *     - pattern: "^HTTP GET /health"
+ * ```
+ */
+declare class PatternSpanProcessor implements SpanProcessor {
+    /**
+     * Called when a span is started
+     * No-op for this processor
+     */
+    onStart(_span: ReadableSpan, _parentContext: Context): void;
+    /**
+     * Called when a span ends
+     * Filters out spans that don't match patterns
+     */
+    onEnd(span: ReadableSpan): void;
+    /**
+     * Shutdown the processor
+     * No-op for this processor
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Force flush pending spans
+     * No-op for this processor
+     */
+    forceFlush(): Promise<void>;
+}
+
+/**
+ * Browser Span Helpers
+ *
+ * Utility functions for adding metadata to spans in browser applications
+ */
+
+/**
+ * Set multiple attributes on a span
+ *
+ * @param span - OpenTelemetry span
+ * @param attributes - Key-value pairs to set as attributes
+ *
+ * @example
+ * ```typescript
+ * setSpanAttributes(span, {
+ *   'user.id': '123',
+ *   'page.url': window.location.href
+ * })
+ * ```
+ */
+declare function setSpanAttributes(span: Span, attributes: Record<string, string | number | boolean>): void;
+/**
+ * Record an exception on a span
+ *
+ * @param span - OpenTelemetry span
+ * @param error - Error object to record
+ * @param context - Additional context attributes
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   // ...
+ * } catch (error) {
+ *   recordException(span, error, { 'page.url': window.location.href })
+ * }
+ * ```
+ */
+declare function recordException(span: Span, error: Error, context?: Record<string, string | number | boolean>): void;
+/**
+ * Mark a span as successful
+ *
+ * Sets status to OK and adds optional attributes
+ *
+ * @param span - OpenTelemetry span
+ * @param attributes - Optional attributes to add
+ */
+declare function markSpanSuccess(span: Span, attributes?: Record<string, string | number | boolean>): void;
+/**
+ * Mark a span as failed
+ *
+ * Sets status to ERROR and adds optional error message/attributes
+ *
+ * @param span - OpenTelemetry span
+ * @param message - Error message
+ * @param attributes - Optional attributes to add
+ */
+declare function markSpanError(span: Span, message?: string, attributes?: Record<string, string | number | boolean>): void;
+/**
+ * Annotate span with HTTP request details
+ *
+ * @param span - OpenTelemetry span
+ * @param options - HTTP request details
+ *
+ * @example
+ * ```typescript
+ * annotateHttpRequest(span, {
+ *   method: 'GET',
+ *   url: 'https://api.example.com/users',
+ *   statusCode: 200,
+ *   responseTime: 150
+ * })
+ * ```
+ */
+declare function annotateHttpRequest(span: Span, options: {
+    method?: string;
+    url?: string;
+    statusCode?: number;
+    responseTime?: number;
+    requestSize?: number;
+    responseSize?: number;
+}): void;
+/**
+ * Annotate span with cache operation details
+ *
+ * @param span - OpenTelemetry span
+ * @param options - Cache operation details
+ *
+ * @example
+ * ```typescript
+ * annotate CacheOperation(span, {
+ *   operation: 'get',
+ *   key: 'user:123',
+ *   hit: true
+ * })
+ * ```
+ */
+declare function annotateCacheOperation(span: Span, options: {
+    operation: 'get' | 'set' | 'delete' | 'clear';
+    key?: string;
+    hit?: boolean;
+    size?: number;
+}): void;
+/**
+ * Annotate span with user interaction details
+ *
+ * @param span - OpenTelemetry span
+ * @param options - User interaction details
+ *
+ * @example
+ * ```typescript
+ * annotateUserInteraction(span, {
+ *   type: 'click',
+ *   target: 'button#submit',
+ *   page: '/checkout'
+ * })
+ * ```
+ */
+declare function annotateUserInteraction(span: Span, options: {
+    type: 'click' | 'submit' | 'input' | 'navigation';
+    target?: string;
+    page?: string;
+}): void;
+/**
+ * Annotate span with page navigation details
+ *
+ * @param span - OpenTelemetry span
+ * @param options - Navigation details
+ *
+ * @example
+ * ```typescript
+ * annotateNavigation(span, {
+ *   from: '/home',
+ *   to: '/profile',
+ *   type: 'client-side'
+ * })
+ * ```
+ */
+declare function annotateNavigation(span: Span, options: {
+    from?: string;
+    to?: string;
+    type?: 'client-side' | 'server-side' | 'initial';
+}): void;
+
+export { type OtlpExporterOptions, PatternSpanProcessor, type SdkInitializationOptions, WebConfigLoaderLive, annotateCacheOperation, annotateHttpRequest, annotateNavigation, annotateUserInteraction, createOtlpExporter, getOtlpEndpoint, getSdkInstance, initializeInstrumentation, loadConfig, loadConfigFromInline, markSpanError, markSpanSuccess, recordException, resetSdk, setSpanAttributes, shutdownSdk };