autotel 3.6.0 → 4.0.0

package/src/request-logger.ts

@@ -282,3 +282,61 @@ export function getRequestLogger(
     },
   };
 }
+
+/**
+ * Returns `true` when a request-logger context can be resolved without throwing —
+ * i.e. an explicit `ctx` was provided, a `runWithRequestContext()` scope is active,
+ * or there is an active OpenTelemetry span.
+ *
+ * Use this to branch on observability availability instead of wrapping
+ * {@link getRequestLogger} in try/catch.
+ */
+export function hasRequestContext(ctx?: TraceContext): boolean {
+  if (ctx) return true;
+  if (requestContextStore.getStore()) return true;
+  return otelTrace.getActiveSpan() != null;
+}
+
+/**
+ * Like {@link getRequestLogger}, but returns `null` instead of throwing when no
+ * request context is available. Intended for best-effort instrumentation where a
+ * missing telemetry context must never crash business logic.
+ */
+export function getRequestLoggerSafe(
+  ctx?: TraceContext,
+  options?: RequestLoggerOptions,
+): RequestLogger | null {
+  if (!hasRequestContext(ctx)) return null;
+  return getRequestLogger(ctx, options);
+}
+
+/**
+ * A no-op {@link RequestLogger} whose methods do nothing. Used as a fallback by
+ * best-effort instrumentation so wrapped handlers can run un-instrumented without
+ * branching on logger presence.
+ */
+export function createNoopRequestLogger(): RequestLogger {
+  const snapshot = (): RequestLogSnapshot => ({
+    timestamp: new Date().toISOString(),
+    traceId: '',
+    spanId: '',
+    correlationId: '',
+    context: {},
+  });
+
+  return {
+    set() {},
+    info() {},
+    warn() {},
+    error() {},
+    getContext() {
+      return {};
+    },
+    emitNow() {
+      return snapshot();
+    },
+    fork(_label, fn) {
+      void Promise.resolve().then(() => fn());
+    },
+  };
+}

package/src/semantic-helpers.test.ts

@@ -3,12 +3,7 @@
  */
 
 import { describe, it, expect, beforeEach } from 'vitest';
