agentengine-sdk-python 0.8.0__py3-none-any.whl → 0.8.2__py3-none-any.whl

ksadk/tracing/setup.py

@@ -1,11 +1,15 @@
 """
-Tracing 初始化 - 支持多 Exporter (InMemory + Langfuse + OTLP)
+Tracing 初始化 - 标准 OTLP 双写（Langfuse 主 + CloudMonitor 次）
+
+每个 Python Agent 进程一个 TracerProvider，挂两个 OTLP/HTTP protobuf BatchSpanProcessor，
+消费同一批 ReadableSpan。仅为 CloudMonitor 克隆并补充兼容属性，不修改原始 span。
+
 支持 ADK 自动插桩 via openinference-instrumentation-google-adk
 """
 
 import atexit
-import base64
 import importlib
+import json
 import logging
 import os
 from collections.abc import Callable, Sequence
@@ -13,6 +17,7 @@ from dataclasses import dataclass
 from typing import Any, Optional
 from urllib.parse import unquote
 
+from opentelemetry.sdk.resources import Resource
 from opentelemetry.sdk.trace import ReadableSpan
 from opentelemetry.sdk.trace.export import SpanExporter, SpanExportResult
 
@@ -20,6 +25,25 @@ from ksadk.tracing.exporters.inmemory_exporter import InMemoryExporter
 
 logger = logging.getLogger(__name__)
 
