@atrim/instrument-node 0.5.0 → 0.5.1-dev.ac2fbfe.20251221201635

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.5.0",
+  "version": "0.5.1-dev.ac2fbfe.20251221201635",
   "description": "OpenTelemetry instrumentation for Node.js with centralized YAML configuration",
   "type": "module",
   "license": "MIT",
@@ -54,15 +54,15 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@effect/opentelemetry": "^0.59.0",
-    "@effect/platform": "^0.93.0",
-    "@effect/platform-node": "latest",
+    "@effect/opentelemetry": "^0.59.1",
+    "@effect/platform": "^0.93.6",
+    "@effect/platform-node": "^0.103.0",
     "@opentelemetry/auto-instrumentations-node": "^0.67.0",
     "@opentelemetry/exporter-trace-otlp-http": "^0.208.0",
     "@opentelemetry/instrumentation": "^0.208.0",
     "@opentelemetry/sdk-node": "^0.208.0",
     "@opentelemetry/sdk-trace-base": "^2.2.0",
-    "effect": "^3.19.0",
+    "effect": "^3.19.8",
     "yaml": "^2.3.0",
     "zod": "^3.22.0"
   },
@@ -74,10 +74,10 @@
     "@opentelemetry/sdk-trace-node": "^2.2.0",
     "@opentelemetry/sdk-trace-web": "^2.2.0",
     "@opentelemetry/semantic-conventions": "^1.38.0",
-    "@types/node": "^20.10.0",
+    "@types/node": "^25.0.0",
     "@vitest/coverage-v8": "^4.0.8",
-    "effect": "^3.19.0",
-    "testcontainers": "^11.8.1",
+    "effect": "^3.19.8",
+    "testcontainers": "^11.10.0",
     "tsup": "^8.0.1",
     "tsx": "^4.7.0",
     "typescript": "^5.7.2",
@@ -122,10 +122,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

@@ -82,7 +82,20 @@ var HttpFilteringConfigSchema = zod.z.object({
   // 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(),