OpenTelemetry Chroma 插桩实战:为 Chroma 向量数据库接入 OpenLLMetry 全链路可观测性
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 - 可选依赖:
instrumentsextra 对应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 |
注意两个细节:
_query是 Segment 层的内部方法。当用户调用collection.query()时,实际上会同时产生两个 Span:公开层chroma.query(记录查询参数与结果事件)和内部层chroma.query.segment._query(记录 collection_id 与查询向量事件)。仓库测试 test_query.py 对此有专门断言。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_countupsert:统计db.chroma.upsert.embeddings_count/metadatas_count/documents_countdelete:统计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:命中文档 iddb.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 会执行三件事:
- 写入
error.type属性(值为异常类名,如Exception) - 记录
exception事件(record_exception(e),含exception.message) - 将 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 从"黑盒"变成链路中可查询、可对比、可回溯的一环。