edgeone 1.5.9 → 1.6.1

package/edgeone-dist/pages/observability-python/__init__.py

@@ -0,0 +1,32 @@
+"""EdgeOne Agent Python Observability.
+
+Public API:
+    setup(entry_names)          → AgentTracer
+    get_tracer()                → AgentTracer | None
+    start_request_span(name)    → (Span, Context)
+    end_request_span(span)      → None
+    shutdown()                   → None
+"""
+from __future__ import annotations
+
+from .bootstrap import setup, get_tracer, start_request_span, end_request_span, shutdown
+from .tracer import AgentTracer, NoOpTracer
+from .context_patches import set_request_context, clear_request_context
+from .context_propagator import (
+    set_agent_conversation_id,
+    reset_agent_conversation_id,
+)
+
+__all__ = [
+    "setup",
+    "get_tracer",
+    "start_request_span",
+    "end_request_span",
+    "shutdown",
+    "AgentTracer",
+    "NoOpTracer",
+    "set_request_context",
+    "clear_request_context",
+    "set_agent_conversation_id",
+    "reset_agent_conversation_id",
+]

package/edgeone-dist/pages/observability-python/_compat.py

@@ -0,0 +1,69 @@
+"""OTel SDK compatibility patches.
+
+- flags patch: Force span flags=0 for Tencent APM parent_span_id detection.
+- detach patch: Suppress ValueError when detaching tokens across async contexts.
+"""
+from __future__ import annotations
+
+
+def apply_compat_patches() -> None:
+    """Apply OTel SDK compatibility patches. Call before any span export."""
+    _patch_span_flags()
+    _patch_context_detach()
+
+
+def _patch_span_flags() -> None:
+    """Force OTLP encoder to emit flags=0.
+
+    Python OTel SDK 1.27+ encodes non-zero flags on OTLP spans.
+    Tencent APM silently drops parent_span_id when flags != 0.
+    """
+    try:
+        from opentelemetry.exporter.otlp.proto.common._internal import (
+            trace_encoder as _enc,
+        )
+        _enc._span_flags = lambda _parent_span_context: 0  # type: ignore[assignment]
+    except ImportError:
+        pass
+
+
+def _patch_context_detach() -> None:
+    """Make context.detach() tolerant of cross-context token resets.
+
+    Problem: OpenInference instrumentors wrap async generators and call
+    context_api.detach(token) in their finally block. When the generator
+    is closed via aclose() from a different async task (e.g. adapter's
+    streaming loop cancels the generator on client disconnect), the
+    ContextVar.reset(token) raises ValueError because the token was
+    created in a different execution context.
+
+    This is harmless — the context will be garbage-collected anyway —
+    but produces noisy "Failed to detach context" tracebacks in logs.
+
+    Fix: patch ContextVarsRuntimeContext.detach to suppress the ValueError.
+    """
+    try:
+        from opentelemetry.context.contextvars_context import (
+            ContextVarsRuntimeContext,
+        )
+    except ImportError:
+        return
+
+    if getattr(ContextVarsRuntimeContext, "_eo_detach_patched", False):
+        return
+
+    _orig_detach = ContextVarsRuntimeContext.detach
+
+    def _safe_detach(self, token):  # type: ignore[no-untyped-def]
+        try:
+            return _orig_detach(self, token)
+        except (ValueError, RuntimeError):
+            # ValueError: token was created in a different Context — happens
+            #   when an async generator is closed from a different task.
+            # RuntimeError: token has already been used — happens when detach
+            #   is called twice (e.g. generator finally + outer finally).
+            # Both are harmless cleanup failures, suppress silently.
+            pass
+
+    ContextVarsRuntimeContext.detach = _safe_detach  # type: ignore[assignment]
+    ContextVarsRuntimeContext._eo_detach_patched = True  # type: ignore[attr-defined]

package/edgeone-dist/pages/observability-python/apm/__init__.py

@@ -0,0 +1,13 @@
+"""EdgeOne Agent Observability — APM adapter layer."""
+from .config import resolve_apm_endpoint, resolve_service_name, apm_identity_attrs
+from .span_exporter import ApmSpanExporter, TranslatorContext
+from .metrics_bridge import ApmMetricsBridge
+
+__all__ = [
+    "resolve_apm_endpoint",
+    "resolve_service_name",
+    "apm_identity_attrs",
+    "ApmSpanExporter",
+    "TranslatorContext",
+    "ApmMetricsBridge",
+]

package/edgeone-dist/pages/observability-python/apm/config.py