+_CLOUD_MONITOR_RESOURCE_SPAN_ATTRIBUTES = (
+    "agentengine.account_id",
+    "agentengine.agent_id",
+    "agentengine.framework",
+    "agentengine.langfuse_project_id",
+    "agentengine.region",
+)
+
+_LANGFUSE_OBSERVATION_TYPES = {
+    "LLM": "generation",
+    "EMBEDDING": "embedding",
+    "CHAIN": "chain",
+    "AGENT": "agent",
+    "TOOL": "tool",
+    "RETRIEVER": "retriever",
+    "EVALUATOR": "evaluator",
+    "GUARDRAIL": "guardrail",
+}
+
 
 def _batch_span_processor_kwargs() -> dict:
     """BatchSpanProcessor 参数：限制单次 export 体积，避免 OTLP collector 413。
@@ -41,9 +65,9 @@ def _batch_span_processor_kwargs() -> dict:
 
 
 _exporter_instance: Optional[InMemoryExporter] = None
-_langfuse_exporter: Optional[Any] = None
 _tracing_initialized: bool = False
 _adk_instrumented: bool = False
+_managed_span_processors: list[Any] = []
 
 
 @dataclass(frozen=True)
@@ -55,7 +79,7 @@ class _OtlpHttpConfig:
 
 
 class _LoggingSpanExporter(SpanExporter):
-    """Small delegating exporter that logs external trace export flow."""
+    """Delegating exporter that logs external trace export flow."""
 
     def __init__(
         self,
@@ -137,12 +161,7 @@ def _span_context(span: Any) -> Any:
     if context is not None:
         return context
     get_context = getattr(span, "get_span_context", None)
-    if callable(get_context):
-        try:
-            return get_context()
-        except Exception:
-            return None
-    return None
+    return get_context() if callable(get_context) else None
 
 
 def _span_id(span: Any) -> Optional[int]:
@@ -159,230 +178,244 @@ def _parent_span_id(span: Any) -> Optional[int]:
 
 def _span_token_usage(span: Any) -> dict[str, int]:
     attributes = getattr(span, "attributes", None) or {}
+    return _token_usage(attributes)
+
+
+def _token_usage(attributes: dict[str, Any]) -> dict[str, int]:
+    input_tokens = _coerce_int(
+        attributes.get("gen_ai.usage.input_tokens")
+        or attributes.get("llm.usage.prompt_tokens")
+        or attributes.get("llm.token_count.prompt")
+    )
+    output_tokens = _coerce_int(
+        attributes.get("gen_ai.usage.output_tokens")
+        or attributes.get("llm.usage.completion_tokens")
+        or attributes.get("llm.token_count.completion")
+    )
+    total_tokens = _coerce_int(
+        attributes.get("gen_ai.usage.total_tokens")
+        or attributes.get("llm.usage.total_tokens")
+        or attributes.get("llm.token_count.total")
+    )
     return {
-        "input": _coerce_int(attributes.get("gen_ai.usage.input_tokens")),
-        "output": _coerce_int(attributes.get("gen_ai.usage.output_tokens")),
-        "cache_read": _coerce_int(attributes.get("gen_ai.usage.cache_read.input_tokens")),
-        "reasoning_output": _coerce_int(attributes.get("gen_ai.usage.reasoning.output_tokens")),
+        "input": input_tokens,
+        "output": output_tokens,
+        "total": total_tokens or input_tokens + output_tokens,
+        "cache_read": _coerce_int(
+            attributes.get("gen_ai.usage.cache_read.input_tokens")
+            or attributes.get("llm.usage.cache_read.input_tokens")
+        ),
+        "reasoning_output": _coerce_int(
+            attributes.get("gen_ai.usage.reasoning.output_tokens")
+            or attributes.get("llm.usage.reasoning_tokens")
+        ),
     }
 
 
-def _has_nonzero_token_usage(usage: dict[str, int]) -> bool:
-    return any(value > 0 for value in usage.values())
+def _first_span_attribute(attributes: dict[str, Any], *keys: str) -> Any:
+    for key in keys:
+        value = attributes.get(key)
+        if value not in (None, ""):
+            return value
+    return None
 
 
-def _instrumentation_scope_name(span: Any) -> str:
-    scope = getattr(span, "instrumentation_scope", None)
-    name = getattr(scope, "name", None)
-    if name:
-        return str(name)
-    info = getattr(span, "instrumentation_info", None)
-    name = getattr(info, "name", None)
-    return str(name or "")
+def _add_langfuse_compatibility_attributes(attributes: dict[str, Any]) -> None:
+    usage = _token_usage(attributes)
+    observation_kind = str(attributes.get("openinference.span.kind") or "").upper()
+    observation_type = _LANGFUSE_OBSERVATION_TYPES.get(observation_kind)
+    if observation_type is None:
+        observation_type = "generation" if _has_nonzero_token_usage(usage) else "span"
+    attributes.setdefault("langfuse.observation.type", observation_type)
 
+    provider = _first_span_attribute(
+        attributes,
+        "gen_ai.provider.name",
+        "gen_ai.system",
+        "llm.provider",
+    )
+    if provider is not None:
+        attributes.setdefault("langfuse.observation.metadata.ls_provider", provider)
 
-def _clone_span_with_attributes(span: Any, attributes: dict[str, Any]) -> Any:
-    try:
-        from opentelemetry.sdk.trace import ReadableSpan
-
-        return ReadableSpan(
-            name=span.name,
-            context=span.context,
-            parent=span.parent,
-            resource=span.resource,
-            attributes=attributes,
-            events=span.events,
-            links=span.links,
-            kind=span.kind,
-            instrumentation_info=getattr(span, "instrumentation_info", None),
-            status=span.status,
-            start_time=span.start_time,
-            end_time=span.end_time,
-            instrumentation_scope=getattr(span, "instrumentation_scope", None),
+    model = _first_span_attribute(
+        attributes,
+        "gen_ai.request.model",
+        "llm.model_name",
+    )
+    if model is not None:
+        attributes.setdefault("langfuse.observation.model.name", model)
+        attributes.setdefault("langfuse.observation.metadata.ls_model_name", model)
+
+    if _has_nonzero_token_usage(usage):
+        attributes.setdefault("gen_ai.usage.total_tokens", usage["total"])
+        usage_details = {
+            "input": usage["input"],
+            "output": usage["output"],
+            "total": usage["total"],
+            "input_cache_read": usage["cache_read"],
+        }
+        attributes["langfuse.observation.usage_details"] = json.dumps(
+            usage_details, separators=(",", ":"), sort_keys=True
         )
-    except Exception:
-        logger.debug("Failed to clone span for CloudMonitor token compatibility", exc_info=True)
-        return span
 
 
-def _prepare_langfuse_spans(spans: Any) -> Any:
-    """Keep ksadk response usage authoritative for Langfuse exports.
-
-    OpenInference LangChain instrumentation can emit llm.token_count.* on nested
-    ChatOpenAI spans. In LangGraph streaming these counts can be cumulative and
-    disagree with the usage returned by ksadk to RunAgent/session state. When a
-    trace already has a ksadk.conversations span with gen_ai.usage.*, strip token
-    attrs from nested OpenInference LangChain spans before exporting to
-    Langfuse. The child spans remain useful for timing and structure, but cannot
-    pollute token accounting.
-    """
-    if not spans:
-        return spans
-    span_list = list(spans)
-    authoritative_trace_ids = {
-        _trace_id(span)
-        for span in span_list
-        if _trace_id(span) is not None
-        and _instrumentation_scope_name(span) == "ksadk.conversations"
-        and _has_nonzero_token_usage(_span_token_usage(span))
-    }
-    if not authoritative_trace_ids:
-        return spans
-
-    strip_prefixes = ("llm.token_count.", "llm.usage.", "gen_ai.usage.")
-    replacements: dict[int, Any] = {}
-    for span in span_list:
-        if _trace_id(span) not in authoritative_trace_ids:
-            continue
-        if _instrumentation_scope_name(span) != "openinference.instrumentation.langchain":
-            continue
-        attributes = dict(getattr(span, "attributes", None) or {})
-        stripped = {
-            key: value
-            for key, value in attributes.items()
-            if not any(str(key).startswith(prefix) for prefix in strip_prefixes)
-        }
-        if len(stripped) != len(attributes):
-            if str(stripped.get("openinference.span.kind") or "").upper() == "LLM":
-                stripped["openinference.span.kind"] = "CHAIN"
-            replacements[id(span)] = _clone_span_with_attributes(span, stripped)
+def _has_nonzero_token_usage(usage: dict[str, int]) -> bool:
+    return any(value > 0 for value in usage.values())
 
-    if not replacements:
-        return spans
-    return [replacements.get(id(span), span) for span in span_list]
 
+def _clone_cloud_monitor_resource(resource: Resource | None) -> Resource | None:
+    if resource is None:
+        return None
+    attributes = dict(resource.attributes)
+    agent_id = str(attributes.get("agentengine.agent_id") or "").strip()
+    if not agent_id or attributes.get("service.name") == agent_id:
+        return resource
+    attributes["service.name"] = agent_id
+    return Resource(attributes, schema_url=resource.schema_url)
+
+
+def _clone_span(
+    span: ReadableSpan,
+    *,
+    attributes: dict[str, Any],
+    resource: Resource | None,
+) -> ReadableSpan:
+    return ReadableSpan(
+        name=span.name,
+        context=span.context,
+        parent=span.parent,
+        resource=resource,
+        attributes=attributes,
+        events=span.events,
+        links=span.links,
+        kind=span.kind,
+        status=span.status,
+        start_time=span.start_time,
+        end_time=span.end_time,
+        instrumentation_scope=getattr(span, "instrumentation_scope", None),
+    )
 
-def _prepare_cloud_monitor_spans(spans: Any) -> Any:
-    """Add root token rollups for CloudMonitor without changing other exporters.
 
