用 OpenTelemetry 观测 Marqo 向量数据库:opentelemetry-instrumentation-marqo 接入与原理指南

原创2026-10-14 11:06:301,606 阅读
文章标签:LLMOps可观测性

用 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)可以概括为:

  1. 抑制检查:若上下文中存在 _SUPPRESS_INSTRUMENTATION_KEY(来自 opentelemetry.instrumentation.utils)或 SUPPRESS_LANGUAGE_MODEL_INSTRUMENTATION_KEY(来自 semconv_ai,见 semconv_ai),则直接调用原方法、不产生 Span——这保证了在嵌套的 LLM/向量库调用中,你可以通过抑制上下文精确控制哪些调用被观测;
  2. 开启 Span:tracer.start_as_current_span(span_name),其中 span_name 来自 WRAPPED_METHODS 配置;
  3. 写入请求属性:先设置 db.system、db.operation,再按方法分发到各自的属性采集函数;
  4. 执行真实调用:return_value = wrapped(*args, **kwargs);
  5. 写入响应属性/事件:仅 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 的模式扩展新的包装方法。

登录后查看全文
openllmetry