@@ -0,0 +1,85 @@
+"""Pinned runtime constants for the APM adapter layer.
+
+Mirrors the Node-side config (src/agent/observability/apm/config.ts) and
+the demo (frameworks-py/src/runner/config.py). Keep in lockstep.
+"""
+from __future__ import annotations
+
+import os
+import socket
+from datetime import datetime
+from typing import Mapping
+
+
+# --- APM endpoint resolution (same env protocol as Node) ---
+
+APM_ENDPOINTS: dict[str, str] = {
+    "ap-beijing": "http://ap-beijing.apm.tencentcs.com:55681",
+    "ap-singapore": "http://ap-singapore.apm.tencentcs.com:55681",
+}
+DEFAULT_REGION = "ap-singapore"
+
+
+def resolve_apm_endpoint() -> str:
+    """Resolve APM endpoint from TENCENTCLOUD_REGION env var."""
+    region = os.environ.get("TENCENTCLOUD_REGION", DEFAULT_REGION)
+    return APM_ENDPOINTS.get(region, APM_ENDPOINTS[DEFAULT_REGION])
+
+
+_cached_dev_service_name: str | None = None
+
+
+def resolve_service_name() -> str:
+    """Resolve service_name: {projectId}-{deploymentId}, fallback to dir+datetime."""
+    project_id = os.environ.get("PAGES_PROJECT_ID", "")
+    deployment_id = os.environ.get("PAGES_DEPLOYMENT_ID", "")
+    if project_id and deployment_id:
+        return f"{project_id}-{deployment_id}"
+    if os.environ.get("OTEL_SERVICE_NAME"):
+        return os.environ["OTEL_SERVICE_NAME"]
+    # Dev mode: parent process (agent-observability) generates a unified
+    # service name via EDGEONE_DEV_SERVICE_NAME so that Node.js and Python
+    # runtimes share the same name on APM dual-export.
+    if os.environ.get("EDGEONE_DEV_SERVICE_NAME"):
+        return os.environ["EDGEONE_DEV_SERVICE_NAME"]
+    # Fallback dev mode: project name + datetime (cached per process).
+    global _cached_dev_service_name
+    if _cached_dev_service_name is None:
+        basename = os.path.basename(os.path.dirname(os.path.dirname(os.getcwd()))) or "agent"
+        date_str = datetime.now().strftime("%Y%m%d%H%M%S")
+        _cached_dev_service_name = f"{basename}-{date_str}"
+    return _cached_dev_service_name
+
+
+# --- Pinned constants (must match Node side exactly) ---
+
+MIN_LLM_CALL_DURATION_MS = 50
+
+METRIC_EXPORT_INTERVAL_MS = 300_000
+METRIC_EXPORT_TIMEOUT_MS = 30_000
+
+APM_IDENTITY_LIBRARY_NAME = "langfuse-sdk"
+APM_IDENTITY_LIBRARY_VERSION = "4.3.1"
+
+
+# --- Identity attrs ---
+
+def _local_ip() -> str:
+    try:
+        with socket.socket(socket.AF_INET, socket.SOCK_DGRAM) as s:
+            s.connect(("8.8.8.8", 80))
+            return s.getsockname()[0]
+    except OSError:
+        return "127.0.0.1"
+
+
+def apm_identity_attrs() -> Mapping[str, str]:
+    """Identity fields APM expects on recognised LLM services."""
+    hostname = socket.gethostname()
+    return {
+        "instrumentation.library.name": APM_IDENTITY_LIBRARY_NAME,
+        "instrumentation.library.version": APM_IDENTITY_LIBRARY_VERSION,
+        "host.name": hostname,
+        "ip": _local_ip(),
+        "service.instance": hostname,
+    }

package/edgeone-dist/pages/observability-python/apm/llm_semconv.py

@@ -0,0 +1,53 @@
+"""OpenInference <-> OpenLLMetry semantic translation.
+
+Mirrors frameworks-py/src/runner/llm_semconv.py exactly.
+"""
+from __future__ import annotations
+
+from typing import Literal
+
+
+OI_LLM_KINDS: tuple[str, ...] = (
+    "LLM",
+    "CHAIN",
+    "AGENT",
+    "TOOL",
+    "EMBEDDING",
+    "RETRIEVER",
+    "RERANKER",
+)
+OI_LLM_KIND_SET: frozenset[str] = frozenset(OI_LLM_KINDS)
+
+OI_LLM_LEAF_KIND_SET: frozenset[str] = frozenset({"LLM"})
+
+
+def oi_kind_to_operation(kind: str) -> Literal["chat", "embedding", "rerank"]:
+    if kind == "EMBEDDING":
+        return "embedding"
+    if kind == "RERANKER":
+        return "rerank"
+    return "chat"
+
+
+def oi_kind_to_genai_span_kind(kind: str) -> str:
+    return "generation" if kind == "LLM" else kind.lower()
+
+
+# Attribute mirror: (dest_key, src_key, coerce)
+OI_TO_GENAI_MIRROR: tuple[tuple[str, str, str | None], ...] = (
+    ("gen_ai.usage.prompt_tokens", "llm.token_count.prompt", "number"),
+    ("gen_ai.usage.completion_tokens", "llm.token_count.completion", "number"),
+    ("llm.usage.total_tokens", "llm.token_count.total", "number"),
+    ("gen_ai.usage.input_tokens", "llm.token_count.prompt", "number"),
+    ("gen_ai.usage.output_tokens", "llm.token_count.completion", "number"),
+    ("gen_ai.usage.total_tokens", "llm.token_count.total", "number"),
+    (
+        "gen_ai.usage.cache_read.input_tokens",
+        "llm.token_count.prompt_details.cache_read",
+        "number",
+    ),
+    ("gen_ai.request.model", "llm.model_name", None),
+    ("gen_ai.response.model", "llm.model_name", None),
+    ("gen_ai.system", "llm.provider", None),
+    ("gen_ai.provider.name", "llm.provider", None),
+)

