fix(maf): delegate metrics and preserve context

Author: sipercai

instrumentation-loongsuite/loongsuite-instrumentation-microsoft-agent-framework/CHANGELOG.md

@@ -7,11 +7,29 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## Unreleased
 
+### Changed
+
+- Delegate GenAI metric recording to the shared ``opentelemetry-util-genai``
+  existing-span lifecycle and remove the process-cumulative ObservableGauges.
+- Stop using ``ARMS_MAF_SLOW_THRESHOLD_MS`` because slow-call aggregation is no
+  longer owned here. Its configuration helper and legacy
+  ``MAFSemanticProcessor`` constructor arguments remain as deprecated no-ops.
+- ``ARMS_MAF_METRICS_ENABLED`` now controls only extension metrics recorded
+  through ``opentelemetry-util-genai``; MAF's native standard metrics are
+  unaffected.
+
 ### Fixed
 
 - Avoid enriching non-MAF spans that use overlapping GenAI operation names.
 - Preserve parent-child context for legacy Microsoft Agent Framework streaming
   agent spans.
+- Record streaming TTFT only after ``ResponseStream`` returns its first update,
+  and keep finalization safe across concurrent threads and ``fork()``.
+- Emit the standard failed-call metric through ``opentelemetry-util-genai``
+  when MAF's native LLM error path does not reach its metric capture, and route
+  MAF's tracer and meter accessors to explicitly supplied providers.
+- Adopt streaming spans created directly by MAF 1.0 through 1.2.1 so shared
+  finalization still runs before their native ``span.end()``.
 
 ## Version 0.7.0 (2026-07-03)
 

instrumentation-loongsuite/loongsuite-instrumentation-microsoft-agent-framework/README.rst

@@ -17,14 +17,25 @@ through ``opentelemetry-util-genai`` before spans are ended:
   token usage, finish reasons, and streaming TTFT where MAF exposes enough
   data.
 * ``MAFSemanticProcessor`` remains as a compatibility layer for MAF workflow,
-  MCP, private-prefix attribute normalization, and the in-process ARMS gauges.
-  Successful spans keep the OpenTelemetry default ``UNSET`` status; failed
-  spans keep MAF's ``ERROR`` status.
+  MCP, and private-prefix attribute normalization. Metrics are recorded through
+  the shared ``opentelemetry-util-genai`` existing-span lifecycle, without
+  creating a second GenAI span. Successful spans keep the OpenTelemetry default
+  ``UNSET`` status; failed spans keep MAF's ``ERROR`` status.
 * ``react_step_patch`` (opt-in via ``ARMS_MAF_REACT_STEP_ENABLED=true``)
   wraps ``FunctionInvocationLayer.get_response`` so that each LLM round-trip
   inside the ReAct loop emits one ``react step`` span via
   ``ExtendedTelemetryHandler.react_step()`` from ``opentelemetry-util-genai``.
 
+When explicit tracer or meter providers are passed to the instrumentor, MAF's
+native provider accessors are routed to them. Instrument before constructing
+MAF clients so their native metric instruments bind to the requested provider.
+
+Compatibility note: MAF 1.0 through 1.2.1 creates streaming Chat spans without
+a per-pull context hook. The processor still installs pre-end shared
+finalization for those spans, but pull-derived TTFT and Chat-child parenting are
+available only with MAF 1.2.2 or newer. This is an upstream lifecycle boundary;
+non-streaming telemetry remains supported on the older versions.
+
 Truncation / PII helpers are reused from ``opentelemetry.util.genai.utils``
 (``gen_ai_json_dumps``), aligned with
 the OpenAI Agents v2 GenAI instrumentation.
@@ -47,6 +58,12 @@ instrumentation package and framework separately:
    pip install loongsuite-instrumentation-microsoft-agent-framework
    pip install agent-framework-core
 
+Published LoongSuite wheels depend on the matching
+``loongsuite-otel-util-genai`` release. For a source-checkout development
+install, build or install ``util/opentelemetry-util-genai`` from the same
+checkout first so the shared existing-span API resolves from that checkout
+rather than another distribution using the same import namespace.
+
 Configuration
 =============
 
