代理可观测性
- 作者仓库星标 0
- 作者仓库 skills-registry
- 领域
- 人工智能
- 作者声明的智能体
- 未找到明确声明;不据此推断已兼容或已测试
- 静态检查
- 88 / 100 · 启发式扫描,不代表运行安全
- 运行环境证据
- 未执行;当前没有隔离运行测试证据
- 作者 / 版本 / 许可证
- @tomevault-io · 未声明许可证
- 上下文用量评级
- 中等消耗
- 接入复杂程度
- 需手动接入
- 是否需要外部接口密钥
- 需要 · OpenAI
- 兼容的系统
- Docker
- 运行环境要求
- Python · Docker
- 检测到的文件与系统行为
-
- 只读
- 允许写入 / 修改
- 读取环境变量
- 网络行为
- 允许外网请求
- 安装命令数
- 无(仅作为资料)
需要注意: 未声明工具权限范围;实际权限由运行环境决定。
# Observability
LangChain ecosystem projects trace through **LangSmith** by default. Tracing turns on automatically when `LANGSMITH_TRACING=true` is set — no code changes required. Every `agent.invoke(...)` becomes one trace; tool calls, sub-agent delegations, and middleware hooks are nested spans.
For production, you'll often want OTEL on top of (or instead of) LangSmith.
## Required environment variables
```
LANGSMITH_API_KEY=ls_... # required
LANGSMITH_TRACING=true # enables capture
LANGSMITH_PROJECT=my-agent # bucket name in the LangSmith UI
```
If `LANGSMITH_TRACING` is unset or `false`, the agent runs but no traces are captured. The agent does *not* fail — silent observability gap. Always set it explicitly.
## Where traces live
LangSmith UI → the project named in `LANGSMITH_PROJECT`. Filter by experiment, time range, or status. Each trace is a tree:
- Top-level: `agent.invoke(...)`.
- Children: middleware `wrap_*` calls, model calls, tool calls, sub-agent `task` invocations.
- Leaves: token streams, tool inputs/outputs, errors with stack traces.
## What middleware looks like in traces
Each middleware that wraps a model or tool call appears as its own span. Useful for diagnosing "why did this take so long" — you can see exactly which retry or fallback fired.
## Manual span instrumentation
```python
from langsmith import traceable
@traceable
def my_helper(x: int) -> int:
return x * 2
```
`@traceable` works on any callable; it shows up as its own span under the parent trace. Use it for application-specific operations not auto-captured (DB queries, external API calls outside of LangChain tools).
## OpenTelemetry integration
LangSmith can emit OTLP traces alongside its native ones, so existing observability backends (Jaeger, Tempo, Honeycomb, Datadog) get the data:
```bash
export OTEL_EXPORTER_OTLP_ENDPOINT="https://api.honeycomb.io"
export OTEL_EXPORTER_OTLP_HEADERS="x-honeycomb-team=$HONEYCOMB_API_KEY"
export LANGSMITH_OTEL_ENABLED=true
```
When `LANGSMITH_OTEL_ENABLED=true`, traces are dual-emitted: to LangSmith AND to your OTLP collector. Spans use OpenTelemetry semantic conventions for AI / LLM workflows.
## Distributed tracing across services
If your agent calls another service (e.g. a separate retriever microservice), propagate the trace context so spans link up:
```python
from opentelemetry import propagate, trace
# When making an outbound call:
headers = {}
propagate.inject(headers) # adds traceparent header
requests.post("https://retriever.internal/", headers=headers, json={...})
```
The downstream service should call `propagate.extract(request.headers)` and create a span as a child.
## Cloud Run-specific tracing
Cloud Run automatically adds `X-Cloud-Trace-Context` to incoming requests. To correlate Cloud Run access logs with LangSmith spans, log the trace ID at the start of each request handler:
```python
import os, structlog
log = structlog.get_logger()
@app.post("/invoke")
def invoke(req, request: Request):
trace_header = request.headers.get("X-Cloud-Trace-Context", "")
cloud_trace_id = trace_header.split("/")[0]
log.bind(cloud_trace_id=cloud_trace_id, thread_id=req.thread_id).info("invoke")
...
```
## Common failure-mode diagnostics
| Symptom | Likely cause | First thing to check |
|---|---|---|
| `agent` import fails | Missing dep, wrong path, syntax error | `python -c "from agent.agent import agent"` from project root |
| Smoke evals fail with auth error | Wrong / missing provider key | `python -c "import os; print(bool(os.getenv('OPENAI_API_KEY')))"` |
| Smoke evals fail with rate-limit | Provider rate limit during eval | Drop dataset to 1 row; add `ModelRetryMiddleware`; retry |
| `langgraph dev` hangs on start | `langgraph.json` graph path wrong | `cat langgraph.json` — verify `./agent/agent.py:agent` exists |
| `langgraph dev` reload stops | Latest edit broke import | Check terminal for the exception |
| Docker container crashes on boot | `.env` not passed at run time | `docker logs <container>` |
| Cloud Run service doesn't start | Listening on 127.0.0.1 instead of 0.0.0.0:$PORT | `gcloud run services logs read SERVICE` |
| Trace shows the LLM but no tool calls | Tool not registered with the model | `bind_tools(TOOLS)` (LangGraph) or `tools=...` arg to `create_agent` |
| Trace shows tool calls but they fail | Tool raised an exception | Click the failing span — exception + traceback are captured |
| Conversation memory lost between turns | No checkpointer or thread_id mismatch | `compile(checkpointer=...)` AND `config={"configurable": {"thread_id": ...}}` on every invoke |
| Token cost suddenly spikes | No `SummarizationMiddleware`; long context | Add it; trigger at ~8000 tokens, keep last 20 messages |
| Random 30-60s pauses in production | Provider rate-limit handled by retry middleware | Check trace — `ModelRetryMiddleware` span shows the backoff sleeps |
| HITL `interrupt()` never resumes | No checkpointer at compile time | `HumanInTheLoopMiddleware` requires a checkpointer |
| Costs much higher than expected | Retries multiplying. No `ModelCallLimitMiddleware` | Add it; cap at e.g. `run_limit=50` |
## Quick local verification (no LangSmith needed)
```bash
python -c "
from agent.agent import agent
result = agent.invoke({'messages': [{'role': 'user', 'content': 'hello'}]})
print(result)
"
```
If this fails, the agent is broken regardless of tracing. Fix it first.
## Production alerting
LangSmith UI supports alerts on:
- p95 latency exceeding a threshold.
- Error rate exceeding a threshold (% of runs that throw).
- Specific evaluator scores dropping below a threshold (eval-as-monitor pattern).
Configure these per project in the LangSmith UI. For escalation to PagerDuty / Slack, use LangSmith's webhook integrations or pipe traces through OTEL into your existing alert stack.
## Trace sampling for high-volume services
LangSmith captures every trace by default. For very high traffic (>100 RPS sustained), sampling is supported via the `LANGSMITH_SAMPLING_RATE` env var (e.g. `0.1` = 10%). Trace integrity is preserved for sampled traces (full tree), so this is safe — you just see fewer of them.
## Trace URLs in code
When `LANGSMITH_TRACING=true`, the SDK prints a trace URL to stderr after each `agent.invoke(...)`. Capture it in production logs for debugging:
```python
import sys, contextlib, io
buf = io.StringIO()
with contextlib.redirect_stderr(buf):
result = agent.invoke({"messages": [...]})
trace_url = next((line for line in buf.getvalue().splitlines() if "smith.langchain.com" in line), "")
log.info("agent_invoked", trace_url=trace_url)
```
---
> Source: [cwijayasundara/agent_cli_langchain](https://github.com/cwijayasundara/agent_cli_langchain) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-05-23 -->
章节与文件索引
按说明文件中的顺序排列。
所需的环境变量
痕迹存在的地方
中间件在痕迹中看起来是什么样的
手动量程仪表
开放遥测集成
文件/命令 -> LANGSMITH_TRACING=true · agent.invoke(...) · LANGSMITH_TRACING · false · LANGSMITH_PROJECT · wrap_* · task · @traceable
内容校验值 -> 75a11dddfc8f
当前原文的自动摘译,尚未人工审校。
所需的环境变量
如果
LANGSMITH_TRACING未设置或false,代理会运行,但不会捕获任何跟踪。代理不会失败——无声的可观察性差距。始终明确设置它。痕迹存在的地方
LangSmith UI →
LANGSMITH_PROJECT中命名的项目。按实验、时间范围或状态进行过滤。每个跟踪都是一棵树:顶级:agent.invoke(...)。子级:中间件wrap_*调用、模型调用、工具调用、子代理task调用。叶子:令牌流、工具输入/输出、堆栈跟踪错误。中间件在痕迹中看起来是什么样的
每个包装模型或工具调用的中间件都显示为其自己的跨度。对于诊断“为什么花了这么长时间”很有用 - 您可以准确地看到触发了哪个重试或回退。
手动量程仪表
@traceable适用于任何可调用对象;它在父跟踪下显示为自己的跨度。将其用于未自动捕获的特定于应用程序的操作(数据库查询、LangChain 工具之外的外部 API 调用)。开放遥测集成
LangSmith 可以与其本机跟踪一起发出 OTLP 跟踪,因此现有的可观察性后端(Jaeger、Tempo、Honeycomb、Datadog)获取数据:当
LANGSMITH_OTEL_ENABLED=true时,跟踪是双重发送的:发送到 LangSmith 和您的 OTLP 收集器。 Spans 使用 OpenTelemetry 语义约定进行 AI / LLM 工作流程。