feat(deer-flow): add loongsuite-instrumentation-deer-flow package

Implements the hybrid LangChain-callback-reuse + 7-wrapt-monkey-patch plan
from llm-dev/deer-flow/investigate/execute.md. The package covers
DeerFlow-specific Entry / Agent (subagent) / Task / Sandbox / Memory spans
on top of the LLM / Tool / ReAct Step spans already produced by
loongsuite-instrumentation-langchain.

Seven wrapt patches on public DeerFlow APIs:
* runtime.runs.worker.run_agent -> ENTRY span
* subagents.executor.SubagentExecutor._aexecute -> AGENT span
* tools.builtins.task_tool.task_tool -> TASK span
* sandbox.sandbox.Sandbox.execute_command + 5 other abstract methods -> TOOL span
* sandbox.sandbox_provider.SandboxProvider.acquire/acquire_async/release -> TASK span
* agents.memory.storage.FileMemoryStorage.load/save -> TASK span
* agents.memory.updater.MemoryUpdater.aupdate_memory -> TASK span

ENTRY / AGENT / TOOL spans use ExtendedTelemetryHandler (auto-emits
genai_* metrics). TASK spans are created manually with tracer.start_span
because ExtendedTelemetryHandler has no start_task/stop_task (TASK is a
LoongSuite extension span kind that predates the handler).

