veadk-python 0.2.16__py3-none-any.whl → 0.2.17__py3-none-any.whl

veadk/tracing/telemetry/attributes/extractors/types.py

@@ -26,6 +26,29 @@ from opentelemetry.trace.span import Span
 
 @dataclass
 class ExtractorResponse:
+    """Response container for telemetry attribute extractors.
+
+    ExtractorResponse encapsulates the output from attribute extraction functions
+    and provides metadata about how the extracted data should be applied to
+    OpenTelemetry spans. It supports different response types for flexible
+    span annotation patterns.
+
+    The response system enables extractors to return various data formats
+    including simple attributes, structured events, and event collections,
+    allowing for rich telemetry data capture and organization.
+
+    Attributes:
+        content: The extracted data to be applied to the span. Can be any type
+            depending on the response type and extractor implementation.
+        type: Specification of how the content should be applied to spans.
+            Controls the span annotation method used.
+
+    Response Types:
+        - "attribute": Sets span attributes using set_attribute()
+        - "event": Adds span events using add_event()
+        - "event_list": Adds multiple events from a structured list
+    """
+
     content: Any
 
     type: Literal["attribute", "event", "event_list"] = "attribute"
@@ -40,6 +63,27 @@ class ExtractorResponse:
     def update_span(
         span: _Span | Span, attr_name: str, response: "ExtractorResponse"
     ) -> None:
+        """Apply extractor response content to an OpenTelemetry span.
+
+        This method interprets the ExtractorResponse and applies its content
+        to the given span using the appropriate OpenTelemetry API method
+        based on the response type.
+
+        Processing Logic:
+        - attribute: Sets span attributes, supporting both single values and lists
+        - event: Adds span events, handling both single events and event lists
+        - event_list: Processes structured event lists with key-value pairs
+
+        Args:
+            span: OpenTelemetry span to annotate with extracted data
+            attr_name: Attribute name or event name for span annotation
+            response: ExtractorResponse containing the data and type information
+
+        Note:
+            - Gracefully handles unsupported response types by discarding them
+            - Type checking ensures safe attribute and event operations
+            - List processing supports nested dictionary structures
+        """
         if response.type == "attribute":
             res = response.content
             if isinstance(res, list):
@@ -73,6 +117,24 @@ class ExtractorResponse:
 
 @dataclass
 class LLMAttributesParams:
+    """Parameter container for LLM attribute extractors.
+
+    LLMAttributesParams packages all the contextual information needed by
+    LLM attribute extraction functions. It provides access to the complete
+    LLM call context including request parameters, response data, and
+    execution environment details.
+
+    Attributes:
+        invocation_context: Complete context of the agent invocation including
+            agent instance, session information, user details, and execution state
+        event_id: Unique identifier for this specific LLM call event within
+            the broader agent execution trace
+        llm_request: Request object containing model name, parameters, prompt
+            content, and configuration settings sent to the language model
+        llm_response: Response object containing generated content, usage metadata,
+            token counts, timing information, and any error details
+    """
+
     invocation_context: InvocationContext
     event_id: str
     llm_request: LlmRequest
@@ -81,6 +143,22 @@ class LLMAttributesParams:
 
 @dataclass
 class ToolAttributesParams:
+    """Parameter container for tool attribute extractors.
+
+    ToolAttributesParams packages all the contextual information needed by
+    tool attribute extraction functions. It provides access to tool execution
+    details including tool metadata, input arguments, and execution results
+    for comprehensive tool usage telemetry.
+
+    Attributes:
+        tool: Tool instance that was executed, containing metadata such as
+            name, description, function signature, and custom metadata
+        args: Dictionary of arguments that were passed to the tool function
+            during execution, including parameter names and values
+        function_response_event: Event object containing the tool's execution
+            results, return values, timing information, and any error details
+    """
+
     tool: BaseTool
     args: dict[str, Any]
     function_response_event: Event

veadk/tracing/telemetry/exporters/apmplus_exporter.py

