@atrim/instrument-node 0.5.0-c05e3a1-20251119131235 → 0.5.1-1451fcf-20260105212505

package/target/dist/index.d.ts

@@ -46,130 +46,33 @@ declare function createOtlpExporter(options?: OtlpExporterOptions): OTLPTraceExp
 declare function getOtlpEndpoint(options?: OtlpExporterOptions): string;
 
 /**
- * Typed error hierarchy for @atrim/instrumentation
+ * Node.js configuration loader
  *
- * These errors use Effect's Data.TaggedError for typed error handling
- * with proper discriminated unions.
- */
-declare const ConfigError_base: new <A extends Record<string, any> = {}>(args: effect_Types.Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => effect_Cause.YieldableError & {
-    readonly _tag: "ConfigError";
-} & Readonly<A>;
-/**
- * Base error for configuration-related failures
- */
-declare class ConfigError extends ConfigError_base<{
-    reason: string;
-    cause?: unknown;
-}> {
-}
-declare const ConfigUrlError_base: new <A extends Record<string, any> = {}>(args: effect_Types.Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => effect_Cause.YieldableError & {
-    readonly _tag: "ConfigUrlError";
-} & Readonly<A>;
-/**
- * Error when fetching configuration from a URL fails
- */
-declare class ConfigUrlError extends ConfigUrlError_base<{
-    reason: string;
-    cause?: unknown;
-}> {
-}
-declare const ConfigValidationError_base: new <A extends Record<string, any> = {}>(args: effect_Types.Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => effect_Cause.YieldableError & {
-    readonly _tag: "ConfigValidationError";
-} & Readonly<A>;
-/**
- * Error when configuration validation fails (invalid YAML, schema mismatch)
- */
-declare class ConfigValidationError extends ConfigValidationError_base<{
-    reason: string;
-    cause?: unknown;
-}> {
-}
-declare const ConfigFileError_base: new <A extends Record<string, any> = {}>(args: effect_Types.Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => effect_Cause.YieldableError & {
-    readonly _tag: "ConfigFileError";
-} & Readonly<A>;
-/**
- * Error when reading configuration from a file fails
+ * Provides configuration loading using native Node.js APIs (fs, fetch)
+ * This module doesn't require Effect Platform, making it work without Effect installed.
  */
-declare class ConfigFileError extends ConfigFileError_base<{
-    reason: string;
-    cause?: unknown;
-}> {
-}
-declare const ServiceDetectionError_base: new <A extends Record<string, any> = {}>(args: effect_Types.Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => effect_Cause.YieldableError & {
-    readonly _tag: "ServiceDetectionError";
-} & Readonly<A>;
-/**
- * Error when service detection fails (package.json not found, invalid format)
- */
-declare class ServiceDetectionError extends ServiceDetectionError_base<{
-    reason: string;
-    cause?: unknown;
-}> {
-}
-declare const InitializationError_base: new <A extends Record<string, any> = {}>(args: effect_Types.Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => effect_Cause.YieldableError & {
-    readonly _tag: "InitializationError";
-} & Readonly<A>;
-/**
- * Error when OpenTelemetry SDK initialization fails
- */
-declare class InitializationError extends InitializationError_base<{
-    reason: string;
-    cause?: unknown;
-}> {
-}
-declare const ExportError_base: new <A extends Record<string, any> = {}>(args: effect_Types.Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => effect_Cause.YieldableError & {
-    readonly _tag: "ExportError";
-} & Readonly<A>;
-/**
- * Error when span export fails (e.g., ECONNREFUSED to collector)
- */
-declare class ExportError extends ExportError_base<{
-    reason: string;
-    cause?: unknown;
-}> {
-}
-declare const ShutdownError_base: new <A extends Record<string, any> = {}>(args: effect_Types.Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => effect_Cause.YieldableError & {
-    readonly _tag: "ShutdownError";
-} & Readonly<A>;
-/**
- * Error when shutting down the SDK fails
- */
-declare class ShutdownError extends ShutdownError_base<{
-    reason: string;
-    cause?: unknown;
-}> {
-}
 
 /**
- * Node.js configuration loader using Effect Platform
- *
- * Provides FileSystem and HttpClient layers for the core ConfigLoader service
- */
-
-/**
- * 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
  */
@@ -305,6 +208,101 @@ declare function shutdownSdk(): Promise<void>;
  */
 declare function resetSdk(): void;
 
+/**
+ * Typed error hierarchy for @atrim/instrumentation
+ *
+ * These errors use Effect's Data.TaggedError for typed error handling
+ * with proper discriminated unions.
+ */
+declare const ConfigError_base: new <A extends Record<string, any> = {}>(args: effect_Types.Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => effect_Cause.YieldableError & {
+    readonly _tag: "ConfigError";
+} & Readonly<A>;
+/**
+ * Base error for configuration-related failures
+ */
+declare class ConfigError extends ConfigError_base<{
+    reason: string;
+    cause?: unknown;
+}> {
+}
+declare const ConfigUrlError_base: new <A extends Record<string, any> = {}>(args: effect_Types.Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => effect_Cause.YieldableError & {
+    readonly _tag: "ConfigUrlError";
+} & Readonly<A>;
+/**
+ * Error when fetching configuration from a URL fails
+ */
+declare class ConfigUrlError extends ConfigUrlError_base<{
+    reason: string;
+    cause?: unknown;
+}> {
+}
+declare const ConfigValidationError_base: new <A extends Record<string, any> = {}>(args: effect_Types.Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => effect_Cause.YieldableError & {
+    readonly _tag: "ConfigValidationError";
+} & Readonly<A>;
+/**
+ * Error when configuration validation fails (invalid YAML, schema mismatch)
+ */
+declare class ConfigValidationError extends ConfigValidationError_base<{
+    reason: string;
+    cause?: unknown;
+}> {
+}
+declare const ConfigFileError_base: new <A extends Record<string, any> = {}>(args: effect_Types.Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => effect_Cause.YieldableError & {
+    readonly _tag: "ConfigFileError";
+} & Readonly<A>;
+/**
+ * Error when reading configuration from a file fails
+ */
+declare class ConfigFileError extends ConfigFileError_base<{
+    reason: string;
+    cause?: unknown;
+}> {
+}
+declare const ServiceDetectionError_base: new <A extends Record<string, any> = {}>(args: effect_Types.Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => effect_Cause.YieldableError & {
+    readonly _tag: "ServiceDetectionError";
+} & Readonly<A>;
+/**
+ * Error when service detection fails (package.json not found, invalid format)
+ */
+declare class ServiceDetectionError extends ServiceDetectionError_base<{
+    reason: string;
+    cause?: unknown;
+}> {
+}
+declare const InitializationError_base: new <A extends Record<string, any> = {}>(args: effect_Types.Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => effect_Cause.YieldableError & {
+    readonly _tag: "InitializationError";
+} & Readonly<A>;
+/**
+ * Error when OpenTelemetry SDK initialization fails
+ */
+declare class InitializationError extends InitializationError_base<{
+    reason: string;
+    cause?: unknown;
+}> {
+}
+declare const ExportError_base: new <A extends Record<string, any> = {}>(args: effect_Types.Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => effect_Cause.YieldableError & {
+    readonly _tag: "ExportError";
+} & Readonly<A>;
+/**
+ * Error when span export fails (e.g., ECONNREFUSED to collector)
+ */
+declare class ExportError extends ExportError_base<{
+    reason: string;
+    cause?: unknown;
+}> {
+}
+declare const ShutdownError_base: new <A extends Record<string, any> = {}>(args: effect_Types.Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => effect_Cause.YieldableError & {
+    readonly _tag: "ShutdownError";
+} & Readonly<A>;
+/**
+ * Error when shutting down the SDK fails
+ */
+declare class ShutdownError extends ShutdownError_base<{
+    reason: string;
+    cause?: unknown;
+}> {
+}
+
 /**
  * Public API for standard OpenTelemetry usage
  *
@@ -398,6 +396,17 @@ declare function resetSdk(): void;
  * })
  * ```
  */
+declare function initializeInstrumentation(options?: SdkInitializationOptions): Promise<NodeSDK | null>;
+/**
+ * Legacy initialization function for pattern-only mode
+ *
+ * This function only initializes pattern matching without setting up the NodeSDK.
+ * Use this if you want to manually configure OpenTelemetry while still using
+ * pattern-based filtering.
+ *
+ * @deprecated Use initializeInstrumentation() instead for complete setup
+ */
+declare function initializePatternMatchingOnly(options?: SdkInitializationOptions): Promise<void>;
 /**
  * Initialize OpenTelemetry instrumentation (Effect version)
  *
@@ -410,14 +419,15 @@ declare function resetSdk(): void;
  * @example
  * ```typescript
  * import { Effect } from 'effect'
- * import { initializeInstrumentation } from '@atrim/instrumentation'
+ * import { initializeInstrumentationEffect } from '@atrim/instrumentation'
+ *
+ * // Basic usage
+ * const program = initializeInstrumentationEffect()
  *
- * // Zero-config initialization (recommended)
- * const program = initializeInstrumentation()
  * await Effect.runPromise(program)
  *
  * // With error handling
- * const program = initializeInstrumentation().pipe(
+ * const program = initializeInstrumentationEffect().pipe(
  *   Effect.catchTag('ConfigError', (error) => {
  *     console.error('Config error:', error.reason)
  *     return Effect.succeed(null)
@@ -428,16 +438,18 @@ declare function resetSdk(): void;
  *   })
  * )
  *
- * // With custom OTLP endpoint
- * const program = initializeInstrumentation({
+ * await Effect.runPromise(program)
+ *
+ * // With custom options
+ * const program = initializeInstrumentationEffect({
  *   otlp: { endpoint: 'https://otel.company.com:4318' },
  *   serviceName: 'my-service'
  * })
  * ```
  */
-declare const initializeInstrumentation: (options?: SdkInitializationOptions) => Effect.Effect<NodeSDK | null, InitializationError | ConfigError>;
+declare const initializeInstrumentationEffect: (options?: SdkInitializationOptions) => Effect.Effect<NodeSDK | null, InitializationError | ConfigError>;
 /**
- * Initialize pattern matching only
+ * Initialize pattern matching only (Effect version)
  *
  * Use this if you want manual OpenTelemetry setup with pattern filtering.
  *
@@ -447,9 +459,9 @@ declare const initializeInstrumentation: (options?: SdkInitializationOptions) =>
  * @example
  * ```typescript
  * import { Effect } from 'effect'
- * import { initializePatternMatchingOnly } from '@atrim/instrumentation'
+ * import { initializePatternMatchingOnlyEffect } from '@atrim/instrumentation'
  *
- * const program = initializePatternMatchingOnly({
+ * const program = initializePatternMatchingOnlyEffect({
  *   configPath: './instrumentation.yaml'
  * }).pipe(
  *   Effect.catchAll((error) => {
@@ -461,7 +473,7 @@ declare const initializeInstrumentation: (options?: SdkInitializationOptions) =>
  * await Effect.runPromise(program)
  * ```
  */
-declare const initializePatternMatchingOnly: (options?: SdkInitializationOptions) => Effect.Effect<void, ConfigError>;
+declare const initializePatternMatchingOnlyEffect: (options?: SdkInitializationOptions) => Effect.Effect<void, ConfigError>;
 
 /**
  * Service Detection Utilities
@@ -508,6 +520,25 @@ declare const getServiceVersion: Effect.Effect<string | undefined, never>;
  * Never fails - returns default ServiceInfo if detection fails
  */
 declare const getServiceInfoWithFallback: Effect.Effect<ServiceInfo, never>;
+/**
+ * Detect service name and version (Promise version)
+ *
+ * @deprecated Use `detectServiceInfo` Effect API for better error handling
+ * @returns Promise that resolves to ServiceInfo with fallback
+ */
+declare function detectServiceInfoAsync(): Promise<ServiceInfo>;
+/**
+ * Get service name with fallback (Promise version)
+ *
+ * @deprecated Use `getServiceName` Effect API
+ */
+declare function getServiceNameAsync(): Promise<string>;
+/**
+ * Get service version if available (Promise version)
+ *
+ * @deprecated Use `getServiceVersion` Effect API
+ */
+declare function getServiceVersionAsync(): Promise<string | undefined>;
 
 /**
  * OpenTelemetry SpanProcessor for pattern-based filtering
@@ -515,6 +546,10 @@ declare const getServiceInfoWithFallback: Effect.Effect<ServiceInfo, never>;
  * 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
  */
 
 /**
@@ -537,6 +572,7 @@ declare const getServiceInfoWithFallback: Effect.Effect<ServiceInfo, never>;
 declare class PatternSpanProcessor implements SpanProcessor {
     private matcher;
     private wrappedProcessor;
+    private httpIgnorePatterns;
     constructor(config: InstrumentationConfig, wrappedProcessor: SpanProcessor);
     /**
      * Called when a span is started
@@ -549,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
      */
@@ -620,4 +668,4 @@ declare function annotateCacheOperation(span: Span$1, operation: 'get' | 'set' |
  */
 declare function suppressShutdownErrors(): void;
 
-export { ConfigError, ConfigFileError, type ConfigLoaderOptions, ConfigUrlError, ConfigValidationError, ExportError, InitializationError, type OtlpExporterOptions, PatternSpanProcessor, type SdkInitializationOptions, ServiceDetectionError, type ServiceInfo, ShutdownError, annotateCacheOperation, annotateDbQuery, annotateHttpRequest, _resetConfigLoaderCache as clearConfigCache, createOtlpExporter, detectServiceInfo, getOtlpEndpoint, getSdkInstance, getServiceInfoWithFallback, getServiceName, getServiceVersion, initializeInstrumentation, initializePatternMatchingOnly, loadConfig, loadConfigFromInline, loadConfigWithOptions, markSpanError, markSpanSuccess, recordException, resetSdk, setSpanAttributes, shutdownSdk, suppressShutdownErrors };
+export { ConfigError, ConfigFileError, type ConfigLoaderOptions, ConfigUrlError, ConfigValidationError, ExportError, InitializationError, type OtlpExporterOptions, PatternSpanProcessor, type SdkInitializationOptions, ServiceDetectionError, type ServiceInfo, ShutdownError, annotateCacheOperation, annotateDbQuery, annotateHttpRequest, _resetConfigLoaderCache as clearConfigCache, createOtlpExporter, detectServiceInfoAsync as detectServiceInfo, detectServiceInfo as detectServiceInfoEffect, getOtlpEndpoint, getSdkInstance, getServiceInfoWithFallback, getServiceNameAsync as getServiceName, getServiceName as getServiceNameEffect, getServiceVersionAsync as getServiceVersion, getServiceVersion as getServiceVersionEffect, initializeInstrumentation, initializeInstrumentationEffect, initializePatternMatchingOnly, initializePatternMatchingOnlyEffect, loadConfig, loadConfigFromInline, loadConfigWithOptions, markSpanError, markSpanSuccess, recordException, resetSdk, setSpanAttributes, shutdownSdk, suppressShutdownErrors };