@aws/aws-distro-opentelemetry-node-autoinstrumentation
Version:
This package provides Amazon Web Services distribution of the OpenTelemetry Node Instrumentation, which allows for auto-instrumentation of NodeJS applications.
168 lines • 6.23 kB
TypeScript
import { LoggerProvider } from '@opentelemetry/sdk-logs';
import { ReadableSpan } from '@opentelemetry/sdk-trace-base';
export declare enum PatternType {
INDEXED = "indexed",
DIRECT = "direct"
}
interface PatternConfig {
type: PatternType;
regex?: string;
roleKey?: string;
role?: string;
defaultRole?: string;
source: string;
}
export declare const LLO_PATTERNS: {
[key: string]: PatternConfig;
};
/**
* Utility class for handling Large Language Objects (LLO) in OpenTelemetry spans.
*
* LLOHandler performs three primary functions:
* 1. Identifies Large Language Objects (LLO) content in spans
* 2. Extracts and transforms these attributes into OpenTelemetry Gen AI Events
* 3. Filters LLO from spans to maintain privacy and reduce span size
*
* The handler uses a configuration-driven approach with a pattern registry that defines
* all supported LLO attribute patterns and their extraction rules. This makes it easy
* to add support for new frameworks without modifying the core logic.
*/
export declare class LLOHandler {
private loggerProvider;
private exactMatchPatterns;
private regexPatterns;
private patternConfigs;
/**
* Initialize an LLOHandler with the specified logger provider.
*
* This constructor compiles patterns from the pattern registry for efficient matching.
*
* @param loggerProvider The OpenTelemetry LoggerProvider used for emitting log records.
*/
constructor(loggerProvider: LoggerProvider);
/**
* Build efficient pattern matching structures from the pattern registry.
*
* Creates:
* - Set of exact match patterns for O(1) lookups
* - List of compiled regex patterns for indexed patterns
* - Mapping of patterns to their configurations
*/
private buildPatternMatchers;
/**
* Processes a sequence of spans to extract and filter LLO attributes.
*
* For each span, this method:
* 1. Collects all LLO attributes from span attributes and all span events
* 2. Emits a single consolidated Gen AI Event with all collected LLO content
* 3. Filters out LLO attributes from the span and its events to maintain privacy
* 4. Preserves non-LLO attributes in the span
*
* Handles LLO attributes from multiple frameworks:
* - Traceloop (indexed prompt/completion patterns and entity input/output)
* - OpenLit (direct prompt/completion patterns, including from span events)
* - OpenInference (input/output values and structured messages)
* - Strands SDK (system prompts and tool results)
* - CrewAI (tasks output and results)
*
* @param spans A list of OpenTelemetry ReadableSpan objects to process
* @returns {ReadableSpan[]} A list of modified spans with LLO attributes removed
*/
processSpans(spans: ReadableSpan[]): ReadableSpan[];
/**
* Collect all LLO attributes from a span's attributes and events.
*
* @param span The span to collect LLO attributes from
* @returns all LLO attributes found in the span
*/
private collectLloAttributesFromSpan;
/**
* Filter LLO attributes from span events.
*
* This method removes LLO attributes from event attributes while preserving
* the event structure and non-LLO attributes.
*
* @param span The ReadableSpan to filter events for
*/
private filterSpanEvents;
/**
* Extract LLO attributes and emit them as a single consolidated Gen AI Event.
*
* This method:
* 1. Collects all LLO attributes using the pattern registry
* 2. Groups them into input and output messages
* 3. Emits one event per span containing all LLO content
*
* The event body format:
* {
* "input": {
* "messages": [
* {
* "role": "system",
* "content": "..."
* },
* {
* "role": "user",
* "content": "..."
* }
* ]
* },
* "output": {
* "messages": [
* {
* "role": "assistant",
* "content": "..."
* }
* ]
* }
* }
*
* @param span The source ReadableSpan containing the attributes
* @param attributes LLO attributes to process
* @param eventTimestamp Optional timestamp to override span timestamps
* @returns
*/
private emitLloAttributes;
/**
* Collect all LLO messages from attributes using the pattern registry.
*
* This is the main collection method that processes all patterns defined
* in the registry and extracts messages accordingly.
*
* @param span The source ReadableSpan containing the attributes
* @param attributes Attributes to process
* @returns {Message[]} LLO messages from attributes using the pattern registry
*/
private collectAllLloMessages;
/**
* Collect messages from indexed patterns (e.g., gen_ai.prompt.0.content).
* Handles patterns with numeric indices and their associated role attributes.
*
* @param attributes Attributes to process
* @returns {Message[]}
*/
private collectIndexedMessages;
private groupMessagesByType;
/**
* Create new attributes with LLO attributes removed.
*
* This method creates an attributes object containing only non-LLO attributes,
* preserving the original values while filtering out sensitive LLO content.
* This helps maintain privacy and reduces the size of spans.
*
* @param attributes Original span or event attributes
* @returns {Attributes} New attributes with LLO attributes removed, or empty object if input is undefined
*/
private filterAttributes;
/**
* Determine if an attribute key contains LLO content based on pattern matching.
* Uses the pattern registry to check if a key matches any LLO pattern.
*
* @param key The attribute key to check
* @returns {boolean} true if the key matches any LLO pattern, false otherwise
*/
private isLloAttribute;
}
export declare const OTEL_SPAN_KEY: symbol;
export {};
//# sourceMappingURL=llo-handler.d.ts.map