@atrim/instrument-node 0.5.1-3a86b84-20260105170223 → 0.5.1-dev.14fdea7.20260108232041

package/README.md

@@ -80,6 +80,35 @@ const process = Effect.gen(function* () {
 
 Available: `annotateUser`, `annotateBatch`, `annotateDataSize`, `annotateLLM`, `annotateQuery`, `annotateHttpRequest`, `annotateError`, `annotatePriority`, `annotateCache`
 
+### Effect Fiber Metadata Extraction
+
+To add Effect fiber metadata (fiber ID, status, parent span info) to your spans, you must **explicitly call** the enrichment functions:
+
+```typescript
+import { autoEnrichSpan, withAutoEnrichedSpan } from '@atrim/instrument-node/effect'
+
+// Option 1: Call autoEnrichSpan() inside a span
+const operation = Effect.gen(function* () {
+  yield* autoEnrichSpan()  // Adds fiber metadata to current span
+  // ... your logic
+}).pipe(Effect.withSpan('app.operation'))
+
+// Option 2: Use the convenience wrapper
+const operation = withAutoEnrichedSpan('app.operation')(
+  Effect.gen(function* () {
+    // ... your logic (fiber metadata added automatically)
+  })
+)
+```
+
+**Extracted metadata:**
+- `effect.fiber.id` - Unique fiber thread name
+- `effect.fiber.status` - Current fiber status
+- `effect.operation.root` / `effect.operation.nested` - Operation hierarchy
+- `effect.parent.span.id`, `effect.parent.span.name`, `effect.parent.trace.id` - Parent span info
+
+> **Note:** The `auto_extract_metadata` config option is currently not implemented. Metadata extraction requires explicit calls as shown above. See [#issue] for tracking automatic extraction support.
+
 ## Configuration (Optional)
 
 Create `instrumentation.yaml` in your project root:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atrim/instrument-node",
-  "version": "0.5.1-3a86b84-20260105170223",
+  "version": "0.5.1-dev.14fdea7.20260108232041",
   "description": "OpenTelemetry instrumentation for Node.js with centralized YAML configuration",
   "type": "module",
   "license": "MIT",
@@ -43,6 +43,11 @@
       "types": "./target/dist/integrations/effect/index.d.ts",
       "import": "./target/dist/integrations/effect/index.js",
       "require": "./target/dist/integrations/effect/index.cjs"
+    },
+    "./effect/auto": {
+      "types": "./target/dist/integrations/effect/auto/index.d.ts",
+      "import": "./target/dist/integrations/effect/auto/index.js",
+      "require": "./target/dist/integrations/effect/auto/index.cjs"
     }
   },
   "main": "./target/dist/index.js",
@@ -54,7 +59,7 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@opentelemetry/auto-instrumentations-node": "^0.67.0",
+    "@opentelemetry/auto-instrumentations-node": "^0.67.3",
     "@opentelemetry/exporter-trace-otlp-http": "^0.208.0",
     "@opentelemetry/instrumentation": "^0.208.0",
     "@opentelemetry/resources": "^2.2.0",
@@ -66,9 +71,9 @@
     "zod": "^3.22.0"
   },
   "devDependencies": {
-    "@effect/opentelemetry": "^0.59.1",
-    "@effect/platform": "^0.93.6",
-    "@effect/platform-node": "^0.103.0",
+    "@effect/opentelemetry": "^0.60.0",
+    "@effect/platform": "^0.94.1",
+    "@effect/platform-node": "^0.104.0",
     "@opentelemetry/api": "^1.9.0",
     "@opentelemetry/sdk-logs": "^0.208.0",
     "@opentelemetry/sdk-metrics": "^2.2.0",
@@ -77,13 +82,13 @@
     "@opentelemetry/semantic-conventions": "^1.38.0",
     "@types/node": "^25.0.3",
     "@vitest/coverage-v8": "^4.0.16",
-    "effect": "^3.19.8",
+    "effect": "^3.19.14",
     "testcontainers": "^11.11.0",
     "tsup": "^8.0.1",
     "tsx": "^4.7.0",
     "typescript": "^5.7.2",
     "vitest": "^4.0.16",
-    "@atrim/instrument-core": "0.5.0"
+    "@atrim/instrument-core": "0.6.0"
   },
   "peerDependencies": {
     "@opentelemetry/api": "^1.0.0",
@@ -126,7 +131,7 @@
     "publish:dev:version": "pnpm version $(node -p \"require('./package.json').version\")-$(git rev-parse --short HEAD)-$(date -u +%Y%m%d%H%M%S) --no-git-tag-version",
     "publish:dev:save": "node -p \"require('./package.json').version\" > .version",
     "publish:dev:publish": "pnpm build && pnpm publish --tag dev --access public --no-git-checks",
-    "publish:dev:reset": "pnpm version 0.5.1 --no-git-tag-version",
+    "publish:dev:reset": "pnpm version 0.5.0 --no-git-tag-version",
     "publish:dev": "pnpm publish:dev:version && pnpm publish:dev:save && pnpm publish:dev:publish && pnpm publish:dev:reset"
   }
 }