@@ -56,6 +73,5 @@ Env                                     Default     Description
 ``ARMS_MAF_INSTRUMENTATION_ENABLED``    ``true``    Master switch; ``false`` disables instrumentation.
 ``ARMS_MAF_SENSITIVE_DATA_ENABLED``     ``false``   Capture inputs/outputs (linked to MAF's sensitive-data option).
 ``ARMS_MAF_REACT_STEP_ENABLED``         ``false``   Emit ``react step`` spans for non-streaming ReAct tool loops.
-``ARMS_MAF_METRICS_ENABLED``            ``true``    Aggregate ARMS GenAI gauges in-process.
-``ARMS_MAF_SLOW_THRESHOLD_MS``          ``1000``    Slow-call threshold in ms.
+``ARMS_MAF_METRICS_ENABLED``            ``true``    Record extension metrics through ``opentelemetry-util-genai``; native MAF metrics are unaffected.
 ======================================  ==========  ==============================================================

instrumentation-loongsuite/loongsuite-instrumentation-microsoft-agent-framework/src/opentelemetry/instrumentation/microsoft_agent_framework/__init__.py

@@ -18,7 +18,7 @@
 with ``force=True`` so a sticky user-disable does not block us), bridges MAF's
 native span helpers through ``opentelemetry-util-genai`` finish helpers, and
 registers :class:`~.span_processor.MAFSemanticProcessor` for workflow/MCP
-normalization plus metrics aggregation.
+normalization. GenAI metrics are delegated to ``opentelemetry-util-genai``.
 
 The optional ReAct step patch (``ARMS_MAF_REACT_STEP_ENABLED=true``) wraps the
 ``FunctionInvocationLayer.get_response`` ReAct loop with
@@ -42,7 +42,6 @@
 from opentelemetry.trace import get_tracer_provider
 
 from .config import (
-    get_slow_threshold_ms,
     is_instrumentation_enabled,
     is_metrics_enabled,
     is_react_step_enabled,
@@ -116,20 +115,32 @@ def _instrument(self, **kwargs: Any) -> None:
         #    invocation finish helpers. This keeps MAF's span lifetime and
         #    streaming cleanup behavior, but writes AGENT/LLM/TOOL semantic
         #    attributes before span.end() creates the exporter snapshot.
-        apply_util_genai_bridge()
+        apply_util_genai_bridge(
+            tracer_provider=tracer_provider,
+            meter_provider=meter_provider,
+            metrics_enabled=is_metrics_enabled(default=True),
+        )
 
         # 3) Register the semantic SpanProcessor. MAF uses the standard OTel
         #    TracerProvider (it does not have its own multi-processor), so
         #    ``add_span_processor`` is the right hook.
         processor = MAFSemanticProcessor(
-            meter_provider=meter_provider,
-            slow_threshold_ms=get_slow_threshold_ms(),
-            metrics_enabled=is_metrics_enabled(default=True),
             capture_sensitive_data=sensitive,
         )
         try:
             tracer_provider.add_span_processor(processor)
         except Exception as exc:
+            # BaseInstrumentor does not mark the instrumentor active when
+            # _instrument raises, so a later uninstrument cannot clean up a
+            # bridge installed above. Roll back this partial transaction now.
+            revert_util_genai_bridge()
+            try:
+                _remove_span_processor(tracer_provider, processor)
+                processor.shutdown()
+            except Exception as cleanup_exc:  # pragma: no cover - defensive
+                logger.debug(
+                    "processor registration cleanup failed: %s", cleanup_exc
+                )
             logger.warning("add_span_processor failed: %s", exc)
             raise
 

instrumentation-loongsuite/loongsuite-instrumentation-microsoft-agent-framework/src/opentelemetry/instrumentation/microsoft_agent_framework/config.py

@@ -61,6 +61,7 @@ def is_metrics_enabled(default: bool = True) -> bool:
 
 
 def get_slow_threshold_ms(default: int = 1000) -> int:
+    """Return the deprecated slow threshold for API compatibility only."""
     raw = os.getenv(ENV_SLOW_THRESHOLD_MS)
     if raw is None:
         return default