@atrim/instrument-node 0.4.0 → 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.0",
+  "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",
@@ -54,6 +59,9 @@
     "LICENSE"
   ],
   "dependencies": {
+    "@effect/opentelemetry": "^0.59.0",
+    "@effect/platform": "^0.93.0",
+    "@effect/platform-node": "latest",
     "@opentelemetry/auto-instrumentations-node": "^0.67.0",
     "@opentelemetry/exporter-trace-otlp-http": "^0.208.0",
     "@opentelemetry/instrumentation": "^0.208.0",
@@ -64,8 +72,6 @@
     "zod": "^3.22.0"
   },
   "devDependencies": {
-    "@effect/opentelemetry": "^0.59.0",
-    "@effect/platform": "^0.93.0",
     "@opentelemetry/api": "^1.9.0",
     "@opentelemetry/resources": "^2.2.0",
     "@opentelemetry/sdk-logs": "^0.208.0",
@@ -81,7 +87,7 @@
     "tsx": "^4.7.0",
     "typescript": "^5.7.2",
     "vitest": "^4.0.8",
-    "@atrim/instrument-core": "0.4.0"
+    "@atrim/instrument-core": "0.5.0"
   },
   "peerDependencies": {
     "@effect/opentelemetry": ">=0.40.0",
@@ -121,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/^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 && npm publish --tag dev --access public",
-    "publish:dev:reset": "npm version 1.0.0 --no-git-tag-version",
+    "publish:dev:publish": "pnpm build && pnpm publish --tag dev --access public --no-git-checks",
+    "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"
   }
 }