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

cloudbase_agent/observability/attributes.py

@@ -0,0 +1,336 @@
+"""
+Attribute creation utilities for Cloudbase Agent observability.
+
+Maps observation attributes to OpenInference and OpenTelemetry semantic conventions.
+"""
+
+import json
+import logging
+from typing import Any, Dict, Optional
+
+from opentelemetry import trace
+from opentelemetry.util.types import AttributeValue
+from openinference.semconv.trace import SpanAttributes, OpenInferenceSpanKindValues
+
+from cloudbase_agent.observability.types import (
+    BaseSpanAttributes,
+    LLMAttributes,
+    ObservationType,
+    ObservationAttributes,
+    TraceAttributes,
+)
+from cloudbase_agent.observability.constants import (
+    OtelSpanAttributes,
+    OpenInferenceSpanKind,
+)
+
+logger = logging.getLogger(__name__)
+
+def _serialize(value: Any) -> Optional[str]:
+    """Safely serialize a value to a JSON string.
+
+    Args:
+        value: The value to serialize.
+
+    Returns:
+        JSON string representation, or None if value is None/empty.
+    """
+    if value is None:
+        return None
+    if isinstance(value, str):
+        return value
+    try:
+        return json.dumps(value, default=str)
+    except Exception:
+        return "<failed to serialize>"
+
+
+def _flatten_metadata(
+    metadata: Optional[Dict[str, Any]], prefix: str
+) -> Dict[str, str]:
+    """Flatten and serialize metadata into OpenTelemetry attribute format.
+
+    Converts nested metadata objects into dot-notation attribute keys.
+    For example, `{ "database": { "host": "localhost" } }` becomes
+    `{ "metadata.database.host": "localhost" }`.
+
+    Args:
+        metadata: Metadata object to flatten.
+        prefix: Attribute prefix (e.g., 'metadata' or 'agkit.observation.metadata').
+
+    Returns:
+        Flattened metadata attributes with string values.
+    """
+    metadata_attributes: Dict[str, str] = {}
+
+    if metadata is None:
+        return metadata_attributes
+
+    if not isinstance(metadata, dict):
+        serialized = _serialize(metadata)
+        if serialized:
+            metadata_attributes[prefix] = serialized
+        return metadata_attributes
+
+    for key, value in metadata.items():
+        serialized = value if isinstance(value, str) else _serialize(value)
+        if serialized:
+            metadata_attributes[f"{prefix}.{key}"] = serialized
+
+    return metadata_attributes
+
+
+def create_trace_attributes(attributes: TraceAttributes) -> Dict[str, AttributeValue]:
+    """Create OpenTelemetry trace attributes from TraceAttributes.
+
+    Args:
+        attributes: Trace attributes to convert.
+
+    Returns:
+        OpenTelemetry-compatible trace attributes.
+    """
+    result = {
+        OtelSpanAttributes.TRACE_NAME: attributes.name,
+        OtelSpanAttributes.USER_ID: attributes.user_id,
+        OtelSpanAttributes.SESSION_ID: attributes.session_id,
+        OtelSpanAttributes.VERSION: attributes.version,
+        OtelSpanAttributes.RELEASE: attributes.release,
+        OtelSpanAttributes.TRACE_INPUT: _serialize(attributes.input),
+        OtelSpanAttributes.TRACE_OUTPUT: _serialize(attributes.output),
+        OtelSpanAttributes.TRACE_TAGS: (
+            ",".join(attributes.tags) if attributes.tags else None
+        ),
+        OtelSpanAttributes.ENVIRONMENT: attributes.environment,
+        OtelSpanAttributes.TRACE_PUBLIC: attributes.public,
+    }
+
+    # Add flattened metadata
+    metadata_attrs = _flatten_and_serialize_metadata(
+        attributes.metadata, OtelSpanAttributes.TRACE_METADATA.value
+    )
+    result.update(metadata_attrs)
+
+    # Filter out None values
+    return {k: v for k, v in result.items() if v is not None}
+
+
+def create_observation_attributes(
+    observation_type: ObservationType, attributes: ObservationAttributes
+) -> Dict[str, AttributeValue]:
+    """Create OpenTelemetry span attributes from observation attributes.
+
+    Maps observation attributes to OpenInference semantic conventions:
+    - Uses `openinference.span.kind` for span type
+    - Uses `llm.*` for LLM-specific attributes
+    - Uses `tool.*` for tool-specific attributes
+    - Falls back to `agkit.observation.*` for non-standard attributes
+
+    Args:
+        observation_type: The type of observation (llm, tool, chain, etc.)
+        attributes: Observation attributes to convert.
+
+    Returns:
+        OpenTelemetry-compatible span attributes.
+    """
+    # Base attributes for all observation types
+    # Handle both dataclass instances and dict input
+    level = None
+    status_message = None
+    version = None
+
+    if isinstance(attributes, dict):
+        level = attributes.get("level")
+        status_message = attributes.get("status_message")
+        version = attributes.get("version")
+        input_value = attributes.get("input")
+        output_value = attributes.get("output")
+        metadata = attributes.get("metadata")
+    else:
+        level = attributes.level
+        status_message = attributes.status_message
+        version = attributes.version
+        input_value = attributes.input
+        output_value = attributes.output
+        metadata = attributes.metadata
+
+    # Get OpenInference span kind with fallback to UNKNOWN
+    try:
+        span_kind = OpenInferenceSpanKind[observation_type.upper()].value
+    except KeyError:
+        logger.warning(
+            f"Unknown observation type '{observation_type}', using UNKNOWN span kind"
+        )
+        span_kind = OpenInferenceSpanKindValues.UNKNOWN.value
+
+    otel_attributes: Dict[str, AttributeValue] = {
+        SpanAttributes.OPENINFERENCE_SPAN_KIND: span_kind,
+        OtelSpanAttributes.OBSERVATION_TYPE.value: observation_type,
+        OtelSpanAttributes.OBSERVATION_LEVEL.value: (
+            level.value if level and hasattr(level, "value") else level
+        ),
+        OtelSpanAttributes.OBSERVATION_STATUS_MESSAGE.value: status_message,
+        OtelSpanAttributes.VERSION.value: version,
+        # Use OpenInference input.value convention
+        SpanAttributes.INPUT_VALUE: _serialize(input_value),
+        # Also set legacy observation.input for compatibility
+        OtelSpanAttributes.OBSERVATION_INPUT.value: _serialize(input_value),
+        # Use OpenInference output.value convention
+        SpanAttributes.OUTPUT_VALUE: _serialize(output_value),
+        # Also set legacy observation.output for compatibility
+        OtelSpanAttributes.OBSERVATION_OUTPUT.value: _serialize(output_value),
+    }
+
+    # LLM-specific attributes
+    if observation_type == ObservationType.LLM:
+        # Handle both dict and dataclass for LLM attributes
+        model = None
+        model_parameters = None
+        usage_details = None
+        completion_start_time = None
+        
+        if isinstance(attributes, dict):
+            model = attributes.get("model")
+            model_parameters = attributes.get("model_parameters")
+            usage_details = attributes.get("usage_details")
+            completion_start_time = attributes.get("completion_start_time")
+        elif hasattr(attributes, "model"):
+            model = attributes.model
+            model_parameters = attributes.model_parameters
+            usage_details = attributes.usage_details
+            completion_start_time = attributes.completion_start_time
+        
+        if model:
+            otel_attributes[
+                SpanAttributes.LLM_MODEL_NAME
+            ] = model
+        if model_parameters:
+            otel_attributes[
+                SpanAttributes.LLM_INVOCATION_PARAMETERS
+            ] = _serialize(model_parameters)
+            # Also set legacy llm.model_parameters for compatibility
+            otel_attributes[
+                OtelSpanAttributes.LLM_MODEL_PARAMETERS.value
+            ] = _serialize(model_parameters)
+        if usage_details:
+            usage = usage_details
+            if isinstance(usage, dict):
+                if usage.get("input") is not None:
+                    otel_attributes[
+                        SpanAttributes.LLM_TOKEN_COUNT_PROMPT
+                    ] = usage["input"]
+                if usage.get("output") is not None:
+                    otel_attributes[
+                        SpanAttributes.LLM_TOKEN_COUNT_COMPLETION
+                    ] = usage["output"]
+                if usage.get("total") is not None:
+                    otel_attributes[
+                        SpanAttributes.LLM_TOKEN_COUNT_TOTAL
+                    ] = usage["total"]
+            # Also set legacy llm.usage_details for compatibility
+            otel_attributes[
+                OtelSpanAttributes.LLM_USAGE_DETAILS.value
+            ] = _serialize(usage_details)
+        if completion_start_time:
+            otel_attributes[
+                OtelSpanAttributes.LLM_COMPLETION_START_TIME.value
+            ] = _serialize(completion_start_time)
+
+    # Embedding-specific attributes
+    if observation_type == ObservationType.EMBEDDING:
+        # Handle both dict and dataclass for embedding attributes
+        model = None
+        model_parameters = None
+        
+        if isinstance(attributes, dict):
+            model = attributes.get("model")
+            model_parameters = attributes.get("model_parameters")
+        elif hasattr(attributes, "model"):
+            model = attributes.model
+            model_parameters = attributes.model_parameters
+        
+        if model:
+            otel_attributes[
+                SpanAttributes.EMBEDDING_MODEL_NAME
+            ] = model
+        if model_parameters:
+            otel_attributes[
+                SpanAttributes.LLM_INVOCATION_PARAMETERS
+            ] = _serialize(model_parameters)
+
+    # Tool-specific attributes
+    if observation_type == ObservationType.TOOL:
+        tool_name = None
+        if isinstance(attributes, dict):
+            tool_name = attributes.get("tool_name")
+        elif hasattr(attributes, "tool_name"):
+            tool_name = attributes.tool_name
+        if tool_name:
+            otel_attributes[SpanAttributes.TOOL_NAME] = tool_name
+
+    # Add metadata (use OpenInference metadata convention)
+    metadata_attrs = _flatten_and_serialize_metadata(
+        metadata, SpanAttributes.METADATA
+    )
+    otel_attributes.update(metadata_attrs)
+
+    # Also add observation.metadata for compatibility
+    obsetvability_metadata_attrs = _flatten_and_serialize_metadata(
+        metadata, OtelSpanAttributes.OBSERVATION_METADATA.value
+    )
+    otel_attributes.update(obsetvability_metadata_attrs)
+
+    # Filter out None values
+    return {k: v for k, v in otel_attributes.items() if v is not None}
+
+
+def _flatten_and_serialize_metadata(
+    metadata: Optional[Dict[str, Any]], prefix: str
+) -> Dict[str, str]:
+    """Flatten and serialize metadata into OpenTelemetry attribute format.
+
+    This is an alias for _flatten_metadata for backward compatibility.
+    """
+    return _flatten_metadata(metadata, prefix)
+
+
+def update_active_trace(attributes: TraceAttributes) -> None:
+    """Update the currently active trace with new attributes.
+
+    Args:
+        attributes: Trace attributes to set.
+    """
+    current_span = trace.get_current_span()
+    if not current_span or not current_span.is_recording():
+        logger.debug(
+            "No active OTEL span in context. Skipping trace update."
+        )
+        return
+
+    trace_attrs = create_trace_attributes(attributes)
+    current_span.set_attributes(trace_attrs)
+
+
+def get_active_trace_id() -> Optional[str]:
+    """Get the current active trace ID.
+
+    Returns:
+        The trace ID as a hex string, or undefined if no active span.
+    """
+    current_span = trace.get_current_span()
+    if not current_span or not current_span.is_recording():
+        return None
+    span_context = current_span.get_span_context()
+    return format(span_context.trace_id, "032x")
+
+
+def get_active_span_id() -> Optional[str]:
+    """Get the current active observation ID.
+
+    Returns:
+        The span ID as a hex string, or undefined if no active span.
+    """
+    current_span = trace.get_current_span()
+    if not current_span or not current_span.is_recording():
+        return None
+    span_context = current_span.get_span_context()
+    return format(span_context.span_id, "016x")

