Hindsight 如何把 OpenTelemetry 分布式追踪接入 Tempo 等 OTLP 后端并查看 retain、recall 的 Span【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight如果你在运行 Hindsight 记忆服务想搞清楚每次retain、recall请求内部到底发生了什么查询嵌入、多路检索、RRF 融合、重排、LLM 调用分别花了多久Hindsight 自带的 OpenTelemetry 分布式追踪可以帮你做到它遵循 GenAI semantic conventions v1.37把这些操作导出为标准 OTLP Span写入 Tempo或其他任意 OTLP 兼容后端再在 Grafana 的 Explore 页面按 Span 层级查看。本文的路径是用仓库自带的 Grafana LGTM 单容器栈起一个 Tempo 后端给 Hindsight API 配两个环境变量开启导出然后在 Grafana 里找到hindsight.retain/hindsight.recall的 Span 树。前提条件Hindsight API 已在运行开发脚本默认使用端口 8888可通过API_PORT覆盖检测端口本机有 Docker 和 docker-compose本地监控栈是一个单容器 Grafana LGTM约 515MB 镜像docker-compose 配置里声明了外部网络hindsight-network该网络不存在时容器起不来需要先用docker network create hindsight-network创建。启动 Tempo 监控栈在仓库根目录执行./scripts/dev/start-monitoring.sh该脚本实际执行docker-compose up前台运行CtrlC 退出启动一个同时提供 Grafana UI、Tempo、Prometheus/Mimir、Loki 的容器并自动挂载 monitoring/grafana/dashboards/ 下的三块预置面板Hindsight Operations、Hindsight LLM Metrics、Hindsight API Service。如果 API 未在localhost:8888检测到脚本会打印警告提示你先运行./scripts/dev/start-api.sh但不阻塞监控栈本身启动。关键端口来自 scripts/dev/monitoring/README.md端口服务3000Grafana UI4317OTLP gRPC endpoint4318OTLP HTTP endpoint不用脚本也可以手动启动cd scripts/dev/monitoring docker-compose up -d。停止监控栈用cd scripts/dev/monitoring docker-compose down这会停止并移除该容器不影响 Hindsight API 本身。注意一处文档不一致configuration.md 的 OpenTelemetry 小节写的是./scripts/dev/start-grafana.sh而 monitoring.md 与仓库实际存在的脚本都是./scripts/dev/start-monitoring.sh。仓库中只有后者本文按实际存在的脚本写。配置 Hindsight API 导出 OTLP Traces给 API 设置以下环境变量后重启monitoring.md 建议直接写入.env开发脚本启动 API 时会加载它# 启用分布式追踪默认 false不开则不导出任何 Span export HINDSIGHT_API_OTEL_TRACES_ENABLEDtrue # Tempo 的 OTLP HTTP 端点本地 LGTM 栈 export HINDSIGHT_API_OTEL_EXPORTER_OTLP_ENDPOINThttp://localhost:4318可选变量默认值来自 configuration.md变量用途默认值HINDSIGHT_API_OTEL_EXPORTER_OTLP_HEADERSOTLP 导出请求头格式key1value1,key2value2-HINDSIGHT_API_OTEL_SERVICE_NAME服务名。API 与独立 worker 共用该变量worker 未设置时默认报为hindsight-workerhindsight-apiHINDSIGHT_API_OTEL_DEPLOYMENT_ENVIRONMENT部署环境名如development、productiondevelopmentOTEL_PYTHON_FASTAPI_EXCLUDED_URLS排除出请求追踪的 URL 模式逗号分隔健康检查等探针流量不产生 Spanhealth,metrics独立 worker 进程遵守同一组HINDSIGHT_API_OTEL_*变量并导出自己的 Span。consolidation、后台 retain、mental model refresh 这些长耗时、高 token 开销的任务大多发生在 worker 里所以如果部署了专用 worker也要给它配上同样的两个变量可以用独立的HINDSIGHT_API_OTEL_SERVICE_NAME把它和 API 在追踪后端里区分开。在 Grafana 中查看 retain、recall 的 Span当 API 处理了 retain / recall 请求后按以下步骤在 Grafana 里找到对应 Span步骤来自 scripts/dev/monitoring/README.md打开 http://localhost:3000本地栈开启了匿名管理员无需登录进入Explore指南针图标数据源选择Tempo点击 Search 查看最近抓到的 traces。找到 trace 后能看到的 Span 层级是固定的来自 monitoring.md 的 Span Hierarchy 一节父 Span操作级hindsight.retain— 记忆写入hindsight.recall— 记忆检索其下有四个子 Spanhindsight.recall_embedding— 查询嵌入hindsight.recall_retrieval— 并行检索semantic、BM25、graph、temporalhindsight.recall_fusion— Reciprocal Rank Fusionhindsight.recall_rerank— cross-encoder 重排hindsight.reflect/hindsight.consolidation/hindsight.mental_model_refresh— 其他操作子 SpanLLM 调用按 scope 命名如hindsight.memory、hindsight.reflect完整 prompt/completion 记录为 Span 上的事件event属性遵循 GenAI 语义约定包括gen_ai.operation.name恒为chat、gen_ai.provider.name、gen_ai.request.model、gen_ai.usage.input_tokens、gen_ai.usage.output_tokens、hindsight.scope。操作 Span 上的属性hindsight.operation操作类型、hindsight.bank_id记忆库 ID、hindsight.query查询文本截断到 100 字符、hindsight.fact_types、hindsight.thinking_budget、hindsight.max_tokens。接入其他 OTLP 后端可选追踪实现走标准 OTLP HTTP 协议因此不止 TempoGrafana LGTM、Langfuse、OpenLIT、DataDog、New Relic、Honeycomb、Pydantic Logfire 等任意 OTLP 兼容后端都可以直接接。区别只是把端点和请求头换成目标后端要求的值。configuration.md 给出的 OpenLIT Cloud 示例export HINDSIGHT_API_OTEL_TRACES_ENABLEDtrue # olit-xxx 是文档中的占位值替换为你自己的 OpenLIT API key export HINDSIGHT_API_OTEL_EXPORTER_OTLP_ENDPOINThttps://otlp.openlit.io export HINDSIGHT_API_OTEL_EXPORTER_OTLP_HEADERSAuthorizationBearer olit-xxx另外如果调用方自己也做了 OpenTelemetry 插桩并在请求里携带 W3Ctraceparent头Hindsight 会延续调用方的 traceAPI 请求作为 server span 挂在调用方下面其触发的所有记忆操作和 LLM 调用都嵌套在其中没有 trace context 的请求则照常自建 trace。边界与限制本地 LGTM 栈仅面向开发。文档明确说明生产环境应单独部署 Grafana LGTM 或使用 Grafana Cloud、DataDog、New Relic 等平台且本地栈开启了匿名管理员登录不要暴露在公网。worker 的 Span 目前是独立 trace后台任务运行在触发它的请求返回很久之后不会与那次请求的 trace 关联。健康检查和/metrics端点默认被排除出追踪OTEL_PYTHON_FASTAPI_EXCLUDED_URLS默认health,metrics探针流量不会淹没真实操作的 Span如需调整改这个变量即可。【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考