@atrim/instrument-node 0.5.0 → 0.5.1

package/target/dist/integrations/effect/index.d.cts

@@ -1,4 +1,4 @@
-import { Layer, FiberSet as FiberSet$1, Effect } from 'effect';
+import { Layer, Effect, FiberSet as FiberSet$1 } from 'effect';
 import { InstrumentationConfig } from '@atrim/instrument-core';
 import * as effect_Runtime from 'effect/Runtime';
 import * as effect_FiberId from 'effect/FiberId';
@@ -142,23 +142,111 @@ declare const EffectInstrumentationLive: Layer.Layer<never, never, never>;
 
 /**
  * Effect-specific span annotation helpers
+ *
+ * Provides reusable helper functions for adding common span attributes.
+ * These helpers follow OpenTelemetry semantic conventions and platform patterns.
+ *
+ * Usage:
+ * ```typescript
+ * Effect.gen(function* () {
+ *   yield* annotateUser(userId, email)
+ *   yield* annotateBatch(items.length, 5)
+ *   const results = yield* storage.writeBatch(items)
+ *   yield* annotateBatch(items.length, 5, results.success, results.failures)
+ * }).pipe(Effect.withSpan('storage.writeBatch'))
+ * ```
  */
-declare function annotateUser(_userId: string, _email?: string): void;
-declare function annotateDataSize(_bytes: number, _count: number): void;
-declare function annotateBatch(_size: number, _batchSize: number): void;
-declare function annotateLLM(_model: string, _operation: string, _inputTokens: number, _outputTokens: number): void;
-declare function annotateQuery(_query: string, _database: string): void;
-declare function annotateHttpRequest(_method: string, _url: string, _statusCode: number): void;
-declare function annotateError(_error: Error, _context?: Record<string, string | number | boolean>): void;
-declare function annotatePriority(_priority: string): void;
-declare function annotateCache(_operation: string, _hit: boolean): void;
+
+/**
+ * Annotate span with user context
+ *
+ * @param userId - User identifier
+ * @param email - Optional user email
+ * @param username - Optional username
+ */
+declare function annotateUser(userId: string, email?: string, username?: string): Effect.Effect<void, never, never>;
+/**
+ * Annotate span with data size metrics
+ *
+ * @param bytes - Total bytes processed
+ * @param items - Number of items
+ * @param compressionRatio - Optional compression ratio
+ */
+declare function annotateDataSize(bytes: number, items: number, compressionRatio?: number): Effect.Effect<void, never, never>;
+/**
+ * Annotate span with batch operation metadata
+ *
+ * @param totalItems - Total number of items in batch
+ * @param batchSize - Size of each batch
+ * @param successCount - Optional number of successful items
+ * @param failureCount - Optional number of failed items
+ */
+declare function annotateBatch(totalItems: number, batchSize: number, successCount?: number, failureCount?: number): Effect.Effect<void, never, never>;
+/**
+ * Annotate span with LLM operation metadata
+ *
+ * @param model - Model name (e.g., 'gpt-4', 'claude-3-opus')
+ * @param provider - LLM provider (e.g., 'openai', 'anthropic')
+ * @param tokens - Optional token usage information
+ */
+declare function annotateLLM(model: string, provider: string, tokens?: {
+    prompt?: number;
+    completion?: number;
+    total?: number;
+}): Effect.Effect<void, never, never>;
+/**
+ * Annotate span with database query metadata
+ *
+ * @param query - SQL query or query description
+ * @param duration - Optional query duration in milliseconds
+ * @param rowCount - Optional number of rows returned/affected
+ * @param database - Optional database name
+ */
+declare function annotateQuery(query: string, duration?: number, rowCount?: number, database?: string): Effect.Effect<void, never, never>;
+/**
+ * Annotate span with HTTP request metadata
+ *
+ * @param method - HTTP method (GET, POST, etc.)
+ * @param url - Request URL
+ * @param statusCode - Optional HTTP status code
+ * @param contentLength - Optional response content length
+ */
+declare function annotateHttpRequest(method: string, url: string, statusCode?: number, contentLength?: number): Effect.Effect<void, never, never>;
+/**
+ * Annotate span with error context
+ *
+ * @param error - Error object or message
+ * @param recoverable - Whether the error is recoverable
+ * @param errorType - Optional error type/category
+ */
+declare function annotateError(error: Error | string, recoverable: boolean, errorType?: string): Effect.Effect<void, never, never>;
+/**
+ * Annotate span with operation priority
+ *
+ * @param priority - Priority level (high, medium, low)
+ * @param reason - Optional reason for priority level
+ */
+declare function annotatePriority(priority: 'high' | 'medium' | 'low', reason?: string): Effect.Effect<void, never, never>;
+/**
+ * Annotate span with cache operation metadata
+ *
+ * @param hit - Whether the cache was hit
+ * @param key - Cache key
+ * @param ttl - Optional time-to-live in seconds
+ */
+declare function annotateCache(hit: boolean, key: string, ttl?: number): Effect.Effect<void, never, never>;
 
 /**
  * Effect metadata extraction
  *
  * Automatically extracts metadata from Effect fibers and adds them as span attributes.
  * This provides valuable context about the Effect execution environment.
+ *
+ * Uses Effect's public APIs:
+ * - Fiber.getCurrentFiber() - Get current fiber information
+ * - Effect.currentSpan - Detect parent spans and nesting
  */
