OpenLLMetry 实战:使用 opentelemetry-instrumentation-milvus 为 Milvus 向量检索接入 OpenTelemetry 全链路可观测

原创2026-10-14 22:03:241,982 阅读
文章标签:LLMOps可观测性

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):

  1. 在 Span 上写入 error.type 属性,值为规范化后的错误类型;
  2. 将异常原样重新抛出,保证业务侧的错误处理行为完全不受影响,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 包装

理解实现机制有助于排查接入问题。整个插桩链路可分为三层:

  1. 入口层:MilvusInstrumentor 继承 OpenTelemetry 的 BaseInstrumentor(见 init.py)。instrument() 触发 _instrument,遍历 WRAPPED_METHODS 中定义的 8 个方法,调用 wrapt.wrap_function_wrapper 将原始方法替换为包装器;uninstrument() 触发 _uninstrument,通过 unwrap 恢复原方法。

  2. 包装层:_with_tracer_wrapper 是一个高阶工厂(wrapper.py),它把 tracer、各指标句柄与方法定义闭包注入到 _wrap,使其符合 wrapt 包装回调的签名 (wrapped, instance, args, kwargs)。

  3. 采集层:_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。

登录后查看全文
openllmetry