splunk-otel-util-genai 0.1.3__py3-none-any.whl

opentelemetry/util/genai/emitters/__init__.py

@@ -0,0 +1,25 @@
+"""Emitter package consolidating all telemetry signal emitters."""
+
+from __future__ import annotations
+
+from pkgutil import extend_path
+
+__path__ = extend_path(__path__, __name__)
+
+from .composite import CompositeEmitter  # noqa: F401
+from .content_events import ContentEventsEmitter  # noqa: F401
+from .evaluation import (  # noqa: F401
+    EvaluationEventsEmitter,
+    EvaluationMetricsEmitter,
+)
+from .metrics import MetricsEmitter  # noqa: F401
+from .span import SpanEmitter  # noqa: F401
+
+__all__ = [
+    "SpanEmitter",
+    "MetricsEmitter",
+    "ContentEventsEmitter",
+    "CompositeEmitter",
+    "EvaluationMetricsEmitter",
+    "EvaluationEventsEmitter",
+]

opentelemetry/util/genai/emitters/composite.py

@@ -0,0 +1,186 @@
+from __future__ import annotations
+
+import logging
+from typing import Any, Iterable, Iterator, Mapping, Sequence
+
+from ..debug import genai_debug_log
+from ..interfaces import EmitterMeta, EmitterProtocol
+from ..types import Error, EvaluationResult, GenAI
+
+_LOGGER = logging.getLogger(__name__)
+
+_CATEGORY_START_ORDER: Sequence[str] = ("span", "metrics", "content_events")
+_CATEGORY_END_ORDER: Sequence[str] = (
+    "evaluation",
+    "metrics",
+    "content_events",
+    "span",
+)
+_EVALUATION_CATEGORY = "evaluation"
+
+
+class CompositeEmitter(EmitterMeta):
+    """Category-aware orchestrator for GenAI emitters.
+
+    Emitters are grouped by category to allow targeted replacement/augmentation while
+    preserving ordering guarantees:
+
+    * ``span`` emitters run first on ``on_start`` and last on ``on_end``/``on_error``
+    * ``metrics`` emitters run before content emitters at the end of an invocation
+    * ``content_events`` emitters observe invocations after metrics but before the
+      final span closure
+    * ``evaluation`` emitters observe ``on_evaluation_results`` and receive ``on_end``/``on_error`` for flush-style behaviour
+    """
+
+    role = "composite"
+    name = "composite"
+
+    def __init__(
+        self,
+        *,
+        span_emitters: Iterable[EmitterProtocol] | None = None,
+        metrics_emitters: Iterable[EmitterProtocol] | None = None,
+        content_event_emitters: Iterable[EmitterProtocol] | None = None,
+        evaluation_emitters: Iterable[EmitterProtocol] | None = None,
+    ) -> None:
+        self._categories: dict[str, list[EmitterProtocol]] = {
+            "span": list(span_emitters or []),
+            "metrics": list(metrics_emitters or []),
+            "content_events": list(content_event_emitters or []),
+            _EVALUATION_CATEGORY: list(evaluation_emitters or []),
+        }
+
+    # ------------------------------------------------------------------
+    # Public API used by the handler lifecycle
+
+    def on_start(self, obj: Any) -> None:  # type: ignore[override]
+        self._dispatch(_CATEGORY_START_ORDER, "on_start", obj=obj)
+
+    def on_end(self, obj: Any) -> None:  # type: ignore[override]
+        self._dispatch(_CATEGORY_END_ORDER, "on_end", obj=obj)
+
+    def on_error(self, error: Error, obj: Any) -> None:  # type: ignore[override]
+        self._dispatch(_CATEGORY_END_ORDER, "on_error", obj=obj, error=error)
+
+    def on_evaluation_results(
+        self,
+        results: Sequence[EvaluationResult],
+        obj: Any | None = None,
+    ) -> None:  # type: ignore[override]
+        if not results:
+            genai_debug_log("emitter.on_evaluation_results.empty", obj)
+            return
+        self._dispatch(
+            (_EVALUATION_CATEGORY,),
+            "on_evaluation_results",
+            obj=obj,
+            results=results,
+        )
+
+    # ------------------------------------------------------------------
+    # Introspection helpers used during configuration refresh
+
+    def iter_emitters(
+        self, categories: Sequence[str] | None = None
+    ) -> Iterator[EmitterProtocol]:
+        names = categories or (
+            "span",
+            "metrics",
+            "content_events",
+            _EVALUATION_CATEGORY,
+        )
+        for name in names:
+            for emitter in self._categories.get(name, []):
+                yield emitter
+
+    def emitters_for(self, category: str) -> Sequence[EmitterProtocol]:
+        return self._categories.get(category, [])
+
+    def categories(self) -> Mapping[str, Sequence[EmitterProtocol]]:
+        return self._categories
+
+    def add_emitter(self, category: str, emitter: EmitterProtocol) -> None:
+        self._categories.setdefault(category, []).append(emitter)
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+
+    def _dispatch(
+        self,
+        categories: Sequence[str],
+        method_name: str,
+        *,
+        obj: Any | None = None,
+        error: Error | None = None,
+        results: Sequence[EvaluationResult] | None = None,
+    ) -> None:
+        try:
+            genai_debug_log(
+                "composite.dispatch.begin",
+                obj if isinstance(obj, GenAI) else None,
+                method=method_name,
+                categories=list(categories),
+                result_count=len(results or ()),
+            )
+        except Exception:  # pragma: no cover - defensive
+            pass
+        for category in categories:
+            emitters = self._categories.get(category)
+            if not emitters:
+                continue
+            for emitter in list(emitters):
+                handler = getattr(emitter, method_name, None)
+                if handler is None:
+                    continue
+                if method_name == "on_evaluation_results":
+                    args = (results or (), obj)
+                    target = obj
+                elif method_name == "on_error":
+                    args = (error, obj)
+                    target = obj
+                else:
+                    args = (obj,)
+                    target = obj
+                try:
+                    handles = getattr(emitter, "handles", None)
+                    if handles is not None and target is not None:
+                        if not handles(target):
+                            try:
+                                genai_debug_log(
+                                    "composite.dispatch.skip",
+                                    target
+                                    if isinstance(target, GenAI)
+                                    else None,
+                                    method=method_name,
+                                    category=category,
+                                    emitter=getattr(
+                                        emitter, "name", repr(emitter)
+                                    ),
+                                )
+                            except Exception:  # pragma: no cover
+                                pass
+                            continue
+                    genai_debug_log(
+                        "composite.dispatch.emit",
+                        target if isinstance(target, GenAI) else None,
+                        method=method_name,
+                        category=category,
+                        emitter=getattr(emitter, "name", repr(emitter)),
+                    )
+                    handler(*args)
+                except Exception:  # pragma: no cover - defensive
+                    _LOGGER.debug(
+                        "Emitter %s failed during %s for category %s",
+                        getattr(emitter, "name", repr(emitter)),
+                        method_name,
+                        category,
+                        exc_info=True,
+                    )
+        try:
+            genai_debug_log(
+                "composite.dispatch.end",
+                obj if isinstance(obj, GenAI) else None,
+                method=method_name,
+            )
+        except Exception:  # pragma: no cover - defensive
+            pass

