edgeone 1.5.9 → 1.6.0

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

@@ -0,0 +1,167 @@
+"""Context propagation patches for OpenInference instrumentors.
+
+Fixes two issues when multiple instrumentors coexist:
+
+1. LangChain + OpenAI: OpenAI instrumentor's ChatCompletion span should be a
+   child of LangChain's ChatOpenAI span, but LangChain uses callbacks (not
+   ContextVar) for span management. Fix: patch OpenAI instrumentor to query
+   LangChain's get_current_span() before creating its own span.
+
+2. CrewAI trace isolation: CrewAI's event bus fires events in a background
+   ThreadPoolExecutor thread. That thread has no OTel context from the main
+   asyncio task. Fix: patch CrewAI's EventAssembler to remember the ambient
+   context at construction time and use it as fallback when the background
+   thread's context is empty.
+
+These patches are applied AFTER instrumentors are activated (since we need to
+patch the already-instantiated objects) and are idempotent.
+"""
+from __future__ import annotations
+
+import logging
+from typing import Optional
+
+logger = logging.getLogger(__name__)
+
+
+def apply_context_patches() -> None:
+    """Apply all context propagation patches. Safe to call multiple times."""
+    _patch_openai_langchain_bridge()
+    _patch_crewai_ambient_context()
+
+
+def _patch_openai_langchain_bridge() -> None:
+    """Patch OpenAI instrumentor to use LangChain's active span as parent.
+
+    Without this, ChatCompletion spans from openai instrumentor land under
+    the root span instead of under LangChain's ChatOpenAI span.
+
+    Strategy: wrap _Request.__call__ and _AsyncRequest.__call__ to attach
+    the LangChain parent context before the original method runs (which
+    calls _start_as_current_span internally). This way the tracer.start_span()
+    inside naturally picks up the correct parent from the ambient context.
+    """
+    try:
+        from openinference.instrumentation.openai import _request as openai_req
+    except ImportError:
+        return  # openai instrumentor not installed
+
+    # Check if already patched
+    if getattr(openai_req, "_eo_langchain_bridge_patched", False):
+        return
+
+    try:
+        from opentelemetry import trace as trace_api
+        from opentelemetry import context as context_api
+        from opentelemetry.trace import INVALID_SPAN
+
+        def _get_langchain_parent_context() -> Optional[context_api.Context]:
+            """Query LangChain instrumentor for the current active span."""
+            try:
+                from openinference.instrumentation.langchain import get_current_span
+                parent_span = get_current_span()
+                if parent_span is not None and parent_span is not INVALID_SPAN:
+                    return trace_api.set_span_in_context(parent_span)
+            except ImportError:
+                pass
+            except Exception:
+                pass
+            return None
+
+        # Patch _Request.__call__: attach LangChain context before execution
+        _orig_request_call = openai_req._Request.__call__
+
+        def _patched_request_call(self, wrapped, instance, args, kwargs):
+            parent_ctx = _get_langchain_parent_context()
+            if parent_ctx is None:
+                return _orig_request_call(self, wrapped, instance, args, kwargs)
+            # Attach LangChain's span as ambient context so start_span picks it up
+            token = context_api.attach(parent_ctx)
+            try:
+                return _orig_request_call(self, wrapped, instance, args, kwargs)
+            finally:
+                context_api.detach(token)
+
+        # Patch _AsyncRequest.__call__
+        _orig_async_request_call = openai_req._AsyncRequest.__call__
+
+        async def _patched_async_request_call(self, wrapped, instance, args, kwargs):
+            parent_ctx = _get_langchain_parent_context()
+            if parent_ctx is None:
+                return await _orig_async_request_call(self, wrapped, instance, args, kwargs)
+            token = context_api.attach(parent_ctx)
+            try:
+                return await _orig_async_request_call(self, wrapped, instance, args, kwargs)
+            finally:
+                context_api.detach(token)
+
+        openai_req._Request.__call__ = _patched_request_call
+        openai_req._AsyncRequest.__call__ = _patched_async_request_call
+        openai_req._eo_langchain_bridge_patched = True
+        logger.debug("[observability] patched openai instrumentor with langchain bridge")
+    except Exception as e:
+        logger.debug(f"[observability] langchain bridge patch failed: {e}")
+
+
+def _patch_crewai_ambient_context() -> None:
+    """Patch CrewAI's kickoff wrapper to inherit the request's OTel context.
+
+    Problem: CrewAI's crew.kickoff() runs in run_in_executor (thread pool).
+    Python's run_in_executor does NOT propagate OTel context to worker threads.
+    So the CrewAI instrumentor's wrapper calls start_as_current_span() but
+    gets an empty context — creating a new trace instead of joining the request's.
+
+    Fix: patch _CrewKickoffWrapper.__call__ to attach our stored request
+    context before the original logic runs.
+    """
+    try:
+        from openinference.instrumentation.crewai import _wrappers as wrappers_mod
+    except ImportError:
+        return  # crewai instrumentor not installed
+
+    if getattr(wrappers_mod, "_eo_ambient_context_patched", False):
+        return
+
+    try:
+        from opentelemetry import context as context_api
+
+        _CrewKickoffWrapper = getattr(wrappers_mod, "_CrewKickoffWrapper", None)
+        if _CrewKickoffWrapper is None:
+            return
+
+        _orig_call = _CrewKickoffWrapper.__call__
+
+        def _patched_kickoff_call(self, wrapped, instance, args, kwargs):
+            from . import context_patches as _cp
+            captured = getattr(_cp, "_crewai_request_context", None)
+            if captured is not None:
+                token = context_api.attach(captured)
+                try:
+                    return _orig_call(self, wrapped, instance, args, kwargs)
+                finally:
+                    context_api.detach(token)
+            return _orig_call(self, wrapped, instance, args, kwargs)
+
+        _CrewKickoffWrapper.__call__ = _patched_kickoff_call
+        wrappers_mod._eo_ambient_context_patched = True
+        logger.debug("[observability] patched crewai kickoff wrapper with ambient context")
+    except Exception as e:
+        logger.debug(f"[observability] crewai ambient context patch failed: {e}")
+
+
+# Module-level variable for adapter to set per-request context.
+# The adapter sets this AFTER attaching the root span context,
+# so CrewAI's background thread can read it.
+_crewai_request_context: Optional["context_api.Context"] = None
+
+
+def set_request_context(ctx) -> None:
+    """Called by adapter after attaching root span context."""
+    global _crewai_request_context
+    _crewai_request_context = ctx
+
+
+def clear_request_context() -> None:
+    """Called by adapter after request completes."""
+    global _crewai_request_context
+    _crewai_request_context = None

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

