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

opentelemetry/util/genai/instruments.py

@@ -0,0 +1,44 @@
+# Copyright The OpenTelemetry Authors
+#
+# 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 opentelemetry.metrics import Histogram, Meter
+
+
+class Instruments:
+    """
+    Manages OpenTelemetry metrics instruments for GenAI telemetry.
+    """
+
+    def __init__(self, meter: Meter):
+        self.operation_duration_histogram: Histogram = meter.create_histogram(
+            name="gen_ai.client.operation.duration",
+            unit="s",
+            description="Duration of GenAI client operations",
+        )
+        self.token_usage_histogram: Histogram = meter.create_histogram(
+            name="gen_ai.client.token.usage",
+            unit="{token}",
+            description="Number of input and output tokens used",
+        )
+        # Agentic AI metrics
+        self.workflow_duration_histogram: Histogram = meter.create_histogram(
+            name="gen_ai.workflow.duration",
+            unit="s",
+            description="Duration of GenAI workflows",
+        )
+        self.agent_duration_histogram: Histogram = meter.create_histogram(
+            name="gen_ai.agent.duration",
+            unit="s",
+            description="Duration of agent operations",
+        )

opentelemetry/util/genai/interfaces.py

@@ -0,0 +1,58 @@
+# Phase 1 refactor: introduce lightweight protocol-style interfaces so future
+# composite generator + plugin system can rely on a stable narrow contract.
+from __future__ import annotations
+
+from typing import Any, Protocol, Sequence, runtime_checkable
+
+from .types import Error, EvaluationResult, LLMInvocation
+
+
+@runtime_checkable
+class EmitterProtocol(Protocol):
+    """Protocol implemented by all telemetry emitters.
+
+    Accepts any GenAI domain object (LLMInvocation, EmbeddingInvocation, etc.).
+    Implementations MAY ignore objects of unsupported types.
+    """
+
+    def on_start(self, obj: Any) -> None:  # pragma: no cover - structural
+        ...
+
+    def on_end(self, obj: Any) -> None:  # pragma: no cover - structural
+        ...
+
+    def on_error(
+        self, error: Error, obj: Any
+    ) -> None:  # pragma: no cover - structural
+        ...
+
+    def on_evaluation_results(
+        self, results: Sequence[EvaluationResult], obj: Any | None = None
+    ) -> None:  # pragma: no cover - structural
+        ...
+
+
+@runtime_checkable
+class EvaluatorProtocol(Protocol):
+    """Protocol for evaluator objects (future phases may broaden)."""
+
+    def evaluate(
+        self, invocation: LLMInvocation
+    ) -> Any:  # pragma: no cover - structural
+        ...
+
+
+class EmitterMeta:
+    """Simple metadata mixin for emitters (role/name used by future plugin system)."""
+
+    role: str = "span"  # default / legacy generators are span focused
+    name: str = "legacy"
+    override: bool = False
+
+    def handles(self, obj: Any) -> bool:  # pragma: no cover (trivial)
+        return True
+
+    def on_evaluation_results(
+        self, results: Sequence[EvaluationResult], obj: Any | None = None
+    ) -> None:  # pragma: no cover - default no-op
+        return None

opentelemetry/util/genai/plugins.py

