用 OpenTelemetry 观测 Marqo 向量数据库:opentelemetry-instrumentation-marqo 接入与原理指南
用 OpenTelemetry 观测 Marqo 向量数据库:opentelemetry-instrumentation-marqo 接入与原理指南
本文面向正在为 RAG / 检索增强应用接入可观测性的开发者,介绍 openllmetry 仓库中的 opentelemetry-instrumentation-marqo 包:如何用两行代码为官方 Marqo Python 客户端注入 OpenTelemetry 追踪,自动采集 add_documents、search、delete_documents 三类操作的 Span,并将查询语句、处理耗时、命中结果等关键信息记录为标准化属性与事件。读完本文,你将掌握该包的安装方式、最小接入示例、完整的 Span 属性与事件语义,以及其底层包装器(wrapper)的实现原理与测试验证方法。
一、这个包解决什么问题
Marqo 是一个面向 AI 应用的向量数据库,支持以张量(tensor)方式进行语义检索。当你的应用通过官方 Marqo 客户端库 调用 Marqo 时,这些调用默认是"黑盒"的——文档写入是否成功、检索耗时多少、命中结果有哪些,都难以与应用的分布式追踪串联起来。
opentelemetry-instrumentation-marqo 以 wrapt 对 Marqo 客户端的 Index 类方法做运行时包装(monkey-patch),在不修改业务代码的前提下,为每次向量库操作生成符合 OpenTelemetry 语义的 Span。它属于 openllmetry(Open-source observability for your GenAI or LLM application,基于 OpenTelemetry 的 GenAI 可观测性方案)的向量数据库观测模块之一,与仓库中同类的 opentelemetry-instrumentation-chromadb、opentelemetry-instrumentation-milvus、opentelemetry-instrumentation-qdrant 等包共同构成完整的向量库追踪矩阵。
说明:本包基于
marqo >= 3.5.1版本开发(见 init.py 中的_instruments声明,测试组内约束为marqo>=3.5.1,<4,见 pyproject.toml),使用时请确保客户端库版本满足该下限。
二、安装
使用 pip 直接安装:
pip install opentelemetry-instrumentation-marqo
如果你想同时安装被观测的 Marqo 客户端库,也可以使用 instruments 附加依赖组(见 pyproject.toml):
pip install "opentelemetry-instrumentation-marqo[instruments]"
该包的运行时依赖包括(见 pyproject.toml):
| 依赖 | 版本约束 | 作用 |
|---|---|---|
opentelemetry-api |
>=1.38.0,<2 |
OpenTelemetry 核心 API(Tracer、Span 等) |
opentelemetry-instrumentation |
>=0.59b0 |
提供 BaseInstrumentor 基类与包装/解包工具 |
opentelemetry-semantic-conventions-ai |
>=0.5.1,<0.6.0 |
提供 AI/向量库专属语义约定(Span 属性与事件名) |
opentelemetry-semantic-conventions |
>=0.63b1 |
提供标准数据库语义约定(如 db.system) |
另外,包内注册了 opentelemetry_instrumentor 入口点(pyproject.toml),因此它同样可以被 opentelemetry-instrument 这类自动注入工具识别。运行时要求 Python >=3.10,<4。
三、最小接入示例
README 给出的最小用法只需两步:导入 MarqoInstrumentor 并调用 instrument():
from opentelemetry.instrumentation.marqo import MarqoInstrumentor
MarqoInstrumentor().instrument()
调用之后,Marqo 客户端的 Index.add_documents、Index.search、Index.delete_documents 三个方法会被自动包装,产生对应 Span。结合一个真实的调用场景:
import marqo
mq = marqo.Client(url="http://localhost:8882")
# 写入文档(注意:必须以关键字参数 documents= 传参,详见下文"限制与注意事项")
mq.index("TestIndex").add_documents(
documents=[
{
"Title": "The Travels of Marco Polo",
"Description": "A 13th-century travelogue describing Polo's travels",
},
{
"Title": "Extravehicular Mobility Unit (EMU)",
"Description": "The EMU is a spacesuit that provides environmental protection",
"_id": "article_591",
},
],
tensor_fields=["Description"],
)
# 语义检索
results = mq.index("TestIndex").search(q="What is the best outfit to wear on the moon?")
# 按 _id 删除文档
mq.index("TestIndex").delete_documents(ids=["article_591"])
以上调用形态与 tests/test_query.py 中的测试代码一致,其真实请求/响应被录制在 tests/cassettes/test_query/ 目录下,可作为对接 Marqo 服务端(示例中为 localhost:8882)时的参考。
配合完整的 TracerProvider 使用
instrument() 默认使用全局 TracerProvider;如需指定,可传入 tracer_provider 参数(_instrument 通过 kwargs.get("tracer_provider") 获取,见 init.py):
from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import SimpleSpanProcessor
from opentelemetry.instrumentation.marqo import MarqoInstrumentor
provider = TracerProvider()
provider.add_span_processor(
SimpleSpanProcessor(
# 举例:导出到 OTLP Collector(opentelemetry-exporter-otlp 需另行安装)
OTLPSpanExporter(endpoint="http://localhost:4317")
)
)
trace.set_tracer_provider(provider)
MarqoInstrumentor().instrument(tracer_provider=provider)
MarqoInstrumentor 内部通过 get_tracer(__name__, __version__) 获取 Tracer,Span 的 instrumentation_scope 名称为 opentelemetry.instrumentation.marqo,版本号与包版本一致(当前为 0.62.4,见 version.py)。
四、观测范围:三个被包装的方法
包装目标在 init.py 中以 WRAPPED_METHODS 声明,共三个:
| 包装对象 | 方法 | Span 名称 | 对应语义 |
|---|---|---|---|
marqo.index.Index |
add_documents |
marqo.add_documents |
批量写入/替换文档 |
marqo.index.Index |
search |
marqo.search |
张量语义检索 |
marqo.index.Index |
delete_documents |
marqo.delete_documents |
按 _id 批量删除文档 |
_instrument 会先检查目标对象是否存在(getattr(wrap_package, wrap_object, None)),再通过 wrap_function_wrapper 对 Index.add_documents、Index.search、Index.delete_documents 分别套上由 _wrap(tracer, wrapped_method) 生成的包装器;对应的 _uninstrument 则调用 unwrap 逐个还原(init.py)。因此你可以随时用 MarqoInstrumentor().uninstrument() 撤销插桩,恢复原始方法行为。
五、Span 属性与事件语义详解
每次调用都会生成一个以对应方法命名的 Span。包装器 _wrap(见 wrapper.py)为所有 Span 统一设置两类标准属性,再按方法类型补充各自的专属属性。
5.1 所有 Span 共有的属性
| 属性名 | 常量(semconv_ai) | 值 | 含义 |
|---|---|---|---|
db.system |
VECTOR_DB_VENDOR |
marqo |
数据库系统标识 |
db.operation |
VECTOR_DB_OPERATION |
add_documents / search / delete_documents |
具体操作名 |
常量定义见 semconv_ai 包。
5.2 按方法区分的专属属性
| 方法 | 属性名 | 来源 | 说明 |
|---|---|---|---|
add_documents |
db.chroma.add.documents_count |
kwargs.get("documents") 的条数 |
本次写入的文档数量。注意该属性名是复用 Chroma 语义约定(CHROMADB_ADD_DOCUMENTS_COUNT,见 semconv_ai),当前版本未单独定义 Marqo 专属常量 |
search |
db.marqo.search.query |
kwargs.get("q") |
检索查询语句,即 Marqo 的 q 参数(wrapper.py) |
search(响应) |
db.marqo.search.processing_time |
响应中的 processingTimeMs |
Marqo 服务端返回的处理耗时(毫秒),是评估检索性能的关键指标(wrapper.py) |
delete_documents |
db.milvus.delete.ids_count |
kwargs.get("ids") 的数量 |
待删除文档的数量。与上面同理,属性名复用 Milvus 的 MILVUS_DELETE_IDS_COUNT 约定(见 semconv_ai) |
delete_documents(响应) |
db.marqo.delete_documents.status |
响应中的 status |
删除操作的状态(如 succeeded) |
其中 db.marqo.* 三个属性名由 opentelemetry-semantic-conventions-ai 的 SpanAttributes 显式定义(semconv_ai):
MARQO_SEARCH_QUERY = "db.marqo.search.query"MARQO_SEARCH_PROCESSING_TIME = "db.marqo.search.processing_time"MARQO_DELETE_DOCUMENTS_STATUS = "db.marqo.delete_documents.status"
当属性值为 None 或空字符串时会被跳过(_set_span_attribute 的判空逻辑,见 wrapper.py),避免产生空属性污染数据。
5.3 search 的命中结果事件
search 除了设置属性,还会为响应中的每一个命中结果(hit)添加一个名称为 db.query.result 的事件(Events.DB_QUERY_RESULT,定义见 semconv_ai),事件属性为整个 hit 字典原样透传:
# wrapper.py 中 _set_search_result_attributes 的核心逻辑
events = kwargs.get("hits")
for event in events:
span.add_event(name=Events.DB_QUERY_RESULT.value, attributes=event)
因此每个事件会携带 _id、_score、_highlights 以及文档字段(如 Title、Description)等完整信息。结合 test_marqo_search.yaml 中录制的真实响应可以看到,一次检索返回的每个 hit 都会成为一个独立事件,例如 _id: article_591、_score: 0.83...。这为后端按查询逐条分析检索质量(分数分布、命中文档构成)提供了直接数据源。
六、源码级实现细节
6.1 包装器执行流程
_wrap 的执行顺序(wrapper.py)可以概括为:
- 抑制检查:若上下文中存在
_SUPPRESS_INSTRUMENTATION_KEY(来自opentelemetry.instrumentation.utils)或SUPPRESS_LANGUAGE_MODEL_INSTRUMENTATION_KEY(来自 semconv_ai,见 semconv_ai),则直接调用原方法、不产生 Span——这保证了在嵌套的 LLM/向量库调用中,你可以通过抑制上下文精确控制哪些调用被观测; - 开启 Span:
tracer.start_as_current_span(span_name),其中 span_name 来自WRAPPED_METHODS配置; - 写入请求属性:先设置
db.system、db.operation,再按方法分发到各自的属性采集函数; - 执行真实调用:
return_value = wrapped(*args, **kwargs); - 写入响应属性/事件:仅
search(处理耗时、命中事件)与delete_documents(状态)有响应后处理。
6.2 异常吞掉而不影响业务
所有属性采集函数都被 @dont_throw 装饰(utils.py):即使取属性、遍历 hits 等环节抛异常,也只会以 debug 级别记录日志("OpenLLMetry failed to trace in %s"),而不会把异常传播到业务代码。这是插桩库的通用安全设计——可观测性失败绝不能拖垮业务。
如果你希望捕获这些被吞掉的异常,可以在构造时传入 exception_logger:
MarqoInstrumentor(exception_logger=my_logger).instrument()
它会被存到 config.py 的 Config.exception_logger,由 dont_throw 在捕获异常时回调。
6.3 插桩生命周期
MarqoInstrumentor 继承 BaseInstrumentor,具备完整的 instrument / uninstrument 生命周期:
instrumentation_dependencies()返回("marqo >= 3.5.1",),供上层工具校验依赖版本;_instrument(tracer_provider=...)完成包装;_uninstrument()通过unwrap恢复原始方法。
七、测试与验证方式
该包在 tests/ 下提供了完整的单元测试,使用 pytest-recording(VCR)回放真实 Marqo 响应,无需启动真实数据库:
- tests/conftest.py:创建
InMemorySpanExporter与SimpleSpanProcessor,设置全局 TracerProvider,并自动执行MarqoInstrumentor().instrument(),测试结束后通过exporter.clear()清空 Span 便于逐用例断言; - tests/test_query.py:三个用例分别断言三个 Span 的属性与事件,例如:
marqo.add_documents的db.system == "marqo"、db.operation == "add_documents"、db.chroma.add.documents_count == 2;marqo.search的db.marqo.search.query与db.marqo.search.processing_time >= 0,以及命中事件的数量、_id、_score、Title字段;marqo.delete_documents的db.milvus.delete.ids_count == 1、db.marqo.delete_documents.status == "succeeded";
- tests/cassettes/test_query/:三个 YAML 文件录制了
create_index、add_documents、search、delete_documents等真实 HTTP 交互,可作为理解 Marqo API 请求/响应结构的样例。
本地运行测试(仓库使用 uv 管理,见 project.json 的 test 目标):
cd packages/opentelemetry-instrumentation-marqo && uv run pytest tests/
八、限制与注意事项
add_documents必须以documents=关键字传参:包装器通过kwargs.get("documents")读取文档列表来统计数量,如果按位置参数传参则无法统计(wrapper.py 的 docstring 亦明确说明)。这也是 openllmetry 仓库在 issue #539 中记录过的已知约束;- 客户端版本下限:请使用
marqo >= 3.5.1,否则_instrument的依赖检查可能失败; - Span 名称固定为
marqo.add_documents/marqo.search/marqo.delete_documents,便于在 Trace 浏览器中建立统一的检索语义; - 事件数据量:
search会对每个 hit 添加一个事件且透传完整文档字段,高召回场景下事件体积较大,接入时建议结合后端采样策略评估; - 该包当前仅覆盖
Index类上的三个操作,create_index、delete_index等索引管理操作不在观测范围内(测试中通过 fixture 执行,但不会生成对应 Span)。
九、结语
opentelemetry-instrumentation-marqo 用极低的接入成本(一行 instrument())把 Marqo 向量检索的写入、查询、删除三类操作纳入 OpenTelemetry 追踪体系,并通过 db.system、db.operation 等标准属性与 db.query.result 事件,让检索质量数据与 LLM 调用链路在同一个 Trace 中自然对齐。对于 RAG 应用的链路追踪、检索性能分析与召回质量排查,它是一个开箱即用的观测组件。若需进一步定制属性语义,可参考其依赖的 opentelemetry-semantic-conventions-ai 包,或参照本包 wrapper.py 的模式扩展新的包装方法。