@@ -0,0 +1,78 @@
+"""Agent context propagator — Python parallel of Node's AgentContextPropagator.
+
+为每个 span 在 onStart 阶段统一注入：
+- ``agent.run_id`` = 该 span 所属 trace 的 ``traceId``（与 traceId 对齐，
+  上报到 APM / langfuse 后体现为 ``langfuse.agent.run_id == traceId``）。
+- ``agent.conversation_id`` = adapter 通过 ``set_agent_conversation_id`` 设置的会话 ID。
+
+注意：业务层 ``ctx.run_id`` 仍由 runtime.py 用 ``uuid4()`` 生成，不受影响；
+本 propagator 只影响上报到 OTel exporter 的 attribute。
+"""
+from __future__ import annotations
+
+from contextvars import ContextVar
+from typing import Optional
+
+from opentelemetry.context import Context
+from opentelemetry.sdk.trace import ReadableSpan, Span
+from opentelemetry.sdk.trace.export import SpanProcessor
+
+
+# 由 adapter 在 attach 完 root span context 之后立刻 set，handler 完成后 reset。
+# 用 ContextVar 而不是模块全局，自然适配 asyncio 的 Task 隔离。
+_conversation_id_var: ContextVar[Optional[str]] = ContextVar(
+    "_eo_agent_conversation_id", default=None
+)
+
+
+def set_agent_conversation_id(conversation_id: Optional[str]):
+    """Adapter 调用：设置当前请求的 conversation_id，返回 token 供 reset 用。
+
+    Returns:
+        ContextVar token; 调用方应在请求结束时执行
+        ``_conversation_id_var.reset(token)``。也可直接调用
+        :func:`reset_agent_conversation_id` 传入该 token。
+    """
+    return _conversation_id_var.set(conversation_id)
+
+
+def reset_agent_conversation_id(token) -> None:
+    try:
+        _conversation_id_var.reset(token)
+    except Exception:
+        # token 失效或跨 context 复位等异常一律忽略，best-effort 清理。
+        pass
+
+
+class AgentContextPropagator(SpanProcessor):
+    """SpanProcessor that injects ``agent.run_id`` (= traceId) and
+    ``agent.conversation_id`` into every span on start.
+    """
+
+    def on_start(
+        self, span: Span, parent_context: Optional[Context] = None
+    ) -> None:  # noqa: D401
+        try:
+            ctx = span.get_span_context()
+            # 16-byte trace id → 32 char hex，对齐 OTel/langfuse 显示格式。
+            trace_id_hex = format(ctx.trace_id, "032x")
+            if trace_id_hex and trace_id_hex != "0" * 32:
+                span.set_attribute("agent.run_id", trace_id_hex)
+        except Exception:
+            pass
+
+        conv_id = _conversation_id_var.get()
+        if conv_id:
+            try:
+                span.set_attribute("agent.conversation_id", conv_id)
+            except Exception:
+                pass
+
+    def on_end(self, span: ReadableSpan) -> None:  # noqa: D401
+        return None
+
+    def shutdown(self) -> None:  # noqa: D401
+        return None
+
+    def force_flush(self, timeout_millis: int = 30000) -> bool:  # noqa: D401
+        return True

