代理可观测性

人工智能 社区

技能解读

当前原文的自动摘译,尚未人工审校。

所需的环境变量

如果 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 工作流程。

流狐档案 运行与权限由流狐静态检查推断,不代表作者声明或实际测试结果。
领域
人工智能
作者声明的智能体
未找到明确声明;不据此推断已兼容或已测试
静态检查
88 / 100 · 启发式扫描,不代表运行安全
运行环境证据
未执行;当前没有隔离运行测试证据
作者 / 版本 / 许可证
@tomevault-io · 未声明许可证
上下文用量评级
中等消耗
接入复杂程度
需手动接入
是否需要外部接口密钥
需要 · OpenAI
兼容的系统
Docker
运行环境要求
Python · Docker
检测到的文件与系统行为
  • 只读
  • 允许写入 / 修改
  • 读取环境变量
网络行为
允许外网请求
安装命令数
无(仅作为资料)

需要注意: 未声明工具权限范围;实际权限由运行环境决定。

作者说明文件(原文) SKILL.md

# 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 -->

讨论

基于 GitHub Discussions。登录 GitHub 即可参与讨论、点赞、订阅更新。