OpenTelemetry Chroma 插桩实战:为 Chroma 向量数据库接入 OpenLLMetry 全链路可观测性

原创2026-10-14 09:00:441,669 阅读
文章标签:LLMOps可观测性

OpenTelemetry Chroma 插桩实战:为 Chroma 向量数据库接入 OpenLLMetry 全链路可观测性

本文以 openllmetry 仓库中的 opentelemetry-instrumentation-chromadb 包为蓝本,系统讲解如何用 OpenTelemetry 追踪 Chroma 向量数据库的客户端调用:从安装、一行代码接入,到 9 类 Collection 操作产生的 Span 属性、查询结果事件与错误处理语义。读完本文,你将能在 RAG 应用中为 Chroma 的增删改查自动生成标准化追踪数据,并看懂其后端语义约定与实现原理。

1. 包概览:追踪 Chroma 客户端调用的轻量插桩

opentelemetry-instrumentation-chromadb 是 openllmetry 项目(基于 OpenTelemetry 的开源 GenAI/LLM 可观测性方案)中的向量数据库插桩包之一。它解决的问题是:使用官方 Chroma library 时,客户端侧对 Chroma 的每一次调用(写入、读取、查询、修改、删除)都处于可观测性盲区——既没有耗时、也没有参数和结果信息,无法和 LLM 调用串成完整链路。

该包通过 wrapt 对 Chroma 客户端对象做函数包装(wrapping),无需改动业务代码即可为每次调用创建 OpenTelemetry Span。从仓库结构看,包体由 5 个文件组成:

  • init.py:定义 ChromaInstrumentor 与待包装方法清单
  • wrapper.py:Span 创建、属性写入与事件生成的核心逻辑
  • config.py:Config 类,目前仅承载 exception_logger
  • utils.py:dont_throw 装饰器,保证插桩逻辑自身异常不干扰业务
  • version.py:包版本号(仓库当前为 0.62.4)

2. 安装与版本约束

按 README.md 提供的标准安装方式:

pip install opentelemetry-instrumentation-chromadb

从 pyproject.toml 可以确认更完整的依赖与约束信息:

  • Python 版本:>=3.10,<4
  • 核心依赖:opentelemetry-api>=1.38.0,<2、opentelemetry-instrumentation>=0.59b0、opentelemetry-semantic-conventions-ai>=0.5.1,<0.6.0(本包使用的 db.chroma.* 属性与 db.query.* 事件名均来自该语义约定包)、opentelemetry-semantic-conventions>=0.63b1
  • 可选依赖:instruments extra 对应 chromadb 本体
  • 插桩目标版本:_instruments = ("chromadb >= 0.3",)(定义于 init.py),即支持 0.3 及以上的 Chroma 客户端;而测试环境使用 chromadb>=0.5.0,<0.6.0

如果你使用 uv 管理依赖(仓库内各包均采用 uv,见 poetry.toml 与 uv.lock),也可以参考 project.json 中定义的 Nx 任务(uv sync --all-groups 安装、uv run pytest tests/ 测试、uv run ruff check . 静态检查)在包目录下完成开发环境搭建。

3. 快速开始:一行代码接入

README.md 给出的最小示例只有两行:

from opentelemetry.instrumentation.chromadb import ChromaInstrumentor

ChromaInstrumentor().instrument()

在真实场景中,还需要先配置 TracerProvider 与 SpanProcessor,追踪数据才有去处。参照仓库测试的 conftest.py 写法,一个完整的最小接入示例是:

from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import SimpleSpanProcessor
from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter
from opentelemetry.instrumentation.chromadb import ChromaInstrumentor

# 1. 配置 SDK 并注册导出器
provider = TracerProvider()
provider.add_span_processor(SimpleSpanProcessor(OTLPSpanExporter()))
trace.set_tracer_provider(provider)

# 2. 插桩 Chroma(在创建 client / collection 之前执行)
ChromaInstrumentor().instrument()

# 3. 之后的 Chroma 调用会自动产生 Span
import chromadb

client = chromadb.PersistentClient(path="./chroma_data")
collection = client.create_collection(name="docs")
collection.add(ids=["id1"], documents=["hello chroma"])
collection.query(query_texts=["hello"], n_results=1)