package/edgeone-dist/pages/observability-python/registry.json

@@ -0,0 +1,95 @@
+[
+  {
+    "name": "langchain",
+    "importPatterns": ["langchain", "langgraph", "langchain_openai", "langchain_core"],
+    "pipPackages": ["openinference-instrumentation-langchain>=0.1.30"]
+  },
+  {
+    "name": "crewai",
+    "importPatterns": ["crewai"],
+    "pipPackages": [
+      "openinference-instrumentation-crewai>=0.1.8",
+      "openinference-instrumentation-litellm>=0.1"
+    ]
+  },
+  {
+    "name": "llama-index",
+    "importPatterns": ["llama_index"],
+    "pipPackages": ["openinference-instrumentation-llama-index>=4.0"]
+  },
+  {
+    "name": "openai",
+    "importPatterns": ["openai"],
+    "pipPackages": ["openinference-instrumentation-openai>=0.1.15"]
+  },
+  {
+    "name": "openai-agents",
+    "importPatterns": ["agents"],
+    "pipPackages": ["openinference-instrumentation-openai-agents>=1.5.0"]
+  },
+  {
+    "name": "anthropic",
+    "importPatterns": ["anthropic"],
+    "pipPackages": ["openinference-instrumentation-anthropic>=1.0.5"]
+  },
+  {
+    "name": "beeai",
+    "importPatterns": ["beeai_framework", "beeai"],
+    "pipPackages": ["openinference-instrumentation-beeai>=0.1.19"]
+  },
+  {
+    "name": "agno",
+    "importPatterns": ["agno"],
+    "pipPackages": ["openinference-instrumentation-agno>=0.1.34"]
+  },
+  {
+    "name": "autogen-agentchat",
+    "importPatterns": ["autogen_agentchat"],
+    "pipPackages": ["openinference-instrumentation-autogen-agentchat>=0.1.9"]
+  },
+  {
+    "name": "autogen",
+    "importPatterns": ["autogen"],
+    "pipPackages": ["openinference-instrumentation-autogen>=0.1.14"]
+  },
+  {
+    "name": "bedrock",
+    "importPatterns": ["boto3", "botocore"],
+    "pipPackages": ["openinference-instrumentation-bedrock>=0.1.39"]
+  },
+  {
+    "name": "claude-agent-sdk",
+    "importPatterns": ["claude_agent_sdk"],
+    "pipPackages": ["openinference-instrumentation-claude-agent-sdk>=0.1.4"]
+  },
+  {
+    "name": "dspy",
+    "importPatterns": ["dspy"],
+    "pipPackages": ["openinference-instrumentation-dspy>=0.1.37"]
+  },
+  {
+    "name": "google-adk",
+    "importPatterns": ["google.adk", "google_adk"],
+    "pipPackages": ["openinference-instrumentation-google-adk>=0.1.14"]
+  },
+  {
+    "name": "google-genai",
+    "importPatterns": ["google.generativeai", "google_generativeai", "google.genai"],
+    "pipPackages": ["openinference-instrumentation-google-genai>=1.0.2"]
+  },
+  {
+    "name": "groq",
+    "importPatterns": ["groq"],
+    "pipPackages": ["openinference-instrumentation-groq>=0.1.16"]
+  },
+  {
+    "name": "guardrails",
+    "importPatterns": ["guardrails"],
+    "pipPackages": ["openinference-instrumentation-guardrails>=0.1.14"]
+  },
+  {
+    "name": "mistralai",
+    "importPatterns": ["mistralai"],
+    "pipPackages": ["openinference-instrumentation-mistralai>=2.0.4"]
+  }
+]

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

