@vfarcic/dot-ai
Version:
AI-powered development productivity platform that enhances software development workflows through intelligent automation and AI-driven assistance
80 lines • 3.24 kB
TypeScript
/**
* AI Provider Tracing Utilities
*
* Generic wrapper for instrumenting AI provider calls with OpenTelemetry.
* Uses official GenAI semantic conventions for AI/LLM operations.
*
* Supports:
* - chat operations (sendMessage)
* - tool_loop operations (toolLoop with agentic tool calling)
* - embeddings operations (generateEmbedding, generateEmbeddings)
*
* Reference: https://opentelemetry.io/docs/specs/semconv/gen-ai/
*/
/**
* Configuration for AI operation tracing
*/
export interface AITracingOptions {
/** AI provider name (e.g., 'anthropic', 'openai', 'google') */
provider: string;
/** Model identifier (e.g., 'claude-sonnet-4-6', 'gpt-5.4', 'text-embedding-3-small') */
model: string;
/** Operation type: 'chat', 'tool_loop', 'embeddings' */
operation: 'chat' | 'tool_loop' | 'embeddings';
/** Optional max tokens parameter (only for chat/tool_loop operations) */
maxTokens?: number;
}
/**
* Metrics extracted from AI operation result
* Fields vary by operation type:
* - chat/tool_loop: inputTokens, outputTokens, cache tokens
* - embeddings: embeddingCount, embeddingDimensions
*/
export interface AITracingResult {
/** Input tokens consumed (chat/tool_loop only) */
inputTokens?: number;
/** Output tokens generated (chat/tool_loop only) */
outputTokens?: number;
/** Cache read tokens (if provider supports caching) */
cacheReadTokens?: number;
/** Cache creation tokens (if provider supports caching) */
cacheCreationTokens?: number;
/** Number of embeddings generated (embeddings only) */
embeddingCount?: number;
/** Dimension size of embeddings (embeddings only) */
embeddingDimensions?: number;
}
/**
* Generic wrapper for AI provider calls
*
* Creates CLIENT spans with official gen_ai.* semantic conventions.
* The auto-instrumented HTTP span becomes a child of this span.
*
* @param options AI operation configuration
* @param handler Function that performs the actual AI call
* @param extractMetrics Function to extract metrics from the result
* @returns Result from the handler function
*
* @example Chat operation
* const response = await withAITracing(
* { provider: 'anthropic', model: 'claude-sonnet-4-6', operation: 'chat' },
* async () => await client.messages.create(...),
* (result) => ({ inputTokens: result.usage.input_tokens, outputTokens: result.usage.output_tokens })
* );
*
* @example Tool loop operation
* const result = await withAITracing(
* { provider: 'anthropic', model: 'claude-sonnet-4-6', operation: 'tool_loop' },
* async () => await provider.toolLoop(...),
* (result) => ({ inputTokens: result.totalTokens.input, outputTokens: result.totalTokens.output })
* );
*
* @example Embeddings operation
* const embedding = await withAITracing(
* { provider: 'openai', model: 'text-embedding-3-small', operation: 'embeddings' },
* async () => await client.embeddings.create(...),
* (result) => ({ embeddingCount: 1, embeddingDimensions: 1536 })
* );
*/
export declare function withAITracing<T>(options: AITracingOptions, handler: () => Promise<T>, extractMetrics: (result: T) => AITracingResult): Promise<T>;
//# sourceMappingURL=ai-tracing.d.ts.map