instrument() 支持传入 tracer_provider 关键字参数,以覆盖全局 provider(见 init.py):

ChromaInstrumentor().instrument(tracer_provider=provider)

对应的卸载接口为 ChromaInstrumentor().uninstrument(),它会逐个 unwrap 已包装的方法,便于在测试或动态开关场景中恢复原始行为。

4. 被追踪的方法与 Span 命名

插桩的落点由 init.py 中的 WRAPPED_METHODS 清单决定,共 9 个:

目标对象 方法 Span 名称
chromadb.api.segment.SegmentAPI _query chroma.query.segment._query
chromadb.Collection add chroma.add
chromadb.Collection get chroma.get
chromadb.Collection peek chroma.peek
chromadb.Collection query chroma.query
chromadb.Collection modify chroma.modify
chromadb.Collection update chroma.update
chromadb.Collection upsert chroma.upsert
chromadb.Collection delete chroma.delete

注意两个细节:

  1. _query 是 Segment 层的内部方法。当用户调用 collection.query() 时,实际上会同时产生两个 Span:公开层 chroma.query(记录查询参数与结果事件)和内部层 chroma.query.segment._query(记录 collection_id 与查询向量事件)。仓库测试 test_query.py 对此有专门断言。
  2. peek(取少量样本)、modify(修改 collection 名称/元数据)这类低频操作也被覆盖,说明插桩目标是完整的方法面而非仅查询路径。

每个 Span 在创建时都会被打上两个基础属性(见 wrapper.py):

  • db.system = "chroma":标识数据库系统
  • db.operation = <方法名>:标识本次操作,如 add、query

这两项对应 OpenTelemetry 语义约定中的 DB_SYSTEM / DB_OPERATION 常量,保证追踪数据可被任何兼容 OTel 的后端(如 Jaeger、Tempo、Traceloop)统一解析。

5. 各操作的 Span 属性详解

属性名全部来自语义约定包 opentelemetry-semantic-conventions-ai 中的 SpanAttributes.CHROMADB_* 常量,按操作分组如下。

5.1 add(写入)

在 wrapper.py 的 _set_add_attributes 中,对 add() 的 4 个核心入参统计数量:

属性 含义
db.chroma.add.ids_count 传入的 ids 数量
db.chroma.add.embeddings_count 传入的 embeddings 数量
db.chroma.add.metadatas_count 传入的 metadatas 数量
db.chroma.add.documents_count 传入的 documents 数量

计数采用 count_or_none 逻辑(wrapper.py):参数存在时取 len(),为空/缺失时返回 None 且不写入属性。这样可以在不复制文档全文的前提下,让分析端一眼看出单次写入的规模——这在批量灌库场景(如 sample-app 中每批 100 条写入 chroma_app.py)非常有用。

5.2 get(读取)

get 的属性(_set_get_attributes,wrapper.py)直接反映筛选参数:

  • db.chroma.get.ids_count:按 id 获取时的数量
  • db.chroma.get.where:过滤条件,经 _encode_where 转为字符串(str(where))
  • db.chroma.get.where_document:文档内容过滤条件字符串
  • db.chroma.get.limit / db.chroma.get.offset:分页参数
  • db.chroma.get.include:返回内容选择(如 ["documents", "metadatas"])

5.3 peek(取样)

peek 仅记录 db.chroma.peek.limit,即采样条数(wrapper.py)。

5.4 query(查询,核心路径)

query 的属性(_set_query_attributes,wrapper.py)是最丰富的:

属性 含义
db.chroma.query.embeddings_count query_embeddings 数量(按向量检索)
db.chroma.query.texts_count query_texts 数量(按文本检索)
db.chroma.query.n_results 返回结果条数(即 top-k)
db.chroma.query.where 过滤条件字符串
db.chroma.query.where_document 文档过滤条件字符串
db.chroma.query.include 返回内容选择

此外还有 Segment 层的 db.chroma.query.segment._query.collection_id,记录实际查询的 collection id(_set_segment_query_attributes,wrapper.py)。注意该函数兼容位置参数与关键字参数两种传参方式:collection_id 既可能通过 kwargs.get("collection_id") 拿到,也可能作为位置参数 args[0] 传入——从源码结构看,这是为了适配不同 Chroma 版本的内部调用约定。

