cloudbase-agent-observability 0.1.0__py3-none-any.whl

cloudbase_agent/observability/__init__.py

@@ -0,0 +1,104 @@
+"""
+Cloudbase Agent Observability - OpenTelemetry-based tracing with OpenInference semantic conventions.
+
+This package provides observability capabilities for Cloudbase Agent agents using OpenTelemetry
+and OpenInference semantic conventions.
+"""
+
+from cloudbase_agent.observability.span_wrapper import (
+    Observation,
+    ObservationAgent,
+    ObservationChain,
+    ObservationEmbedding,
+    ObservationLLM,
+    ObservationRetriever,
+    ObservationReranker,
+    ObservationSpan,
+    ObservationTool,
+)
+from cloudbase_agent.observability.tracer import get_tracer, set_tracer_provider
+from cloudbase_agent.observability.attributes import (
+    create_observation_attributes,
+    create_trace_attributes,
+)
+from cloudbase_agent.observability.types import (
+    ObservationLevel,
+    ObservationType,
+)
+from cloudbase_agent.observability.api import (
+    start_observation,
+    update_active_trace,
+    get_active_trace_id,
+    get_active_span_id,
+)
+from cloudbase_agent.observability.constants import (
+    OpenInferenceAttributes,
+    OpenInferenceSpanKind,
+    OtelSpanAttributes,
+    OBSERVABILITY_TRACER_NAME,
+    OBSERVABILITY_SDK_NAME,
+)
+
+# Server utilities (optional import - requires opentelemetry-sdk)
+try:
+    from cloudbase_agent.observability.server import (
+        setup_observability,
+        setup_observability_async,
+        BatchConfig,
+        ConsoleTraceConfig,
+        OTLPTraceConfig,
+        CustomTraceConfig,
+        ObservabilityConfig,
+    )
+    SERVER_AVAILABLE = True
+except ImportError:
+    SERVER_AVAILABLE = False
+
+__all__ = [
+    # Span wrapper classes
+    "Observation",
+    "ObservationSpan",
+    "ObservationLLM",
+    "ObservationEmbedding",
+    "ObservationAgent",
+    "ObservationTool",
+    "ObservationChain",
+    "ObservationRetriever",
+    "ObservationReranker",
+    # Tracer functions
+    "get_tracer",
+    "set_tracer_provider",
+    # Attribute functions
+    "create_observation_attributes",
+    "create_trace_attributes",
+    # Types
+    "ObservationType",
+    "ObservationLevel",
+    # API functions
+    "start_observation",
+    "update_active_trace",
+    "get_active_trace_id",
+    "get_active_span_id",
+    # Constants
+    "OpenInferenceAttributes",
+    "OpenInferenceSpanKind",
+    "OtelSpanAttributes",
+    "OBSERVABILITY_TRACER_NAME",
+    "OBSERVABILITY_SDK_NAME",
+]
+
+# Server exports (available only when opentelemetry-sdk is installed)
+if SERVER_AVAILABLE:
+    __all__.extend([
+        # Server setup API
+        "setup_observability",
+        "setup_observability_async",
+        # Server configuration types
+        "BatchConfig",
+        "ConsoleTraceConfig",
+        "OTLPTraceConfig",
+        "CustomTraceConfig",
+        "ObservabilityConfig",
+    ])
+
+__version__ = "0.1.0"

cloudbase_agent/observability/api.py