@@ -112,6 +112,25 @@ _GEN_AI_CLIENT_TOKEN_USAGE_BUCKETS = [
 
 @dataclass
 class Meters:
+    """Metric names and identifiers for OpenTelemetry instrumentation.
+
+    This class defines standardized metric names used for LLM and agent
+    observability. The metrics follow OpenTelemetry semantic conventions
+    for generative AI operations and include custom APMPlus metrics for
+    enhanced monitoring capabilities.
+
+    Standard Gen AI Metrics:
+        - LLM_CHAT_COUNT: Counter for LLM invocation frequency
+        - LLM_TOKEN_USAGE: Histogram for token consumption analysis
+        - LLM_OPERATION_DURATION: Histogram for operation latency tracking
+        - LLM_COMPLETIONS_EXCEPTIONS: Counter for error rate monitoring
+        - Streaming metrics: Performance analysis for streaming responses
+
+    APMPlus Custom Metrics:
+        - APMPLUS_SPAN_LATENCY: Span execution time for performance analysis
+        - APMPLUS_TOOL_TOKEN_USAGE: Tool-specific token consumption tracking
+    """
+
     LLM_CHAT_COUNT = "gen_ai.chat.count"
     LLM_TOKEN_USAGE = "gen_ai.client.token.usage"
     LLM_OPERATION_DURATION = "gen_ai.client.operation.duration"
@@ -134,9 +153,42 @@ class Meters:
 
 
 class MeterUploader:
+    """Metrics uploader for APMPlus observability platform integration.
+
+    MeterUploader manages the collection and transmission of telemetry metrics
+    to Volcengine's APMPlus platform. It creates and maintains OpenTelemetry
+    metric instruments for comprehensive agent performance monitoring.
+
+    Key Features:
+    - Automatic metric instrument creation with appropriate buckets
+    - LLM call metrics including token usage and latency
+    - Tool execution metrics for performance analysis
+    - Error tracking and exception monitoring
+    - Integration with OpenTelemetry metrics SDK
+
+    Metrics Collected:
+    - LLM invocation counts and frequencies
+    - Token consumption (input/output) with histogram distribution
+    - Operation latency with performance bucket analysis
+    - Error rates and exception details
+    - Span-level performance metrics for APMPlus dashboards
+    """
+
     def __init__(
         self, name: str, endpoint: str, headers: dict, resource_attributes: dict
     ) -> None:
+        """Initialize the meter uploader with APMPlus configuration.
+
+        Sets up the global metrics provider, creates metric instruments,
+        and configures OTLP export to APMPlus endpoints with proper
+        resource attribution and authentication.
+
+        Args:
+            name: Meter name for identification and organization
+            endpoint: APMPlus OTLP endpoint URL for metric transmission
+            headers: Authentication headers including APMPlus app key
+            resource_attributes: Service metadata for metric attribution
+        """
         # global_metrics_provider -> global_tracer_provider
         # exporter -> exporter
         # metric_reader -> processor
@@ -224,6 +276,26 @@ class MeterUploader:
         llm_request: LlmRequest,
         llm_response: LlmResponse,
     ) -> None:
+        """Record comprehensive metrics for LLM call operations.
+
+        Captures detailed telemetry data for language model invocations
+        including token consumption, latency, and error information.
+        This data enables cost optimization, performance analysis, and
+        reliability monitoring in APMPlus dashboards.
+
+        Metrics Recorded:
+        - Invocation count with model and operation attributes
+        - Input/output token usage with separate tracking
+        - Operation duration from span timing data
+        - Error counts and exception details
+        - Span latency for performance analysis
+
+        Args:
+            invocation_context: Context with agent, session, and user information
+            event_id: Unique identifier for this LLM call event
+            llm_request: Request object with model and parameter details
+            llm_response: Response object with content and usage metadata
+        """
         attributes = {
             "gen_ai_system": "volcengine",
             "gen_ai_response_model": llm_request.model,
@@ -307,6 +379,22 @@ class MeterUploader:
         args: dict[str, Any],
         function_response_event: Event,
     ):
+        """Record metrics for tool execution operations.
+
+        Captures performance and usage metrics for tool invocations
+        including execution latency and estimated token consumption.
+        Enables monitoring of tool performance and resource usage patterns.
+
+        Metrics Recorded:
+        - Tool execution latency from span timing
+        - Input/output token estimation based on text length
+        - Tool-specific attributes for categorization
+
+        Args:
+            tool: Tool instance that was executed
+            args: Arguments passed to the tool function
+            function_response_event: Event containing execution results
+        """
         logger.debug(f"Record tool call work in progress. Tool: {tool.name}")
         span = trace.get_current_span()
         if not span:
@@ -349,6 +437,17 @@ class MeterUploader:
 
 
 class APMPlusExporterConfig(BaseModel):
+    """Configuration model for APMPlus exporter settings.
+
+    Manages connection parameters and authentication details for
+    integrating with Volcengine's APMPlus observability platform.
+
+    Attributes:
+        endpoint: OTLP endpoint URL for APMPlus data ingestion
+        app_key: Authentication key for APMPlus API access
+        service_name: Service identifier displayed in APMPlus interface
+    """
+
     endpoint: str = Field(
         default_factory=lambda: settings.apmplus_config.otel_exporter_endpoint,
     )
@@ -362,9 +461,56 @@ class APMPlusExporterConfig(BaseModel):
 
 
 class APMPlusExporter(BaseExporter):
+    """OpenTelemetry exporter for Volcengine APMPlus observability platform.
+
+    APMPlusExporter provides comprehensive integration with Volcengine's APMPlus
+    platform, enabling advanced observability for VeADK agents. It combines
+    distributed tracing with detailed metrics collection for complete visibility
+    into agent performance, costs, and reliability.
+
+    Key Capabilities:
+    - OTLP-based span export to APMPlus with authentication
+    - Comprehensive metrics collection for LLM and tool operations
+    - Automatic resource attribution with service identification
+    - Cost tracking through detailed token usage metrics
+    - Performance monitoring with latency histograms
+    - Error tracking and exception monitoring
+
+    Configuration:
+    The exporter uses VeADK settings for automatic configuration but
+    can be customized with explicit parameters. Authentication is
+    handled through APMPlus app keys in request headers.
+
+    Examples:
+        Basic usage with default settings:
+        ```python
+        exporter = APMPlusExporter()
+        tracer = OpentelemetryTracer(exporters=[exporter])
+        ```
+
+    Note:
+        - Requires valid APMPlus app key for authentication
+        - Endpoint should point to APMPlus OTLP ingestion service
+        - Service name appears in APMPlus dashboards for identification
+        - Metrics and spans are automatically correlated by trace context
+        - Supports both development and production environments
+    """
+
     config: APMPlusExporterConfig = Field(default_factory=APMPlusExporterConfig)
 
     def model_post_init(self, context: Any) -> None:
