Xinmin Zeng 2a97ec3e58
docs: turn README into an index and move reference detail to docs/guide (#8113)
* docs: turn README into an index and move reference detail to docs/guide

The README had grown to 393 KB because every change appended its notes there. The text moves verbatim into 18 topic guides under docs/guide/; only headings are re-leveled and relative links re-pointed. The README keeps the introduction, a quick start and a guide index. Contributor test notes move to CONTRIBUTING.md.

* docs: send user docs to topic guides and budget the root README

The rule 'update README.md for user-facing changes' is what grew the README. Guidance now points to docs/guide/, and check_agent_guidance.py fails when the root README exceeds 16 KiB (AG003).

* chore: remove unreferenced screenshots and finished plan notes

pr-build/ holds two PR screenshots (3 MB) from #1986. plans/ holds the plan for the merged #4049. docs/SKILL_NAME_CONFLICT_FIX.md is a February change note. Nothing references them.

* docs: route always-loaded AGENTS.md files to scoped guides

* docs(agents): cut scoped guides to scope, verify, traps, decisions

Each AGENTS.md keeps four kinds of content: the scope of the directory, the
verification commands, traps a local test run does not show, and decisions the
code cannot state. Values, field lists, function inventories, test names, issue
numbers and history are deleted, because the code, the tests and git state them.

Search and fetch providers share one community guide. Four guides with no
remaining content are removed. The size check now allows 6 KiB per file (hard
limit 8 KiB) and 24 KiB per chain (hard limit 32 KiB).

* style: format frontend guide table and guidance test imports

---------

Co-authored-by: Willem Jiang <willem.jiang@gmail.com>
2026-11-11 13:26:17 +08:00

1.8 KiB

Tracing (deerflow/tracing/)

Wires LangSmith, Langfuse and Monocle. The providers are enabled by environment variables; the variable names and the Langfuse field mapping are in tracing/ and config/. The request correlation ID is covered in the harness guide.

Verify

cd backend
python -m pytest tests -q -k "tracing or langfuse or monocle"

LangSmith and Langfuse

  • Callbacks attach at the graph invocation root, not at the model. One run then produces one trace, and the Langfuse handler lifts the trace attributes only when it sees the root chain start.
  • Three places merge the trace metadata before they invoke a graph: the run worker, DeerFlowClient.stream and the subagent executor. A new entry point that invokes a graph does the same, after model selection.
  • A subagent trace carries the parent thread_id as its session, so it groups with the parent thread.
  • build_langfuse_trace_metadata() returns {} when Langfuse is off. A LangSmith-only deployment is unaffected.

Monocle

  • Monocle is not a callback. Its setup installs a process-global OpenTelemetry TracerProvider and instruments the clients, once per process.
  • The Gateway lifespan is the only call site. Importing deerflow.agents must not start tracing, and build_tracing_callbacks() does not call the setup.
  • The embedded client and the TUI are not instrumented. An embedded user who wants Monocle traces calls setup_monocle_tracing_if_enabled() before the run.
  • DeerFlow adds no per-run fields to Monocle traces. There is no attribute layer to maintain here.
  • Monocle and Langfuse share the global provider. The library that starts second attaches its span processor to the existing provider, so Monocle's exporters also receive Langfuse's spans when both are on.