---
type: study
status: verified
created: 2026-08-11
updated: 2026-08-11
sensitivity: standard
tags:
  - study
  - langchain
  - python
  - integrations
  - callbacks
  - audit
  - observability
topic: LangChain Python Callback 遥测与防篡改审计
sources:
  - https://docs.langchain.com/oss/python/integrations/callbacks/agentsystems_notary
  - https://docs.langchain.com/oss/python/integrations/callbacks/google_bigquery
last_verified: 2026-08-11
---
# Callbacks：遥测与防篡改审计

## 两个路由解决不同问题

| 路由 | 安装/认证 | 解决的问题 |
|---|---|---|
| `agentsystems_notary` | `agentsystems-notary`；raw storage 凭证、签名 key、可选模型 key | 原始 LLM payload 留在自有存储，同时把 SHA-256 hash + namespace/session/timestamp metadata 写入 Arweave 或 custodied WORM storage，以后重新 hash 验证是否被修改。 |
| `google_bigquery` | `langchain-google-community[bigquery]`；GCP ADC/IAM | 把 LangChain/LangGraph event 写入 BigQuery，形成 trace、token、latency、tool/chain/retriever/agent lifecycle 分析和实时 dashboard。当前为 Preview，使用付费 Storage Write API。 |

## AgentSystems Notary

Notary 的价值是 tamper evidence：审计时用原始 payload 重算 hash，与独立存储比对。匹配说明提供的内容与已锚定 hash 一致；它不证明模型回答正确、输入真实、日志一定完整，也不替代身份、授权或业务审计。

页面的 decentralized 示例把完整 payload 放 S3，把 hash 放 Arweave，并用本地 RSA key 签名。生产应：

- 私钥放 KMS/HSM，轮换和恢复流程可演练；页面明确提示丢 key 会失去 ownership proof。
- Arweave namespace 是公开信息，应使用匿名 ID，并安全保存 customer/agent/environment 的映射。
- raw prompt/response 可能含高度敏感数据；S3 使用加密、最小权限、object lock/retention、访问审计和删除政策。
- 记录 callback 投递失败、hash storage 延迟和缺号；不能让 notary 故障无指标地丢审计证据。

## BigQuery Callback Handler

页面当前能力包括 LangGraph node 和 top-level invocation 事件、per-event typed views、additive schema upgrade、sub-agent attribution、token/cache/model/tool config、latency、allow/deny list、internal-chain noise filter、`flush()` 和 FastAPI dashboard。

运行边界：

- 先创建 dataset；handler 可自动建 events table/views，但生产建议用明确 DDL，按 date partition、event/agent/user cluster 管理。
- `flush(timeout)` 只排空队列，handler 仍可复用；进程最终退出调用 `shutdown()`。
- 内部 queue 默认最大 10,000，满时会丢新 event；必须监控 dropped count，不能把“应用成功”误当“审计已落库”。
- inline content 默认上限 500 KB；配置 GCS 时大内容 offload，否则截断/占位。`is_truncated` 和 object reference 要进入查询与告警。
- auto schema upgrade 只 additive add-column，不 drop/rename/retype；多 handler 共享 dataset 时 view prefix 需避免冲突。

IAM 页面要求 project-level BigQuery job user、table-level data editor；GCS offload 再加 object creator/viewer。实际生产可进一步拆建表/建 view 与仅写 event 的部署角色，避免运行账号长期拥有 DDL。

## 最关键的隐私陷阱

Handler 能记录 prompt、response、tool payload、session/user metadata 和 multimodal 内容。`content_formatter` 可用于 PII redaction，但文档明确：formatter 失败时会 warning 并回退到 raw content，确保不影响 agent。对隐私要求 fail-closed 的系统不能直接依赖这个默认行为，应在 callback 之前完成不可绕过的脱敏，或让日志管道拒绝写入并告警。

`session_id`、`user_id`、agent、custom tags 只存内部不可识别 ID；dashboard、views、signed GCS URL 和 conversational analytics 分别配置最小权限。日志 retention、location、查询费用、Storage Write 费用和 GCS 生命周期应一并治理。

## 可靠性与验证

- callback 不应改变业务结果，但 telemetry 丢失要有独立 SLO；高合规场景可能选择 fail-closed 或同步审计 outbox。
- 写入重试要有限且有 jitter，停机前 flush；网络分区/进程崩溃测试队列丢失窗口。
- 用 trace/span/parent、invocation/session/agent 维度核对事件闭合；过滤 internal chain 也要保留真实 root trace。
- Notary 与 BigQuery 可以互补：BigQuery 便于查询，独立 hash 用于检测篡改；仍需完整性序列、备份和访问审计。

## 验证边界

已完整读取两个官方 Markdown 路由及 BigQuery 配置/DDL/事件边界。没有真实写入 S3/Arweave/BigQuery，也没有验证队列、费用、KMS 或审计恢复流程。