Back to Details

weave-instrument

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Weave instrumentation

Weave 埋点

Complete the login check before editing or initializing. If no valid login exists, send only that section's reply and stop.
After a valid login, inspect the application's dependencies, agent boundaries, and existing OTel provider. Confirm 
entity/project
and runtime credentials before sending data; never read, print, or commit API keys. Read trace fidelity before changing any instrumentation path. Initialize once at startup with 
weave.init("entity/project")
in Python or 
await weave.init(...)
in Node.
在编辑或初始化之前，先完成登录检查。 如果没有有效的登录状态，只发送该部分的回复并停止。
完成有效登录后，检查应用的依赖项、Agent 边界和现有的 OTel provider。在发送数据前，确认 
entity/project
和运行时凭据；绝不读取、打印或提交 API key。修改任何埋点路径之前，请阅读追踪保真度。在 Python 中于启动时初始化一次 
weave.init("entity/project")
，或在 Node 中初始化一次 
await weave.init(...)
。

Check login first

首先检查登录

Before editing code or initializing tracing, verify the existing W&B login for the target deployment with a noninteractive, read-only identity request through the configured SDK or connector. Use credentials in place; never print, copy, or inspect secret values. Do not call 
login
or tracing 
init
as a login probe.
If no valid login exists, stop. Do not edit, initialize, or continue this skill. Do not run 
wandb login
in this session. This session's shell is not a normal terminal, so 
wandb login --verify
exits with 
No API key configured
instead of prompting. Do not ask for a key in this chat or create credentials.
Send only this, and nothing else. No decisions, notes, plans, or documentation links:
There's no W&B login yet, so this stops here. Open a new terminal tab and run 
wandb login --verify
. Create an API key at https://wandb.ai/authorize?ref=models. If the browser opens a different page, open that link again. Paste the key in that terminal, not here, and type continue.
On a self-hosted or dedicated deployment, use 
wandb login --verify --host <base-url>
and the authorize page that command prints. Still send only that.
  • If the check is unavailable or fails because of connectivity or permissions, report login/access as unverified and stop; do not assume credentials are invalid.
  • After the user continues, confirm the application runtime can use its own configured credentials and access 
    entity/project
    . A browser login does not establish SDK authentication. Node/Forge runtimes without a 
    .netrc
    fallback need credentials configured by the user through their runtime secret mechanism.
在编辑代码或初始化追踪之前，通过已配置的 SDK 或 connector 对目标部署的现有 W&B 登录状态进行验证，方式是发起非交互式、只读的身份请求。原地使用凭据；绝不打印、复制或检查 secret 值。不要将 
login
或追踪 
init
作为登录探测来调用。
如果不存在有效的登录状态，请停止。不要编辑、初始化或继续执行此 skill。 不要在当前会话中运行 
wandb login
。当前会话的 shell 不是普通终端，因此 
wandb login --verify
会直接退出并显示 
No API key configured
，而不会提示输入。不要在当前对话中索要 key，也不要创建凭据。
仅发送以下内容，不要发送任何其他内容。不要包含决策、备注、计划或文档链接：
目前尚未进行 W&B 登录，因此流程到此停止。请打开一个新的终端标签页并运行 
wandb login --verify
。请在 https://wandb.ai/authorize?ref=models 创建 API key。如果浏览器打开了其他页面，请再次打开此链接。请在那个终端中粘贴 key，而不是粘贴到这里，然后输入 continue。
在自托管或专用部署上，使用 
wandb login --verify --host <base-url>
以及该命令打印的授权页面。仍然只发送上述内容。
  • 如果检查不可用，或因连接或权限问题而失败，请将登录或访问状态报告为未验证并停止；不要假定凭据无效。
  • 用户继续操作后，确认应用运行时能够使用自身配置的凭据并访问 
    entity/project
    。浏览器登录并不等同于建立 SDK 身份验证。没有 
    .netrc
    回退机制的 Node/Forge 运行时需要由用户通过运行时 secret 机制配置凭据。

Choose the mechanism