opentelemetry/util/genai/emitters/configuration.py

@@ -0,0 +1,324 @@
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from types import MethodType
+from typing import Any, Dict, Iterable, List, Sequence
+
+from ..config import Settings
+from ..interfaces import EmitterProtocol
+from ..plugins import load_emitter_specs
+from ..types import ContentCapturingMode
+from .composite import CompositeEmitter
+from .content_events import ContentEventsEmitter
+from .evaluation import EvaluationEventsEmitter, EvaluationMetricsEmitter
+from .metrics import MetricsEmitter
+from .span import SpanEmitter
+from .spec import CategoryOverride, EmitterFactoryContext, EmitterSpec
+
+_logger = logging.getLogger(__name__)
+
+_CATEGORY_SPAN = "span"
+_CATEGORY_METRICS = "metrics"
+_CATEGORY_CONTENT = "content_events"
+_CATEGORY_EVALUATION = "evaluation"
+
+
+@dataclass(frozen=True)
+class CaptureControl:
+    span_allowed: bool
+    span_initial: bool
+    events_initial: bool
+    mode: ContentCapturingMode
+
+
+def build_emitter_pipeline(
+    *,
+    tracer: Any,
+    meter: Any,
+    event_logger: Any,
+    content_logger: Any,
+    evaluation_histogram: Any,
+    settings: Settings,
+) -> tuple[CompositeEmitter, CaptureControl]:
+    """Construct the CompositeEmitter and capture control metadata."""
+
+    span_allowed = (
+        settings.capture_messages_override
+        or settings.legacy_capture_request
+        or not settings.enable_content_events
+    )
+    span_initial = span_allowed and settings.capture_messages_mode in (
+        ContentCapturingMode.SPAN_ONLY,
+        ContentCapturingMode.SPAN_AND_EVENT,
+    )
+    events_initial = settings.enable_content_events and (
+        settings.capture_messages_mode
+        in (
+            ContentCapturingMode.EVENT_ONLY,
+            ContentCapturingMode.SPAN_AND_EVENT,
+        )
+    )
+
+    context = EmitterFactoryContext(
+        tracer=tracer,
+        meter=meter,
+        event_logger=event_logger,
+        content_logger=content_logger,
+        evaluation_histogram=evaluation_histogram,
+        capture_span_content=span_initial,
+        capture_event_content=events_initial,
+    )
+
+    category_specs: Dict[str, List[EmitterSpec]] = {
+        _CATEGORY_SPAN: [],
+        _CATEGORY_METRICS: [],
+        _CATEGORY_CONTENT: [],
+        _CATEGORY_EVALUATION: [],
+    }
+    spec_registry: Dict[str, EmitterSpec] = {}
+
+    def _register(spec: EmitterSpec) -> None:
+        target = category_specs.setdefault(spec.category, [])
+        mode = getattr(spec, "mode", "append")
+        if mode == "replace-category":
+            target.clear()
+            target.append(spec)
+        elif mode == "prepend":
+            target.insert(0, spec)
+        elif mode == "replace-same-name":
+            replaced = False
+            for idx, existing in enumerate(target):
+                if existing.name == spec.name:
+                    target[idx] = spec
+                    replaced = True
+                    break
+            if not replaced:
+                target.append(spec)
+        else:
+            target.append(spec)
+        spec_registry[spec.name] = spec
+
+    if settings.enable_span and not settings.only_traceloop_compat:
+        _register(
+            EmitterSpec(
+                name="SemanticConvSpan",
+                category=_CATEGORY_SPAN,
+                factory=lambda ctx: SpanEmitter(
+                    tracer=ctx.tracer,
+                    capture_content=ctx.capture_span_content,
+                ),
+            )
+        )
+    if settings.enable_metrics:
+        _register(
+            EmitterSpec(
+                name="SemanticConvMetrics",
+                category=_CATEGORY_METRICS,
+                factory=lambda ctx: MetricsEmitter(meter=ctx.meter),
+            )
+        )
+    if settings.enable_content_events:
+        _register(
+            EmitterSpec(
+                name="ContentEvents",
+                category=_CATEGORY_CONTENT,
+                factory=lambda ctx: ContentEventsEmitter(
+                    logger=ctx.content_logger,
+                    capture_content=ctx.capture_event_content,
+                ),
+            )
+        )
+
+    # Evaluation emitters are always present
+    _register(
+        EmitterSpec(
+            name="EvaluationMetrics",
+            category=_CATEGORY_EVALUATION,
+            factory=lambda ctx: EvaluationMetricsEmitter(
+                ctx.evaluation_histogram  # now a callable returning histogram per metric
+            ),
+        )
+    )
+    _register(
+        EmitterSpec(
+            name="EvaluationEvents",
+            category=_CATEGORY_EVALUATION,
+            factory=lambda ctx: EvaluationEventsEmitter(
+                ctx.content_logger,
+                emit_legacy_event=settings.emit_legacy_evaluation_event,
+            ),
+        )
+    )
+
+    for spec in load_emitter_specs(settings.extra_emitters):
+        if spec.category not in {
+            _CATEGORY_SPAN,
+            _CATEGORY_METRICS,
+            _CATEGORY_CONTENT,
+            _CATEGORY_EVALUATION,
+        }:
+            _logger.warning(
+                "Emitter spec %s targets unknown category '%s'",
+                spec.name,
+                spec.category,
+            )
+            continue
+        _register(spec)
+
+    _apply_category_overrides(
+        category_specs, spec_registry, settings.category_overrides
+    )
+
+    span_emitters = _instantiate_category(
+        category_specs.get(_CATEGORY_SPAN, ()), context
+    )
+    metrics_emitters = _instantiate_category(
+        category_specs.get(_CATEGORY_METRICS, ()), context
+    )
+    content_emitters = _instantiate_category(
+        category_specs.get(_CATEGORY_CONTENT, ()), context
+    )
+    evaluation_emitters = _instantiate_category(
+        category_specs.get(_CATEGORY_EVALUATION, ()), context
+    )
+
+    composite = CompositeEmitter(
+        span_emitters=span_emitters,
+        metrics_emitters=metrics_emitters,
+        content_event_emitters=content_emitters,
+        evaluation_emitters=evaluation_emitters,
+    )
+    control = CaptureControl(
+        span_allowed=span_allowed,
+        span_initial=span_initial,
+        events_initial=events_initial,
+        mode=settings.capture_messages_mode,
+    )
+    return composite, control
+
+
+def _instantiate_category(
+    specs: Iterable[EmitterSpec], context: EmitterFactoryContext
+) -> List[EmitterProtocol]:
+    instances: List[EmitterProtocol] = []
+    for spec in specs:
+        try:
+            emitter = spec.factory(context)
+            if spec.invocation_types:
+                allowed = {name for name in spec.invocation_types}
+                original = getattr(emitter, "handles", None)
+                orig_func = getattr(original, "__func__", None)
+
+                def _filtered_handles(
+                    self, obj, _allowed=allowed, _orig=orig_func
+                ):
+                    if obj is None:
+                        if _orig is not None:
+                            return _orig(self, obj)
+                        return True
+                    if type(obj).__name__ not in _allowed:
+                        return False
+                    if _orig is not None:
+                        return _orig(self, obj)
+                    return True
+
+                setattr(
+                    emitter,
+                    "handles",
+                    MethodType(_filtered_handles, emitter),
+                )
+            instances.append(emitter)
+        except Exception:  # pragma: no cover - defensive
+            _logger.exception("Failed to instantiate emitter %s", spec.name)
+    return instances
+
+
+def _apply_category_overrides(
+    category_specs: Dict[str, List[EmitterSpec]],
+    spec_registry: Dict[str, EmitterSpec],
+    overrides: Dict[str, CategoryOverride],
+) -> None:
+    for category, override in overrides.items():
+        current = category_specs.setdefault(category, [])
+        if override.mode == "replace-category":
+            replacement: List[EmitterSpec] = []
+            for name in override.emitter_names:
+                spec = spec_registry.get(name)
+                if spec is None:
+                    _logger.warning(
+                        "Emitter '%s' referenced in %s override is not registered",
+                        name,
+                        category,
+                    )
+                    continue
+                replacement.append(spec)
+            if not replacement:
+                _logger.warning(
+                    "replace-category override for '%s' resolved to empty set; retaining existing emitters (fallback)",
+                    category,
+                )
+            else:
+                # Auto-augment evaluation if user attempted to replace with only SplunkEvaluationResults
+                if (
+                    category == _CATEGORY_EVALUATION
+                    and len(replacement) == 1
+                    and replacement[0].name == "SplunkEvaluationResults"
+                ):
+                    builtin_metrics = spec_registry.get("EvaluationMetrics")
+                    if builtin_metrics and builtin_metrics not in replacement:
+                        replacement.insert(0, builtin_metrics)
+                category_specs[category] = replacement
+            continue
+        if override.mode == "prepend":
+            additions = _resolve_specs(
+                override.emitter_names, spec_registry, category
+            )
+            category_specs[category] = additions + current
+            continue
+        if override.mode == "replace-same-name":
+            for name in override.emitter_names:
+                spec = spec_registry.get(name)
+                if spec is None:
+                    _logger.warning(
+                        "Emitter '%s' referenced in %s override is not registered",
+                        name,
+                        category,
+                    )
+                    continue
+                replaced = False
+                for idx, existing in enumerate(current):
+                    if existing.name == name:
+                        current[idx] = spec
+                        replaced = True
+                        break
+                if not replaced:
+                    current.append(spec)
+            continue
+        # append (default)
+        additions = _resolve_specs(
+            override.emitter_names, spec_registry, category
+        )
+        current.extend(additions)
+
+
+def _resolve_specs(
+    names: Sequence[str],
+    spec_registry: Dict[str, EmitterSpec],
+    category: str,
+) -> List[EmitterSpec]:
+    resolved: List[EmitterSpec] = []
+    for name in names:
+        spec = spec_registry.get(name)
+        if spec is None:
+            _logger.warning(
+                "Emitter '%s' referenced in %s override is not registered",
+                name,
+                category,
+            )
+            continue
+        resolved.append(spec)
+    return resolved
+
+
+__all__ = ["CaptureControl", "build_emitter_pipeline"]