@@ -0,0 +1,141 @@
+"""Framework → OpenInference instrumentor mapping."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Callable
+
+
+@dataclass(frozen=True)
+class Entry:
+    name: str
+    instrumentor_factories: tuple[Callable[[], object], ...]
+
+
+def _langchain_instrumentor() -> object:
+    from openinference.instrumentation.langchain import LangChainInstrumentor
+    instrumentor = LangChainInstrumentor()
+    # Patch missing callback methods that newer LangChain versions call.
+    # openinference-instrumentation-langchain may not have implemented these yet.
+    _tracer_cls = None
+    try:
+        from openinference.instrumentation.langchain._tracer import OpenInferenceTracer
+        _tracer_cls = OpenInferenceTracer
+    except ImportError:
+        pass
+    if _tracer_cls is not None:
+        for method in ("on_resume", "on_interrupt"):
+            if not hasattr(_tracer_cls, method):
+                setattr(_tracer_cls, method, lambda self, *a, **kw: None)
+    return instrumentor
+
+
+def _crewai_instrumentor() -> object:
+    from openinference.instrumentation.crewai import CrewAIInstrumentor
+    return CrewAIInstrumentor()
+
+
+def _litellm_instrumentor() -> object:
+    from openinference.instrumentation.litellm import LiteLLMInstrumentor
+    return LiteLLMInstrumentor()
+
+
+def _llama_index_instrumentor() -> object:
+    from openinference.instrumentation.llama_index import LlamaIndexInstrumentor
+    return LlamaIndexInstrumentor()
+
+
+def _openai_instrumentor() -> object:
+    from openinference.instrumentation.openai import OpenAIInstrumentor
+    return OpenAIInstrumentor()
+
+
+def _openai_agents_instrumentor() -> object:
+    from openinference.instrumentation.openai_agents import OpenAIAgentsInstrumentor
+    return OpenAIAgentsInstrumentor()
+
+
+def _anthropic_instrumentor() -> object:
+    from openinference.instrumentation.anthropic import AnthropicInstrumentor
+    return AnthropicInstrumentor()
+
+
+def _beeai_instrumentor() -> object:
+    from openinference.instrumentation.beeai import BeeAIInstrumentor
+    return BeeAIInstrumentor()
+
+
+def _agno_instrumentor() -> object:
+    from openinference.instrumentation.agno import AgnoInstrumentor
+    return AgnoInstrumentor()
+
+
+def _autogen_agentchat_instrumentor() -> object:
+    from openinference.instrumentation.autogen_agentchat import AutoGenAgentChatInstrumentor
+    return AutoGenAgentChatInstrumentor()
+
+
+def _autogen_instrumentor() -> object:
+    from openinference.instrumentation.autogen import AutoGenInstrumentor
+    return AutoGenInstrumentor()
+
+
+def _bedrock_instrumentor() -> object:
+    from openinference.instrumentation.bedrock import BedrockInstrumentor
+    return BedrockInstrumentor()
+
+
+def _claude_agent_sdk_instrumentor() -> object:
+    from openinference.instrumentation.claude_agent_sdk import ClaudeAgentSDKInstrumentor
+    return ClaudeAgentSDKInstrumentor()
+
+
+def _dspy_instrumentor() -> object:
+    from openinference.instrumentation.dspy import DSPyInstrumentor
+    return DSPyInstrumentor()
+
+
+def _google_adk_instrumentor() -> object:
+    from openinference.instrumentation.google_adk import GoogleADKInstrumentor
+    return GoogleADKInstrumentor()
+
+
+def _google_genai_instrumentor() -> object:
+    from openinference.instrumentation.google_genai import GoogleGenAIInstrumentor
+    return GoogleGenAIInstrumentor()
+
+
+def _groq_instrumentor() -> object:
+    from openinference.instrumentation.groq import GroqInstrumentor
+    return GroqInstrumentor()
+
+
+def _guardrails_instrumentor() -> object:
+    from openinference.instrumentation.guardrails import GuardrailsInstrumentor
+    return GuardrailsInstrumentor()
+
+
+def _mistralai_instrumentor() -> object:
+    from openinference.instrumentation.mistralai import MistralAIInstrumentor
+    return MistralAIInstrumentor()
+
+
+REGISTRY: tuple[Entry, ...] = (
+    Entry(name="langchain", instrumentor_factories=(_langchain_instrumentor,)),
+    Entry(name="crewai", instrumentor_factories=(_crewai_instrumentor, _litellm_instrumentor)),
+    Entry(name="llama-index", instrumentor_factories=(_llama_index_instrumentor,)),
+    Entry(name="openai", instrumentor_factories=(_openai_instrumentor,)),
+    Entry(name="openai-agents", instrumentor_factories=(_openai_agents_instrumentor,)),
+    Entry(name="anthropic", instrumentor_factories=(_anthropic_instrumentor,)),
+    Entry(name="beeai", instrumentor_factories=(_beeai_instrumentor,)),
+    Entry(name="agno", instrumentor_factories=(_agno_instrumentor,)),
+    Entry(name="autogen-agentchat", instrumentor_factories=(_autogen_agentchat_instrumentor,)),
+    Entry(name="autogen", instrumentor_factories=(_autogen_instrumentor,)),
+    Entry(name="bedrock", instrumentor_factories=(_bedrock_instrumentor,)),
+    Entry(name="claude-agent-sdk", instrumentor_factories=(_claude_agent_sdk_instrumentor,)),
+    Entry(name="dspy", instrumentor_factories=(_dspy_instrumentor,)),
+    Entry(name="google-adk", instrumentor_factories=(_google_adk_instrumentor,)),
+    Entry(name="google-genai", instrumentor_factories=(_google_genai_instrumentor,)),
+    Entry(name="groq", instrumentor_factories=(_groq_instrumentor,)),
+    Entry(name="guardrails", instrumentor_factories=(_guardrails_instrumentor,)),
+    Entry(name="mistralai", instrumentor_factories=(_mistralai_instrumentor,)),
+)

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

@@ -0,0 +1,214 @@
+"""Telemetry initialization — TracerProvider + APM exporter setup."""
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from typing import Any, Optional
+
+from opentelemetry import trace as otel_trace
+from opentelemetry.context import Context, get_current
+from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
+from opentelemetry.sdk.resources import Resource
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import BatchSpanProcessor
+from opentelemetry.trace import Span, Tracer, set_span_in_context
+
+from .apm.config import resolve_apm_endpoint, resolve_service_name
+from .apm.metrics_bridge import ApmMetricsBridge
+from .apm.span_exporter import ApmSpanExporter, TranslatorContext
+from ._compat import apply_compat_patches
+from .context_propagator import AgentContextPropagator
+
+
+@dataclass
+class Telemetry:
+    tracer_provider: TracerProvider
+    tracer: Tracer
+    metrics_bridge: ApmMetricsBridge
+    _root_span_ids: set = field(default_factory=set)
+    _root_spans_with_children: set = field(default_factory=set)
+
+    def start_request_span(
+        self, name: str, attributes: dict[str, Any] | None = None
+    ) -> tuple[Span, Context]:
+        span = self.tracer.start_span(name, attributes=attributes or {})
+        self._root_span_ids.add(format(span.get_span_context().span_id, "016x"))
+        ctx = set_span_in_context(span, get_current())
+        return span, ctx
+
+    def end_request_span(self, span: Span) -> None:
+        span_id = format(span.get_span_context().span_id, "016x")
+        span.end()
+        # Flush pending spans BEFORE removing the root span ID.
+        # BatchSpanProcessor exports asynchronously — child spans queued
+        # earlier need the root ID still present when _is_trace_entry runs
+        # inside the ApmSpanExporter so they get gen_ai.is_entry=true.
+        try:
+            self.tracer_provider.force_flush(timeout_millis=5000)
+        except Exception:
+            pass
+        self._root_span_ids.discard(span_id)
+        self._root_spans_with_children.discard(span_id)
+
+    def shutdown(self) -> None:
+        self._root_span_ids.clear()
+        self._root_spans_with_children.clear()
+        try:
+            self.metrics_bridge.shutdown()
+        except Exception:
+            pass
+        try:
+            self.tracer_provider.shutdown()
+        except Exception:
+            pass
+
+
+_telemetry: Telemetry | None = None
+
+
+def setup_telemetry(
+    *,
+    tracer_provider: TracerProvider | None = None,
+    endpoint: str | None = None,
+    service_name: str | None = None,
+    apm_token: str | None = None,
+) -> Telemetry:
+    """Initialize telemetry. Called once at process startup.
+
+    Args:
+        tracer_provider: Override for testing (InMemoryExporter).
+                         If None, creates production provider with APM exporter.
+    """
+    global _telemetry
+    if _telemetry is not None:
+        return _telemetry
+
+    apply_compat_patches()
+
+    endpoint = endpoint or os.environ.get("OTEL_EXPORTER_OTLP_ENDPOINT") or resolve_apm_endpoint()
+    service_name = service_name or resolve_service_name()
+    environment = os.environ.get("NODE_ENV") or "development"
+    apm_token = apm_token or os.environ.get("SVC_TRACE_KEY_LB6V03", "")
+
+    # Dev dual-export: optionally send to remote APM alongside local Studio.
+    dev_apm_token = os.environ.get("EDGEONE_DEV_APM_TOKEN", "")
+    dev_apm_endpoint = os.environ.get("EDGEONE_DEV_APM_ENDPOINT") or resolve_apm_endpoint()
+
+    # 使用 Resource.create() 以保留 SDK 默认属性（telemetry.sdk.language 等），
+    # 否则 inferRuntime() 无法识别 Python runtime，会误判为 agent-node。
+    # Resource.create() 会自动合并 OTEL_RESOURCE_ATTRIBUTES 和 SDK 默认属性。
+    resource = Resource.create({
+        "service.name": service_name,
+        "deployment.environment": environment,
+        "token": dev_apm_token or apm_token,
+    })
+
+    root_span_ids: set[str] = set()
+    root_spans_with_children: set[str] = set()
+
+    if tracer_provider is None:
+        translator_ctx = TranslatorContext(
+            is_root_span_id=lambda sid: sid in root_span_ids,
+            root_span_has_children=lambda sid: sid in root_spans_with_children,
+        )
+        raw_exporter = OTLPSpanExporter(endpoint=f"{endpoint.rstrip('/')}/v1/traces")
+        wrapped_exporter = ApmSpanExporter(raw_exporter, translator_ctx)
+
+        tracer_provider = TracerProvider(resource=resource)
+        tracer_provider.add_span_processor(BatchSpanProcessor(wrapped_exporter))
+
+        # Dev APM dual-export processor (if EDGEONE_DEV_APM_TOKEN is set)
+        if dev_apm_token:
+            dev_apm_raw = OTLPSpanExporter(endpoint=f"{dev_apm_endpoint.rstrip('/')}/v1/traces")
+            dev_apm_wrapped = ApmSpanExporter(dev_apm_raw, translator_ctx)
+            tracer_provider.add_span_processor(BatchSpanProcessor(dev_apm_wrapped))
+            print(f"[observability] APM dual-export enabled → {dev_apm_endpoint}")
+
+        metrics_bridge = ApmMetricsBridge(
+            endpoint=dev_apm_endpoint if dev_apm_token else endpoint,
+            apm_token=dev_apm_token or apm_token,
+            resource=resource,
+        )
+        tracer_provider.add_span_processor(metrics_bridge.span_processor)
+
+        # Inject agent.run_id (= traceId) and agent.conversation_id into every span.
+        # Mirrors Node's AgentContextPropagator so langfuse.agent.run_id aligns with traceId.
+        tracer_provider.add_span_processor(AgentContextPropagator())
+
+        # Track which root spans have children (for gen_ai.is_entry on root span)
+        tracer_provider.add_span_processor(
+            _RootChildrenTracker(root_span_ids, root_spans_with_children)
+        )
+
+        otel_trace.set_tracer_provider(tracer_provider)
+    else:
+        # Test mode — no APM exporter, no metrics bridge, don't touch global state
+        metrics_bridge = _NoOpMetricsBridge()
+        # 测试模式下也注册 propagator，让 InMemoryExporter 能验证注入行为。
+        try:
+            tracer_provider.add_span_processor(AgentContextPropagator())
+        except Exception:
+            # 某些测试 provider 可能不支持重复添加，忽略即可。
+            pass
+
+    tracer = tracer_provider.get_tracer("edgeone-agent-observability", "0.1.0")
+
+    _telemetry = Telemetry(
+        tracer_provider=tracer_provider,
+        tracer=tracer,
+        metrics_bridge=metrics_bridge,
+        _root_span_ids=root_span_ids,
+        _root_spans_with_children=root_spans_with_children,
+    )
+    return _telemetry
+
+
+def get_telemetry() -> Telemetry | None:
+    return _telemetry
+
+
+def reset_telemetry() -> None:
+    """Reset global state. For testing only."""
+    global _telemetry
+    _telemetry = None
+
+
+class _NoOpMetricsBridge:
+    """Stub for test mode."""
+    @property
+    def span_processor(self):
+        return None
+
+    def shutdown(self) -> None:
+        pass
+
+
+class _RootChildrenTracker:
+    """SpanProcessor that marks root spans as having children when a child starts."""
+
+    def __init__(self, root_span_ids: set[str], root_spans_with_children: set[str]) -> None:
+        self._root_span_ids = root_span_ids
+        self._root_spans_with_children = root_spans_with_children
+
+    def on_start(self, span: Span, parent_context: Optional[Context] = None) -> None:
+        parent = span.parent if hasattr(span, "parent") else None
+        if parent is None:
+            return
+        try:
+            parent_id = format(parent.span_id, "016x")
+        except (AttributeError, TypeError):
+            return
+        if parent_id in self._root_span_ids:
+            self._root_spans_with_children.add(parent_id)
+
+    def _on_ending(self, span) -> None:
+        pass
+
+    def on_end(self, span) -> None:
+        pass
+
+    def shutdown(self) -> None:
+        pass
+
+    def force_flush(self, timeout_millis: int = 30000) -> bool:
+        return True