@@ -0,0 +1,114 @@
+from __future__ import annotations
+
+import logging
+from typing import Iterable, Mapping, Sequence
+
+from opentelemetry.util._importlib_metadata import (
+    entry_points,  # pyright: ignore[reportUnknownVariableType]
+)
+
+from .emitters.spec import EmitterSpec
+
+_logger = logging.getLogger(__name__)
+
+
+def load_emitter_specs(
+    names: Sequence[str] | None = None,
+) -> list[EmitterSpec]:
+    """Load emitter specs declared under the ``opentelemetry_util_genai_emitters`` entry point.
+
+    Entry points should return an iterable of :class:`EmitterSpec` instances or dictionaries
+    matching the ``EmitterSpec`` constructor signature. When ``names`` is provided, only
+    entry points whose name matches (case-insensitive) the selection are loaded.
+    Legacy group support has been removed; vendor packages must migrate to the new group.
+    """
+
+    selected = {name.lower() for name in names} if names else None
+    loaded_specs: list[EmitterSpec] = []
+    seen: set[str] = set()
+    # Primary (new) group
+    for ep in entry_points(group="opentelemetry_util_genai_emitters"):
+        ep_name = getattr(ep, "name", "")
+        seen.add(ep_name.lower())
+        if selected and ep_name.lower() not in selected:
+            continue
+        try:
+            provider = ep.load()
+        except Exception:  # pragma: no cover - defensive
+            _logger.exception("Emitter entry point %s failed to load", ep_name)
+            continue
+        try:
+            loaded_specs.extend(_coerce_to_specs(provider, ep_name))
+        except Exception:  # pragma: no cover - defensive
+            _logger.exception(
+                "Emitter entry point %s returned an unsupported value", ep_name
+            )
+    # Silent legacy fallback (temporary for transition/tests). Only consult if specific names requested
+    # or if no specs loaded yet and legacy group is present.
+    if (selected and loaded_specs) or (not selected and loaded_specs):
+        pass  # already satisfied
+    else:
+        try:
+            for ep in entry_points(group="opentelemetry_genai_emitters"):
+                ep_name = getattr(ep, "name", "")
+                if ep_name.lower() in seen:
+                    continue
+                if selected and ep_name.lower() not in selected:
+                    continue
+                try:
+                    provider = ep.load()
+                except Exception:  # pragma: no cover - defensive
+                    _logger.exception(
+                        "(legacy group) Emitter entry point %s failed to load",
+                        ep_name,
+                    )
+                    continue
+                try:
+                    loaded_specs.extend(_coerce_to_specs(provider, ep_name))
+                except Exception:  # pragma: no cover - defensive
+                    _logger.exception(
+                        "(legacy group) Emitter entry point %s returned an unsupported value",
+                        ep_name,
+                    )
+        except Exception:  # pragma: no cover - defensive
+            _logger.debug("Legacy emitter entry point group not available")
+    if selected:
+        missing = selected - seen
+        for name in missing:
+            _logger.debug("Emitter entry point '%s' was not found", name)
+    return loaded_specs
+
+
+def _coerce_to_specs(provider: object, source: str) -> list[EmitterSpec]:
+    if provider is None:
+        return []
+    if callable(provider):
+        return _coerce_to_specs(provider(), source)
+    if isinstance(provider, EmitterSpec):
+        return [provider]
+    if isinstance(provider, Mapping):
+        return [_mapping_to_spec(provider, source)]
+    if isinstance(provider, Iterable):
+        specs: list[EmitterSpec] = []
+        for item in provider:
+            if isinstance(item, EmitterSpec):
+                specs.append(item)
+            elif isinstance(item, Mapping):
+                specs.append(_mapping_to_spec(item, source))
+            else:
+                raise TypeError(
+                    f"Unsupported emitter spec element {item!r} from {source}"
+                )
+        return specs
+    raise TypeError(
+        f"Unsupported emitter spec provider {provider!r} from {source}"
+    )
+
+
+def _mapping_to_spec(data: Mapping[str, object], source: str) -> EmitterSpec:
+    if "factory" not in data:
+        raise ValueError(f"Emitter spec from {source} must define a factory")
+    return EmitterSpec(**data)  # type: ignore[arg-type]
+
+
+__all__ = ["load_emitter_specs"]

opentelemetry/util/genai/span_context.py

@@ -0,0 +1,80 @@
+from __future__ import annotations
+
+from typing import Any, Tuple
+
+from opentelemetry import trace
+from opentelemetry.trace import NonRecordingSpan, Span, SpanContext
+
+from .types import GenAI
+
+
+def extract_span_context(span: Span | Any | None) -> SpanContext | None:
+    """Return a SpanContext from the given span-like object if available."""
+
+    if span is None:
+        return None
+
+    context = getattr(span, "context", None)
+    if context is not None and getattr(context, "trace_id", 0):
+        return context
+
+    get_ctx = getattr(span, "get_span_context", None)
+    if callable(get_ctx):
+        try:
+            context = get_ctx()
+        except Exception:  # pragma: no cover - defensive
+            context = None
+    if context is not None and getattr(context, "trace_id", 0):
+        return context
+    return None
+
+
+def store_span_context(target: GenAI, context: SpanContext | None) -> None:
+    """Persist span context metadata on the GenAI invocation."""
+
+    if context is None:
+        return
+    if not getattr(context, "trace_id", 0):
+        return
+
+    target.span_context = context
+    target.trace_id = getattr(context, "trace_id", None)
+    target.span_id = getattr(context, "span_id", None)
+    trace_flags = getattr(context, "trace_flags", None)
+    if trace_flags is not None:
+        try:
+            target.trace_flags = int(trace_flags)
+        except Exception:  # pragma: no cover - defensive
+            target.trace_flags = None
+
+
+def span_context_hex_ids(
+    context: SpanContext | None,
+) -> Tuple[str | None, str | None]:
+    """Return hexadecimal trace/span identifiers."""
+
+    if context is None or not getattr(context, "trace_id", 0):
+        return None, None
+    trace_id = f"{context.trace_id:032x}"
+    span_id = f"{context.span_id:016x}"
+    return trace_id, span_id
+
+
+def build_otel_context(
+    span: Span | None,
+    context: SpanContext | None,
+) -> trace.Context | None:
+    """Return an OpenTelemetry Context carrying a span or span_context."""
+
+    if span is not None:
+        try:
+            return trace.set_span_in_context(span)
+        except Exception:  # pragma: no cover - defensive
+            pass
+    if context is not None:
+        try:
+            non_recording = NonRecordingSpan(context)
+            return trace.set_span_in_context(non_recording)
+        except Exception:  # pragma: no cover - defensive
+            return None
+    return None