-    CloudMonitor already parses gen_ai.usage.* on LLM child spans, but its root-span
-    and overview APIs currently use root-level token fields. ADK/OpenInference often
-    emits token usage on nested LLM spans only, and sometimes duplicates the same LLM
-    usage on a parent and a child span. To avoid double counting, aggregate only
-    token-bearing leaf spans and copy the result to the root span for this exporter.
-    """
+def _prepare_cloud_monitor_spans(
+    spans: Sequence[ReadableSpan],
+) -> Sequence[ReadableSpan]:
+    """Clone CloudMonitor spans with resource identity and root usage compatibility."""
     if not spans:
         return spans
     span_list = list(spans)
-    span_ids = {_span_id(span) for span in span_list if _span_id(span) is not None}
-    if not span_ids:
-        return spans
-
-    children_by_parent: dict[tuple[Optional[int], int], list[Any]] = {}
-    roots: list[Any] = []
+    session_ids_by_trace: dict[Optional[int], Any] = {}
+    for span in span_list:
+        attributes = dict(getattr(span, "attributes", None) or {})
+        session_id = _first_span_attribute(
+            attributes,
+            "session.id",
+            "langfuse.session.id",
+            "ksadk.session_id",
+        )
+        if session_id is not None:
+            session_ids_by_trace.setdefault(_trace_id(span), session_id)
+    span_keys = {
+        (_trace_id(span), _span_id(span)) for span in span_list if _span_id(span) is not None
+    }
+    children_by_parent: dict[tuple[Optional[int], int], list[ReadableSpan]] = {}
+    roots: list[ReadableSpan] = []
     for span in span_list:
-        sid = _span_id(span)
-        if sid is None:
+        span_id = _span_id(span)
+        if span_id is None:
             continue
-        parent_id = _parent_span_id(span)
         trace_id = _trace_id(span)
-        if parent_id is None or parent_id not in span_ids:
+        parent_id = _parent_span_id(span)
+        if parent_id is None or (trace_id, parent_id) not in span_keys:
             roots.append(span)
         else:
             children_by_parent.setdefault((trace_id, parent_id), []).append(span)
 
-    token_usage_by_id = {
+    usage_by_span = {
         (_trace_id(span), _span_id(span)): _span_token_usage(span)
         for span in span_list
         if _span_id(span) is not None
     }
-
     has_token_descendant_cache: dict[tuple[Optional[int], int], bool] = {}
 
-    def has_token_descendant(span: Any) -> bool:
-        sid = _span_id(span)
-        if sid is None:
+    def has_token_descendant(span: ReadableSpan) -> bool:
+        key = (_trace_id(span), _span_id(span))
+        if key[1] is None:
             return False
-        key = (_trace_id(span), sid)
         if key in has_token_descendant_cache:
             return has_token_descendant_cache[key]
-        for child in children_by_parent.get(key, []):
-            child_sid = _span_id(child)
-            if child_sid is None:
-                continue
-            child_key = (_trace_id(child), child_sid)
-            if _has_nonzero_token_usage(token_usage_by_id.get(child_key, {})):
-                has_token_descendant_cache[key] = True
-                return True
-            if has_token_descendant(child):
-                has_token_descendant_cache[key] = True
-                return True
-        has_token_descendant_cache[key] = False
-        return False
-
-    def collect_leaf_usage(span: Any, usage: dict[str, int]) -> None:
-        sid = _span_id(span)
-        if sid is None:
-            return
-        key = (_trace_id(span), sid)
-        own_usage = token_usage_by_id.get(key, {})
+        result = any(
+            _has_nonzero_token_usage(usage_by_span.get((_trace_id(child), _span_id(child)), {}))
+            or has_token_descendant(child)
+            for child in children_by_parent.get(key, [])
+        )
+        has_token_descendant_cache[key] = result
+        return result
+
+    def collect_leaf_usage(span: ReadableSpan, aggregate: dict[str, int]) -> None:
+        key = (_trace_id(span), _span_id(span))
+        own_usage = usage_by_span.get(key, {})
         if _has_nonzero_token_usage(own_usage) and not has_token_descendant(span):
             for usage_key, value in own_usage.items():
-                usage[usage_key] += value
+                aggregate[usage_key] += value
             return
         for child in children_by_parent.get(key, []):
-            collect_leaf_usage(child, usage)
+            collect_leaf_usage(child, aggregate)
 
-    replacements: dict[int, Any] = {}
+    root_usage: dict[int, dict[str, int]] = {}
     for root in roots:
-        aggregate = {"input": 0, "output": 0, "cache_read": 0, "reasoning_output": 0}
-        collect_leaf_usage(root, aggregate)
-        if not _has_nonzero_token_usage(aggregate):
-            continue
-
-        attributes = dict(getattr(root, "attributes", None) or {})
-        updated = False
-        attr_map = {
-            "gen_ai.usage.input_tokens": "input",
-            "gen_ai.usage.output_tokens": "output",
-            "gen_ai.usage.cache_read.input_tokens": "cache_read",
-            "gen_ai.usage.reasoning.output_tokens": "reasoning_output",
+        aggregate = {
+            "input": 0,
+            "output": 0,
+            "total": 0,
+            "cache_read": 0,
+            "reasoning_output": 0,
         }
-        for attr_name, usage_key in attr_map.items():
-            if _coerce_int(attributes.get(attr_name)) <= 0 and aggregate[usage_key] > 0:
-                attributes[attr_name] = aggregate[usage_key]
-                updated = True
-
-        if updated:
-            replacements[id(root)] = _clone_span_with_attributes(root, attributes)
-
-    if not replacements:
-        return spans
-    return [replacements.get(id(span), span) for span in span_list]
-
-
-def _build_langfuse_otlp_config(
-    langfuse_config: dict[str, Any] | None = None,
-) -> dict[str, Any] | None:
-    """Build Langfuse OTLP direct exporter config from explicit config or env."""
-    if langfuse_config:
-        public_key = langfuse_config.get("public_key") or ""
-        secret_key = langfuse_config.get("secret_key") or ""
-        host = langfuse_config.get("host") or "http://localhost:3000"
-    else:
-        public_key = os.getenv("LANGFUSE_PUBLIC_KEY", "")
-        secret_key = os.getenv("LANGFUSE_SECRET_KEY", "")
-        host = (
-            os.getenv("LANGFUSE_BASE_URL") or os.getenv("LANGFUSE_HOST") or "http://localhost:3000"
-        )
-
-    if not public_key or not secret_key:
-        return None
-
-    headers = _build_langfuse_otlp_headers(public_key, secret_key)
-    return {
-        "endpoint": f"{host.rstrip('/')}/api/public/otel/v1/traces",
-        "headers": headers,
-        "protocol": "http/protobuf",
-    }
-
-
-def _build_langfuse_otlp_headers(public_key: str, secret_key: str) -> dict[str, str]:
-    auth = base64.b64encode(f"{public_key}:{secret_key}".encode("utf-8")).decode("ascii")
-    return {
-        "Authorization": f"Basic {auth}",
-        "x-langfuse-ingestion-version": "4",
+        collect_leaf_usage(root, aggregate)
+        root_usage[id(root)] = aggregate
+
+    resource_cache: dict[int, Resource | None] = {}
+    transformed: list[ReadableSpan] = []
+    usage_attributes = {
+        "gen_ai.usage.input_tokens": "input",
+        "gen_ai.usage.output_tokens": "output",
+        "gen_ai.usage.total_tokens": "total",
+        "gen_ai.usage.cache_read.input_tokens": "cache_read",
+        "gen_ai.usage.reasoning.output_tokens": "reasoning_output",
     }
+    for span in span_list:
+        original_resource = getattr(span, "resource", None)
+        original_resource_attributes = getattr(original_resource, "attributes", {}) or {}
+        resource_key = id(original_resource)
+        if resource_key not in resource_cache:
+            resource_cache[resource_key] = _clone_cloud_monitor_resource(original_resource)
+        resource = resource_cache[resource_key]
+        attributes = dict(getattr(span, "attributes", None) or {})
+        resource_attributes = getattr(resource, "attributes", {}) or {}
+        for key in _CLOUD_MONITOR_RESOURCE_SPAN_ATTRIBUTES:
+            value = resource_attributes.get(key)
+            if value not in (None, ""):
+                attributes.setdefault(f"gen_ai.{key}", value)
+        agent_name = original_resource_attributes.get(
+            "agentengine.agent_name"
+        ) or original_resource_attributes.get("service.name")
+        if agent_name not in (None, ""):
+            attributes.setdefault("gen_ai.agentengine.agent_name", agent_name)
+        aggregate = root_usage.get(id(span), {})
+        for attribute, usage_key in usage_attributes.items():
+            if _coerce_int(attributes.get(attribute)) <= 0 and aggregate.get(usage_key, 0) > 0:
+                attributes[attribute] = aggregate[usage_key]
+
+        session_id = session_ids_by_trace.get(_trace_id(span))
+        if session_id is not None:
+            attributes.setdefault("session.id", session_id)
+        _add_langfuse_compatibility_attributes(attributes)
+
+        original_attributes = dict(getattr(span, "attributes", None) or {})
+        if resource is original_resource and attributes == original_attributes:
+            transformed.append(span)
+        else:
+            transformed.append(_clone_span(span, attributes=attributes, resource=resource))
+    return transformed
 
 
 def _parse_otlp_headers(raw: str) -> dict[str, str]:
@@ -408,7 +441,7 @@ def _decode_otlp_header_value(key: str, value: str) -> str:
     for scheme in ("Basic", "Bearer"):
         prefix = f"{scheme}+"
         if decoded.startswith(prefix):
-            return f"{scheme} {decoded[len(prefix):]}"
+            return f"{scheme} {decoded[len(prefix) :]}"
     return decoded
 
 
@@ -420,10 +453,6 @@ def _derive_otlp_traces_endpoint(endpoint: str) -> str:
     return f"{endpoint}/v1/traces"
 
 
-def _env_flag_disabled(value: str) -> bool:
-    return value.strip().lower() in {"0", "false", "no", "off", "disabled"}
-
-
 def _env_flag_enabled(value: str) -> bool:
     return value.strip().lower() in {"1", "true", "yes", "on"}
 
@@ -449,53 +478,48 @@ def _get_service_name() -> str:
 
 
 def _build_cloud_monitor_otlp_http_config() -> Optional[_OtlpHttpConfig]:
-    """Build CloudMonitor OTLP HTTP traces exporter config from CLOUD_MONITOR_* env."""
-    enabled = os.getenv("CLOUD_MONITOR_OTLP_ENABLED", "").strip()
-    if enabled and _env_flag_disabled(enabled):
-        logger.info("CloudMonitor OTLP exporter disabled by CLOUD_MONITOR_OTLP_ENABLED=%s", enabled)
-        return None
-    cloud_monitor_langfuse_configured = all(
-        os.getenv(name, "").strip()
-        for name in (
-            "CLOUD_MONITOR_LANGFUSE_PUBLIC_KEY",
-            "CLOUD_MONITOR_LANGFUSE_SECRET_KEY",
-        )
-    ) and bool(
-        os.getenv("CLOUD_MONITOR_LANGFUSE_HOST", "").strip()
-        or os.getenv("CLOUD_MONITOR_OTLP_ENDPOINT", "").strip()
-    )
-    cloud_monitor_otlp_forced = _env_flag_enabled(enabled)
-    cloud_monitor_callback_requested = _env_flag_enabled(
-        os.getenv("LANGFUSE_USE_CALLBACK", "")
-    ) and not _env_flag_disabled(os.getenv("CLOUD_MONITOR_LANGFUSE_ENABLED", ""))
-    if (
-        cloud_monitor_langfuse_configured
-        and cloud_monitor_callback_requested
-        and not cloud_monitor_otlp_forced
-    ):
-        logger.info(
-            "CloudMonitor OTLP exporter skipped because CloudMonitor Langfuse SDK "
-            "callback is requested"
-        )
-        return None
+    """Build CloudMonitor OTLP HTTP traces exporter config from CLOUD_MONITOR_OTLP_* env.
 
