@atrim/instrument-node 0.5.0-c05e3a1-20251119131235 → 0.5.1

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-c05e3a1-20251119131235",
+  "version": "0.5.1",
   "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"
   },
@@ -76,7 +76,7 @@
     "@opentelemetry/semantic-conventions": "^1.38.0",
     "@types/node": "^20.10.0",
     "@vitest/coverage-v8": "^4.0.8",
-    "effect": "^3.19.0",
+    "effect": "^3.19.8",
     "testcontainers": "^11.8.1",
     "tsup": "^8.0.1",
     "tsx": "^4.7.0",

package/target/dist/index.cjs

@@ -706,6 +706,15 @@ var getServiceInfoWithFallback = detectServiceInfo.pipe(
     })
   )
 );
+async function detectServiceInfoAsync() {
+  return effect.Effect.runPromise(getServiceInfoWithFallback);
+}
+async function getServiceNameAsync() {
+  return effect.Effect.runPromise(getServiceName);
+}
+async function getServiceVersionAsync() {
+  return effect.Effect.runPromise(getServiceVersion);
+}
 var NodeConfigLoaderLive = ConfigLoaderLive.pipe(
   effect.Layer.provide(effect.Layer.mergeAll(platformNode.NodeContext.layer, platform.FetchHttpClient.layer))
 );