package/edgeone-dist/pages/observability-python/apm/metrics_bridge.py

@@ -0,0 +1,226 @@
+"""APM Metrics bridge — drives gen_ai.client.operation.duration histogram.
+
+Mirrors frameworks-py/src/runner/apm_metrics_bridge.py.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+from opentelemetry.context import Context
+from opentelemetry.exporter.otlp.proto.http.metric_exporter import OTLPMetricExporter
+from opentelemetry.sdk.metrics import MeterProvider
+from opentelemetry.sdk.metrics.export import (
+    AggregationTemporality,
+    PeriodicExportingMetricReader,
+)
+from opentelemetry.sdk.metrics._internal.instrument import (
+    Counter,
+    Histogram,
+    ObservableCounter,
+    ObservableGauge,
+    ObservableUpDownCounter,
+    UpDownCounter,
+)
+from opentelemetry.sdk.resources import Resource
+from opentelemetry.sdk.trace import ReadableSpan, Span
+from opentelemetry.sdk.trace.export import SpanProcessor
+from opentelemetry.trace.status import StatusCode
+
+from .config import (
+    METRIC_EXPORT_INTERVAL_MS,
+    METRIC_EXPORT_TIMEOUT_MS,
+    MIN_LLM_CALL_DURATION_MS,
+)
+from .llm_semconv import (
+    OI_LLM_KIND_SET,
+    OI_LLM_LEAF_KIND_SET,
+    oi_kind_to_operation,
+)
+
+# 与 span_exporter._INTERRUPT_EXCEPTION_NAMES 保持一致：LangGraph 控制流异常名，
+# 外加 interrupt 触发后流拆除 / 取消的 teardown 信号 GeneratorExit / CancelledError。
+_INTERRUPT_EXCEPTION_NAMES = frozenset({
+    "GraphInterrupt",
+    "NodeInterrupt",
+    "ParentCommand",
+    "GeneratorExit",
+    "CancelledError",
+})
+
+# 与 span_exporter._CREWAI_INTERRUPT_EXCEPTION_NAMES 保持一致：CrewAI @human_feedback
+# 暂停信号 HumanFeedbackPending，非业务错误，仅在 crewai instrumentation scope 内归一，
+# 避免把人工反馈暂停计入 LLM 错误指标。
+_CREWAI_INTERRUPT_EXCEPTION_NAMES = frozenset({
+    "HumanFeedbackPending",
+})
+
+
+def _is_crewai_scope(span: ReadableSpan) -> bool:
+    scope = getattr(span, "instrumentation_scope", None)
+    name = getattr(scope, "name", None)
+    return isinstance(name, str) and "crewai" in name.lower()
+
+
+def _iter_exception_type_names(span: ReadableSpan):
+    attrs = span.attributes or {}
+    for key in ("exception.type", "error.type"):
+        v = attrs.get(key)
+        if isinstance(v, str) and v:
+            yield v.rsplit(".", 1)[-1]
+    for ev in getattr(span, "events", None) or ():
+        if getattr(ev, "name", None) != "exception":
+            continue
+        ev_attrs = getattr(ev, "attributes", None) or {}
+        v = ev_attrs.get("exception.type")
+        if isinstance(v, str) and v:
+            yield v.rsplit(".", 1)[-1]
+
+
+def _is_interrupt_span(span: ReadableSpan) -> bool:
+    names = list(_iter_exception_type_names(span))
+    if any(n in _INTERRUPT_EXCEPTION_NAMES for n in names):
+        return True
+    if _is_crewai_scope(span) and any(
+        n in _CREWAI_INTERRUPT_EXCEPTION_NAMES for n in names
+    ):
+        return True
+    return False
+
+
+def _pick_str(span: ReadableSpan, *keys: str) -> str | None:
+    attrs = span.attributes or {}
+    for k in keys:
+        v = attrs.get(k)
+        if isinstance(v, str) and v:
+            return v
+    return None
+
+
+def _shared_attrs(span: ReadableSpan) -> dict[str, Any]:
+    model = (
+        _pick_str(span, "llm.model_name", "gen_ai.response.model", "gen_ai.request.model")
+        or "unknown"
+    )
+    system = (
+        _pick_str(span, "llm.provider", "gen_ai.system", "gen_ai.provider.name")
+        or "unknown"
+    )
+    oi_kind = _pick_str(span, "openinference.span.kind") or ""
+    request_type = _pick_str(span, "llm.request.type") or oi_kind_to_operation(oi_kind)
+    out: dict[str, Any] = {
+        "gen_ai.system": system,
+        "gen_ai.response.model": model,
+        "gen_ai.operation.name": request_type,
+    }
+    streaming = (span.attributes or {}).get("llm.is_streaming")
+    if streaming is True or streaming == "true":
+        out["stream"] = True
+    return out
+
+
+def _is_oi_llm_leaf(span: ReadableSpan) -> bool:
+    kind = _pick_str(span, "openinference.span.kind")
+    return kind is not None and kind in OI_LLM_LEAF_KIND_SET
+
+
+def _is_oi_llm_span(span: ReadableSpan) -> bool:
+    kind = _pick_str(span, "openinference.span.kind")
+    return kind is not None and kind in OI_LLM_KIND_SET
+
+
+def _duration_seconds(span: ReadableSpan) -> float:
+    if span.start_time is None or span.end_time is None:
+        return 0.0
+    return (span.end_time - span.start_time) / 1e9
+
+
+_DELTA_PREF = {
+    Counter: AggregationTemporality.DELTA,
+    UpDownCounter: AggregationTemporality.CUMULATIVE,
+    Histogram: AggregationTemporality.DELTA,
+    ObservableCounter: AggregationTemporality.DELTA,
+    ObservableUpDownCounter: AggregationTemporality.CUMULATIVE,
+    ObservableGauge: AggregationTemporality.CUMULATIVE,
+}
+
+
+class ApmMetricsBridge:
+    def __init__(self, *, endpoint: str, apm_token: str, resource: Resource) -> None:
+        self._exporter = OTLPMetricExporter(
+            endpoint=f"{endpoint.rstrip('/')}/v1/metrics",
+            preferred_temporality=_DELTA_PREF,
+        )
+        self._reader = PeriodicExportingMetricReader(
+            self._exporter,
+            export_interval_millis=METRIC_EXPORT_INTERVAL_MS,
+            export_timeout_millis=METRIC_EXPORT_TIMEOUT_MS,
+        )
+        self._meter_provider = MeterProvider(
+            resource=resource,
+            metric_readers=[self._reader],
+        )
+        meter = self._meter_provider.get_meter(
+            "edgeone-agent-apm-bridge",
+            "0.1.0",
+        )
+        self._duration_histogram = meter.create_histogram(
+            name="gen_ai.client.operation.duration",
+            unit="s",
+            description="GenAI operation duration",
+        )
+        self._processor = _BridgeSpanProcessor(self)
+
+    @property
+    def span_processor(self) -> SpanProcessor:
+        return self._processor
+
+    def record(self, span: ReadableSpan) -> None:
+        if not _is_oi_llm_span(span):
+            return
+        if not _is_oi_llm_leaf(span):
+            return
+        if not _pick_str(
+            span,
+            "llm.model_name",
+            "gen_ai.response.model",
+            "gen_ai.request.model",
+        ):
+            return
+        dur = _duration_seconds(span)
+        if dur * 1000 < MIN_LLM_CALL_DURATION_MS:
+            return
+        attrs = _shared_attrs(span)
+        if (
+            span.status
+            and span.status.status_code == StatusCode.ERROR
+            and not _is_interrupt_span(span)
+        ):
+            err = _pick_str(span, "error.type", "exception.type") or "error"
+            attrs["error.type"] = err
+        self._duration_histogram.record(dur, attributes=attrs)
+
+    def shutdown(self) -> None:
+        try:
+            self._meter_provider.shutdown()
+        except Exception:
+            pass
+
+
+class _BridgeSpanProcessor(SpanProcessor):
+    def __init__(self, bridge: ApmMetricsBridge) -> None:
+        self._bridge = bridge
+
+    def on_start(self, span: Span, parent_context: Context | None = None) -> None:
+        return None
+
+    def on_end(self, span: ReadableSpan) -> None:
+        try:
+            self._bridge.record(span)
+        except Exception:
+            pass
+
+    def shutdown(self) -> None:
+        return None
+
+    def force_flush(self, timeout_millis: int = 30_000) -> bool:
+        return True