opentelemetry/util/genai/emitters/content_events.py

@@ -0,0 +1,153 @@
+from __future__ import annotations
+
+import logging
+from typing import Any, Optional
+
+from opentelemetry._logs import Logger, get_logger
+
+from ..interfaces import EmitterMeta
+from ..types import (
+    AgentCreation,
+    AgentInvocation,
+    EmbeddingInvocation,
+    Error,
+    LLMInvocation,
+    Step,
+    Workflow,
+)
+from .utils import (
+    _agent_to_log_record,
+    _embedding_to_log_record,
+    _llm_invocation_to_log_record,
+    _step_to_log_record,
+    _workflow_to_log_record,
+)
+
+
+class ContentEventsEmitter(EmitterMeta):
+    """Emits input/output content as events (log records) instead of span attributes.
+
+    Supported: LLMInvocation only.
+
+    Exclusions:
+      * EmbeddingInvocation – embeddings are vector lookups; content events intentionally omitted to reduce noise & cost.
+      * ToolCall – tool calls typically reference external functions/APIs; their arguments are already span attributes and
+        are not duplicated as content events (future structured tool audit events may be added separately).
+
+    This explicit exclusion avoids surprising cardinality growth and keeps event volume proportional to user/chat messages.
+    """
+
+    role = "content_event"
+    name = "semconv_content_events"
+
+    def __init__(
+        self, logger: Optional[Logger] = None, capture_content: bool = False
+    ):
+        self._logger: Logger = logger or get_logger(__name__)
+        self._capture_content = capture_content
+        self._py_logger = logging.getLogger(f"{__name__}.ContentEventsEmitter")
+        if self._py_logger.isEnabledFor(logging.DEBUG):
+            self._py_logger.debug(
+                "Initialized ContentEventsEmitter capture_content=%s logger=%s",
+                capture_content,
+                type(self._logger).__name__,
+            )
+
+    def on_start(self, obj: Any) -> None:
+        # LLM events are emitted in finish() when we have both input and output
+        return None
+
+    def on_end(self, obj: Any) -> None:
+        if not self._capture_content:
+            if self._py_logger.isEnabledFor(logging.DEBUG):
+                self._py_logger.debug(
+                    "Skipping content emission (capture_content disabled) obj_type=%s",
+                    type(obj).__name__,
+                )
+            return
+        # Emit workflow event (includes initial input + final output messages)
+        if isinstance(obj, Workflow):
+            self._emit_workflow_event(obj)
+            return
+        # Emit agent creation/invocation event (input/output messages where available)
+        if isinstance(obj, (AgentCreation, AgentInvocation)):
+            self._emit_agent_event(obj)
+            return
+        # Optional: step and embedding events (currently excluded from request scope)
+        # Uncomment if needed later:
+        # if isinstance(obj, Step):
+        #     self._emit_step_event(obj); return
+        # if isinstance(obj, EmbeddingInvocation):
+        #     self._emit_embedding_event(obj); return
+        if isinstance(obj, LLMInvocation):
+            # Emit a single event for the entire LLM invocation
+            try:
+                record = _llm_invocation_to_log_record(
+                    obj,
+                    self._capture_content,
+                )
+                if record and self._logger:
+                    if self._py_logger.isEnabledFor(logging.DEBUG):
+                        self._py_logger.debug(
+                            "Emitting LLM content event trace_id=%s span_id=%s",
+                            getattr(obj, "trace_id", None),
+                            getattr(obj, "span_id", None),
+                        )
+                    self._logger.emit(record)
+                elif self._py_logger.isEnabledFor(logging.DEBUG):
+                    self._py_logger.debug(
+                        "No log record generated for LLM invocation (capture_content=%s)",
+                        self._capture_content,
+                    )
+            except (TypeError, ValueError, AttributeError) as e:
+                logging.getLogger(__name__).warning(
+                    "Failed to emit LLM invocation event: %s", e, exc_info=True
+                )
+
+    def on_error(self, error: Error, obj: Any) -> None:
+        return None
+
+    def handles(self, obj: Any) -> bool:
+        return isinstance(
+            obj,
+            (LLMInvocation, Workflow, AgentCreation, AgentInvocation, Step),
+        )
+
+    # Helper methods for new agentic types
+    def _emit_workflow_event(self, workflow: Workflow) -> None:
+        """Emit an event for a workflow."""
+        try:
+            record = _workflow_to_log_record(workflow, self._capture_content)
+            if record and self._logger:
+                self._logger.emit(record)
+        except (TypeError, ValueError, AttributeError):
+            return None
+
+    def _emit_agent_event(
+        self, agent: AgentCreation | AgentInvocation
+    ) -> None:
+        """Emit an event for an agent operation."""
+        try:
+            record = _agent_to_log_record(agent, self._capture_content)
+            if record and self._logger:
+                self._logger.emit(record)
+        except (TypeError, ValueError, AttributeError):
+            return None
+
+    def _emit_step_event(self, step: Step) -> None:
+        """Emit an event for a step."""
+        try:
+            record = _step_to_log_record(step, self._capture_content)
+            if record and self._logger:
+                self._logger.emit(record)
+        except (TypeError, ValueError, AttributeError):
+            return None
+
+    def _emit_embedding_event(self, embedding: EmbeddingInvocation) -> None:
+        """Emit an event for an embedding operation."""
+        try:
+            record = _embedding_to_log_record(embedding, self._capture_content)
+            if record and self._logger:
+                self._logger.emit(record)
+        except (TypeError, ValueError, AttributeError):
+            return None