@@ -787,7 +796,7 @@ async function loadConfigWithOptions(options = {}) {
 
 // src/core/sdk-initializer.ts
 var sdkInstance = null;
-var initializationDeferred = null;
+var initializationPromise = null;
 function buildHttpInstrumentationConfig(options, config, _otlpEndpoint) {
   const httpConfig = { enabled: true };
   const programmaticPatterns = options.http?.ignoreOutgoingUrls || [];
@@ -903,38 +912,27 @@ function isTracingAlreadyInitialized() {
     return false;
   }
 }
-var initializeSdkEffect = (options = {}) => effect.Effect.gen(function* () {
+async function initializeSdk(options = {}) {
   if (sdkInstance) {
     logger.warn("@atrim/instrumentation: SDK already initialized. Returning existing instance.");
     return sdkInstance;
   }
-  if (initializationDeferred) {
+  if (initializationPromise) {
     logger.log(
-      "@atrim/instrumentation: SDK initialization in progress, waiting for completion..."
+      "@atrim/instrumentation: SDK already initialized, waiting for initialization to complete..."
     );
-    return yield* effect.Deferred.await(initializationDeferred);
-  }
-  const deferred = yield* effect.Deferred.make();
-  initializationDeferred = deferred;
-  const result = yield* performInitializationEffect(options).pipe(
-    effect.Effect.tap((sdk) => effect.Deferred.succeed(deferred, sdk)),
-    effect.Effect.tapError((error) => effect.Deferred.fail(deferred, error)),
-    effect.Effect.ensuring(
-      effect.Effect.sync(() => {
-        initializationDeferred = null;
-      })
-    )
-  );
-  return result;
-});
-var performInitializationEffect = (options) => effect.Effect.gen(function* () {
-  const config = yield* effect.Effect.tryPromise({
-    try: () => loadConfigWithOptions(options),
-    catch: (error) => new InitializationError2({
-      reason: "Failed to load configuration",
-      cause: error
-    })
-  });
+    return initializationPromise;
+  }
+  initializationPromise = performInitialization(options);
+  try {
+    const result = await initializationPromise;
+    return result;
+  } finally {
+    initializationPromise = null;
+  }
+}
+async function performInitialization(options) {
+  const config = await loadConfigWithOptions(options);
   const loggingLevel = config.instrumentation.logging || "on";
   logger.setLevel(loggingLevel);
   const alreadyInitialized = isTracingAlreadyInitialized();
@@ -950,25 +948,14 @@ var performInitializationEffect = (options) => effect.Effect.gen(function* () {
     logger.log("");
     return null;
   }
-  const serviceInfo = yield* detectServiceInfo.pipe(
-    effect.Effect.catchAll(
-      () => effect.Effect.succeed({
-        name: "unknown-service",
-        version: void 0
-      })
-    )
-  );
+  const serviceInfo = await detectServiceInfoAsync();
   const serviceName = options.serviceName || serviceInfo.name;
   const serviceVersion = options.serviceVersion || serviceInfo.version;
-  const rawExporter = yield* effect.Effect.sync(() => createOtlpExporter(options.otlp));
-  const exporter = yield* effect.Effect.sync(() => new SafeSpanExporter(rawExporter));
+  const rawExporter = createOtlpExporter(options.otlp);
+  const exporter = new SafeSpanExporter(rawExporter);
   const useSimpleProcessor = process.env.NODE_ENV === "test" || process.env.OTEL_USE_SIMPLE_PROCESSOR === "true";
-  const baseProcessor = yield* effect.Effect.sync(
-    () => useSimpleProcessor ? new sdkTraceBase.SimpleSpanProcessor(exporter) : new sdkTraceBase.BatchSpanProcessor(exporter)
-  );
-  const patternProcessor = yield* effect.Effect.sync(
-    () => new PatternSpanProcessor(config, baseProcessor)
-  );
+  const baseProcessor = useSimpleProcessor ? new sdkTraceBase.SimpleSpanProcessor(exporter) : new sdkTraceBase.BatchSpanProcessor(exporter);
+  const patternProcessor = new PatternSpanProcessor(config, baseProcessor);
   const instrumentations = [];
   const hasWebFramework = hasWebFrameworkInstalled();
   const enableAutoInstrumentation = shouldEnableAutoInstrumentation(
@@ -981,11 +968,15 @@ var performInitializationEffect = (options) => effect.Effect.gen(function* () {
     const undiciConfig = buildUndiciInstrumentationConfig(options, config);
     instrumentations.push(
       ...autoInstrumentationsNode.getNodeAutoInstrumentations({
+        // Enable HTTP instrumentation with filtering (for http/https modules)
         "@opentelemetry/instrumentation-http": httpConfig,
+        // Enable undici instrumentation with filtering (for fetch API)
         "@opentelemetry/instrumentation-undici": undiciConfig,
+        // Enable web framework instrumentations
         "@opentelemetry/instrumentation-express": { enabled: true },
         "@opentelemetry/instrumentation-fastify": { enabled: true },
         "@opentelemetry/instrumentation-koa": { enabled: true },
+        // Disable noisy instrumentations by default
         "@opentelemetry/instrumentation-fs": { enabled: false },
         "@opentelemetry/instrumentation-dns": { enabled: false }
       })
@@ -1013,20 +1004,18 @@ var performInitializationEffect = (options) => effect.Effect.gen(function* () {
     serviceName,
     ...serviceVersion && { serviceVersion },
     instrumentations,
+    // Allow advanced overrides
     ...options.sdk
   };
-  const sdk = yield* effect.Effect.sync(() => {
-    const s = new sdkNode.NodeSDK(sdkConfig);
-    s.start();
-    return s;
-  });
+  const sdk = new sdkNode.NodeSDK(sdkConfig);
+  sdk.start();
   sdkInstance = sdk;
   if (!options.disableAutoShutdown) {
-    yield* effect.Effect.sync(() => registerShutdownHandlers(sdk));
+    registerShutdownHandlers(sdk);
   }
   logInitialization(config, serviceName, serviceVersion, options, enableAutoInstrumentation);
   return sdk;
-});
+}
 function getSdkInstance() {
   return sdkInstance;
 }
@@ -1039,7 +1028,7 @@ async function shutdownSdk() {
 }
 function resetSdk() {
   sdkInstance = null;
-  initializationDeferred = null;
+  initializationPromise = null;
 }
 function registerShutdownHandlers(sdk) {
   const shutdown = async (signal) => {
@@ -1096,8 +1085,30 @@ function logInitialization(config, serviceName, serviceVersion, options, autoIns
 }
 
 // src/api.ts
-var initializeInstrumentation = (options = {}) => effect.Effect.gen(function* () {
-  const sdk = yield* initializeSdkEffect(options);
+async function initializeInstrumentation(options = {}) {
+  const sdk = await initializeSdk(options);
+  if (sdk) {
+    const config = await loadConfigWithOptions(options);
+    initializePatternMatcher(config);
+  }
+  return sdk;
+}
+async function initializePatternMatchingOnly(options = {}) {
+  const config = await loadConfigWithOptions(options);
+  initializePatternMatcher(config);
+  logger.log("@atrim/instrumentation: Pattern matching initialized (legacy mode)");
+  logger.log(
+    "  Note: NodeSDK is not initialized. Use initializeInstrumentation() for complete setup."
+  );
+}
+var initializeInstrumentationEffect = (options = {}) => effect.Effect.gen(function* () {
+  const sdk = yield* effect.Effect.tryPromise({
+    try: () => initializeSdk(options),
+    catch: (error) => new InitializationError2({
+      reason: "SDK initialization failed",
+      cause: error
+    })
+  });
   if (sdk) {
     yield* effect.Effect.tryPromise({
       try: () => loadConfigWithOptions(options),
@@ -1115,7 +1126,7 @@ var initializeInstrumentation = (options = {}) => effect.Effect.gen(function* ()
   }
   return sdk;
 });
-var initializePatternMatchingOnly = (options = {}) => effect.Effect.gen(function* () {
+var initializePatternMatchingOnlyEffect = (options = {}) => effect.Effect.gen(function* () {
   const config = yield* effect.Effect.tryPromise({
     try: () => loadConfigWithOptions(options),
     catch: (error) => new ConfigError2({
@@ -1125,7 +1136,7 @@ var initializePatternMatchingOnly = (options = {}) => effect.Effect.gen(function
   });
   yield* effect.Effect.sync(() => {
     initializePatternMatcher(config);
-    logger.log("@atrim/instrumentation: Pattern matching initialized (pattern-only mode)");
+    logger.log("@atrim/instrumentation: Pattern matching initialized (legacy mode)");
     logger.log(
       "  Note: NodeSDK is not initialized. Use initializeInstrumentation() for complete setup."
     );
@@ -1241,15 +1252,20 @@ exports.annotateDbQuery = annotateDbQuery;
 exports.annotateHttpRequest = annotateHttpRequest;
 exports.clearConfigCache = _resetConfigLoaderCache;
 exports.createOtlpExporter = createOtlpExporter;
-exports.detectServiceInfo = detectServiceInfo;
+exports.detectServiceInfo = detectServiceInfoAsync;
+exports.detectServiceInfoEffect = detectServiceInfo;
 exports.getOtlpEndpoint = getOtlpEndpoint;
 exports.getPatternMatcher = getPatternMatcher;
 exports.getSdkInstance = getSdkInstance;
 exports.getServiceInfoWithFallback = getServiceInfoWithFallback;
-exports.getServiceName = getServiceName;
-exports.getServiceVersion = getServiceVersion;
+exports.getServiceName = getServiceNameAsync;
+exports.getServiceNameEffect = getServiceName;
+exports.getServiceVersion = getServiceVersionAsync;
+exports.getServiceVersionEffect = getServiceVersion;
 exports.initializeInstrumentation = initializeInstrumentation;
+exports.initializeInstrumentationEffect = initializeInstrumentationEffect;
 exports.initializePatternMatchingOnly = initializePatternMatchingOnly;
+exports.initializePatternMatchingOnlyEffect = initializePatternMatchingOnlyEffect;
 exports.loadConfig = loadConfig;
 exports.loadConfigFromInline = loadConfigFromInline;
 exports.loadConfigWithOptions = loadConfigWithOptions;