+        """Initialize APMPlus exporter components after model construction.
+
+        Sets up OTLP span exporter, batch processor, and meter uploader
+        with proper authentication and resource attribution for APMPlus
+        integration.
+
+        Components Initialized:
+        - OTLP span exporter with APMPlus endpoint and authentication
+        - Batch span processor for efficient data transmission
+        - Meter uploader for comprehensive metrics collection
+        - Resource attributes for service identification
+        """
         logger.info(f"APMPlusExporter sevice name: {self.config.service_name}")
 
         headers = {
@@ -391,6 +537,17 @@ class APMPlusExporter(BaseExporter):
 
     @override
     def export(self) -> None:
+        """Force immediate export of pending telemetry data to APMPlus.
+
+        Triggers force flush on the OTLP span exporter to ensure all
+        buffered span data is immediately transmitted to APMPlus for
+        real-time observability and debugging.
+
+        Operations:
+        - Forces flush of span exporter if initialized
+        - Logs export status and configuration details
+        - Handles cases where exporter is not properly initialized
+        """
         if self._exporter:
             self._exporter.force_flush()
 

veadk/tracing/telemetry/exporters/base_exporter.py

@@ -18,6 +18,14 @@ from pydantic import BaseModel, ConfigDict, Field
 
 
 class BaseExporter(BaseModel):
+    """Abstract base class for OpenTelemetry span exporters in VeADK tracing system.
+
+    BaseExporter provides the foundation for implementing custom telemetry data
+    exporters that send span data to various observability platforms. It defines
+    the common interface and configuration structure that all concrete exporters
+    must follow.
+    """
+
     model_config = ConfigDict(arbitrary_types_allowed=True, extra="allow")
 
     resource_attributes: dict = Field(default_factory=dict)

veadk/tracing/telemetry/exporters/cozeloop_exporter.py

@@ -27,6 +27,17 @@ logger = get_logger(__name__)
 
 
 class CozeloopExporterConfig(BaseModel):
+    """Configuration model for CozeLoop exporter settings.
+
+    Manages connection parameters and authentication details for
+    integrating with CozeLoop observability and evaluation platform.
+
+    Attributes:
+        endpoint: OTLP HTTP endpoint URL for CozeLoop data ingestion
+        space_id: Workspace identifier for organizing data in CozeLoop
+        token: Authentication token for CozeLoop API access
+    """
+
     endpoint: str = Field(
         default_factory=lambda: settings.cozeloop_config.otel_exporter_endpoint,
     )
@@ -39,9 +50,47 @@ class CozeloopExporterConfig(BaseModel):
 
 
 class CozeloopExporter(BaseExporter):
+    """OpenTelemetry exporter for CozeLoop evaluation and observability platform.
+
+    CozeloopExporter provides integration with CozeLoop platform for agent
+    evaluation, monitoring, and analysis. It uses HTTP-based OTLP export
+    to send trace data to CozeLoop's evaluation infrastructure for detailed
+    performance analysis and evaluation workflows.
+
+    Integration:
+    CozeLoop specializes in AI agent evaluation and provides advanced
+    analytics for conversation quality, tool usage effectiveness, and
+    overall agent performance metrics. The exporter enables seamless
+    integration with CozeLoop's evaluation workflows.
+
+    Examples:
+        Basic usage with default settings:
+        ```python
+        exporter = CozeloopExporter()
+        tracer = OpentelemetryTracer(exporters=[exporter])
+        ```
+
+    Note:
+        - Requires valid CozeLoop workspace ID and authentication token
+        - Data is organized by workspace for multi-tenant isolation
+        - Suitable for both development and production evaluation workflows
+    """
+
     config: CozeloopExporterConfig = Field(default_factory=CozeloopExporterConfig)
 
     def model_post_init(self, context: Any) -> None:
+        """Initialize CozeLoop exporter components after model construction.
+
+        Sets up HTTP-based OTLP span exporter and batch processor with
+        proper authentication headers and workspace identification for
+        CozeLoop platform integration.
+
+        Components Initialized:
+        - HTTP OTLP span exporter with CozeLoop endpoint
+        - Batch span processor for efficient data transmission
+        - Authentication headers with workspace ID and bearer token
+        - Timeout configuration for reliable network operations
+        """
         logger.info(f"CozeloopExporter space ID: {self.config.space_id}")
 
         headers = {
@@ -60,7 +109,17 @@ class CozeloopExporter(BaseExporter):
 
     @override
     def export(self) -> None:
-        """Force export of telemetry data."""
+        """Force immediate export of pending telemetry data to CozeLoop.
+
+        Triggers force flush on the HTTP OTLP span exporter to ensure all
+        buffered span data is immediately transmitted to CozeLoop for
+        real-time evaluation and analysis.
+
+        Operations:
+        - Forces flush of span exporter if initialized
+        - Logs export status with endpoint and workspace details
+        - Handles cases where exporter is not properly initialized
+        """
         if self._exporter:
             self._exporter.force_flush()
             logger.info(

veadk/tracing/telemetry/exporters/inmemory_exporter.py

@@ -31,7 +31,27 @@ logger = get_logger(__name__)
 
 # ======== Adapted from Google ADK ========
 class _InMemoryExporter(export.SpanExporter):
+    """Internal span exporter that stores spans in memory for local analysis and debugging.
+
+    This exporter collects and stores OpenTelemetry spans in memory rather than
+    sending them to external services. It's particularly useful for development,
+    testing, and local trace analysis scenarios where immediate access to span
+    data is needed.
+
+    Key Features:
+    - In-memory span storage with session-based organization
+    - Trace ID tracking for span correlation
+    - Session-to-trace mapping for efficient filtering
+    - Support for span retrieval by session ID
+
+    Attributes:
+        _spans: List of all collected ReadableSpan objects
+        trace_id: Current trace identifier from the most recent span
+        session_trace_dict: Mapping of session IDs to their associated trace IDs
+    """
+
     def __init__(self) -> None:
+        """Initialize the in-memory exporter with empty storage containers."""
         super().__init__()
         self._spans = []
         self.trace_id = ""
@@ -39,6 +59,18 @@ class _InMemoryExporter(export.SpanExporter):
 
     @override
     def export(self, spans: Sequence[ReadableSpan]) -> export.SpanExportResult:
+        """Export spans to in-memory storage with session tracking.
+
+        Processes and stores spans while maintaining session-to-trace mapping
+        for efficient retrieval. Extracts session information from LLM call spans
+        to enable session-based filtering.
+
+        Args:
+            spans: Sequence of ReadableSpan objects to store
+
+        Returns:
+            SpanExportResult.SUCCESS: Always returns success for in-memory storage
+        """
         for span in spans:
             if span.context:
                 self.trace_id = span.context.trace_id
@@ -60,23 +92,70 @@ class _InMemoryExporter(export.SpanExporter):
 
     @override
     def force_flush(self, timeout_millis: int = 30000) -> bool:
+        """Force flush operation for in-memory exporter.
+
+        Since spans are immediately stored in memory, this operation
+        always succeeds without performing any actual flushing.
+
+        Returns:
+            bool: Always True indicating successful flush
+        """
         return True
 
     def get_finished_spans(self, session_id: str):
+        """Retrieve all spans associated with a specific session ID.
+
+        Filters stored spans to return only those belonging to the specified
+        session, enabling session-scoped trace analysis and debugging.
+
+        Args:
+            session_id: Session identifier to filter spans by
+
+        Returns:
+            list[ReadableSpan]: List of spans associated with the session,
+                empty list if session not found or no spans available
+        """
         trace_ids = self.session_trace_dict.get(session_id, None)
         if trace_ids is None or not trace_ids:
             return []
         return [x for x in self._spans if x.context.trace_id in trace_ids]
 
     def clear(self):
+        """Clear all stored spans and session mappings.
+
+        Removes all collected span data from memory, useful for cleanup
+        between test runs or to free memory in long-running processes.
+        """
         self._spans.clear()
 
 
 class _InMemorySpanProcessor(export.SimpleSpanProcessor):
+    """Custom span processor for in-memory export with enhanced span annotation.
+
+    Extends SimpleSpanProcessor to add VeADK-specific span attributes and
+    context management. Handles span lifecycle events to set appropriate
+    attributes and manage OpenTelemetry context for nested span hierarchies.
+    """
+
     def __init__(self, exporter: _InMemoryExporter) -> None:
+        """Initialize the span processor with the given in-memory exporter.
+
+        Args:
+            exporter: _InMemoryExporter instance for storing processed spans
+        """
         super().__init__(exporter)
 
     def on_start(self, span, parent_context) -> None:
+        """Handle span start events with type-specific attribute setting.
+
+        Automatically detects span types based on name patterns and applies
+        appropriate attributes. Sets up OpenTelemetry context for hierarchical
+        span management and instrumentation suppression.
+
+        Args:
+            span: The span being started
+            parent_context: Parent OpenTelemetry context
+        """
         if span.name.startswith("invocation"):
             span.set_attribute("gen_ai.operation.name", "chain")
             span.set_attribute("gen_ai.span.kind", "workflow")
@@ -99,6 +178,15 @@ class _InMemorySpanProcessor(export.SimpleSpanProcessor):
             setattr(span, "_agent_run_token", token)  # for later detach
 
     def on_end(self, span: ReadableSpan) -> None:
+        """Handle span end events with proper context cleanup.
+
+        Exports the finished span to the in-memory storage while managing
+        OpenTelemetry context and cleaning up attached tokens to prevent
+        memory leaks.
+
+        Args:
+            span: The span that has finished execution
+        """
         if span.context:
             if not span.context.trace_flags.sampled:
                 return
@@ -120,9 +208,38 @@ class _InMemorySpanProcessor(export.SimpleSpanProcessor):
 
 
 class InMemoryExporter(BaseExporter):
-    """InMemory Exporter mainly for store spans in memory for debugging / observability purposes."""
+    """In-memory span exporter for local debugging and observability analysis.
+
+    InMemoryExporter provides a complete in-memory tracing solution that stores
+    spans locally for immediate analysis, debugging, and testing. It's ideal for
+    development environments where external observability platforms are not
+    available or not desired.
+
+    Use Cases:
+    - Development and debugging of agent workflows
+    - Unit and integration testing with trace verification
+    - Local trace analysis and performance profiling
+    - Offline environments without external connectivity
+    - Trace data export for post-processing and analysis
+
+    Integration:
+    The exporter is automatically added to OpentelemetryTracer instances
+    and cannot be manually configured to avoid conflicts. It provides the
+    foundation for local trace file generation and analysis.
+
+    Note:
+        - Cannot be added to exporter lists (validation prevents this)
+        - Automatically managed by OpentelemetryTracer
+        - Memory usage grows with span count - consider periodic clearing
+        - Session tracking requires properly configured session IDs
+    """
 
     def __init__(self, name: str = "inmemory_exporter") -> None:
+        """Initialize the in-memory exporter with internal components.
+
+        Args:
+            name: Identifier for this exporter instance.
+        """
         super().__init__()
 
         self.name = name

veadk/tracing/telemetry/exporters/tls_exporter.py

@@ -27,6 +27,19 @@ logger = get_logger(__name__)
 
 
 class TLSExporterConfig(BaseModel):
+    """Configuration model for Volcengine TLS exporter settings.
+
+    Manages connection parameters and authentication details for
+    integrating with Volcengine's TLS logging and observability platform.
+
+    Attributes:
+        endpoint: OTLP HTTP endpoint URL for TLS data ingestion
+        region: Volcengine region where the TLS service is deployed
+        topic_id: TLS topic identifier for organizing log data
+        access_key: Volcengine access key for API authentication
+        secret_key: Volcengine secret key for API authentication
+    """
+
     endpoint: str = Field(
         default_factory=lambda: settings.tls_config.otel_exporter_endpoint,
     )
@@ -41,9 +54,51 @@ class TLSExporterConfig(BaseModel):
 
 
 class TLSExporter(BaseExporter):
+    """OpenTelemetry exporter for Volcengine TLS platform.
+
+    TLSExporter provides integration with Volcengine's TLS platform for
+    centralized logging and trace data management. It uses HTTP-based OTLP
+    export to send trace data to TLS topics for storage, analysis, and
+    long-term retention.
+
+    Use Cases:
+    - Centralized trace data storage and archival
+    - Long-term performance trend analysis
+    - Compliance and audit trail requirements
+    - Cross-service trace correlation and analysis
+    - Integration with existing TLS logging infrastructure
+
+    Examples:
+        Basic usage with default settings:
+        ```python
+        exporter = TLSExporter()
+        tracer = OpentelemetryTracer(exporters=[exporter])
+        ```
+
+    Note:
+        - Requires valid Volcengine credentials and TLS topic ID
+        - Data is organized by topics for efficient management
+        - Supports regional deployments for data locality compliance
+        - Integrates with TLS alerting and analysis features
+        - Suitable for production environments requiring data retention
+    """
+
     config: TLSExporterConfig = Field(default_factory=TLSExporterConfig)
 
     def model_post_init(self, context: Any) -> None:
+        """Initialize TLS exporter components after model construction.
+
+        Sets up HTTP-based OTLP span exporter and batch processor with
+        Volcengine authentication headers and TLS topic configuration for
+        centralized trace data management.
+
+        Components Initialized:
+        - HTTP OTLP span exporter with TLS endpoint
+        - Batch span processor for efficient data transmission
+        - Authentication headers with Volcengine credentials
+        - Topic and region configuration for data routing
+        - Timeout configuration for reliable network operations
+        """
         logger.info(f"TLSExporter topic ID: {self.config.topic_id}")
 
         headers = {
@@ -64,6 +119,17 @@ class TLSExporter(BaseExporter):
 
     @override
     def export(self) -> None:
+        """Force immediate export of pending telemetry data to TLS.
+
+        Triggers force flush on the HTTP OTLP span exporter to ensure all
+        buffered span data is immediately transmitted to TLS for centralized
+        logging and analysis.
+
+        Operations:
+        - Forces flush of span exporter if initialized
+        - Logs export status with endpoint and topic details
+        - Handles cases where exporter is not properly initialized
+        """
         if self._exporter:
             self._exporter.force_flush()
             logger.info(