@atrim/instrument-node 0.4.0 → 0.5.0-c05e3a1-20251119131235

package/target/dist/index.d.ts

@@ -3,8 +3,8 @@ import { NodeSDKConfiguration, NodeSDK } from '@opentelemetry/sdk-node';
 import { Instrumentation } from '@opentelemetry/instrumentation';
 import { RequestOptions, IncomingMessage } from 'node:http';
 import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
-import { ConfigLoaderOptions, InstrumentationConfig, PatternMatcher } from '@atrim/instrument-core';
-export { ConfigLoaderOptions, InstrumentationConfig, PatternConfig, PatternMatcher, getPatternMatcher, loadConfig, shouldInstrumentSpan } from '@atrim/instrument-core';
+import { InstrumentationConfig, PatternMatcher } from '@atrim/instrument-core';
+export { InstrumentationConfig, PatternConfig, PatternMatcher, getPatternMatcher, shouldInstrumentSpan } from '@atrim/instrument-core';
 import * as effect_Cause from 'effect/Cause';
 import * as effect_Types from 'effect/Types';
 import { SpanProcessor, Span, ReadableSpan } from '@opentelemetry/sdk-trace-base';
@@ -45,6 +45,155 @@ declare function createOtlpExporter(options?: OtlpExporterOptions): OTLPTraceExp
  */
 declare function getOtlpEndpoint(options?: OtlpExporterOptions): string;
 
+/**
+ * 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;
+}> {
+}
+
+/**
+ * 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)
+ *
+ * @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?: {
+    cacheTimeout?: number;
+}): 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>;
+/**
+ * Legacy options interface for backward compatibility
+ */
+interface ConfigLoaderOptions {
+    configPath?: string;
+    configUrl?: string;
+    config?: InstrumentationConfig;
+    cacheTimeout?: number;
+}
+/**
+ * Load configuration with priority order (backward compatible API)
+ *
+ * Priority order (highest to lowest):
+ * 1. Explicit config object (options.config)
+ * 2. Environment variable (ATRIM_INSTRUMENTATION_CONFIG)
+ * 3. Explicit path/URL (options.configPath or options.configUrl)
+ * 4. Project root file (./instrumentation.yaml)
+ * 5. Default config (built-in defaults)
+ *
+ * @param options - Configuration options
+ * @returns Promise that resolves to validated configuration
+ */
+declare function loadConfigWithOptions(options?: ConfigLoaderOptions): Promise<InstrumentationConfig>;
+
 /**
  * NodeSDK Initialization
  *
@@ -156,101 +305,6 @@ 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
  *
@@ -344,17 +398,6 @@ declare class ShutdownError extends ShutdownError_base<{
  * })
  * ```
  */
-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)
  *
@@ -367,15 +410,14 @@ declare function initializePatternMatchingOnly(options?: SdkInitializationOption
  * @example
  * ```typescript
  * import { Effect } from 'effect'
- * import { initializeInstrumentationEffect } from '@atrim/instrumentation'
- *
- * // Basic usage
- * const program = initializeInstrumentationEffect()
+ * import { initializeInstrumentation } from '@atrim/instrumentation'
  *
+ * // Zero-config initialization (recommended)
+ * const program = initializeInstrumentation()
  * await Effect.runPromise(program)
  *
  * // With error handling
- * const program = initializeInstrumentationEffect().pipe(
+ * const program = initializeInstrumentation().pipe(
  *   Effect.catchTag('ConfigError', (error) => {
  *     console.error('Config error:', error.reason)
  *     return Effect.succeed(null)
@@ -386,18 +428,16 @@ declare function initializePatternMatchingOnly(options?: SdkInitializationOption
  *   })
  * )
  *
- * await Effect.runPromise(program)
- *
- * // With custom options
- * const program = initializeInstrumentationEffect({
+ * // With custom OTLP endpoint
+ * const program = initializeInstrumentation({
  *   otlp: { endpoint: 'https://otel.company.com:4318' },
  *   serviceName: 'my-service'
  * })
  * ```
  */
-declare const initializeInstrumentationEffect: (options?: SdkInitializationOptions) => Effect.Effect<NodeSDK | null, InitializationError | ConfigError>;
+declare const initializeInstrumentation: (options?: SdkInitializationOptions) => Effect.Effect<NodeSDK | null, InitializationError | ConfigError>;
 /**
- * Initialize pattern matching only (Effect version)
+ * Initialize pattern matching only
  *
  * Use this if you want manual OpenTelemetry setup with pattern filtering.
  *
@@ -407,9 +447,9 @@ declare const initializeInstrumentationEffect: (options?: SdkInitializationOptio
  * @example
  * ```typescript
  * import { Effect } from 'effect'
- * import { initializePatternMatchingOnlyEffect } from '@atrim/instrumentation'
+ * import { initializePatternMatchingOnly } from '@atrim/instrumentation'
  *
- * const program = initializePatternMatchingOnlyEffect({
+ * const program = initializePatternMatchingOnly({
  *   configPath: './instrumentation.yaml'
  * }).pipe(
  *   Effect.catchAll((error) => {
@@ -421,7 +461,7 @@ declare const initializeInstrumentationEffect: (options?: SdkInitializationOptio
  * await Effect.runPromise(program)
  * ```
  */
-declare const initializePatternMatchingOnlyEffect: (options?: SdkInitializationOptions) => Effect.Effect<void, ConfigError>;
+declare const initializePatternMatchingOnly: (options?: SdkInitializationOptions) => Effect.Effect<void, ConfigError>;
 
 /**
  * Service Detection Utilities
@@ -468,25 +508,6 @@ 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
@@ -599,4 +620,4 @@ declare function annotateCacheOperation(span: Span$1, operation: 'get' | 'set' |
  */
 declare function suppressShutdownErrors(): void;
 
-export { ConfigError, ConfigFileError, ConfigUrlError, ConfigValidationError, ExportError, InitializationError, type OtlpExporterOptions, PatternSpanProcessor, type SdkInitializationOptions, ServiceDetectionError, type ServiceInfo, ShutdownError, annotateCacheOperation, annotateDbQuery, annotateHttpRequest, 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, 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, detectServiceInfo, getOtlpEndpoint, getSdkInstance, getServiceInfoWithFallback, getServiceName, getServiceVersion, initializeInstrumentation, initializePatternMatchingOnly, loadConfig, loadConfigFromInline, loadConfigWithOptions, markSpanError, markSpanSuccess, recordException, resetSdk, setSpanAttributes, shutdownSdk, suppressShutdownErrors };