-    app_key = os.getenv("CLOUD_MONITOR_APP_KEY", "").strip()
+    traces 专用 headers 优先于通用 headers。仅当两个 headers 环境变量整体缺失时，
+    才把旧 CLOUD_MONITOR_APP_KEY 按过渡兼容翻译为 Ksc-Appkey header。
+    """
     traces_endpoint = os.getenv("CLOUD_MONITOR_OTLP_TRACES_ENDPOINT", "").strip()
     base_endpoint = os.getenv("CLOUD_MONITOR_OTLP_ENDPOINT", "").strip()
     endpoint = traces_endpoint
     if not endpoint and base_endpoint:
         endpoint = _derive_otlp_traces_endpoint(base_endpoint)
 
-    if not app_key and not endpoint:
-        logger.debug("CloudMonitor OTLP exporter not configured: missing app key and endpoint")
-        return None
-    if not app_key:
-        logger.warning("CloudMonitor OTLP exporter skipped: CLOUD_MONITOR_APP_KEY is missing")
-        return None
+    raw_traces_headers = os.getenv("CLOUD_MONITOR_OTLP_TRACES_HEADERS", "")
+    raw_generic_headers = os.getenv("CLOUD_MONITOR_OTLP_HEADERS", "")
+    raw_headers = raw_traces_headers.strip() or raw_generic_headers
+    headers = _parse_otlp_headers(raw_headers)
+    # One-version compatibility applies only when both header variables are
+    # absent. A present-but-invalid traces or generic header bundle must fail
+    # closed rather than silently mixing it with the legacy AppKey.
+    if not raw_traces_headers.strip() and not raw_generic_headers.strip():
+        app_key = os.getenv("CLOUD_MONITOR_APP_KEY", "").strip()
+        if app_key:
+            if not endpoint:
+                logger.warning(
+                    "CloudMonitor OTLP exporter skipped: CLOUD_MONITOR_APP_KEY fallback "
+                    "requires CLOUD_MONITOR_OTLP_ENDPOINT or CLOUD_MONITOR_OTLP_TRACES_ENDPOINT"
+                )
+                return None
+            headers["Ksc-Appkey"] = app_key
+            logger.info(
+                "CloudMonitor OTLP using deprecated CLOUD_MONITOR_APP_KEY -> Ksc-Appkey fallback; "
+                "server should inject CLOUD_MONITOR_OTLP_TRACES_HEADERS or "
+                "CLOUD_MONITOR_OTLP_HEADERS instead"
+            )
+
     if not endpoint:
+        logger.debug("CloudMonitor OTLP exporter not configured: missing endpoint")
+        return None
+    if not _has_header(headers, "Ksc-Appkey"):
         logger.warning(
-            "CloudMonitor OTLP exporter skipped: CLOUD_MONITOR_OTLP_ENDPOINT or "
-            "CLOUD_MONITOR_OTLP_TRACES_ENDPOINT is missing"
+            "CloudMonitor OTLP exporter skipped: Ksc-Appkey missing in "
+            "CLOUD_MONITOR_OTLP_TRACES_HEADERS/CLOUD_MONITOR_OTLP_HEADERS and no "
+            "CLOUD_MONITOR_APP_KEY fallback"
         )
         return None
 
@@ -511,16 +535,12 @@ def _build_cloud_monitor_otlp_http_config() -> Optional[_OtlpHttpConfig]:
         )
         return None
 
-    headers = _parse_otlp_headers(os.getenv("CLOUD_MONITOR_OTLP_HEADERS", ""))
-    headers["Ksc-Appkey"] = app_key
     service_name = _get_service_name()
     logger.info(
-        "CloudMonitor OTLP config resolved: endpoint=%s protocol=%s service_name=%s "
-        "app_key_present=%s header_keys=%s",
+        "CloudMonitor OTLP config resolved: endpoint=%s protocol=%s service_name=%s header_keys=%s",
         endpoint,
         protocol,
         service_name or "",
-        bool(app_key),
         ",".join(sorted(headers)),
     )
     return _OtlpHttpConfig(
@@ -531,48 +551,12 @@ def _build_cloud_monitor_otlp_http_config() -> Optional[_OtlpHttpConfig]:
     )
 
 
-def _is_langfuse_otlp_endpoint(endpoint: str) -> bool:
-    if not endpoint:
-        return False
-    normalized_endpoint = endpoint.strip().rstrip("/")
-    langfuse_hosts = [
-        os.getenv("LANGFUSE_HOST", "").strip().rstrip("/"),
-        os.getenv("LANGFUSE_BASE_URL", "").strip().rstrip("/"),
-    ]
-    if any(host and normalized_endpoint.startswith(host) for host in langfuse_hosts):
-        return True
-    return "/api/public/otel" in normalized_endpoint
-
-
-def _is_langfuse_callback_endpoint(endpoint: str) -> bool:
-    return _env_flag_enabled(os.getenv("LANGFUSE_USE_CALLBACK", "")) and _is_langfuse_otlp_endpoint(
-        endpoint
-    )
-
-
-def _apply_langfuse_auth_fallback(endpoint: str, headers: dict[str, str]) -> bool:
-    """Add Langfuse OTLP auth when the platform provides endpoint + keys but no headers."""
-    if not _is_langfuse_otlp_endpoint(endpoint) or _has_header(headers, "Authorization"):
-        return False
-
-    public_key = os.getenv("LANGFUSE_PUBLIC_KEY", "").strip()
-    secret_key = os.getenv("LANGFUSE_SECRET_KEY", "").strip()
-    if not public_key or not secret_key:
-        logger.warning(
-            "Generic OTLP endpoint looks like Langfuse but LANGFUSE_PUBLIC_KEY/SECRET_KEY "
-            "are missing; Authorization header was not added"
-        )
-        return False
-
-    langfuse_headers = _build_langfuse_otlp_headers(public_key, secret_key)
-    headers["Authorization"] = langfuse_headers["Authorization"]
-    if not _has_header(headers, "x-langfuse-ingestion-version"):
-        headers["x-langfuse-ingestion-version"] = langfuse_headers["x-langfuse-ingestion-version"]
-    return True
-
-
 def _build_generic_otlp_http_config() -> Optional[dict]:
-    """Build generic OTLP HTTP traces exporter config from standard OTEL env."""
+    """Build generic OTLP HTTP traces exporter config from standard OTEL env.
+
+    This path consumes only the standard OTEL_EXPORTER_OTLP_* contract. Backend
+    identity and authentication are opaque to KsADK.
+    """
     traces_endpoint = os.getenv("OTEL_EXPORTER_OTLP_TRACES_ENDPOINT", "").strip()
     base_endpoint = os.getenv("OTEL_EXPORTER_OTLP_ENDPOINT", "").strip()
     endpoint = traces_endpoint
@@ -580,13 +564,6 @@ def _build_generic_otlp_http_config() -> Optional[dict]:
         endpoint = _derive_otlp_traces_endpoint(base_endpoint)
     if not endpoint:
         return None
-    if _is_langfuse_callback_endpoint(endpoint):
-        logger.info(
-            "Generic OTLP HTTP exporter skipped because LANGFUSE_USE_CALLBACK is enabled "
-            "for endpoint=%s",
-            endpoint,
-        )
-        return None
 
     protocol = (
         os.getenv("OTEL_EXPORTER_OTLP_TRACES_PROTOCOL", "").strip().lower()
@@ -603,53 +580,58 @@ def _build_generic_otlp_http_config() -> Optional[dict]:
         "OTEL_EXPORTER_OTLP_HEADERS", ""
     )
     headers = _parse_otlp_headers(raw_headers)
-    langfuse_auth_fallback = _apply_langfuse_auth_fallback(endpoint, headers)
     logger.info(
-        "Generic OTLP HTTP config resolved: endpoint=%s protocol=http/protobuf "
-        "header_keys=%s langfuse_auth_fallback=%s",
+        "Generic OTLP HTTP config resolved: endpoint=%s protocol=http/protobuf header_keys=%s",
         endpoint,
         ",".join(sorted(headers)),
-        langfuse_auth_fallback,
     )
     return {
         "endpoint": endpoint,
         "headers": headers,
         "protocol": "http/protobuf",
-        "langfuse_auth_fallback": langfuse_auth_fallback,
     }
 
 
+def _register_span_processor(provider: Any, processor: Any) -> None:
+    provider.add_span_processor(processor)
+    _managed_span_processors.append(processor)
+
+
 def setup_tracing(
     enable_inmemory: bool = True,
-    enable_langfuse: bool | None = None,  # Auto-detect from env
+    enable_langfuse: bool | None = None,
     langfuse_config: dict[str, Any] | None = None,
     enable_otlp: bool = False,
     otlp_endpoint: str = "localhost:4317",
     enable_adk_instrumentation: bool = True,  # Auto-instrument ADK
-    use_callback_only: bool | None = None,  # Explicit override
     **kwargs,
 ) -> Optional[InMemoryExporter]:
     """初始化 Tracing (支持多 Exporter)
 
     Args:
         enable_inmemory: 是否启用内存 Exporter (Web UI 使用)