-import {
-  traceLLM,
-  traceDB,
-  traceHTTP,
-  traceMessaging,
-} from './semantic-helpers';
+import { traceDB, traceHTTP, traceMessaging } from './semantic-helpers';
 import { createTraceCollector } from './testing';
 
 describe('Semantic Helpers', () => {
@@ -18,69 +13,7 @@ describe('Semantic Helpers', () => {
     collector = createTraceCollector();
   });
 
-  describe('traceLLM', () => {
-    it('should add Gen AI semantic convention attributes', async () => {
-      const generateText = traceLLM({
-        model: 'gpt-4',
-        operation: 'chat',
-        provider: 'openai',
-      })((_ctx) => async (prompt: string) => {
-        return `Response to: ${prompt}`;
-      });
-
-      await generateText('Hello');
-
-      const spans = collector.getSpans();
-      expect(spans).toHaveLength(1);
-
-      const span = spans[0];
-      expect(span.attributes['gen.ai.request.model']).toBe('gpt-4');
-      expect(span.attributes['gen.ai.operation.name']).toBe('chat');
-      expect(span.attributes['gen.ai.system']).toBe('openai');
-    });
-
-    it('should use default operation when not specified', async () => {
-      const generateText = traceLLM({
-        model: 'claude-3',
-      })((_ctx) => async () => 'result');
-
-      await generateText();
-
-      const spans = collector.getSpans();
-      expect(spans[0].attributes['gen.ai.operation.name']).toBe('chat');
-    });
-
-    it('should support embedding operation', async () => {
-      const embed = traceLLM({
-        model: 'text-embedding-3-small',
-        operation: 'embedding',
-        provider: 'openai',
-      })((_ctx) => async (_text: string) => [0.1, 0.2, 0.3]);
-
-      await embed('test text');
-
-      const spans = collector.getSpans();
-      expect(spans[0].attributes['gen.ai.operation.name']).toBe('embedding');
-    });
-
-    it('should support additional custom attributes', async () => {
-      const generateText = traceLLM({
-        model: 'gpt-4',
-        attributes: {
-          'custom.attribute': 'custom-value',
-          'custom.number': 123,
-        },
-      })((_ctx) => async () => 'result');
-
-      await generateText();
-
-      const spans = collector.getSpans();
-      const span = spans[0];
-      expect(span.attributes['gen.ai.request.model']).toBe('gpt-4');
-      expect(span.attributes['custom.attribute']).toBe('custom-value');
-      expect(span.attributes['custom.number']).toBe(123);
-    });
-  });
+  // GenAI/LLM helpers (`traceLLM`) moved to the `autotel-genai` package.
 
   describe('traceDB', () => {
     it('should add DB semantic convention attributes', async () => {
@@ -273,24 +206,6 @@ describe('Semantic Helpers', () => {
   });
 
   describe('Attribute merging', () => {
-    it('should merge custom attributes with semantic attributes in traceLLM', async () => {
-      const fn = traceLLM({
-        model: 'gpt-4',
-        attributes: {
-          'gen.ai.request.temperature': 0.7,
-          'custom.attr': 'value',
-        },
-      })((_ctx) => async () => 'result');
-
-      await fn();
-
-      const spans = collector.getSpans();
-      const span = spans[0];
-      expect(span.attributes['gen.ai.request.model']).toBe('gpt-4');
-      expect(span.attributes['gen.ai.request.temperature']).toBe(0.7);
-      expect(span.attributes['custom.attr']).toBe('value');
-    });
-
     it('should allow custom attributes to override semantic defaults', async () => {
       const fn = traceDB({
         system: 'postgresql',

package/src/semantic-helpers.ts

@@ -11,23 +11,6 @@ import { trace } from './functional';
 import type { TraceContext } from './trace-context';
 import type { Attributes } from '@opentelemetry/api';
 
-/**
- * Configuration for LLM (Large Language Model) operations
- *
- * Follows Gen AI semantic conventions:
- * https://opentelemetry.io/docs/specs/semconv/gen-ai/
- */
-export interface LLMConfig {
-  /** Model name (e.g., 'gpt-4', 'claude-3-opus') */
-  model: string;
-  /** Operation type */
-  operation?: 'chat' | 'completion' | 'embedding';
-  /** Model provider (e.g., 'openai', 'anthropic', 'cohere') - maps to gen.ai.system */
-  provider?: string;
-  /** Additional attributes to add to the span */
-  attributes?: Attributes;
-}
-
 /**
  * Configuration for database operations
  *
@@ -79,135 +62,6 @@ export interface MessagingConfig {
   attributes?: Attributes;
 }
 
-/**
- * Trace LLM operations with Gen AI semantic conventions
- *
- * Automatically adds standard attributes for LLM operations:
- * - gen.ai.request.model
- * - gen.ai.operation.name
- * - gen.ai.system
- *
- * **Use Cases:**
- * - Chat completions
- * - Text generation
- * - Embeddings
- * - Multi-step LLM workflows
- *
- * @param config - LLM operation configuration
- * @returns Traced function factory with Gen AI attributes
- *
- * @example Chat completion with OpenAI
- * ```typescript
- * import { traceLLM } from 'autotel/semantic-helpers'
- * import OpenAI from 'openai'
- *
- * const openai = new OpenAI()
- *
- * export const generateResponse = traceLLM({
- *   model: 'gpt-4-turbo',
- *   operation: 'chat',
- *   provider: 'openai'
- * })(ctx => async (prompt: string) => {
- *   const response = await openai.chat.completions.create({
- *     model: 'gpt-4-turbo',
- *     messages: [{ role: 'user', content: prompt }]
- *   })
- *
- *   // Add usage metrics to span
- *   ctx.setAttribute('gen.ai.usage.completion_tokens', response.usage?.completion_tokens)
- *   ctx.setAttribute('gen.ai.usage.prompt_tokens', response.usage?.prompt_tokens)
- *
- *   return response.choices[0].message.content
- * })
- * ```
- *
- * @example Anthropic Claude with streaming
- * ```typescript
- * import { traceLLM } from 'autotel/semantic-helpers'
- * import Anthropic from '@anthropic-ai/sdk'
- *
- * const anthropic = new Anthropic()
- *
- * export const streamResponse = traceLLM({
- *   model: 'claude-3-opus-20240229',
- *   operation: 'chat',
- *   provider: 'anthropic'
- * })(ctx => async function* (prompt: string) {
- *   const stream = await anthropic.messages.create({
- *     model: 'claude-3-opus-20240229',
- *     messages: [{ role: 'user', content: prompt }],
- *     stream: true,
- *     max_tokens: 1024
- *   })
- *
- *   let totalTokens = 0
- *   for await (const event of stream) {
- *     if (event.type === 'content_block_delta') {
- *       yield event.delta.text
- *     }
- *     if (event.type === 'message_stop') {
- *       ctx.setAttribute('gen.ai.usage.completion_tokens', event.message.usage.output_tokens)
- *       totalTokens = event.message.usage.output_tokens
- *     }
- *   }
- *
- *   return totalTokens
- * })
- * ```
- *
- * @example Embeddings
- * ```typescript
- * import { traceLLM } from 'autotel/semantic-helpers'
- * import { OpenAIEmbeddings } from '@langchain/openai'
- *
- * const embeddings = new OpenAIEmbeddings()
- *
- * export const embed = traceLLM({
- *   model: 'text-embedding-3-small',
- *   operation: 'embedding',
- *   provider: 'openai'
- * })(ctx => async (text: string) => {
- *   const result = await embeddings.embedQuery(text)
- *   ctx.setAttribute('gen.ai.response.embedding_length', result.length)
- *   return result
- * })
- * ```
- *
- * @public
- */
-export function traceLLM<TArgs extends unknown[], TReturn>(config: LLMConfig) {
-  return (
-    fnFactory: (ctx: TraceContext) => (...args: TArgs) => Promise<TReturn>,
-  ): ((...args: TArgs) => Promise<TReturn>) => {
-    return trace<TArgs, TReturn>((ctx) => {
-      // Set semantic convention attributes
-      ctx.setAttribute('gen.ai.request.model', config.model);
-      ctx.setAttribute('gen.ai.operation.name', config.operation || 'chat');
-      if (config.provider) {
-        ctx.setAttribute('gen.ai.system', config.provider);
-      }
-      if (config.attributes) {
-        for (const [key, value] of Object.entries(config.attributes)) {
-          if (value !== undefined && value !== null) {
-            // setAttribute only accepts primitives (string | number | boolean)
-            // Arrays and objects should be serialized
-            const attrValue =
-              typeof value === 'string' ||
-              typeof value === 'number' ||
-              typeof value === 'boolean'
-                ? value
-                : JSON.stringify(value);
-            ctx.setAttribute(key, attrValue);
-          }
-        }
-      }
-
-      // Call the user's factory to get their function and return it
-      return fnFactory(ctx);
-    });
-  };
-}
-
 /**
  * Trace database operations with DB semantic conventions
  *

package/src/validate.test.ts

@@ -17,7 +17,9 @@ import { VALIDATION_ATTR } from './validation-attributes';
 
 /** A fake `SchemaLike` so tests don't depend on Zod. */
 function schema<T>(
-  decide: (input: unknown) => { success: true; data: T } | { success: false; error: unknown },
+  decide: (
+    input: unknown,
+  ) => { success: true; data: T } | { success: false; error: unknown },
 ) {
   return { safeParse: decide };
 }

package/src/validate.ts

@@ -25,7 +25,10 @@
 
 import { trace } from '@opentelemetry/api';
 import { createCounter } from './metric-helpers';
-import { createStructuredError, type StructuredError } from './structured-error';
+import {
+  createStructuredError,
+  type StructuredError,
+} from './structured-error';
 import { hashJson } from './stable-hash';
 import type { SchemaLike } from './define-event';
 import {
@@ -164,7 +167,8 @@ function extractRawIssues(error: unknown): Array<Record<string, unknown>> {
       (error as { errors?: unknown }).errors;
     if (Array.isArray(candidate)) {
       return candidate.filter(
-        (i): i is Record<string, unknown> => i !== null && typeof i === 'object',
+        (i): i is Record<string, unknown> =>
+          i !== null && typeof i === 'object',
       );
     }
   }
@@ -292,7 +296,9 @@ export function defineValidator<T, S extends SchemaLike<T>>(
       const issues = formatValidationIssues(parsed.error);
       record(issues);
       if (mode === 'reject') {
-        throw options.onReject?.(issues, name) ?? defaultRejectError(issues, name);
+        throw (
+          options.onReject?.(issues, name) ?? defaultRejectError(issues, name)
+        );
       }
       // observe: continue with the raw input (documented type caveat)
       return input as T;

package/dist/attributes.cjs.map

@@ -1 +0,0 @@
-{"version":3,"sources":[],"names":[],"mappings":"","file":"attributes.cjs"}

package/dist/attributes.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":[],"names":[],"mappings":"","file":"attributes.js"}

package/dist/chunk-2ZKEORFN.cjs

@@ -1,14 +0,0 @@
-'use strict';
-
-// src/semantic-conventions.ts
-function httpRequestHeaderAttribute(name) {
-  return `http.request.header.${name.toLowerCase()}`;
-}
-function httpResponseHeaderAttribute(name) {
-  return `http.response.header.${name.toLowerCase()}`;
-}
-
-exports.httpRequestHeaderAttribute = httpRequestHeaderAttribute;
-exports.httpResponseHeaderAttribute = httpResponseHeaderAttribute;
-//# sourceMappingURL=chunk-2ZKEORFN.cjs.map
-//# sourceMappingURL=chunk-2ZKEORFN.cjs.map

package/dist/chunk-2ZKEORFN.cjs.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/semantic-conventions.ts"],"names":[],"mappings":";;;AAQO,SAAS,2BAA2B,IAAA,EAAsB;AAC/D,EAAA,OAAO,CAAA,oBAAA,EAAuB,IAAA,CAAK,WAAA,EAAa,CAAA,CAAA;AAClD;AAEO,SAAS,4BAA4B,IAAA,EAAsB;AAChE,EAAA,OAAO,CAAA,qBAAA,EAAwB,IAAA,CAAK,WAAA,EAAa,CAAA,CAAA;AACnD","file":"chunk-2ZKEORFN.cjs","sourcesContent":["import {\n  HTTPAttributes,\n  ServiceAttributes,\n  URLAttributes,\n} from './attributes/registry';\n\nexport { HTTPAttributes, ServiceAttributes, URLAttributes };\n\nexport function httpRequestHeaderAttribute(name: string): string {\n  return `http.request.header.${name.toLowerCase()}`;\n}\n\nexport function httpResponseHeaderAttribute(name: string): string {\n  return `http.response.header.${name.toLowerCase()}`;\n}\n"]}