OpenLLMetry 实战:使用 opentelemetry-instrumentation-milvus 为 Milvus 向量检索接入 OpenTelemetry 全链路可观测
OpenLLMetry 实战:使用 opentelemetry-instrumentation-milvus 为 Milvus 向量检索接入 OpenTelemetry 全链路可观测
本指南以 openllmetry 仓库中的 opentelemetry-instrumentation-milvus 包为主体,系统讲解如何对官方 pymilvus 客户端发起的建集合、写入、查询与向量检索调用进行自动插桩(instrumentation),生成符合 OpenTelemetry 语义约定的 Span、事件与指标。读完本文,你将掌握该插桩包的安装方式、支持拦截的全部 Milvus 操作、各类 Span 属性与事件指标的含义、错误处理机制,以及底层基于 wrapt 的包装实现原理,能够在 RAG / 知识库类应用中直接落地向量库调用追踪。
一、这个插桩包解决什么问题
在基于大模型的 RAG(检索增强生成)应用中,Milvus 作为向量数据库承担着"召回最相关片段"的关键职责,查询链路往往包含:文本向量化(Embedding)→ 写入 Milvus → 检索召回 → 送入 LLM 生成。opentelemetry-instrumentation-milvus 正是为这条链路上的向量库环节补齐可观测能力:它会在客户端侧(即你的应用进程内)自动拦截对官方 Milvus library(即 pymilvus)的调用,无需改动业务代码,即可生成:
- Span(追踪):记录每次 Milvus 调用的操作类型、集合名、过滤表达式、检索参数与结果统计;
- Event(事件):逐条记录查询/检索返回的实体与距离,便于后续分析召回质量;
- Metric(指标):统计查询耗时、检索距离、插入/更新/删除单位消耗,可用于容量规划与性能监控。
该包属于 openllmetry 项目(Open-source observability for your GenAI or LLM application, based on OpenTelemetry)旗下的数据库插桩家族,与仓库中的 opentelemetry-instrumentation-pinecone、opentelemetry-instrumentation-qdrant 等向量库插桩共用同一套语义约定体系(见 opentelemetry-semantic-conventions-ai),保证不同向量库之间的观测数据口径一致。
二、安装与依赖前提
通过 pip 直接安装:
pip install opentelemetry-instrumentation-milvus
安装前请注意以下前提条件(以当前仓库 pyproject.toml 为准):
| 依赖项 | 版本要求 | 说明 |
|---|---|---|
| Python | >=3.10,<4 |
运行环境要求 |
| pymilvus | >=2.4.1 |
被插桩的目标客户端库,声明于 _instruments = ("pymilvus >= 2.4.1",) |
| opentelemetry-api | >=1.38.0,<2 |
基础观测 API |
| opentelemetry-instrumentation | >=0.59b0 |
提供 BaseInstrumentor 基类与包装工具 |
| opentelemetry-semantic-conventions-ai | >=0.5.2,<0.6.0 |
提供 Milvus / 向量库语义约定与指标名定义 |
如果你希望本地运行测试,可以使用可选依赖 pymilvus[milvus_lite],它内置了嵌入式 Milvus,无需单独部署服务端即可验证插桩效果。此外,该包在 pyproject.toml 中注册了 OpenTelemetry 标准的自动插桩入口点:
[project.entry-points."opentelemetry_instrumentor"]
milvus = "opentelemetry.instrumentation.milvus:MilvusInstrumentor"
这意味着除了手动 instrument(),它也能被 opentelemetry-instrument 命令行工具按名称自动加载。
三、快速开始
原文档给出的最小接入方式只有三行(其中两行是导入与初始化):
from opentelemetry.instrumentation.milvus import MilvusInstrumentor
MilvusInstrumentor().instrument()
调用 instrument() 之后,你的应用中对 pymilvus.MilvusClient 的相关方法调用即会被自动包装。一个完整的最小可运行示例(结合仓库测试中的用法,见 tests/conftest.py):
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.milvus import MilvusInstrumentor
import pymilvus
# 1. 配置 TracerProvider(生产环境请替换为 OTLP 等真实导出器)
exporter = InMemorySpanExporter()
provider = TracerProvider()
provider.add_span_processor(SimpleSpanProcessor(exporter))
trace.set_tracer_provider(provider)
# 2. 插桩 Milvus 客户端
MilvusInstrumentor().instrument()
# 3. 正常的 Milvus 调用,无需任何业务改动
milvus = pymilvus.MilvusClient(uri="./milvus_demo.db")
milvus.create_collection(collection_name="Colors", dimension=5)
milvus.insert(collection_name="Colors", data=[{"id": 1, "vector": [0.1, 0.2, 0.3, 0.4, 0.5]}])
# 4. 此时即可在 exporter 中取到名为 milvus.insert 的 Span
for span in exporter.get_finished_spans():
print(span.name, span.attributes)
需要说明的是,instrument() 通过 _instrument 钩子完成包装;当不再需要时,可以调用 MilvusInstrumentor().uninstrument() 恢复原始方法(对应 _uninstrument 钩子,见 init.py)。
四、支持拦截的 8 类 Milvus 操作与 Span 命名
在 init.py 中,WRAPPED_METHODS 明确定义了被包装的方法与 Span 名称:
| pymilvus.MilvusClient 方法 | Span 名称 | 拦截时机 |
|---|---|---|
create_collection |
milvus.create_collection |
创建集合 |
insert |
milvus.insert |
插入数据 |
upsert |
milvus.upsert |
插入或更新(按主键) |
delete |
milvus.delete |
按主键/过滤条件删除 |
search |
milvus.search |
向量相似度检索 |
get |
milvus.get |
按主键批量取数据 |
query |
milvus.query |
标量条件查询 |
hybrid_search |
milvus.hybrid_search |
混合检索(多路召回 + Ranker 融合) |
包装逻辑封装在 wrapper.py 的 _wrap 函数中:它为每个调用开启一个以 Span 名称为名的当前 Span,写入通用属性,再根据方法名分派到不同的属性采集函数,最后调用原始方法并统计结果。每个 Span 都会写入两个通用属性:
db.system=milvus(沿用 OpenTelemetry 数据库语义约定的db.system属性)db.operation= 方法名(如insert、search)
这也与仓库测试中的断言一致:span.attributes.get(SpanAttributes.VECTOR_DB_VENDOR) == "milvus",而 VECTOR_DB_VENDOR = "db.system"、VECTOR_DB_OPERATION = "db.operation" 定义于 opentelemetry-semantic-conventions-ai 的 SpanAttributes。
五、Span 属性:从请求参数到结果统计
插桩会根据操作类型,从调用参数(kwargs)中提取高价值属性写入 Span。所有属性名均定义在 semconv_ai/init.py 的 SpanAttributes 中,统一采用 db.milvus.<操作>.<字段> 的命名风格。下面按操作分组列出(与 wrapper.py 源码一一对应):
create_collection
| 属性 | 对应参数 | 说明 |
|---|---|---|
db.milvus.create_collection.collection_name |
collection_name |
集合名 |
db.milvus.create_collection.dimension |
dimension |
向量维度 |
db.milvus.create_collection.primary_field |
primary_field_name |
主键字段名 |
db.milvus.create_collection.metric_type |
metric_type |
距离度量类型(如 COSINE / IP / L2) |
db.milvus.create_collection.timeout |
timeout |
超时时间(秒) |
db.milvus.create_collection.id_type |
id_type |
主键类型 |
db.milvus.create_collection.vector_field |
vector_field_name |
向量字段名 |
insert / upsert
| 属性 | 说明 |
|---|---|
db.milvus.insert.collection_name / db.milvus.upsert.collection_name |
集合名 |
db.milvus.insert.data_count / db.milvus.upsert.data_count |
写入数据条数(len(data)) |
db.milvus.insert.partition_name / db.milvus.upsert.partition_name |
分区名(若指定) |
db.milvus.insert.timeout / db.milvus.upsert.timeout |
超时时间 |
delete
| 属性 | 说明 |
|---|---|
db.milvus.delete.collection_name |
集合名 |
db.milvus.delete.ids_count |
待删除主键数量 |
db.milvus.delete.filter |
过滤表达式(字符串化) |
db.milvus.delete.partition_name |
分区名 |
db.milvus.delete.timeout |
超时时间 |
get
| 属性 | 说明 |
|---|---|
db.milvus.get.collection_name |
集合名 |
db.milvus.get.ids_count |
主键数量 |
db.milvus.get.output_fields_count |
输出字段数量 |
db.milvus.get.partition_names_count |
分区数量 |
db.milvus.get.timeout |
超时时间 |
query(标量条件查询)
| 属性 | 说明 |
|---|---|
db.milvus.query.collection_name |
集合名 |
db.milvus.query.filter |
过滤表达式,如 'color == "brown"' |
db.milvus.query.ids_count |
主键数量 |
db.milvus.query.limit |
返回条数上限 |
db.milvus.query.output_fields_count |
输出字段数量 |
db.milvus.query.partition_names_count |
分区数量 |
db.milvus.query.timeout |
超时时间 |
search(向量检索)
| 属性 | 说明 |
|---|---|
db.milvus.search.collection_name |
集合名 |
db.milvus.search.data_count |
查询向量条数 |
db.milvus.search.anns_field |
向量字段名 |
db.milvus.search.limit |
top-k 条数 |
db.milvus.search.filter |
检索前过滤表达式 |
db.milvus.search.search_params |
检索参数(如 {"radius": 0.5, "metric_type": "COSINE"}) |
db.milvus.search.query_vector_dimension |
各查询向量的维度列表 |
db.milvus.search.output_fields_count |
输出字段数量 |
db.milvus.search.partition_names_count / partition_names |
分区统计与名单 |
db.milvus.search.timeout |
超时时间 |
db.milvus.search.embeddings_count |
查询向量数量(调用方未传 data 时不写) |
db.milvus.search.result_count |
命中结果总数(单向量检索场景) |
hybrid_search(混合检索)
| 属性 | 说明 |
|---|---|
db.milvus.search.collection_name |
集合名 |
db.milvus.search.annsearch_request |
各路检索请求信息列表(anns_field + param) |
db.milvus.search.ranker_type |
Ranker 类名,如 RRFRanker |
db.milvus.search.limit / data_count / output_fields_count / timeout |
同 search 语义 |
值得注意的一个设计细节是"计数类属性统一用数量而非原始列表":源码通过 count_or_none() 把 ids、data、output_fields 等列表参数转换为 len() 长度,从而避免把整批向量或大量主键 ID 写入属性导致数据膨胀;而真正需要明细的地方(如 filter、search_params、ranker_type)则以字符串形式保留。
跨库标准化属性(VECTOR_DB 命名空间)
除 db.milvus.* 专属属性外,插桩还输出一组跨向量库统一的标准化属性(源码注释中标注为 issue #1870 引入),定义于 semconv_ai/init.py:
| 属性 | 含义 |
|---|---|
db.vector.query.embeddings_count |
本次查询的向量条数(与 db.milvus.search.embeddings_count 同时写入) |
db.vector.query.result_count |
命中的结果总数(无命中时为 0,语义明确) |
db.vector.query.top_distance |
命中最优(最小)距离,仅在存在距离数据时写入 |
这套属性与 Pinecone、Qdrant 等插桩保持一致,方便在不同向量库之间做横向对比。
六、事件(Events):逐条结果的可观测明细
除了 Span 属性中的聚合统计,插桩还会把每一条返回结果作为 Span 事件(Event)记录下来(对应 Events 枚举):
query 操作 → db.query.result 事件
每行返回记录产生一个事件,事件属性直接取自该行的实体字段(如 color_tag、id 等)。在 wrapper.py 中实现。
search / hybrid_search → db.search.result 事件
每个匹配项产生一个事件,属性包括(定义于 EventAttributes,见 semconv_ai/init.py):
| 事件属性 | 含义 |
|---|---|
db.search.query.id |
查询向量序号(多向量检索时区分是哪一路查询) |
db.search.result.id |
命中记录的主键 |
db.search.result.distance |
该条命中与查询向量的距离(字符串形式) |
db.search.result.entity |
命中的实体内容(JSON 字符串) |
对于单向量检索,插桩还会在 Span 上写入 db.milvus.search.result_count(总命中数);对于多向量检索,则按查询序号写入 db.milvus.search.result_count_<query_idx> 形式的分组计数(见 wrapper.py)。这些事件非常适合用来排查"召回结果是否符合预期"、分析距离分布等精细化问题。
七、指标(Metrics):耗时、距离与写入单位消耗
当指标功能开启时,插桩会注册 5 个指标(实现见 init.py,名称定义于 Meters 枚举,见 semconv_ai/init.py):
| 指标名 | 类型 | 单位 | 含义 |
|---|---|---|---|
db.client.query.duration |
Histogram | s |
query 操作耗时 |
db.client.search.distance |
Histogram | 无 | 检索命中的距离分布 |
db.client.usage.insert_units |
Counter | 无 | insert 写入单位消耗(serverless 场景) |
db.client.usage.upsert_units |
Counter | 无 | upsert 写入单位消耗 |
db.client.usage.delete_units |
Counter | 无 | delete 写入单位消耗 |
这些指标都携带 db.system=milvus、db.operation=<方法名> 的公共维度,便于按操作类型聚合。指标上报的触发逻辑位于 wrapper.py:query 完成后记录耗时(仅当耗时 > 0);search / hybrid_search 完成后逐条记录距离;insert / upsert / delete 完成后从返回的 insert_count / upsert_count / delete_count 累加单位消耗。
开关与环境变量:指标默认开启。若希望关闭指标仅保留追踪,可设置环境变量 TRACELOOP_METRICS_ENABLED=false(判断逻辑在 utils.py 中,取值为 "true" / "false",不区分大小写)。关闭后插桩仍会创建 Span,但不会注册上述指标。
八、错误处理:error.type 与异常原样抛出
当 Milvus 调用抛出异常时,插桩会做两件事(见 wrapper.py):
- 在 Span 上写入
error.type属性,值为规范化后的错误类型; - 将异常原样重新抛出,保证业务侧的错误处理行为完全不受影响,Span 状态也会被标记为 ERROR。
error.type 的取值来源有两处:pymilvus.client.types.Status 中的整数状态码枚举名,以及 pymilvus.exceptions.ErrorCode 的枚举名(见 wrapper.py)。若异常自带 code 属性且能匹配到枚举,则使用对应的枚举名,否则回退为异常的类名。
仓库测试 test_error.py 验证了这一点:对不存在的集合 "random" 执行 search 时,Span 状态码为 StatusCode.ERROR,且 span.attributes.get("error.type") == "COLLECTION_NOT_FOUND"。
九、高级配置:异常日志器与 Provider 注入
1. 自定义异常日志器(exception_logger)
插桩内部所有采集逻辑都包了一层 dont_throw 装饰器(见 utils.py):即使插桩自身的属性提取、结果统计等环节出错,也只会记录 debug 日志而绝不打断你的业务调用。如果你希望在这些静默异常发生时收到通知,可以传入自定义日志器:
def my_logger(e: Exception):
print("instrumentation failed silently:", e)
MilvusInstrumentor(exception_logger=my_logger).instrument()
该值最终写入 config.py 中的全局 Config.exception_logger,在 dont_throw 捕获异常时被回调。
2. 自定义 TracerProvider / MeterProvider
插桩遵循 OpenTelemetry 标准惯例,支持通过 instrument() 的 kwargs 注入自定义 Provider,便于与你的采集管线对接:
MilvusInstrumentor().instrument(
tracer_provider=my_tracer_provider, # 自定义 TracerProvider
meter_provider=my_meter_provider, # 自定义 MeterProvider
)
未传入时分别使用全局默认 Provider(get_tracer(__name__, __version__) / get_meter(__name__, __version__))。
十、工作原理:从 BaseInstrumentor 到 wrapt 包装
理解实现机制有助于排查接入问题。整个插桩链路可分为三层:
-
入口层:
MilvusInstrumentor继承 OpenTelemetry 的BaseInstrumentor(见 init.py)。instrument()触发_instrument,遍历WRAPPED_METHODS中定义的 8 个方法,调用wrapt.wrap_function_wrapper将原始方法替换为包装器;uninstrument()触发_uninstrument,通过unwrap恢复原方法。 -
包装层:
_with_tracer_wrapper是一个高阶工厂(wrapper.py),它把 tracer、各指标句柄与方法定义闭包注入到_wrap,使其符合wrapt包装回调的签名(wrapped, instance, args, kwargs)。 -
采集层:
_wrap内部分三步——开启 Span 并写入db.system/db.operation;按方法分派到_set_*_attributes采集请求参数;调用原始方法后按返回类型分派到结果事件与指标统计。所有_set_*辅助函数均被@dont_throw保护,即"插桩自身的故障永远不能让业务调用失败"。
一个容易混淆的点是:包装对象是 pymilvus.MilvusClient 类本身(wrap_package=pymilvus、wrap_object="MilvusClient"),因此无论你持有哪个 MilvusClient 实例,调用都会命中包装器。
十一、测试与验证:仓库中的可复现用例
仓库为该插桩提供了完整的测试集(见 packages/opentelemetry-instrumentation-milvus/tests),其中 conftest.py 搭建了标准的测试环境:用 InMemorySpanExporter + SimpleSpanProcessor 捕获 Span、用 InMemoryMetricReader 捕获指标,并在会话级 fixture 中自动执行 MilvusInstrumentor().instrument()。
测试用例覆盖了完整的操作面,可作为你理解预期行为的参考:
- test_query.py:验证 insert/upsert/query/get/delete 的 Span 属性与单位消耗指标(如插入 1003 条数据后,
db.client.usage.insert_units数据点值应为 1003); - test_search.py:验证单/多向量检索的 Span 属性、
db.search.result事件、query_vector_dimension(单向量为"[5]"、三向量为"[5, 5, 5]")以及标准化属性db.vector.query.*; - test_hybrid_search.py:验证基于
AnnSearchRequest+RRFRanker的混合检索,断言annsearch_request与ranker_type=RRFRanker; - test_error.py:验证错误场景下 Span 状态为 ERROR 且
error.type=COLLECTION_NOT_FOUND。
一个贴近实战的验证思路是:在你的 RAG 应用中按上述方式接入后,对同一个查询分别执行"无过滤条件 / 带过滤表达式 / 多路混合检索"三类请求,观察 db.milvus.search.filter、db.milvus.search.search_params、db.search.result.distance 等属性的差异,即可快速定位召回质量波动的原因;再结合 db.client.query.duration 直方图,评估向量检索在整体链路中的耗时占比。
小结
opentelemetry-instrumentation-milvus 以"零侵入、全自动"的方式为 pymilvus 客户端补齐了 OpenTelemetry 可观测性:8 类核心操作自动生成语义化 Span,逐条结果以事件呈现,耗时/距离/写入单位以指标沉淀,错误以 error.type 标准化标记,并且全程由 dont_throw 保证插桩故障不影响业务。无论是排查 RAG 召回质量,还是量化向量检索性能,它都是 openllmetry 生态中直接可用的开箱组件。本文涉及的源码均可按文中给出的相对路径在仓库内深入阅读,例如属性定义可对照 semconv_ai/init.py 中的 SpanAttributes / Meters / Events 枚举,采集逻辑可对照 wrapper.py。