Recursion guard mirrors crewai _ENTRY_DEPTH / _TASK_DEPTH ContextVar pattern.
Subagent cross-loop context propagation is free: DeerFlow executor.py:749/845
already uses contextvars.copy_context() (per Review Agent's correction).

PII handling: gen_ai.tool.call.arguments / result and Memory input.value /
output.value are gated by OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT
(default false); Memory content has a second-level switch
OTEL_DEER_FLOW_CAPTURE_MEMORY_CONTENT (default false).

Version guard: _instruments = ("deer-flow >= 2.1, < 3.0",); import failures
are silently skipped by DeerFlowInstrumentor._instrument.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: 123liuziming

instrumentation-loongsuite/loongsuite-instrumentation-deer-flow/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+## 0.1.0.dev
+
+* Initial release: DeerFlow 2.1+ instrumentation following the hybrid
+  LangChain-callback-reuse + 7-wrapt-monkey-patch plan from
+  `llm-dev/deer-flow/investigate/execute.md`.
+* Covers Entry / Agent (subagent) / Task (task_tool, sandbox lifecycle,
+  memory load/save/update) / Tool (Sandbox ABC) spans. LLM / Tool (LangChain)
+  / ReAct Step spans are delegated to `loongsuite-instrumentation-langchain`.
+* PII handling: Memory content gated by a two-level switch
+  (`OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT` +
+  `OTEL_DEER_FLOW_CAPTURE_MEMORY_CONTENT`).

instrumentation-loongsuite/loongsuite-instrumentation-deer-flow/README.md

@@ -0,0 +1,71 @@
+# LoongSuite Instrumentation for DeerFlow
+
+OpenTelemetry instrumentation for [ByteDance DeerFlow](https://github.com/bytedance/deer-flow)
+(`deer-flow >= 2.1, < 3.0`).
+
+## Design
+
+This package follows the hybrid plan documented in
+`llm-dev/deer-flow/investigate/execute.md`:
+
+* **LLM / Tool / ReAct Step spans are delegated** to
+  `loongsuite-instrumentation-langchain` — DeerFlow builds on
+  `langchain.agents.create_agent`, so LangChain's `BaseCallbackManager` wrap
+  already emits those spans. This package **does not** wrap
+  `BaseCallbackManager`, avoiding duplicate spans.
+* **DeerFlow-specific Entry / Agent / Task / Sandbox / Memory spans** are
+  produced by seven `wrapt` monkey patches on DeerFlow public APIs:
+
+| # | Module / Symbol | Span kind | Operation name |
+| --- | --- | --- | --- |
+| 1 | `deerflow.runtime.runs.worker.run_agent` | ENTRY | `enter` |
+| 2 | `deerflow.subagents.executor.SubagentExecutor._aexecute` | AGENT | `invoke_agent` |
+| 3 | `deerflow.tools.builtins.task_tool.task_tool` | TASK | `run_task` |
+| 4 | `deerflow.sandbox.sandbox.Sandbox.execute_command` (+ `read_file` / `write_file` / `glob` / `grep` / `list_dir`) | TOOL | `execute_tool` |
+| 5 | `deerflow.sandbox.sandbox_provider.SandboxProvider.acquire` / `acquire_async` / `release` | TASK | `run_task` |
+| 6 | `deerflow.agents.memory.storage.FileMemoryStorage.load` / `save` | TASK | `run_task` |
+| 7 | `deerflow.agents.memory.updater.MemoryUpdater.aupdate_memory` | TASK | `run_task` |
+
+Span creation for ENTRY / AGENT / TOOL uses `opentelemetry.util.genai.ExtendedTelemetryHandler`,
+which also auto-emits the `genai_*` metrics via its built-in
+`ExtendedInvocationMetricsRecorder`. TASK spans are created manually with
+`tracer.start_as_current_span` because `ExtendedTelemetryHandler` does not
+expose `start_task` / `stop_task` (TASK is a LoongSuite extension kind that
+predates the handler).
+
+## Configuration
+
+| Env | Default | Effect |
+| --- | --- | --- |
+| `OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT` | `false` | Standard gen-ai content capture switch. Controls `gen_ai.input.messages` / `gen_ai.output.messages` / `gen_ai.tool.call.arguments` / `gen_ai.tool.call.result`. |
+| `OTEL_DEER_FLOW_CAPTURE_MEMORY_CONTENT` | `false` | Second-level switch: when true (and the standard switch is also true), Memory spans will populate `input.value` / `output.value`. Memory content contains PII, hence the double gate. |
+
+## Context propagation
+
+DeerFlow propagates `contextvars` into subagent isolated event loops via
+`contextvars.copy_context()` (executor.py:749/845). OTel Context follows
+`ContextVar` automatically, so the ENTRY span's parent/child relationship to
+the subagent AGENT span is preserved without any manual injection here.
+
+## Usage
+
+```python
+from opentelemetry.instrumentation.deer_flow import DeerFlowInstrumentor
+
+DeerFlowInstrumentor().instrument()
+```
+
+Or via the `opentelemetry-instrument` CLI entry point:
+
+```
+opentelemetry-instrument --instrumentation_modules deer_flow
+```
+
+## Limitations
+
+* IM Channel entry points (Slack / Feishu / Discord) do not go through
+  `run_agent`; they are not instrumented in v1.
+* `task_tool` produces both a TASK span (this package, parent) and a TOOL
+  span (langchain instrumentation, child). This is intentional — the TASK
+  span describes "dispatch to subagent" semantics while the TOOL span covers
+  the LangChain `@tool` invocation mechanics.

instrumentation-loongsuite/loongsuite-instrumentation-deer-flow/pyproject.toml

@@ -0,0 +1,54 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "loongsuite-instrumentation-deer-flow"
+dynamic = ["version"]
+description = "LoongSuite DeerFlow (bytedance/deer-flow) instrumentation"
+readme = "README.md"
+license = "Apache-2.0"
+requires-python = ">=3.12"
+authors = [
+  { name = "Zhiyong Liu", email = "liuzhiyong.lzy@alibaba-inc.com" },
+  { name = "OpenTelemetry Authors", email = "cncf-opentelemetry-contributors@lists.cncf.io" },
+]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: Apache Software License",
+  "Programming Language :: Python",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+]
+dependencies = [
+  "opentelemetry-api >= 1.37.0",
+  "opentelemetry-instrumentation >= 0.58b0",
+  "opentelemetry-semantic-conventions >= 0.58b0",
+  "wrapt >= 1.0.0, < 2.0.0",
+  "opentelemetry-util-genai",
+]
+
+[project.optional-dependencies]
+instruments = [
+  "deer-flow >= 2.1, < 3.0",
+]
+
+[project.entry-points.opentelemetry_instrumentor]
+deer_flow = "opentelemetry.instrumentation.deer_flow:DeerFlowInstrumentor"
+
+[project.urls]
+Homepage = "https://github.com/alibaba/loongsuite-python-agent/tree/main/instrumentation-loongsuite/loongsuite-instrumentation-deer-flow"
+Repository = "https://github.com/alibaba/loongsuite-python-agent"
+
+[tool.hatch.version]
+path = "src/opentelemetry/instrumentation/deer_flow/version.py"
+
+[tool.hatch.build.targets.sdist]
+include = [
+  "/src",
+  "/tests",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/opentelemetry"]

instrumentation-loongsuite/loongsuite-instrumentation-deer-flow/src/opentelemetry/instrumentation/deer_flow/__init__.py

@@ -0,0 +1,144 @@
+# 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.
+
+"""OpenTelemetry instrumentation for ByteDance DeerFlow.
+
+Implements the hybrid plan documented in
+``llm-dev/deer-flow/investigate/execute.md``: LLM / Tool / ReAct Step spans are
+delegated to ``loongsuite-instrumentation-langchain`` (DeerFlow is built on
+``langchain.agents.create_agent``), while DeerFlow-specific Entry / Agent /
+Task / Sandbox / Memory spans are produced by this package via seven
+``wrapt`` monkey patches on DeerFlow public APIs:
+
+* ``runtime.runs.worker.run_agent`` → ENTRY span
+* ``subagents.executor.SubagentExecutor._aexecute`` → AGENT span (subagent)
+* ``tools.builtins.task_tool.task_tool`` → TASK span (subagent dispatch)
+* ``sandbox.sandbox.Sandbox.execute_command`` (and the other abstract
+  methods) → TOOL span (``bash`` / ``read_file`` / ...)
+* ``sandbox.sandbox_provider.SandboxProvider.acquire`` /
+  ``acquire_async`` / ``release`` → TASK span (sandbox lifecycle)
+* ``agents.memory.storage.FileMemoryStorage.load`` / ``save`` → TASK span
+  (``memory.load`` / ``memory.save``)
+* ``agents.memory.updater.MemoryUpdater.aupdate_memory`` → TASK span
+  (``memory.update``)
+
+This package **does not** wrap ``BaseCallbackManager`` — that path is owned by
+``loongsuite-instrumentation-langchain`` and wrapping it again would create
+duplicate LLM / Tool spans.
+"""
+
+from __future__ import annotations
+
+import logging
+from importlib import import_module
+from typing import Any, Collection
+
+from opentelemetry.instrumentation.deer_flow.package import _instruments
+from opentelemetry.instrumentation.deer_flow.version import __version__
+from opentelemetry.instrumentation.instrumentor import BaseInstrumentor
+from opentelemetry.instrumentation.utils import unwrap
+from opentelemetry.util.genai.extended_handler import ExtendedTelemetryHandler
+
+logger = logging.getLogger(__name__)
+
+# (module_name, attr_path) tuples registered by ``_instrument`` so that
+# ``_uninstrument`` can call ``unwrap`` on each target.
+_UNINSTRUMENT_TARGETS: list[tuple[str, str]] = []
+
+
+class DeerFlowInstrumentor(BaseInstrumentor):
+    """Instrument ByteDance DeerFlow 2.1+ with OpenTelemetry."""
+
+    def __init__(self) -> None:
+        super().__init__()
+        self._handler: ExtendedTelemetryHandler | None = None
+        self._targets: list[tuple[str, str]] = []
+
+    def instrumentation_dependencies(self) -> Collection[str]:
+        return _instruments
+
+    def _instrument(self, **kwargs: Any) -> None:
+        try:
+            import deerflow  # noqa: F401  — exercise the dependency.
+        except ImportError:
+            logger.debug(
+                "DeerFlow is not installed; skipping instrumentation."
+            )
+            return
+        except Exception as exc:
+            logger.warning(
+                "DeerFlow import raised an unexpected error: %s", exc
+            )
+            return
+
+        tracer_provider = kwargs.get("tracer_provider")
+        meter_provider = kwargs.get("meter_provider")
+        logger_provider = kwargs.get("logger_provider")
+
+        self._handler = ExtendedTelemetryHandler(
+            tracer_provider=tracer_provider,
+            meter_provider=meter_provider,
+            logger_provider=logger_provider,
+        )
+
+        from opentelemetry.instrumentation.deer_flow.patches import (
+            entry,
+            memory,
+            sandbox,
+            subagent,
+            task_tool,
+        )
+
+        self._targets = []
+        for module in (entry, subagent, task_tool, sandbox, memory):
+            try:
+                targets = module.instrument(self._handler)
+            except Exception as exc:
+                logger.warning(
+                    "DeerFlow patch module %s failed to instrument: %s",
+                    module.__name__,
+                    exc,
+                    exc_info=True,
+                )
+                continue
+            self._targets.extend(targets)
+
+        _UNINSTRUMENT_TARGETS[:] = list(self._targets)
+
+    def _uninstrument(self, **kwargs: Any) -> None:
+        del kwargs
+        for module_name, attr in self._targets:
+            try:
+                module = import_module(module_name)
+                if "." in attr:
+                    class_name, method_name = attr.split(".", 1)
+                    cls = getattr(module, class_name, None)
+                    if cls is None:
+                        continue
+                    unwrap(cls, method_name)
+                else:
+                    unwrap(module, attr)
+            except Exception as exc:
+                logger.debug(
+                    "DeerFlow: could not unwrap %s.%s: %s",
+                    module_name,
+                    attr,
+                    exc,
+                )
+        self._targets = []
+        _UNINSTRUMENT_TARGETS[:] = []
+        self._handler = None
+
+
+__all__ = ["DeerFlowInstrumentor", "__version__"]

instrumentation-loongsuite/loongsuite-instrumentation-deer-flow/src/opentelemetry/instrumentation/deer_flow/package.py

@@ -0,0 +1,17 @@
+# 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.
+
+_instruments = ("deer-flow >= 2.1, < 3.0",)
+
+_supports_metrics = True

instrumentation-loongsuite/loongsuite-instrumentation-deer-flow/src/opentelemetry/instrumentation/deer_flow/patches/__init__.py

@@ -0,0 +1,27 @@
+# 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.
+
+"""DeerFlow wrapt patch modules.
+
+Each submodule wraps a DeerFlow public API with an ``ExtendedTelemetryHandler``
+-powered span. ``instrument(handler)`` returns a list of ``(module_name,
+attr_path)`` tuples that ``DeerFlowInstrumentor._uninstrument`` can pass to
+``unwrap``.
+"""
+
+from __future__ import annotations
+
+from . import entry, memory, sandbox, subagent, task_tool
+
+__all__ = ["entry", "memory", "sandbox", "subagent", "task_tool"]