package/target/dist/index.cjs

@@ -76,6 +76,69 @@ var AutoIsolationConfigSchema = zod.z.object({
     add_metadata: zod.z.boolean().default(true)
   }).default({})
 });
+var SpanNamingRuleSchema = zod.z.object({
+  // Match criteria (all specified criteria must match)
+  match: zod.z.object({
+    // Regex pattern to match file path
+    file: zod.z.string().optional(),
+    // Regex pattern to match function name
+    function: zod.z.string().optional(),
+    // Regex pattern to match module name
+    module: zod.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: zod.z.string()
+});
+var AutoInstrumentationConfigSchema = zod.z.object({
+  // Enable/disable auto-instrumentation
+  enabled: zod.z.boolean().default(false),
+  // Tracing granularity
+  // - 'fiber': Trace at fiber creation (recommended, lower overhead)
+  // - 'operator': Trace each Effect operator (higher granularity, more overhead)
+  granularity: zod.z.enum(["fiber", "operator"]).default("fiber"),
+  // Smart span naming configuration
+  span_naming: zod.z.object({
+    // Default span name template when no rules match
+    default: zod.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: zod.z.boolean().default(true),
+    // Naming rules (first match wins)
+    rules: zod.z.array(SpanNamingRuleSchema).default([])
+  }).default({}),
+  // Pattern-based filtering
+  filter: zod.z.object({
+    // Only trace spans matching these patterns (empty = trace all)
+    include: zod.z.array(zod.z.string()).default([]),
+    // Never trace spans matching these patterns
+    exclude: zod.z.array(zod.z.string()).default([])
+  }).default({}),
+  // Performance controls
+  performance: zod.z.object({
+    // Sample rate (0.0 - 1.0)
+    sampling_rate: zod.z.number().min(0).max(1).default(1),
+    // Skip fibers shorter than this duration (e.g., "10ms", "100 millis")
+    min_duration: zod.z.string().default("0ms"),
+    // Maximum concurrent traced fibers (0 = unlimited)
+    max_concurrent: zod.z.number().default(0)
+  }).default({}),
+  // Automatic metadata extraction
+  metadata: zod.z.object({
+    // Extract Effect fiber information
+    fiber_info: zod.z.boolean().default(true),
+    // Extract source location (file:line)
+    source_location: zod.z.boolean().default(true),
+    // Extract parent fiber information
+    parent_fiber: zod.z.boolean().default(true)
+  }).default({})
+});
 var HttpFilteringConfigSchema = zod.z.object({
   // Patterns to ignore for outgoing HTTP requests (string patterns only in YAML)
   ignore_outgoing_urls: zod.z.array(zod.z.string()).optional(),
@@ -97,6 +160,30 @@ var HttpFilteringConfigSchema = zod.z.object({
     include_urls: zod.z.array(zod.z.string()).optional()
   }).optional()
 });
+var ExporterConfigSchema = zod.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: zod.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: zod.z.string().optional(),
+  // Custom headers to send with OTLP requests (for type: otlp)
+  // Useful for authentication (x-api-key, Authorization, etc.)
+  headers: zod.z.record(zod.z.string()).optional(),
+  // Span processor type
+  // - 'batch': Batch spans for export (production, lower overhead)
+  // - 'simple': Export immediately (development, no batching delay)
+  processor: zod.z.enum(["batch", "simple"]).default("batch"),
+  // Batch processor settings (for processor: batch)
+  batch: zod.z.object({
+    // Max time to wait before exporting (milliseconds)
+    scheduled_delay_millis: zod.z.number().default(1e3),
+    // Max batch size
+    max_export_batch_size: zod.z.number().default(100)
+  }).optional()
+});
 var InstrumentationConfigSchema = zod.z.object({
   version: zod.z.string(),
   instrumentation: zod.z.object({
@@ -110,12 +197,16 @@ var InstrumentationConfigSchema = zod.z.object({
     // Enable/disable Effect tracing entirely
     // When false, EffectInstrumentationLive returns Layer.empty
     enabled: zod.z.boolean().default(true),
-    // Exporter mode:
+    // 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: zod.z.enum(["unified", "standalone"]).default("unified"),
+    // Exporter configuration (for auto-instrumentation)
+    exporter_config: ExporterConfigSchema.optional(),
     auto_extract_metadata: zod.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()
 });