5.5 modify / update / upsert / delete

  • modify:记录 db.chroma.modify.name(新名称);代码中留有 # TODO: Add metadata attribute 注释(wrapper.py),说明元数据属性尚未实现
  • update:与 add 对称,统计 db.chroma.update.ids_count / embeddings_count / metadatas_count / documents_count
  • upsert:统计 db.chroma.upsert.embeddings_count / metadatas_count / documents_count
  • delete:统计 db.chroma.delete.ids_count,并记录 db.chroma.delete.where / where_document

6. 查询级事件:向量与结果的可观测细节

仅靠属性只能描述“查了什么”,无法描述“查到了什么”。该包在 Span 事件(Event) 层面补充了两种关键数据,事件名与属性名定义在语义约定包的 Events / EventAttributes 枚举中(semconv_ai/init.py)。

6.1 db.query.embeddings(查询向量)

在 Segment 层 _query 的 Span 上,每次查询的每个 query_embeddings 都会产生一个 db.query.embeddings 事件,携带 db.query.embeddings.vector 属性——即向量本身的 JSON 序列化(json.dumps,兼容 numpy 数组的 tolist(),见 wrapper.py)。

测试 test_query.py 验证了向量长度与数值范围(Chroma 默认 embedding 函数输出的归一化向量各分量落在 [-1, 1] 区间)。这意味着后端可以直接回放“用哪个向量做了检索”。

6.2 db.query.result(查询结果)

query 的 Span 会为每一个返回结果生成一个 db.query.result 事件,属性包括:

  • db.query.result.id:命中文档 id
  • db.query.result.distance:距离值
  • db.query.result.metadata:元数据(dict 会被 JSON 序列化)
  • db.query.result.document:命中文档内容

实现位于 _add_query_result_events(wrapper.py)。由于 Chroma 查询结果是"每个查询一个内层列表"的嵌套结构(ids、distances、metadatas、documents 四个平行 list-of-lists),源码用两层 itertools.zip_longest 展开:外层按查询个数遍历,内层按 n_results 逐条产生事件。因此:

  • 单次查询 n_results=2 → 恰好 2 个 db.query.result 事件
  • 2 个 query_embeddings × n_results=2 → 共 4 个事件