选择机制

  • Explicit agent spans: use the Session SDK for turns, model calls, tools, and delegation when auto-instrumentation cannot produce the required tree. Read the Python or TypeScript reference.
  • Auto-instrumentation: use only when the installed SDK captures the library and desired span shape. Check Python's 
    INTEGRATION_MODULE_MAPPING
    or Node's 
    integrations/hooks.ts
    , then verify emitted spans. Read auto-instrumentation caveats; registry membership alone does not prove capture is active. Avoid duplicate manual wrapping.
  • Existing OTel pipeline: add Weave export to that provider using endpoint configuration.
A turn spans one user exchange, including its tool loop. An LLM span covers one model call through stream completion; a Tool covers execution; a SubAgent covers delegation. Record actual output/usage and preserve provider tool-call IDs. Keep return values, exceptions, retries, and cancellation unchanged. Close spans on failure and isolate concurrent conversations.
  • 显式 Agent span： 当自动埋点无法生成所需的树结构时，使用 Session SDK 跟踪轮次、模型调用、工具和委派。请阅读 Python 或 TypeScript 参考文档。
  • 自动埋点： 仅当已安装的 SDK 能够捕获相关库并生成所需的 span 形态时使用。检查 Python 的 
    INTEGRATION_MODULE_MAPPING
    或 Node 的 
    integrations/hooks.ts
    ，然后验证生成的 span。请阅读自动埋点注意事项；仅属于 registry 并不能证明捕获功能已启用。避免重复进行手动包装。
  • 现有 OTel pipeline： 使用 endpoint 配置，将 Weave export 添加到该 provider。
一个 turn span 涵盖一次用户交互，包括其工具循环。LLM span 覆盖从一次模型调用到流式完成的全过程；Tool span 涵盖执行过程；SubAgent span 涵盖委派。记录实际输出和用量，并保留 provider 的 tool-call ID。保持返回值、异常、重试和取消行为不变。失败时关闭 span，并隔离并发对话。

Implement incrementally

增量实施

Add one traced path at a time: a model call, its tool loop, then delegation or concurrency where applicable. After each change, run the path and follow read-back verification. Compare emitted and stored spans with the actual execution before extending the instrumentation.
Fix mismatches and rerun the same check before continuing. Empty results, failed queries, and unavailable checks are unverified, not passes. Stop at that boundary and report what the user must do to unblock verification.
每次只添加一条带追踪的路径：先处理一次模型调用，再处理其工具循环，然后在适用时处理委派或并发。每次更改后，运行该路径并按照回读验证执行检查。
扩展埋点之前，将生成并存储的 span 与实际执行情况进行对比。修复不一致之处，并在继续之前重新运行同一检查。空结果、失败的查询和不可用的检查均属于未验证，而不是通过。到达该边界时停止，并报告用户需要采取什么措施才能解除验证阻塞。

Verify

验证

Run relevant application tests and the conformance check for the paths you instrumented. If the full suite requires CI, browsers, or unavailable services, run focused local checks covering success and failure, and report the skipped coverage. Check parentage and 
gen_ai.operation.name
: 
invoke_agent
for turns/subagents, 
chat
for LLMs, 
execute_tool
for tools. Agent-shaped traces belong in Agents; flat calls in Calls. Confirm backend arrival when credentials are available; an init banner or successful flush is not delivery proof. Otherwise report the unverified surface and give the application's exact smoke command.
Adapted from Weave. Use the installed SDK's exports when they differ from these references.
针对已埋点的路径，运行相关应用测试和一致性检查。如果完整测试套件需要 CI、浏览器或当前不可用的服务，请运行覆盖成功和失败场景的重点本地检查，并报告跳过的覆盖范围。检查父级关系和 
gen_ai.operation.name
：turn 和 SubAgent 使用 
invoke_agent
，LLM 使用 
chat
，工具使用 
execute_tool
。Agent 形态的 trace 属于 Agents，扁平调用属于 Calls。
凭据可用时，确认数据已到达后端；init 横幅或成功 flush 并不能证明数据已送达。否则，报告未验证的范围，并给出应用精确的 smoke command。
改编自 Weave。 如果已安装 SDK 的导出接口与这些参考文档不同，请以已安装 SDK 的导出接口为准。