@atrim/instrument-node 0.4.1 → 0.5.0-3a3dd2c-20251124202015

package/README.md

@@ -161,6 +161,72 @@ const program = Effect.gen(function* () {
 await Effect.runPromise(program)
 ```
 
+### Effect-TS Span Annotation Helpers
+
+The library provides 9 production-tested annotation helpers for enriching spans with semantic attributes:
+
+```typescript
+import { Effect } from 'effect'
+import {
+  annotateUser,
+  annotateBatch,
+  annotateDataSize,
+  annotateLLM,
+  annotateQuery,
+  annotateHttpRequest,
+  annotateError,
+  annotatePriority,
+  annotateCache,
+  autoEnrichSpan,
+  withAutoEnrichedSpan
+} from '@atrim/instrument-node/effect'
+
+// Example: Batch processing with automatic enrichment
+const processBatch = Effect.gen(function* () {
+  // Auto-enrich with Effect metadata (fiber ID, status, parent span info)
+  yield* autoEnrichSpan()
+
+  // Add user context
+  yield* annotateUser('user-123', 'user@example.com')
+
+  // Add batch metadata
+  yield* annotateBatch(100, 10) // 100 items in batches of 10
+
+  // Process items
+  const results = yield* processItems(items)
+
+  // Update with results
+  yield* annotateBatch(100, 10, results.success, results.failures)
+
+  return results
+}).pipe(Effect.withSpan('batch.process'))
+
+// Or use the convenience wrapper
+const processWithAutoEnrich = withAutoEnrichedSpan('batch.process')(
+  Effect.gen(function* () {
+    yield* annotateBatch(100, 10)
+    return yield* processItems(items)
+  })
+)
+```
+
+**Available annotation helpers:**
+- `annotateUser(userId, email?, username?)` - User context
+- `annotateDataSize(bytes, items, compressionRatio?)` - Data size metrics
+- `annotateBatch(totalItems, batchSize, successCount?, failureCount?)` - Batch operations
+- `annotateLLM(model, provider, tokens?)` - LLM operations (GPT, Claude, etc.)
+- `annotateQuery(query, duration?, rowCount?, database?)` - Database queries
+- `annotateHttpRequest(method, url, statusCode?, contentLength?)` - HTTP requests
+- `annotateError(error, recoverable, errorType?)` - Error context
+- `annotatePriority(priority, reason?)` - Operation priority
+- `annotateCache(hit, key, ttl?)` - Cache operations
+
+**Auto-enrichment utilities:**
+- `autoEnrichSpan()` - Automatically add Effect metadata (fiber ID, status, parent span info)
+- `withAutoEnrichedSpan(name, options?)` - Wrapper combining `Effect.withSpan()` + auto-enrichment
+
+All helpers return `Effect.Effect<void>` and use `Effect.annotateCurrentSpan()` under the hood.
+
 ### Bun Runtime
 
 ```typescript

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atrim/instrument-node",
-  "version": "0.4.1",
+  "version": "0.5.0-3a3dd2c-20251124202015",
   "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",
@@ -82,7 +87,7 @@
     "tsx": "^4.7.0",
     "typescript": "^5.7.2",
     "vitest": "^4.0.8",
-    "@atrim/instrument-core": "0.4.1"
+    "@atrim/instrument-core": "0.5.0"
   },
   "peerDependencies": {
     "@effect/opentelemetry": ">=0.40.0",
@@ -122,10 +127,10 @@
     "format": "prettier --write \"src/**/*.ts\" \"test/**/*.ts\"",
     "format:check": "prettier --check \"src/**/*.ts\" \"test/**/*.ts\"",
     "clean": "rm -rf target",
-    "publish:dev:version": "npm version $(git describe --tags --abbrev=0 | sed 's/^.*@//' | sed 's/^v//')-$(git rev-parse --short HEAD)-$(date -u +%Y%m%d%H%M%S) --no-git-tag-version",
+    "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": "npm version 1.0.0 --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,13 +76,69 @@ var AutoIsolationConfigSchema = zod.z.object({
     add_metadata: zod.z.boolean().default(true)
   }).default({})
 });
+var SpanNamingRuleSchema = zod.z.object({
+  // Match conditions (all specified conditions must match)
+  match: zod.z.object({
+    // Match by file path pattern (regex)
+    file: zod.z.string().optional(),
+    // Match by function name pattern (regex)
+    function: zod.z.string().optional(),
+    // Match by operator type (gen, all, forEach, etc.)
+    operator: zod.z.string().optional(),
+    // Match by call stack pattern (regex)
+    stack: zod.z.string().optional(),
+    // Match by fiber annotation key
+    annotation: zod.z.string().optional()
+  }),
+  // Name template with substitution variables
+  // Available: {operator}, {function}, {module}, {file}, {line}, {class}, {match:N}
+  name: zod.z.string()
+});
+var AutoTracingConfigSchema = zod.z.object({
+  // Global enable/disable for auto-tracing
+  enabled: zod.z.boolean().default(true),
+  // Span naming configuration
+  span_naming: zod.z.object({
+    // Default name template when no rules match
+    default: zod.z.string().default("effect.{operator}"),
+    // Custom naming rules (applied in order, first match wins)
+    rules: zod.z.array(SpanNamingRuleSchema).default([])
+  }).default({}),
+  // Pattern filtering
+  filter_patterns: zod.z.object({
+    // Only trace spans matching these patterns
+    include: zod.z.array(zod.z.string()).default([]),
+    // Exclude spans matching these patterns (takes precedence)
+    exclude: zod.z.array(zod.z.string()).default([])
+  }).default({}),
+  // Sampling configuration
+  sampling: zod.z.object({
+    // Sampling rate (0.0 to 1.0)
+    rate: zod.z.number().min(0).max(1).default(1),
+    // Only trace effects with duration > this value
+    min_duration: zod.z.string().default("0 millis")
+  }).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(),
   // Patterns to ignore for incoming HTTP requests (string patterns only in YAML)
   ignore_incoming_paths: zod.z.array(zod.z.string()).optional(),
   // Require parent span for outgoing requests (prevents root spans for HTTP calls)
-  require_parent_for_outgoing_spans: zod.z.boolean().optional()
+  require_parent_for_outgoing_spans: zod.z.boolean().optional(),
+  // Trace context propagation configuration
+  // Controls which cross-origin requests receive W3C Trace Context headers (traceparent, tracestate)
+  propagate_trace_context: zod.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: zod.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: zod.z.array(zod.z.string()).optional()
+  }).optional()
 });
 var InstrumentationConfigSchema = zod.z.object({
   version: zod.z.string(),
@@ -95,7 +151,8 @@ var InstrumentationConfigSchema = zod.z.object({
   }),
   effect: zod.z.object({
     auto_extract_metadata: zod.z.boolean(),
-    auto_isolation: AutoIsolationConfigSchema.optional()
+    auto_isolation: AutoIsolationConfigSchema.optional(),
+    auto_tracing: AutoTracingConfigSchema.optional()
   }).optional(),
   http: HttpFilteringConfigSchema.optional()
 });