@@ -0,0 +1,302 @@
+"""
+Public API for Cloudbase Agent observability.
+
+Provides convenient functions for creating and managing observations.
+"""
+
+from datetime import datetime
+from typing import Any, Dict, Optional, Union, overload
+
+from opentelemetry import context, trace
+from opentelemetry.trace import SpanContext, Status, StatusCode
+from opentelemetry.util.types import AttributeValue
+
+from cloudbase_agent.observability.types import (
+    ObservationType,
+    BaseSpanAttributes,
+    LLMAttributes,
+    EmbeddingAttributes,
+    AgentAttributes,
+    ToolAttributes,
+    ChainAttributes,
+    RetrieverAttributes,
+    RerankerAttributes,
+    EvaluatorAttributes,
+    GuardrailAttributes,
+    ObservationAttributes,
+    TraceAttributes,
+)
+from cloudbase_agent.observability.span_wrapper import (
+    Observation,
+    ObservationSpan,
+    ObservationLLM,
+    ObservationEmbedding,
+    ObservationAgent,
+    ObservationTool,
+    ObservationChain,
+    ObservationRetriever,
+    ObservationReranker,
+    ObservationEvaluator,
+    ObservationGuardrail,
+)
+from cloudbase_agent.observability.tracer import get_tracer
+from cloudbase_agent.observability.attributes import (
+    update_active_trace as _update_active_trace,
+    get_active_trace_id as _get_active_trace_id,
+    get_active_span_id as _get_active_span_id,
+)
+
+
+def _create_parent_context(
+    parent_span_context: Optional[SpanContext],
+) -> context.Context:
+    """Create a parent context from a span context.
+
+    Args:
+        parent_span_context: The span context to use as parent.
+
+    Returns:
+        The created context (returns current context if no parent).
+    """
+    # Create a NonRecordingSpan with the parent context
+    from opentelemetry.trace import NonRecordingSpan
+    parent_span = NonRecordingSpan(parent_span_context)
+
+    # Use the parent context to set the span in context
+    return trace.set_span_in_context(parent_span)
+
+
+@overload
+def start_observation(
+    name: str,
+    attributes: LLMAttributes,
+    *,
+    as_type: "Literal['llm']",
+    parent_span_context: Optional[SpanContext] = None,
+    start_time: Optional[datetime] = None,
+) -> ObservationLLM:
+    ...
+
+
+@overload
+def start_observation(
+    name: str,
+    attributes: EmbeddingAttributes,
+    *,
+    as_type: "Literal['embedding']",
+    parent_span_context: Optional[SpanContext] = None,
+    start_time: Optional[datetime] = None,
+) -> ObservationEmbedding:
+    ...
+
+
+@overload
+def start_observation(
+    name: str,
+    attributes: AgentAttributes,
+    *,
+    as_type: "Literal['agent']",
+    parent_span_context: Optional[SpanContext] = None,
+    start_time: Optional[datetime] = None,
+) -> ObservationAgent:
+    ...
+
+
+@overload
+def start_observation(
+    name: str,
+    attributes: ToolAttributes,
+    *,
+    as_type: "Literal['tool']",
+    parent_span_context: Optional[SpanContext] = None,
+    start_time: Optional[datetime] = None,
+) -> ObservationTool:
+    ...
+
+
+@overload
+def start_observation(
+    name: str,
+    attributes: ChainAttributes,
+    *,
+    as_type: "Literal['chain']",
+    parent_span_context: Optional[SpanContext] = None,
+    start_time: Optional[datetime] = None,
+) -> ObservationChain:
+    ...
+
+
+@overload
+def start_observation(
+    name: str,
+    attributes: RetrieverAttributes,
+    *,
+    as_type: "Literal['retriever']",
+    parent_span_context: Optional[SpanContext] = None,
+    start_time: Optional[datetime] = None,
+) -> ObservationRetriever:
+    ...
+
+
+@overload
+def start_observation(
+    name: str,
+    attributes: RerankerAttributes,
+    *,
+    as_type: "Literal['reranker']",
+    parent_span_context: Optional[SpanContext] = None,
+    start_time: Optional[datetime] = None,
+) -> ObservationReranker:
+    ...
+
+
+@overload
+def start_observation(
+    name: str,
+    attributes: EvaluatorAttributes,
+    *,
+    as_type: "Literal['evaluator']",
+    parent_span_context: Optional[SpanContext] = None,
+    start_time: Optional[datetime] = None,
+) -> ObservationEvaluator:
+    ...
+
+
+@overload
+def start_observation(
+    name: str,
+    attributes: GuardrailAttributes,
+    *,
+    as_type: "Literal['guardrail']",
+    parent_span_context: Optional[SpanContext] = None,
+    start_time: Optional[datetime] = None,
+) -> ObservationGuardrail:
+    ...
+
+
+@overload
+def start_observation(
+    name: str,
+    attributes: Optional[BaseSpanAttributes] = None,
+    *,
+    as_type: "Literal['span']" = "span",
+    parent_span_context: Optional[SpanContext] = None,
+    start_time: Optional[datetime] = None,
+) -> ObservationSpan:
+    ...
+
+
+def start_observation(
+    name: str,
+    attributes: Optional[ObservationAttributes] = None,
+    *,
+    as_type: ObservationType = "span",
+    parent_span_context: Optional[SpanContext] = None,
+    start_time: Optional[datetime] = None,
+) -> Observation:
+    """Create and start a new Cloudbase Agent observation.
+
+    Supports multiple observation types with full type safety:
+    - **span**: General-purpose operations (default)
+    - **llm**: LLM calls and AI model interactions
+    - **embedding**: Text embedding and vector operations
+    - **agent**: AI agent workflows
+    - **tool**: Individual tool calls
+    - **chain**: Multi-step processes
+    - **retriever**: Document retrieval
+    - **reranker**: Result reranking
+    - **evaluator**: Quality assessment
+    - **guardrail**: Safety checks
+
+    Args:
+        name: Descriptive name for the observation.
+        attributes: Type-specific attributes.
+        as_type: Type of observation to create. Defaults to 'span'.
+        parent_span_context: Optional parent span context for linking.
+        start_time: Optional custom start time.
+
+    Returns:
+        Strongly-typed observation object.
+
+    Examples:
+        LLM observation:
+        >>> llm = start_observation('openai-gpt-4', {
+        ...     'input': [{'role': 'user', 'content': 'Hello'}],
+        ...     'model': 'gpt-4',
+        ...     'model_parameters': {'temperature': 0.7}
+        ... }, as_type='llm')
+
+        Tool observation:
+        >>> tool = start_observation('weather-api', {
+        ...     'input': {'location': 'SF'}
+        ... }, as_type='tool')
+    """
+    tracer = get_tracer()
+
+    # Start the OTEL span with optional parent context
+    if parent_span_context:
+        # Use start_as_current_span with parent context for proper context propagation
+        from opentelemetry.trace import NonRecordingSpan
+        parent_span = NonRecordingSpan(parent_span_context)
+        parent_ctx = trace.set_span_in_context(parent_span)
+
+        # Use context manager to properly attach/detach
+        token = context.attach(parent_ctx)
+        otel_span = tracer.start_span(name, start_time=start_time)
+        # Keep context attached - the span wrapper will manage it
+    else:
+        token = None
+        otel_span = tracer.start_span(name, start_time=start_time)
+
+    # Store token in span for cleanup when span ends
+    if token:
+        otel_span._agkit_context_token = token
+
+    # Create the appropriate observation wrapper
+    if as_type == "llm":
+        return ObservationLLM(otel_span, attributes)
+    elif as_type == "embedding":
+        return ObservationEmbedding(otel_span, attributes)
+    elif as_type == "agent":
+        return ObservationAgent(otel_span, attributes)
+    elif as_type == "tool":
+        return ObservationTool(otel_span, attributes)
+    elif as_type == "chain":
+        return ObservationChain(otel_span, attributes)
+    elif as_type == "retriever":
+        return ObservationRetriever(otel_span, attributes)
+    elif as_type == "reranker":
+        return ObservationReranker(otel_span, attributes)
+    elif as_type == "evaluator":
+        return ObservationEvaluator(otel_span, attributes)
+    elif as_type == "guardrail":
+        return ObservationGuardrail(otel_span, attributes)
+    else:
+        return ObservationSpan(otel_span, attributes)
+
+
+def update_active_trace(attributes: TraceAttributes) -> None:
+    """Update the currently active trace with new attributes.
+
+    Args:
+        attributes: Trace attributes to set.
+    """
+    _update_active_trace(attributes)
+
+
+def get_active_trace_id() -> Optional[str]:
+    """Get the current active trace ID.
+
+    Returns:
+        The trace ID as a hex string, or None if no active span.
+    """
+    return _get_active_trace_id()
+
+
+def get_active_span_id() -> Optional[str]:
+    """Get the current active observation ID.
+
+    Returns:
+        The span ID as a hex string, or None if no active span.
+    """
+    return _get_active_span_id()