+
 /**
  * Metadata extracted from Effect fibers
  */
@@ -166,8 +254,95 @@ interface EffectMetadata {
     'effect.fiber.id'?: string;
     'effect.fiber.status'?: string;
     'effect.operation.root'?: boolean;
-    'effect.operation.interrupted'?: boolean;
+    'effect.operation.nested'?: boolean;
+    'effect.parent.span.id'?: string;
+    'effect.parent.span.name'?: string;
+    'effect.parent.trace.id'?: string;
 }
+/**
+ * Extract Effect-native metadata from current execution context
+ *
+ * Uses Effect's native APIs:
+ * - Fiber.getCurrentFiber() - Get current fiber information
+ * - Effect.currentSpan - Detect parent spans and nesting
+ *
+ * @returns Effect that yields extracted metadata
+ */
+declare function extractEffectMetadata(): Effect.Effect<EffectMetadata>;
+
+/**
+ * Effect Auto-Enrichment Utilities
+ *
+ * Provides utilities for automatically extracting and enriching spans with Effect-native metadata.
+ *
+ * Usage:
+ * ```typescript
+ * import { autoEnrichSpan, withAutoEnrichedSpan } from '@atrim/instrument-node/effect'
+ *
+ * // Option 1: Manual enrichment
+ * Effect.gen(function* () {
+ *   yield* autoEnrichSpan()  // Auto-add Effect metadata
+ *   yield* annotateBatch(items.length, 10)  // Add custom attributes
+ *   const result = yield* storage.writeBatch(items)
+ *   return result
+ * }).pipe(Effect.withSpan('storage.writeBatch'))
+ *
+ * // Option 2: Automatic enrichment wrapper
+ * const instrumented = withAutoEnrichedSpan('storage.writeBatch')(
+ *   Effect.gen(function* () {
+ *     yield* annotateBatch(items.length, 10)
+ *     return yield* storage.writeBatch(items)
+ *   })
+ * )
+ * ```
+ */
+
+/**
+ * Auto-enrich the current span with Effect metadata
+ *
+ * This function should be called within an Effect.withSpan() context.
+ * It extracts Effect metadata (fiber ID, status, parent span info)
+ * and adds it as span attributes.
+ *
+ * Best practice: Call this at the start of your instrumented Effect:
+ *
+ * ```typescript
+ * Effect.gen(function* () {
+ *   yield* autoEnrichSpan()  // Auto-add metadata
+ *   yield* annotateBatch(items.length, 10)  // Add custom attributes
+ *   const result = yield* storage.writeBatch(items)
+ *   return result
+ * }).pipe(Effect.withSpan('storage.writeBatch'))
+ * ```
+ *
+ * @returns Effect that annotates the current span with Effect metadata
+ */
+declare function autoEnrichSpan(): Effect.Effect<void>;
+/**
+ * Create a wrapper that combines Effect.withSpan with automatic enrichment
+ *
+ * This is a convenience function that wraps an Effect with both:
+ * 1. A span (via Effect.withSpan)
+ * 2. Automatic metadata extraction (via autoEnrichSpan)
+ *
+ * Usage:
+ * ```typescript
+ * const instrumented = withAutoEnrichedSpan('storage.writeBatch')(
+ *   Effect.gen(function* () {
+ *     yield* annotateBatch(items.length, 10)
+ *     return yield* storage.writeBatch(items)
+ *   })
+ * )
+ * ```
+ *
+ * @param spanName - The name of the span
+ * @param options - Optional span options
+ * @returns Function that wraps an Effect with an auto-enriched span
+ */
+declare function withAutoEnrichedSpan<A, E, R>(spanName: string, options?: {
+    readonly attributes?: Record<string, unknown>;
+    readonly kind?: 'client' | 'server' | 'producer' | 'consumer' | 'internal';
+}): (self: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>;
 
 /**
  * Options for span isolation when running effects in FiberSet
@@ -356,4 +531,4 @@ declare const FiberSet: {
     }) => Effect.Effect<RuntimeFiber<A, E>, never, R>;
 };
 
-export { EffectInstrumentationLive, type EffectMetadata, FiberSet, type IsolationOptions, annotateBatch, annotateCache, annotateDataSize, annotateError, annotateHttpRequest, annotateLLM, annotatePriority, annotateQuery, annotateSpawnedTasks, annotateUser, createEffectInstrumentation, runIsolated, runWithSpan };
+export { EffectInstrumentationLive, type EffectMetadata, FiberSet, type IsolationOptions, annotateBatch, annotateCache, annotateDataSize, annotateError, annotateHttpRequest, annotateLLM, annotatePriority, annotateQuery, annotateSpawnedTasks, annotateUser, autoEnrichSpan, createEffectInstrumentation, extractEffectMetadata, runIsolated, runWithSpan, withAutoEnrichedSpan };

package/target/dist/integrations/effect/index.d.ts

@@ -1,4 +1,4 @@
-import { Layer, FiberSet as FiberSet$1, Effect } from 'effect';
+import { Layer, Effect, FiberSet as FiberSet$1 } from 'effect';
 import { InstrumentationConfig } from '@atrim/instrument-core';
 import * as effect_Runtime from 'effect/Runtime';
 import * as effect_FiberId from 'effect/FiberId';
@@ -142,23 +142,111 @@ declare const EffectInstrumentationLive: Layer.Layer<never, never, never>;
 
 /**
  * Effect-specific span annotation helpers
+ *
+ * Provides reusable helper functions for adding common span attributes.
+ * These helpers follow OpenTelemetry semantic conventions and platform patterns.
+ *
+ * Usage:
+ * ```typescript
+ * Effect.gen(function* () {
+ *   yield* annotateUser(userId, email)
+ *   yield* annotateBatch(items.length, 5)
+ *   const results = yield* storage.writeBatch(items)
+ *   yield* annotateBatch(items.length, 5, results.success, results.failures)
+ * }).pipe(Effect.withSpan('storage.writeBatch'))
+ * ```
  */
-declare function annotateUser(_userId: string, _email?: string): void;
-declare function annotateDataSize(_bytes: number, _count: number): void;
-declare function annotateBatch(_size: number, _batchSize: number): void;
-declare function annotateLLM(_model: string, _operation: string, _inputTokens: number, _outputTokens: number): void;
-declare function annotateQuery(_query: string, _database: string): void;
-declare function annotateHttpRequest(_method: string, _url: string, _statusCode: number): void;
-declare function annotateError(_error: Error, _context?: Record<string, string | number | boolean>): void;
-declare function annotatePriority(_priority: string): void;
-declare function annotateCache(_operation: string, _hit: boolean): void;
+
+/**
+ * Annotate span with user context
+ *
+ * @param userId - User identifier
+ * @param email - Optional user email
+ * @param username - Optional username
+ */
+declare function annotateUser(userId: string, email?: string, username?: string): Effect.Effect<void, never, never>;
+/**
+ * Annotate span with data size metrics
+ *
+ * @param bytes - Total bytes processed
+ * @param items - Number of items
+ * @param compressionRatio - Optional compression ratio
+ */
+declare function annotateDataSize(bytes: number, items: number, compressionRatio?: number): Effect.Effect<void, never, never>;
+/**
+ * Annotate span with batch operation metadata
+ *
+ * @param totalItems - Total number of items in batch
+ * @param batchSize - Size of each batch
+ * @param successCount - Optional number of successful items
+ * @param failureCount - Optional number of failed items
+ */
+declare function annotateBatch(totalItems: number, batchSize: number, successCount?: number, failureCount?: number): Effect.Effect<void, never, never>;
+/**
+ * Annotate span with LLM operation metadata
+ *
+ * @param model - Model name (e.g., 'gpt-4', 'claude-3-opus')
+ * @param provider - LLM provider (e.g., 'openai', 'anthropic')
+ * @param tokens - Optional token usage information
+ */
+declare function annotateLLM(model: string, provider: string, tokens?: {
+    prompt?: number;
+    completion?: number;
+    total?: number;
+}): Effect.Effect<void, never, never>;
+/**
+ * Annotate span with database query metadata
+ *
+ * @param query - SQL query or query description
+ * @param duration - Optional query duration in milliseconds
+ * @param rowCount - Optional number of rows returned/affected
+ * @param database - Optional database name
+ */
+declare function annotateQuery(query: string, duration?: number, rowCount?: number, database?: string): Effect.Effect<void, never, never>;
+/**
+ * Annotate span with HTTP request metadata
+ *
+ * @param method - HTTP method (GET, POST, etc.)
+ * @param url - Request URL
+ * @param statusCode - Optional HTTP status code
+ * @param contentLength - Optional response content length
+ */
+declare function annotateHttpRequest(method: string, url: string, statusCode?: number, contentLength?: number): Effect.Effect<void, never, never>;
+/**
+ * Annotate span with error context
+ *
+ * @param error - Error object or message
+ * @param recoverable - Whether the error is recoverable
+ * @param errorType - Optional error type/category
+ */
+declare function annotateError(error: Error | string, recoverable: boolean, errorType?: string): Effect.Effect<void, never, never>;
+/**
+ * Annotate span with operation priority
+ *
+ * @param priority - Priority level (high, medium, low)
+ * @param reason - Optional reason for priority level
+ */
+declare function annotatePriority(priority: 'high' | 'medium' | 'low', reason?: string): Effect.Effect<void, never, never>;
+/**
+ * Annotate span with cache operation metadata
+ *
+ * @param hit - Whether the cache was hit
+ * @param key - Cache key
+ * @param ttl - Optional time-to-live in seconds
+ */
+declare function annotateCache(hit: boolean, key: string, ttl?: number): Effect.Effect<void, never, never>;
 
 /**
  * Effect metadata extraction
  *
  * Automatically extracts metadata from Effect fibers and adds them as span attributes.
  * This provides valuable context about the Effect execution environment.
+ *
+ * Uses Effect's public APIs:
+ * - Fiber.getCurrentFiber() - Get current fiber information
+ * - Effect.currentSpan - Detect parent spans and nesting
  */
+
 /**
  * Metadata extracted from Effect fibers
  */
@@ -166,8 +254,95 @@ interface EffectMetadata {
     'effect.fiber.id'?: string;
     'effect.fiber.status'?: string;
     'effect.operation.root'?: boolean;
-    'effect.operation.interrupted'?: boolean;
+    'effect.operation.nested'?: boolean;
+    'effect.parent.span.id'?: string;
+    'effect.parent.span.name'?: string;
+    'effect.parent.trace.id'?: string;
 }
+/**
+ * Extract Effect-native metadata from current execution context
+ *
+ * Uses Effect's native APIs:
+ * - Fiber.getCurrentFiber() - Get current fiber information
+ * - Effect.currentSpan - Detect parent spans and nesting
+ *
+ * @returns Effect that yields extracted metadata
+ */
+declare function extractEffectMetadata(): Effect.Effect<EffectMetadata>;
+
+/**
+ * Effect Auto-Enrichment Utilities
+ *
+ * Provides utilities for automatically extracting and enriching spans with Effect-native metadata.
+ *
+ * Usage:
+ * ```typescript
+ * import { autoEnrichSpan, withAutoEnrichedSpan } from '@atrim/instrument-node/effect'
+ *
+ * // Option 1: Manual enrichment
+ * Effect.gen(function* () {
+ *   yield* autoEnrichSpan()  // Auto-add Effect metadata
+ *   yield* annotateBatch(items.length, 10)  // Add custom attributes
+ *   const result = yield* storage.writeBatch(items)
+ *   return result
+ * }).pipe(Effect.withSpan('storage.writeBatch'))
+ *
+ * // Option 2: Automatic enrichment wrapper
+ * const instrumented = withAutoEnrichedSpan('storage.writeBatch')(
+ *   Effect.gen(function* () {
+ *     yield* annotateBatch(items.length, 10)
+ *     return yield* storage.writeBatch(items)
+ *   })
+ * )
+ * ```
+ */
+
+/**
+ * Auto-enrich the current span with Effect metadata
+ *
+ * This function should be called within an Effect.withSpan() context.
+ * It extracts Effect metadata (fiber ID, status, parent span info)
+ * and adds it as span attributes.
+ *
+ * Best practice: Call this at the start of your instrumented Effect:
+ *
+ * ```typescript
+ * Effect.gen(function* () {
+ *   yield* autoEnrichSpan()  // Auto-add metadata
+ *   yield* annotateBatch(items.length, 10)  // Add custom attributes
+ *   const result = yield* storage.writeBatch(items)
+ *   return result
+ * }).pipe(Effect.withSpan('storage.writeBatch'))
+ * ```
+ *
+ * @returns Effect that annotates the current span with Effect metadata
+ */
+declare function autoEnrichSpan(): Effect.Effect<void>;
+/**
+ * Create a wrapper that combines Effect.withSpan with automatic enrichment
+ *
+ * This is a convenience function that wraps an Effect with both:
+ * 1. A span (via Effect.withSpan)
+ * 2. Automatic metadata extraction (via autoEnrichSpan)
+ *
+ * Usage:
+ * ```typescript
+ * const instrumented = withAutoEnrichedSpan('storage.writeBatch')(
+ *   Effect.gen(function* () {
+ *     yield* annotateBatch(items.length, 10)
+ *     return yield* storage.writeBatch(items)
+ *   })
+ * )
+ * ```
+ *
+ * @param spanName - The name of the span
+ * @param options - Optional span options
+ * @returns Function that wraps an Effect with an auto-enriched span
+ */
+declare function withAutoEnrichedSpan<A, E, R>(spanName: string, options?: {
+    readonly attributes?: Record<string, unknown>;
+    readonly kind?: 'client' | 'server' | 'producer' | 'consumer' | 'internal';
+}): (self: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>;
 
 /**
  * Options for span isolation when running effects in FiberSet
@@ -356,4 +531,4 @@ declare const FiberSet: {
     }) => Effect.Effect<RuntimeFiber<A, E>, never, R>;
 };
 
-export { EffectInstrumentationLive, type EffectMetadata, FiberSet, type IsolationOptions, annotateBatch, annotateCache, annotateDataSize, annotateError, annotateHttpRequest, annotateLLM, annotatePriority, annotateQuery, annotateSpawnedTasks, annotateUser, createEffectInstrumentation, runIsolated, runWithSpan };
+export { EffectInstrumentationLive, type EffectMetadata, FiberSet, type IsolationOptions, annotateBatch, annotateCache, annotateDataSize, annotateError, annotateHttpRequest, annotateLLM, annotatePriority, annotateQuery, annotateSpawnedTasks, annotateUser, autoEnrichSpan, createEffectInstrumentation, extractEffectMetadata, runIsolated, runWithSpan, withAutoEnrichedSpan };