veadk-python 0.2.27__py3-none-any.whl

veadk/tracing/telemetry/exporters/cozeloop_exporter.py

@@ -0,0 +1,129 @@
+# Copyright (c) 2025 Beijing Volcano Engine Technology Co., Ltd. and/or its affiliates.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from typing import Any
+
+from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
+from opentelemetry.sdk.trace.export import BatchSpanProcessor
+from pydantic import BaseModel, Field
+from typing_extensions import override
+
+from veadk.config import settings
+from veadk.tracing.telemetry.exporters.base_exporter import BaseExporter
+from veadk.utils.logger import get_logger
+
+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,
+    )
+    space_id: str = Field(
+        default_factory=lambda: settings.cozeloop_config.otel_exporter_space_id,
+    )
+    token: str = Field(
+        default_factory=lambda: settings.cozeloop_config.otel_exporter_api_key,
+    )
+
+
+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 = {
+            "cozeloop-workspace-id": self.config.space_id,
+            "authorization": f"Bearer {self.config.token}",
+        }
+        self.headers |= headers
+
+        self._exporter = OTLPSpanExporter(
+            endpoint=self.config.endpoint,
+            headers=self.headers,
+            timeout=10,
+        )
+
+        self.processor = BatchSpanProcessor(self._exporter)
+
+    @override
+    def export(self) -> None:
+        """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(
+                f"CozeloopExporter exports data to {self.config.endpoint}, space id: {self.config.space_id}"
+            )
+        else:
+            logger.warning("CozeloopExporter internal exporter is not initialized.")

veadk/tracing/telemetry/exporters/inmemory_exporter.py

@@ -0,0 +1,248 @@
+# Copyright (c) 2025 Beijing Volcano Engine Technology Co., Ltd. and/or its affiliates.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from typing import Sequence
+
+from opentelemetry.context import (
+    _SUPPRESS_INSTRUMENTATION_KEY,
+    attach,
+    detach,
+    set_value,
+)
+from opentelemetry.sdk.trace import ReadableSpan, export
+from typing_extensions import override
+
+from veadk.tracing.telemetry.exporters.base_exporter import BaseExporter
+from veadk.utils.logger import get_logger
+
+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 = ""
+        self.session_trace_dict = {}
+
+    @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
+            else:
+                logger.warning(
+                    f"Span context is missing, failed to get `trace_id`. span: {span}"
+                )
+
+            if span.name == "call_llm":
+                attributes = dict(span.attributes or {})
+                session_id = attributes.get("gen_ai.session.id", None)
+                if session_id:
+                    if session_id not in self.session_trace_dict:
+                        self.session_trace_dict[session_id] = [self.trace_id]
+                    else:
+                        self.session_trace_dict[session_id] += [self.trace_id]
+        self._spans.extend(spans)
+        return export.SpanExportResult.SUCCESS
+
+    @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")
+            span.set_attribute("gen_ai.usage.total_tokens", 0)
+            ctx = set_value("invocation_span_instance", span, context=parent_context)
+            # suppress instrumentation for llm to avoid auto instrument from apmplus, such as openai
+            ctx = set_value(
+                "suppress_language_model_instrumentation", True, context=ctx
+            )
+
+            token = attach(ctx)  # mount context on `invocation` root span in Google ADK
+            setattr(span, "_invocation_token", token)  # for later detach
+
+        if span.name.startswith("agent_run") or span.name.startswith("invoke_agent"):
+            span.set_attribute("gen_ai.operation.name", "agent")
+            span.set_attribute("gen_ai.span.kind", "agent")
+
+            ctx = set_value("agent_run_span_instance", span, context=parent_context)
+            token = attach(ctx)
+            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
+            token = attach(set_value(_SUPPRESS_INSTRUMENTATION_KEY, True))
+            try:
+                self.span_exporter.export((span,))
+            # pylint: disable=broad-exception-caught
+            except Exception:
+                logger.exception("Exception while exporting Span.")
+            detach(token)
+
+            token = getattr(span, "_invocation_token", None)
+            if token:
+                detach(token)
+
+            token = getattr(span, "_agent_run_token", None)
+            if token:
+                detach(token)
+
+
+class InMemoryExporter(BaseExporter):
+    """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
+
+        self._exporter = _InMemoryExporter()
+        self.processor = _InMemorySpanProcessor(self._exporter)

veadk/tracing/telemetry/exporters/tls_exporter.py

@@ -0,0 +1,139 @@
+# Copyright (c) 2025 Beijing Volcano Engine Technology Co., Ltd. and/or its affiliates.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from typing import Any
+
+from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
+from opentelemetry.sdk.trace.export import BatchSpanProcessor
+from pydantic import BaseModel, Field
+from typing_extensions import override
+
+from veadk.config import getenv, settings
+from veadk.tracing.telemetry.exporters.base_exporter import BaseExporter
+from veadk.utils.logger import get_logger
+
+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,
+    )
+    region: str = Field(
+        default_factory=lambda: settings.tls_config.otel_exporter_region,
+    )
+    topic_id: str = Field(
+        default_factory=lambda: settings.tls_config.otel_exporter_topic_id,
+    )
+    access_key: str = Field(default_factory=lambda: getenv("VOLCENGINE_ACCESS_KEY"))
+    secret_key: str = Field(default_factory=lambda: getenv("VOLCENGINE_SECRET_KEY"))
+
+
+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 = {
+            "x-tls-otel-tracetopic": self.config.topic_id,
+            "x-tls-otel-ak": self.config.access_key,
+            "x-tls-otel-sk": self.config.secret_key,
+            "x-tls-otel-region": self.config.region,
+        }
+        self.headers |= headers
+
+        self._exporter = OTLPSpanExporter(
+            endpoint=self.config.endpoint,
+            headers=headers,
+            timeout=10,
+        )
+
+        self.processor = BatchSpanProcessor(self._exporter)
+
+    @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(
+                f"TLSExporter exports data to {self.config.endpoint}, topic id: {self.config.topic_id}"
+            )
+        else:
+            logger.warning("TLSExporter internal exporter is not initialized.")