cloudbase_agent/observability/constants.py

@@ -0,0 +1,78 @@
+"""
+OTEL attribute constants for Cloudbase Agent observability.
+
+Uses OpenInference semantic conventions where applicable:
+https://github.com/Arize-ai/openinference/tree/main/spec
+
+Falls back to Cloudbase Agent specific attributes where OpenInference doesn't define a standard.
+"""
+
+from enum import Enum
+from openinference.semconv.trace import SpanAttributes, OpenInferenceSpanKindValues
+
+
+# Re-export OpenInference SpanAttributes for standard attributes
+# Use this for all OpenInference standard conventions (input.value, llm.model_name, etc.)
+OpenInferenceAttributes = SpanAttributes
+
+
+# Re-export OpenInference span kind values
+class OpenInferenceSpanKind(str, Enum):
+    """OpenInference span kind values."""
+
+    AGENT = OpenInferenceSpanKindValues.AGENT.value
+    CHAIN = OpenInferenceSpanKindValues.CHAIN.value
+    LLM = OpenInferenceSpanKindValues.LLM.value
+    TOOL = OpenInferenceSpanKindValues.TOOL.value
+    RETRIEVER = OpenInferenceSpanKindValues.RETRIEVER.value
+    EMBEDDING = OpenInferenceSpanKindValues.EMBEDDING.value
+    RERANKER = OpenInferenceSpanKindValues.RERANKER.value
+    EVALUATOR = OpenInferenceSpanKindValues.EVALUATOR.value
+    GUARDRAIL = OpenInferenceSpanKindValues.GUARDRAIL.value
+
+
+# SDK information
+OBSERVABILITY_TRACER_NAME = "agkit-tracer"
+OBSERVABILITY_SDK_NAME = "agkit-observability"
+
+
+class OtelSpanAttributes(str, Enum):
+    """
+    Cloudbase Agent specific (non-standard) OTEL attributes.
+
+    For standard OpenInference attributes (input.value, llm.model_name, etc.),
+    use OpenInferenceAttributes (SpanAttributes) instead.
+    """
+
+    # Cloudbase Agent Trace attributes (non-standard)
+    TRACE_NAME = "trace.name"
+    TRACE_TAGS = "trace.tags"
+    TRACE_PUBLIC = "trace.public"
+    TRACE_METADATA = "trace.metadata"
+    TRACE_INPUT = "trace.input"
+    TRACE_OUTPUT = "trace.output"
+
+    # Cloudbase Agent Observation attributes (non-standard)
+    OBSERVATION_TYPE = "observation.type"
+    OBSERVATION_LEVEL = "observation.level"
+    OBSERVATION_STATUS_MESSAGE = "observation.status_message"
+    OBSERVATION_INPUT = "observation.input"
+    OBSERVATION_OUTPUT = "observation.output"
+    OBSERVATION_METADATA = "observation.metadata"
+
+    # Cloudbase Agent LLM-specific (non-standard)
+    LLM_COMPLETION_START_TIME = "llm.completion_start_time"
+    LLM_MODEL_PARAMETERS = "llm.model_parameters"
+    LLM_USAGE_DETAILS = "llm.usage_details"
+    LLM_COST_DETAILS = "llm.cost_details"
+
+    # Cloudbase Agent Retriever-specific (non-standard)
+    RETRIEVER_NAME = "retriever.name"
+    RETRIEVER_QUERY = "retriever.query"
+    RETRIEVER_INDEX_ID = "retriever.index_id"
+    RETRIEVER_TOP_K = "retriever.top_k"
+
+    # Cloudbase Agent General (non-standard)
+    ENVIRONMENT = "environment"
+    RELEASE = "release"
+    VERSION = "version"

cloudbase_agent/observability/coze/__init__.py

@@ -0,0 +1,10 @@
+"""
+Coze integration for Cloudbase Agent observability.
+
+This module provides a CozeEventHandler that automatically traces Coze
+bot workflows using OpenTelemetry with OpenInference semantic conventions.
+"""
+
+from cloudbase_agent.observability.coze.event_handler import CozeEventHandler
+
+__all__ = ["CozeEventHandler"]