-        enable_langfuse: 是否启用 Langfuse (None = 自动检测环境变量)
-        langfuse_config: Langfuse 配置 {"public_key", "secret_key", "host"}
-        enable_otlp: 是否启用 OTLP Exporter
-        otlp_endpoint: OTLP 端点地址
+        enable_langfuse: 已废弃并忽略；请配置标准 OTEL_EXPORTER_OTLP_*
+        langfuse_config: 已废弃并忽略；认证信息放入标准 OTLP headers
+        enable_otlp: 是否启用 OTLP gRPC Exporter
+        otlp_endpoint: OTLP gRPC 端点地址
         enable_adk_instrumentation: 是否启用 ADK 自动插桩
-        use_callback_only: 是否仅使用 CallbackHandler (防止 OTel 重复)
 
     Returns:
         InMemoryExporter 实例 (用于 Web UI 获取 traces)
     """
-    global _exporter_instance, _langfuse_exporter, _tracing_initialized, _adk_instrumented
+    global _exporter_instance, _tracing_initialized, _adk_instrumented
 
     # 防止重复初始化
     if _tracing_initialized:
         logger.debug("Tracing already initialized, skipping")
         return _exporter_instance
 
+    if enable_langfuse or langfuse_config:
+        logger.warning(
+            "enable_langfuse/langfuse_config are ignored; configure the standard "
+            "OTEL_EXPORTER_OTLP_* contract instead"
+        )
+
     try:
         from opentelemetry import trace
         from opentelemetry.sdk.trace import TracerProvider
@@ -661,11 +643,9 @@ def setup_tracing(
     # 检查是否已有 TracerProvider (避免覆盖)
     existing_provider = trace.get_tracer_provider()
     if existing_provider and hasattr(existing_provider, "add_span_processor"):
-        # 使用现有 provider，直接添加 processor
         provider = existing_provider
         logger.debug("Using existing TracerProvider")
     else:
-        # 创建新的 TracerProvider
         provider = TracerProvider()
         trace.set_tracer_provider(provider)
         logger.debug("Created new TracerProvider")
@@ -674,11 +654,10 @@ def setup_tracing(
     if enable_inmemory:
         exporter = InMemoryExporter(max_traces=kwargs.get("max_traces", 1000))
         _exporter_instance = exporter
-        provider.add_span_processor(SimpleSpanProcessor(exporter))
+        _register_span_processor(provider, SimpleSpanProcessor(exporter))
         logger.info("InMemory exporter enabled")
 
-    # 2. Generic OTLP HTTP exporter from standard environment variables.
-    # This keeps user code backend-agnostic; Langfuse is only one possible OTLP backend.
+    # 2. Generic OTLP HTTP exporter (标准 OTEL_* —— 托管 Agent 的 Langfuse 主路)
     generic_otlp_config = _build_generic_otlp_http_config()
     if generic_otlp_config:
         try:
@@ -696,17 +675,10 @@ def setup_tracing(
                 endpoint=generic_otlp_config["endpoint"],
                 service_name=_get_service_name(),
                 header_keys=sorted(generic_otlp_config["headers"]),
-                span_transform=(
-                    _prepare_langfuse_spans
-                    if _is_langfuse_otlp_endpoint(generic_otlp_config["endpoint"])
-                    else None
-                ),
             )
-            provider.add_span_processor(
-                BatchSpanProcessor(
-                    otlp_exporter,
-                    **_batch_span_processor_kwargs(),
-                )
+            _register_span_processor(
+                provider,
+                BatchSpanProcessor(otlp_exporter, **_batch_span_processor_kwargs()),
             )
             logger.info(
                 "Generic OTLP HTTP exporter enabled: %s (%s) headers=%s",
@@ -719,9 +691,7 @@ def setup_tracing(
         except Exception as e:
             logger.error(f"Failed to initialize generic OTLP HTTP exporter: {e}")
 
-    # 3. CloudMonitor OTLP HTTP exporter.
-    # This uses CloudMonitor-specific env vars, so existing Langfuse / generic OTLP paths
-    # continue to behave exactly as configured by the user or platform.
+    # 3. CloudMonitor OTLP HTTP exporter (次路 —— 平台 CLOUD_MONITOR_OTLP_*)
     cloud_monitor_config = _build_cloud_monitor_otlp_http_config()
     if cloud_monitor_config:
         try:
@@ -741,11 +711,9 @@ def setup_tracing(
                 header_keys=sorted(cloud_monitor_config.headers),
                 span_transform=_prepare_cloud_monitor_spans,
             )
-            provider.add_span_processor(
-                BatchSpanProcessor(
-                    cloud_monitor_exporter,
-                    **_batch_span_processor_kwargs(),
-                )
+            _register_span_processor(
+                provider,
+                BatchSpanProcessor(cloud_monitor_exporter, **_batch_span_processor_kwargs()),
             )
             logger.info(
                 "CloudMonitor OTLP exporter enabled: endpoint=%s protocol=%s service_name=%s",
@@ -758,64 +726,7 @@ def setup_tracing(
         except Exception as e:
             logger.error(f"Failed to initialize CloudMonitor OTLP exporter: {e}")
 
-    # 4. Langfuse OTLP direct exporter (auto-detect or explicit config)
-    # 注意: 对于 LangGraph/LangChain 框架，推荐使用 CallbackHandler 而非 OTel Exporter
-    # 同时使用两者会导致重复的 trace
-    langfuse_enabled = enable_langfuse
-    if langfuse_enabled is None:
-        # Auto-detect from environment variables
-        langfuse_enabled = not generic_otlp_config and bool(
-            os.getenv("LANGFUSE_PUBLIC_KEY") or (langfuse_config or {}).get("public_key")
-        )
-
-    # 检查是否应该禁用 LangfuseExporter (当使用 LangChain/LangGraph 时)
-    # 优先使用显式参数，否则读取环境变量
-    if use_callback_only is None:
-        use_callback_only = os.getenv("LANGFUSE_USE_CALLBACK", "false").lower() == "true"
-
-    if langfuse_enabled and not use_callback_only:
-        try:
-            from opentelemetry.exporter.otlp.proto.http.trace_exporter import (
-                OTLPSpanExporter as HttpOTLPSpanExporter,
-            )
-
-            config = _build_langfuse_otlp_config(langfuse_config)
-            if config:
-                raw_langfuse_otlp_exporter = HttpOTLPSpanExporter(
-                    endpoint=config["endpoint"],
-                    headers=config["headers"],
-                )
-                otlp_exporter = _LoggingSpanExporter(
-                    raw_langfuse_otlp_exporter,
-                    name="Langfuse OTLP",
-                    endpoint=config["endpoint"],
-                    service_name=_get_service_name(),
-                    header_keys=sorted(config["headers"]),
-                    span_transform=_prepare_langfuse_spans,
-                )
-                provider.add_span_processor(
-                    BatchSpanProcessor(
-                        otlp_exporter,
-                        **_batch_span_processor_kwargs(),
-                    )
-                )
-                logger.info(
-                    "Langfuse OTLP exporter enabled: %s (%s) headers=%s",
-                    config["endpoint"],
-                    config["protocol"],
-                    ",".join(sorted(config["headers"])),
-                )
-            else:
-                logger.warning("Langfuse credentials not found, skipping")
-
-        except ImportError as e:
-            logger.warning(f"Langfuse OTLP exporter not available: {e}")
-        except Exception as e:
-            logger.error(f"Failed to initialize Langfuse OTLP exporter: {e}")
-    elif langfuse_enabled:
-        logger.info("Langfuse will use CallbackHandler (recommended for LangChain/LangGraph)")
-
-    # 5. OTLP Exporter (optional)
+    # 4. OTLP gRPC Exporter (optional compatibility path)
     if enable_otlp:
         try:
             from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import (
@@ -823,17 +734,15 @@ def setup_tracing(
             )
 
             grpc_otlp_exporter = GrpcOTLPSpanExporter(endpoint=otlp_endpoint)
-            provider.add_span_processor(
-                BatchSpanProcessor(
-                    grpc_otlp_exporter,
-                    **_batch_span_processor_kwargs(),
-                )
+            _register_span_processor(
+                provider,
+                BatchSpanProcessor(grpc_otlp_exporter, **_batch_span_processor_kwargs()),
             )
             logger.info(f"OTLP exporter enabled: {otlp_endpoint}")
         except ImportError:
             logger.warning("OTLP exporter not installed")
 
-    # 6. ADK Auto-Instrumentation (for Google ADK projects)
+    # 5. ADK Auto-Instrumentation (for Google ADK projects)
     if enable_adk_instrumentation and not _adk_instrumented:
         try:
             instrumentation_module = importlib.import_module(
@@ -851,7 +760,7 @@ def setup_tracing(
         except Exception as e:
             logger.debug(f"ADK instrumentation failed: {e}")
 
-    # 7. LangChain Auto-Instrumentation
+    # 6. LangChain Auto-Instrumentation (covers LangChain + LangGraph LLM/tool/node spans)
     if enable_adk_instrumentation:
         try:
             from openinference.instrumentation.langchain import LangChainInstrumentor
@@ -874,18 +783,28 @@ def setup_tracing(
 
 
 def shutdown_tracing():
-    """Gracefully shutdown tracing to prevent Ctrl+C errors"""
-    global _langfuse_exporter, _tracing_initialized
+    """Flush and stop every processor installed by this module.
 