这一行为被 test_query_results.py 以"回归测试"的形式锁定(该文件开头注明对应 issue #1870,即修复过"一次查询只产生 1 个结果事件"的缺陷),其测试用例 test_chromadb_multi_query_returns_all_chunks 明确断言 2×2=4 个事件。

在 RAG 排查场景中,这套事件让工程师能直接回答三个问题:召回的是哪些 chunk?距离(相似度)是多少?这些 chunk 喂给了哪个 LLM prompt?——事件与 LLM Span 结合,即可还原完整的 RAG 链路。

7. 错误处理与异常语义

当被包装的 Chroma 调用抛异常时,wrapper.py 会执行三件事:

  1. 写入 error.type 属性(值为异常类名,如 Exception)
  2. 记录 exception 事件(record_exception(e),含 exception.message)
  3. 将 Span 状态置为 ERROR,并携带异常信息字符串

随后重新抛出原始异常,保证业务代码的异常语义不被吞掉。测试 test_error_handling.py 通过 mock 让内部 _add / _query 抛错,验证了 StatusCode.ERROR、error.type 与 exception 事件三者齐备。

与上述"业务异常如实上报"互补的是 dont_throw 装饰器(utils.py):它包裹的是属性写入函数(_set_add_attributes 等),保证即使插桩自身的取值/序列化逻辑出错,也只记 debug 日志而绝不影响真正的数据库调用——这是插桩库的健壮性底线。

8. 可配置项:exception_logger

插桩器目前只暴露一个配置点。构造 ChromaInstrumentor(exception_logger=...) 时,传入的可调用对象会被存入 Config.exception_logger(config.py),并在 dont_throw 捕获到插桩层异常时被回调(utils.py)。

典型用法:把插桩自身的异常接到你的错误监控体系(如 Sentry、日志系统):

def my_exception_logger(exc):
    logging.getLogger("chroma_instrumentation").error("trace failed", exc_info=exc)

ChromaInstrumentor(exception_logger=my_exception_logger).instrument()

9. 在真实 RAG 应用中的集成方式

仓库的 sample-app 提供了完整的落地参考。在 chroma_app.py 中,一个基于 SciFact 语料的 RAG 流程展示了本包的实际价值:

from traceloop.sdk import Traceloop

Traceloop.init(app_name="chroma_app")   # 自动装载包括 Chroma 在内的插桩

chroma_client = chromadb.Client()
scifact_corpus_collection = chroma_client.create_collection(
    name="scifact_corpus", embedding_function=embedding_function
)

# 批量灌库:每批 100 条,产生 chroma.add Span(带各计数属性)
for i in range(0, len(corpus_df), batch_size):
    scifact_corpus_collection.add(
        ids=batch_df["doc_id"].apply(lambda x: str(x)).tolist(),
        documents=...,
        metadatas=[{"structured": structured} for structured in ...],
    )

# 检索:产生 chroma.query Span + db.query.result 事件
claim_query_result = scifact_corpus_collection.query(
    query_texts=claims, include=["documents", "distances"], n_results=3
)

该示例展示了两个要点:一是通过 Traceloop.init 可自动启用插桩(本包同时注册了 opentelemetry_instrumentor 入口点,见 pyproject.toml,因此也支持 opentelemetry-instrument 自动插桩方式);二是Chroma 查询 → OpenAI 补全的前后衔接——chroma.query 的 db.query.result 事件与后续 chat.completions 的 LLM Span 处于同一 trace 上下文,检索质量与生成质量可以互相印证。

类似的集成还出现在 llama-index 生态中,见 llama_index_chroma_huggingface_app.py(通过 ChromaVectorStore 使用 Chroma),说明该插桩对上层框架的访问同样生效——只要最终调用落在 chromadb.Collection 的方法上。

10. 如何验证插桩效果

如果你想在本地快速验证 Span 产出,可以直接复用仓库测试的验证思路。最小验证脚本:

from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import SimpleSpanProcessor
from opentelemetry.sdk.trace.export.in_memory_span_exporter import InMemorySpanExporter
from opentelemetry.instrumentation.chromadb import ChromaInstrumentor
import chromadb

exporter = InMemorySpanExporter()
provider = TracerProvider()
provider.add_span_processor(SimpleSpanProcessor(exporter))
trace.set_tracer_provider(provider)
ChromaInstrumentor().instrument()

client = chromadb.EphemeralClient()
col = client.create_collection(name="demo")
col.add(ids=["a", "b"], documents=["doc a", "doc b"])
col.query(query_texts=["doc"], n_results=2)

for span in exporter.get_finished_spans():
    print(span.name, dict(span.attributes), [e.name for e in span.events])

预期输出会包含:chroma.add(带 db.chroma.add.*_count 属性)、chroma.query(带 db.chroma.query.* 属性与 2 个 db.query.result 事件)、chroma.query.segment._query(带 collection_id 与 db.query.embeddings 事件)。仓库的 conftest.py 正是采用这套 InMemory 方案,可直接对照。

11. 小结:一套属性 + 两类事件的可观测模型

综合来看,opentelemetry-instrumentation-chromadb 为 Chroma 建立了"基础标识属性(db.system / db.operation)+ 操作参数属性(db.chroma.*)+ 查询级事件(db.query.embeddings / db.query.result)+ 异常语义(error.type / exception 事件)"四层可观测模型:

  • 基础属性让所有 Chroma 调用可被统一筛选与聚合;
  • 参数属性忠实记录每次操作的规模与筛选条件,便于性能分析(如大批量 add、低效的 where 条件);
  • 查询事件把"召回内容"写入链路,支撑 RAG 质量归因;
  • 异常语义确保错误路径同样可观测且不改变业务行为。

这套模型与仓库中其他向量数据库插桩(Pinecone、Milvus、Qdrant、Weaviate 等,均共享 opentelemetry-semantic-conventions-ai 的 db.* 命名空间)保持一致,是 openllmetry 在向量检索可观测性上的统一设计。接入它只需 pip install 加一行 ChromaInstrumentor().instrument(),即可让 Chroma 从"黑盒"变成链路中可查询、可对比、可回溯的一环。

登录后查看全文
openllmetry