@atrim/instrument-node 0.4.1 → 0.5.0-14fdea7-20260109020503

package/target/dist/index.d.cts

@@ -46,35 +46,33 @@ declare function createOtlpExporter(options?: OtlpExporterOptions): OTLPTraceExp
 declare function getOtlpEndpoint(options?: OtlpExporterOptions): string;
 
 /**
- * Node.js configuration loader using Effect Platform
+ * Node.js configuration loader
  *
- * Provides FileSystem and HttpClient layers for the core ConfigLoader service
+ * Provides configuration loading using native Node.js APIs (fs, fetch)
+ * This module doesn't require Effect Platform, making it work without Effect installed.
  */
 
 /**
- * Reset the cached loader (for testing purposes)
- * @internal
- */
-declare function _resetConfigLoaderCache(): void;
-/**
- * Load configuration from URI (Promise-based convenience API)
- *
- * Automatically provides Node.js platform layers (FileSystem + HttpClient)
+ * Load configuration from URI (file path or URL)
  *
  * @param uri - Configuration URI (file://, http://, https://, or relative path)
- * @param options - Optional loading options (e.g., to disable caching)
  * @returns Promise that resolves to validated configuration
  */
-declare function loadConfig(uri: string, options?: {
+declare function loadConfig(uri: string, _options?: {
     cacheTimeout?: number;
 }): Promise<InstrumentationConfig>;
 /**
- * Load configuration from inline content (Promise-based convenience API)
+ * Load configuration from inline content
  *
  * @param content - YAML string, JSON string, or plain object
  * @returns Promise that resolves to validated configuration
  */
 declare function loadConfigFromInline(content: string | unknown): Promise<InstrumentationConfig>;
+/**
+ * Reset the config loader cache (no-op for native implementation)
+ * @internal
+ */
+declare function _resetConfigLoaderCache(): void;
 /**
  * Legacy options interface for backward compatibility
  */
@@ -548,6 +546,10 @@ declare function getServiceVersionAsync(): Promise<string | undefined>;
  * This processor filters spans based on configured patterns before they are exported.
  * It wraps another processor (typically BatchSpanProcessor) and only forwards spans
  * that match the instrumentation patterns.
+ *
+ * Filtering is applied at two levels:
+ * 1. Span name patterns (instrument_patterns / ignore_patterns)
+ * 2. HTTP path patterns (http.ignore_incoming_paths) - for HTTP spans
  */
 
 /**
@@ -570,6 +572,7 @@ declare function getServiceVersionAsync(): Promise<string | undefined>;
 declare class PatternSpanProcessor implements SpanProcessor {
     private matcher;
     private wrappedProcessor;
+    private httpIgnorePatterns;
     constructor(config: InstrumentationConfig, wrappedProcessor: SpanProcessor);
     /**
      * Called when a span is started
@@ -582,8 +585,20 @@ declare class PatternSpanProcessor implements SpanProcessor {
      * Called when a span is ended
      *
      * This is where we make the final decision on whether to export the span.
+     * We check both span name patterns and HTTP path patterns.
      */
     onEnd(span: ReadableSpan): void;
+    /**
+     * Check if span should be ignored based on HTTP path attributes
+     *
+     * This checks the span's url.path, http.route, or http.target attributes
+     * against the configured http.ignore_incoming_paths patterns.
+     *
+     * This enables filtering of Effect HTTP spans (and any other HTTP spans)
+     * based on path patterns, which is essential for filtering out OTLP
+     * endpoint requests like /v1/traces, /v1/logs, /v1/metrics.
+     */
+    private shouldIgnoreHttpSpan;
     /**
      * Shutdown the processor
      */

package/target/dist/index.d.ts

@@ -46,35 +46,33 @@ declare function createOtlpExporter(options?: OtlpExporterOptions): OTLPTraceExp
 declare function getOtlpEndpoint(options?: OtlpExporterOptions): string;
 
 /**
- * Node.js configuration loader using Effect Platform
+ * Node.js configuration loader
  *
- * Provides FileSystem and HttpClient layers for the core ConfigLoader service
+ * Provides configuration loading using native Node.js APIs (fs, fetch)
+ * This module doesn't require Effect Platform, making it work without Effect installed.
  */
 
 /**
- * Reset the cached loader (for testing purposes)
- * @internal
- */
-declare function _resetConfigLoaderCache(): void;
-/**
- * Load configuration from URI (Promise-based convenience API)
- *
- * Automatically provides Node.js platform layers (FileSystem + HttpClient)
+ * Load configuration from URI (file path or URL)
  *
  * @param uri - Configuration URI (file://, http://, https://, or relative path)
- * @param options - Optional loading options (e.g., to disable caching)
  * @returns Promise that resolves to validated configuration
  */
-declare function loadConfig(uri: string, options?: {
+declare function loadConfig(uri: string, _options?: {
     cacheTimeout?: number;
 }): Promise<InstrumentationConfig>;
 /**
- * Load configuration from inline content (Promise-based convenience API)
+ * Load configuration from inline content
  *
  * @param content - YAML string, JSON string, or plain object
  * @returns Promise that resolves to validated configuration
  */
 declare function loadConfigFromInline(content: string | unknown): Promise<InstrumentationConfig>;
+/**
+ * Reset the config loader cache (no-op for native implementation)
+ * @internal
+ */
+declare function _resetConfigLoaderCache(): void;
 /**
  * Legacy options interface for backward compatibility
  */
@@ -548,6 +546,10 @@ declare function getServiceVersionAsync(): Promise<string | undefined>;
  * This processor filters spans based on configured patterns before they are exported.
  * It wraps another processor (typically BatchSpanProcessor) and only forwards spans
  * that match the instrumentation patterns.
+ *
+ * Filtering is applied at two levels:
+ * 1. Span name patterns (instrument_patterns / ignore_patterns)
+ * 2. HTTP path patterns (http.ignore_incoming_paths) - for HTTP spans
  */
 
 /**
@@ -570,6 +572,7 @@ declare function getServiceVersionAsync(): Promise<string | undefined>;
 declare class PatternSpanProcessor implements SpanProcessor {
     private matcher;
     private wrappedProcessor;
+    private httpIgnorePatterns;
     constructor(config: InstrumentationConfig, wrappedProcessor: SpanProcessor);
     /**
      * Called when a span is started
@@ -582,8 +585,20 @@ declare class PatternSpanProcessor implements SpanProcessor {
      * Called when a span is ended
      *
      * This is where we make the final decision on whether to export the span.
+     * We check both span name patterns and HTTP path patterns.
      */
     onEnd(span: ReadableSpan): void;
+    /**
+     * Check if span should be ignored based on HTTP path attributes
+     *
+     * This checks the span's url.path, http.route, or http.target attributes
+     * against the configured http.ignore_incoming_paths patterns.
+     *
+     * This enables filtering of Effect HTTP spans (and any other HTTP spans)
+     * based on path patterns, which is essential for filtering out OTLP
+     * endpoint requests like /v1/traces, /v1/logs, /v1/metrics.
+     */
+    private shouldIgnoreHttpSpan;
     /**
      * Shutdown the processor
      */

package/target/dist/index.js

@@ -11,8 +11,7 @@ import { z } from 'zod';
 import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
 import { readFile } from 'fs/promises';
 import { join } from 'path';
-import { NodeContext } from '@effect/platform-node';
-import { FetchHttpClient } from '@effect/platform';
+import { createRequire } from 'module';
 
 var __defProp = Object.defineProperty;
 var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
@@ -53,13 +52,113 @@ var AutoIsolationConfigSchema = z.object({
     add_metadata: z.boolean().default(true)
   }).default({})
 });
+var SpanNamingRuleSchema = z.object({
+  // Match criteria (all specified criteria must match)
+  match: z.object({
+    // Regex pattern to match file path
+    file: z.string().optional(),
+    // Regex pattern to match function name
+    function: z.string().optional(),
+    // Regex pattern to match module name
+    module: z.string().optional()
+  }),
+  // Span name template with variables:
+  // {fiber_id} - Fiber ID
+  // {function} - Function name
+  // {module} - Module name
+  // {file} - File path
+  // {line} - Line number
+  // {operator} - Effect operator (gen, all, forEach, etc.)
+  // {match:field:N} - Captured regex group from match
+  name: z.string()
+});
+var AutoInstrumentationConfigSchema = z.object({
+  // Enable/disable auto-instrumentation
+  enabled: z.boolean().default(false),
+  // Tracing granularity
+  // - 'fiber': Trace at fiber creation (recommended, lower overhead)
+  // - 'operator': Trace each Effect operator (higher granularity, more overhead)
+  granularity: z.enum(["fiber", "operator"]).default("fiber"),
+  // Smart span naming configuration
+  span_naming: z.object({
+    // Default span name template when no rules match
+    default: z.string().default("effect.fiber.{fiber_id}"),
+    // Infer span names from source code (requires stack trace parsing)
+    // Adds ~50-100μs overhead per fiber
+    infer_from_source: z.boolean().default(true),
+    // Naming rules (first match wins)
+    rules: z.array(SpanNamingRuleSchema).default([])
+  }).default({}),
+  // Pattern-based filtering
+  filter: z.object({
+    // Only trace spans matching these patterns (empty = trace all)
+    include: z.array(z.string()).default([]),
+    // Never trace spans matching these patterns
+    exclude: z.array(z.string()).default([])
+  }).default({}),
+  // Performance controls
+  performance: z.object({
+    // Sample rate (0.0 - 1.0)
+    sampling_rate: z.number().min(0).max(1).default(1),
+    // Skip fibers shorter than this duration (e.g., "10ms", "100 millis")
+    min_duration: z.string().default("0ms"),
+    // Maximum concurrent traced fibers (0 = unlimited)
+    max_concurrent: z.number().default(0)
+  }).default({}),
+  // Automatic metadata extraction
+  metadata: z.object({
+    // Extract Effect fiber information
+    fiber_info: z.boolean().default(true),
+    // Extract source location (file:line)
+    source_location: z.boolean().default(true),
+    // Extract parent fiber information
+    parent_fiber: z.boolean().default(true)
+  }).default({})
+});
 var HttpFilteringConfigSchema = z.object({
   // Patterns to ignore for outgoing HTTP requests (string patterns only in YAML)
   ignore_outgoing_urls: z.array(z.string()).optional(),
   // Patterns to ignore for incoming HTTP requests (string patterns only in YAML)
   ignore_incoming_paths: z.array(z.string()).optional(),
   // Require parent span for outgoing requests (prevents root spans for HTTP calls)
-  require_parent_for_outgoing_spans: z.boolean().optional()
+  require_parent_for_outgoing_spans: z.boolean().optional(),
+  // Trace context propagation configuration
+  // Controls which cross-origin requests receive W3C Trace Context headers (traceparent, tracestate)
+  propagate_trace_context: z.object({
+    // Strategy for trace propagation
+    // - "all": Propagate to all cross-origin requests (may cause CORS errors)
+    // - "none": Never propagate trace headers
+    // - "same-origin": Only propagate to same-origin requests (default, safe)
+    // - "patterns": Propagate based on include_urls patterns
+    strategy: z.enum(["all", "none", "same-origin", "patterns"]).default("same-origin"),
+    // URL patterns to include when strategy is "patterns"
+    // Supports regex patterns (e.g., "^https://api\\.myapp\\.com")
+    include_urls: z.array(z.string()).optional()
+  }).optional()
+});
+var ExporterConfigSchema = z.object({
+  // Exporter type: 'otlp' | 'console' | 'none'
+  // - 'otlp': Export to OTLP endpoint (production)
+  // - 'console': Log spans to console (development)
+  // - 'none': No export (disable tracing)
+  type: z.enum(["otlp", "console", "none"]).default("otlp"),
+  // OTLP endpoint URL (for type: otlp)
+  // Defaults to OTEL_EXPORTER_OTLP_ENDPOINT env var or http://localhost:4318
+  endpoint: z.string().optional(),
+  // Custom headers to send with OTLP requests (for type: otlp)
+  // Useful for authentication (x-api-key, Authorization, etc.)
+  headers: z.record(z.string()).optional(),
+  // Span processor type
+  // - 'batch': Batch spans for export (production, lower overhead)
+  // - 'simple': Export immediately (development, no batching delay)
+  processor: z.enum(["batch", "simple"]).default("batch"),
+  // Batch processor settings (for processor: batch)
+  batch: z.object({
+    // Max time to wait before exporting (milliseconds)
+    scheduled_delay_millis: z.number().default(1e3),
+    // Max batch size
+    max_export_batch_size: z.number().default(100)
+  }).optional()
 });
 var InstrumentationConfigSchema = z.object({
   version: z.string(),
@@ -71,11 +170,54 @@ var InstrumentationConfigSchema = z.object({
     ignore_patterns: z.array(PatternConfigSchema)
   }),
   effect: z.object({
+    // Enable/disable Effect tracing entirely
+    // When false, EffectInstrumentationLive returns Layer.empty
+    enabled: z.boolean().default(true),
+    // Exporter mode (legacy - use exporter.type instead):
+    // - "unified": Use global TracerProvider from Node SDK (recommended, enables filtering)
+    // - "standalone": Use Effect's own OTLP exporter (bypasses Node SDK filtering)
+    exporter: z.enum(["unified", "standalone"]).default("unified"),
+    // Exporter configuration (for auto-instrumentation)
+    exporter_config: ExporterConfigSchema.optional(),
     auto_extract_metadata: z.boolean(),
-    auto_isolation: AutoIsolationConfigSchema.optional()
+    auto_isolation: AutoIsolationConfigSchema.optional(),
+    // Auto-instrumentation: automatic tracing of all Effect fibers
+    auto_instrumentation: AutoInstrumentationConfigSchema.optional()
   }).optional(),
   http: HttpFilteringConfigSchema.optional()
 });
+var defaultConfig = {
+  version: "1.0",
+  instrumentation: {
+    enabled: true,
+    logging: "on",
+    description: "Default instrumentation configuration",
+    instrument_patterns: [
+      { pattern: "^app\\.", enabled: true, description: "Application operations" },
+      { pattern: "^http\\.server\\.", enabled: true, description: "HTTP server operations" },
+      { pattern: "^http\\.client\\.", enabled: true, description: "HTTP client operations" }
+    ],
+    ignore_patterns: [
+      { pattern: "^test\\.", description: "Test utilities" },
+      { pattern: "^internal\\.", description: "Internal operations" },
+      { pattern: "^health\\.", description: "Health checks" }
+    ]
+  },
+  effect: {
+    enabled: true,
+    exporter: "unified",
+    auto_extract_metadata: true
+  }
+};
+function parseAndValidateConfig(content) {
+  let parsed;
+  if (typeof content === "string") {
+    parsed = parse(content);
+  } else {
+    parsed = content;
+  }
+  return InstrumentationConfigSchema.parse(parsed);
+}
 (class extends Data.TaggedError("ConfigError") {
   get message() {
     return this.reason;
@@ -253,7 +395,7 @@ var makeConfigLoader = Effect.gen(function* () {
     })
   });
 });
-var ConfigLoaderLive = Layer.effect(ConfigLoader, makeConfigLoader);
+Layer.effect(ConfigLoader, makeConfigLoader);
 var PatternMatcher = class {
   constructor(config) {
     __publicField2(this, "ignorePatterns", []);
@@ -417,8 +559,14 @@ var PatternSpanProcessor = class {
   constructor(config, wrappedProcessor) {
     __publicField(this, "matcher");
     __publicField(this, "wrappedProcessor");
+    __publicField(this, "httpIgnorePatterns", []);
     this.matcher = new PatternMatcher(config);
     this.wrappedProcessor = wrappedProcessor;
+    if (config.http?.ignore_incoming_paths) {
+      this.httpIgnorePatterns = config.http.ignore_incoming_paths.map(
+        (pattern) => new RegExp(pattern)
+      );
+    }
   }
   /**
    * Called when a span is started
@@ -436,12 +584,40 @@ var PatternSpanProcessor = class {
    * Called when a span is ended
    *
    * This is where we make the final decision on whether to export the span.
+   * We check both span name patterns and HTTP path patterns.
    */
   onEnd(span) {
     const spanName = span.name;
-    if (this.matcher.shouldInstrument(spanName)) {
-      this.wrappedProcessor.onEnd(span);
+    if (!this.matcher.shouldInstrument(spanName)) {
+      return;
     }
+    if (this.shouldIgnoreHttpSpan(span)) {
+      return;
+    }
+    this.wrappedProcessor.onEnd(span);
+  }
+  /**
+   * Check if span should be ignored based on HTTP path attributes
+   *
+   * This checks the span's url.path, http.route, or http.target attributes
+   * against the configured http.ignore_incoming_paths patterns.
+   *
+   * This enables filtering of Effect HTTP spans (and any other HTTP spans)
+   * based on path patterns, which is essential for filtering out OTLP
+   * endpoint requests like /v1/traces, /v1/logs, /v1/metrics.
+   */
+  shouldIgnoreHttpSpan(span) {
+    if (this.httpIgnorePatterns.length === 0) {
+      return false;
+    }
+    const urlPath = span.attributes["url.path"];
+    const httpRoute = span.attributes["http.route"];
+    const httpTarget = span.attributes["http.target"];
+    const pathToCheck = urlPath || httpRoute || httpTarget;
+    if (!pathToCheck) {
+      return false;
+    }
+    return this.httpIgnorePatterns.some((pattern) => pattern.test(pathToCheck));
   }
   /**
    * Shutdown the processor
@@ -679,83 +855,55 @@ async function getServiceNameAsync() {
 async function getServiceVersionAsync() {
   return Effect.runPromise(getServiceVersion);
 }
-var NodeConfigLoaderLive = ConfigLoaderLive.pipe(
-  Layer.provide(Layer.mergeAll(NodeContext.layer, FetchHttpClient.layer))
-);
-var cachedLoaderPromise = null;
-function getCachedLoader() {
-  if (!cachedLoaderPromise) {
-    cachedLoaderPromise = Effect.runPromise(
-      Effect.gen(function* () {
-        return yield* ConfigLoader;
-      }).pipe(Effect.provide(NodeConfigLoaderLive))
-    );
-  }
-  return cachedLoaderPromise;
+async function loadFromFile(filePath) {
+  const { readFile: readFile2 } = await import('fs/promises');
+  const content = await readFile2(filePath, "utf-8");
+  return parseAndValidateConfig(content);
 }
-function _resetConfigLoaderCache() {
-  cachedLoaderPromise = null;
+async function loadFromUrl(url) {
+  const response = await fetch(url);
+  if (!response.ok) {
+    throw new Error(`Failed to fetch config from ${url}: ${response.statusText}`);
+  }
+  const content = await response.text();
+  return parseAndValidateConfig(content);
 }
-async function loadConfig(uri, options) {
-  if (options?.cacheTimeout === 0) {
-    const program = Effect.gen(function* () {
-      const loader2 = yield* ConfigLoader;
-      return yield* loader2.loadFromUri(uri);
-    });
-    return Effect.runPromise(program.pipe(Effect.provide(NodeConfigLoaderLive)));
+async function loadConfig(uri, _options) {
+  if (uri.startsWith("http://") || uri.startsWith("https://")) {
+    return loadFromUrl(uri);
+  }
+  if (uri.startsWith("file://")) {
+    const filePath = uri.slice(7);
+    return loadFromFile(filePath);
   }
-  const loader = await getCachedLoader();
-  return Effect.runPromise(loader.loadFromUri(uri));
+  return loadFromFile(uri);
 }
 async function loadConfigFromInline(content) {
-  const loader = await getCachedLoader();
-  return Effect.runPromise(loader.loadFromInline(content));
+  return parseAndValidateConfig(content);
 }
-function getDefaultConfig() {
-  return {
-    version: "1.0",
-    instrumentation: {
-      enabled: true,
-      logging: "on",
-      description: "Default instrumentation configuration",
-      instrument_patterns: [
-        { pattern: "^app\\.", enabled: true, description: "Application operations" },
-        { pattern: "^http\\.server\\.", enabled: true, description: "HTTP server operations" },
-        { pattern: "^http\\.client\\.", enabled: true, description: "HTTP client operations" }
-      ],
-      ignore_patterns: [
-        { pattern: "^test\\.", description: "Test utilities" },
-        { pattern: "^internal\\.", description: "Internal operations" },
-        { pattern: "^health\\.", description: "Health checks" }
-      ]
-    },
-    effect: {
-      auto_extract_metadata: true
-    }
-  };
+function _resetConfigLoaderCache() {
 }
 async function loadConfigWithOptions(options = {}) {
-  const loadOptions = options.cacheTimeout !== void 0 ? { cacheTimeout: options.cacheTimeout } : void 0;
   if (options.config) {
     return loadConfigFromInline(options.config);
   }
   const envConfigPath = process.env.ATRIM_INSTRUMENTATION_CONFIG;
   if (envConfigPath) {
-    return loadConfig(envConfigPath, loadOptions);
+    return loadConfig(envConfigPath);
   }
   if (options.configUrl) {
-    return loadConfig(options.configUrl, loadOptions);
+    return loadConfig(options.configUrl);
   }
   if (options.configPath) {
-    return loadConfig(options.configPath, loadOptions);
+    return loadConfig(options.configPath);
   }
   const { existsSync } = await import('fs');
   const { join: join2 } = await import('path');
   const defaultPath = join2(process.cwd(), "instrumentation.yaml");
   if (existsSync(defaultPath)) {
-    return loadConfig(defaultPath, loadOptions);
+    return loadConfig(defaultPath);
   }
-  return getDefaultConfig();
+  return defaultConfig;
 }
 
 // src/core/sdk-initializer.ts
@@ -1047,9 +1195,39 @@ function logInitialization(config, serviceName, serviceVersion, options, autoIns
   logger.log(`  - OTLP endpoint: ${endpoint}`);
   logger.log("");
 }
+var require2 = createRequire(import.meta.url);
+function validateOpenTelemetryApi() {
+  try {
+    require2.resolve("@opentelemetry/api");
+  } catch {
+    throw new Error(
+      "@atrim/instrument-node requires @opentelemetry/api as a peer dependency.\n\nInstall it with:\n  npm install @opentelemetry/api\n\nOr with your preferred package manager:\n  pnpm add @opentelemetry/api\n  yarn add @opentelemetry/api\n  bun add @opentelemetry/api"
+    );
+  }
+}
+function validateEffectDependencies() {
+  const packages = ["effect", "@effect/opentelemetry", "@effect/platform"];
+  for (const pkg of packages) {
+    try {
+      require2.resolve(pkg);
+    } catch {
+      return false;
+    }
+  }
+  return true;
+}
+var validateDependencies = Effect.try({
+  try: () => validateOpenTelemetryApi(),
+  catch: (error) => new InitializationError2({
+    reason: error instanceof Error ? error.message : "Dependency validation failed",
+    cause: error
+  })
+});
+Effect.sync(() => validateEffectDependencies());
 
 // src/api.ts
 async function initializeInstrumentation(options = {}) {
+  validateOpenTelemetryApi();
   const sdk = await initializeSdk(options);
   if (sdk) {
     const config = await loadConfigWithOptions(options);
@@ -1066,6 +1244,7 @@ async function initializePatternMatchingOnly(options = {}) {
   );
 }
 var initializeInstrumentationEffect = (options = {}) => Effect.gen(function* () {
+  yield* validateDependencies;
   const sdk = yield* Effect.tryPromise({
     try: () => initializeSdk(options),
     catch: (error) => new InitializationError2({