-    if _langfuse_exporter is not None:
+    The global provider may belong to another library, so KsADK never shuts the
+    provider itself. It owns and closes only the processors it registered.
+    """
+    processors = list(_managed_span_processors)
+    _managed_span_processors.clear()
+    for processor in processors:
         try:
-            if hasattr(_langfuse_exporter, "_exporter"):
-                _langfuse_exporter._exporter.shutdown()
-            logger.debug("Langfuse exporter shutdown gracefully")
+            processor.force_flush(timeout_millis=30000)
+        except TypeError:
+            try:
+                processor.force_flush()
+            except Exception:
+                logger.exception("Tracing processor force_flush failed")
         except Exception:
-            pass  # Ignore shutdown errors
-
-    _tracing_initialized = False
+            logger.exception("Tracing processor force_flush failed")
+    for processor in processors:
+        try:
+            processor.shutdown()
+        except Exception:
+            logger.exception("Tracing processor shutdown failed")
 
 
 def get_memory_exporter() -> Optional[InMemoryExporter]:
@@ -893,11 +812,6 @@ def get_memory_exporter() -> Optional[InMemoryExporter]:
     return _exporter_instance
 
 
-def get_langfuse_exporter():
-    """获取 Langfuse Exporter 实例"""
-    return _langfuse_exporter
-
-
 def get_tracer(name: str = "ksadk"):
     """获取 Tracer"""
     try: