基于 OpenTelemetry 的 Weaviate 向量数据库客户端插桩:openllmetry 的 opentelemetry-instrumentation-weaviate 使用与原理剖析

原创2026-10-14 18:00:441,400 阅读
文章标签:LLMOps可观测性

基于 OpenTelemetry 的 Weaviate 向量数据库客户端插桩:openllmetry 的 opentelemetry-instrumentation-weaviate 使用与原理剖析

本文以 openllmetry 仓库中 packages/opentelemetry-instrumentation-weaviate/README.md 为骨架,结合该包源码与测试,系统讲解如何对 Weaviate 向量数据库的 Python 客户端调用进行 OpenTelemetry 追踪。读者将掌握该插桩包的安装方式、一键启用方法、被追踪的客户端 API 清单、生成的 Span 命名与属性结构,以及它在 weaviate-client v3 与 v4 两代 API 上的兼容实现原理。

一、这个包解决什么问题

Weaviate 是一款开源的向量数据库,常被用于检索增强生成(RAG)场景。当应用通过官方 Weaviate Python 客户端 写入或查询向量数据时,这些客户端调用发生在应用内部,默认不会被 OpenTelemetry 追踪到,导致"数据写入、相似度检索、聚合查询"等关键环节在链路图中是黑盒。

opentelemetry-instrumentation-weaviate 就是 openllmetry 项目中专门解决该问题的插桩库:对使用官方 weaviate-client 发出的客户端侧调用进行追踪,将 Schema 管理、数据对象 CRUD、批量导入、GraphQL 查询等操作自动转换为符合 OpenTelemetry 语义的 Span,并挂载 db.system、db.operation 等标准属性(见 semconv_ai 中 VECTOR_DB 语义定义),从而让向量数据库操作真正进入可观测链路。

二、安装

在项目中直接通过 pip 安装即可:

pip install opentelemetry-instrumentation-weaviate

根据 pyproject.toml 中的依赖声明,该包运行时依赖:

  • opentelemetry-api>=1.38.0,<2
  • opentelemetry-instrumentation>=0.59b0
  • opentelemetry-semantic-conventions-ai>=0.5.1,<0.6.0(提供 Span 属性常量,如 VECTOR_DB_VENDOR = "db.system")
  • opentelemetry-semantic-conventions>=0.63b1

同时通过可选依赖声明了被插桩对象:instruments = <a href="https://link.gitcode.com/i/bd0d49db16ca7398d56d6412313d0a2b" target="_blank">"weaviate-client"]。包声明支持 Python >=3.10,<4,并以 hatchling 为构建后端;版本信息统一维护在 [version.py(当前为 0.62.4)。

需要说明的是:仅仅安装插桩包还不够,你通常还需要配置 OpenTelemetry SDK 的 TracerProvider 与 Span 导出器(Console、Jaeger 或云厂商 Collector 等),否则产生的 Span 无法被采集与可视化。

三、最小启用示例:三行代码接入

README 给出了最核心的启用方式——导入 WeaviateInstrumentor 并调用 instrument():

from opentelemetry.instrumentation.weaviate import WeaviateInstrumentor

WeaviateInstrumentor().instrument()

这段代码会在当前进程中自动完成所有可插桩方法的 monkey-patch(详见下一节"插桩原理")。更完整的接入步骤建议配合 OpenTelemetry SDK 一起使用,参考该包的 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.weaviate import WeaviateInstrumentor

exporter = InMemorySpanExporter()
processor = SimpleSpanProcessor(exporter)

provider = TracerProvider()
provider.add_span_processor(processor)
trace.set_tracer_provider(provider)

WeaviateInstrumentor().instrument()

此外,该包在 pyproject.toml 中注册了 opentelemetry_instrumentor 入口点:

[project.entry-points."opentelemetry_instrumentor"]
weaviate_client = "opentelemetry.instrumentation.weaviate:WeaviateInstrumentor"

这意味着除了在代码中显式调用,也可以借助 opentelemetry-instrument 命令行工具或遵循该规范的自动发现机制完成插桩。若使用 traceloop-sdk,则可在初始化时通过 Instruments.WEAVIATE 显式声明启用(示例见 packages/sample-app/sample_app/weaviate_v4.py)。

四、插桩原理:版本兼容与自动 patch

4.1 支持的客户端版本范围

在 init.py 中声明了被插桩库的版本约束:

_instruments = ("weaviate-client >= 3.26.0, <5",)

即支持 weaviate-client 从 3.26.0 到 5.0.0 之前的所有版本,横跨官方客户端的 v3 与 v4 两代 API 风格(仓库中的 sample_app/weaviate_v3.py 与 sample_app/weaviate_v4.py 分别演示了两代客户端用法)。

4.2 两套插桩方法清单

WeaviateInstrumentor(继承自 BaseInstrumentor)内部维护了两份待插桩方法声明:WRAPPED_METHODS_v3 与 WRAPPED_METHODS_v4,每项包含 module(目标模块)、object(目标类)、method(方法名)与 span_name(Span 名称)。_instrument() 遍历全部方法列表,对每个目标执行"导入模块 → 取类 → 用 wrap_function_wrapper 包一层"的操作;模块不存在(如只装了 v4 客户端而没有 v3 的 weaviate.schema 模块)时则静默跳过,从而天然兼容不同客户端版本。

v3 代 API 追踪的方法(对应旧式 weaviate.Client):

模块 对象/方法 Span 名称
weaviate.schema Schema.get / create_class / create / delete_class / delete_all db.weaviate.schema.*
weaviate.data.crud_data DataObject.create / validate / get db.weaviate.data.crud_data.*
weaviate.batch.crud_batch Batch.add_data_object / flush db.weaviate.batch.crud_batch.*
weaviate.gql.query Query.get / aggregate / raw db.weaviate.gql.query.*
weaviate.gql.get GetBuilder.do db.weaviate.gql.query.get.do

v4 代 API 追踪的方法(对应新版 weaviate.WeaviateClient):

模块 对象/方法 Span 名称
weaviate.collections.collections _Collections.get / create / create_from_dict / delete / delete_all db.weaviate.collections.*
weaviate.collections.data _DataCollection.insert / replace / update db.weaviate.collections.data.*
weaviate.collections.batch.collection _BatchCollection.add_object db.weaviate.collections.batch.add_object
weaviate.collections.queries.* _FetchObjectByIDQuery.fetch_object_by_id、_FetchObjectsQuery.fetch_objects db.weaviate.collections.query.*
weaviate.collections.grpc.query _QueryGRPC.get db.weaviate.collections.query.get
weaviate.gql.filter / weaviate.gql.aggregate / weaviate.gql.get GraphQL.do、AggregateBuilder.do、GetBuilder.do db.weaviate.gql.*
weaviate.client WeaviateClient.graphql_raw_query db.weaviate.client.graphql_raw_query

完整定义见 init.py 第 21-211 行。从这些 Span 名称可以看出设计取向:v3 阶段使用 db.weaviate.schema / db.weaviate.data / db.weaviate.batch 命名空间,v4 阶段统一收敛为 db.weaviate.collections,便于在 trace 中一眼定位操作类型。

4.3 Span 生成与错误处理

每个被插桩方法最终都会进入 wrapper.py 的 _wrap 执行统一逻辑:

  1. 抑制机制:若上下文中存在 _SUPPRESS_INSTRUMENTATION_KEY(即其他插桩显式要求关闭追踪,如避免双重记录),则直接调用原函数、不生成 Span;
  2. 创建 Span:以 span_name 为名创建 tracer.start_as_current_span,并关闭自动的 exception 记录与状态设置(record_exception=False, set_status_on_exception=False),交给后续逻辑自行控制;
  3. 写入基础属性:db.system=weaviate、db.operation=<方法名>(对应 semconv_ai 的 VECTOR_DB_VENDOR / VECTOR_DB_OPERATION);
  4. 补充业务属性:根据目标对象类型,从 InstrumentorFactory 挑选对应的 _Instrumentor 子类,把调用参数映射为 {namespace}.{method}.{arg} 形式的属性(详见下文);
  5. 错误语义:原函数抛出异常时,Span 上记录 error.type(异常类名,遵循 OTel error 语义)、通过 span.record_exception(e) 记录异常事件,并将 Span 状态置为 ERROR 后重新抛出原异常,保证业务调用方感知不变。

4.4 参数如何变成 Span 属性

wrapper.py 中的 ArgsGetter 负责"无论参数是以位置参数还是关键字参数传入,都能正确取出",并将 dict 序列化为 JSON 字符串后写入属性。随后由各 _Instrumentor 子类的 mapped_attributes 决定具体记录哪些参数。例如:

  • v3 的 _DataObjectInstrumentorV3 记录 weaviate.data.crud_data.create.data_object / class_name / uuid / vector / consistency_level / tenant;
  • v4 的 _DataObjectInstrumentor 记录 weaviate.collections.data.insert.properties / references / uuid / vector;
  • v4 查询类记录 db.weaviate.collections.query.fetch_objects.limit / offset / after / filters / sort / return_metadata / return_properties / return_references 等。

这意味着你无需手动埋点,即可在 Span 中看到"往哪个集合插入了什么属性、按什么条件查询、返回哪些字段"等关键上下文。

4.5 插桩失败不拖垮业务

属性映射逻辑整体被 utils.py 的 dont_throw 装饰器 包裹:即使某个参数的 JSON 序列化失败或属性写入出错,也只会记录 debug 日志并通过可配置的 Config.exception_logger 回调(见 config.py,可通过 WeaviateInstrumentor(exception_logger=...) 传入)上报,而不会抛出异常影响业务调用。

五、实际产生的 Span 长什么样

以仓库测试为最直接的证据。在 tests/test_weaviate_instrumentation.py(针对 v4 客户端)和 tests/test_weaviate_instrumentation_v3.py(针对 v3 客户端)中,断言了如下典型结果:

  • 创建集合(v4):Span db.weaviate.collections.create,属性 db.system=weaviate、db.operation=create、db.weaviate.collections.create.name='"Article"';
  • 插入数据(v4):Span db.weaviate.collections.data.insert,属性 weaviate.collections.data.insert.properties 等于原始 dict 的 JSON 序列化结果;
  • 批量写入(v4):Span db.weaviate.collections.batch.add_object,属性中的 properties 可还原出每一条写入内容;
  • 原生 GraphQL(v4):Span db.weaviate.client.graphql_raw_query,属性 db.weaviate.client.graphql_raw_query.gql_query 完整保留 Get { Article(limit: 2) { author text } } 原始查询语句;
  • v3 对应场景则产生 db.weaviate.schema.create_class(属性 db.weaviate.schema.create_class.schema_class)、db.weaviate.data.crud_data.create(属性 weaviate.data.crud_data.create.data_object 与 class_name)、db.weaviate.gql.query.raw(属性 db.weaviate.query.raw.gql_query)等。

测试还覆盖了版本联动:tests/conftest.py 会根据 weaviate.__version__ 判断当前客户端是 v3 还是 v4,并自动跳过不适用的测试文件;默认情况下多数用例通过 pytest-recording 录制/回放真实请求(cassettes/ 目录下的 YAML 文件),仅 --with_grpc 标记的用例需要真实运行的 Weaviate 实例。

六、在 RAG 应用中落地:一个端到端示例

将插桩与典型的"建集合 → 批量灌入 → 向量检索"流程结合,即可得到可观测的 RAG 数据链路。仓库的 sample_app/weaviate_v4.py 给出了完整参考(配合 traceloop-sdk 使用):

import weaviate
import weaviate.classes as wvc
from traceloop.sdk import Traceloop
from traceloop.sdk.decorators import task, workflow
from traceloop.sdk.instruments import Instruments

Traceloop.init(
    app_name="weaviate_app",
    disable_batch=True,
    exporter=ConsoleSpanExporter(),
    instruments={Instruments.WEAVIATE},   # 显式启用 Weaviate 插桩
)

client = weaviate.connect_to_local()

# 1. 建集合(产生 db.weaviate.collections.create)
client.collections.create(
    name="Article",
    properties=[
        wvc.config.Property(name="author", data_type=wvc.config.DataType.TEXT),
        wvc.config.Property(name="text", data_type=wvc.config.DataType.TEXT),
    ],
)

# 2. 批量写入(产生 db.weaviate.collections.batch.add_object)
collection = client.collections.get("Article")
with collection.batch.dynamic() as batch:
    for obj in [...]:
        batch.add_object(properties=obj)

# 3. 查询(产生 db.weaviate.collections.query.fetch_objects)
result = collection.query.fetch_objects(return_properties=["author"])

在导出的 trace 中,你会看到完整的 Span 层级:工作流/任务 Span 之下,每个向量数据库操作都有自己的子 Span,配合 db.system=weaviate 与 db.operation 即可快速定位"哪一步写入失败、哪一步查询超时"。

七、排查与限制提示

  • Span 未出现:先确认安装了 weaviate-client 且版本在 >=3.26.0,<5 范围内;再确认 WeaviateInstrumentor().instrument() 在客户端创建之前执行(插桩是进程级 patch,必须先于调用生效)。
  • 属性冗余与安全:插桩会把数据对象、原始 GraphQL 查询等以 JSON 形式写入 Span 属性,若集合中包含敏感字段,应在导出侧按属性名做过滤或脱敏。
  • 误差处理是尽力而为:插桩自身的属性提取失败不会影响业务(见 4.5 节),但 Span 中可能缺少部分参数信息,这是设计取舍而非缺陷。
  • 版本适配:v3 与 v4 的 Span 名称命名空间不同(db.weaviate.schema.* 对 db.weaviate.collections.*),在做链路分析或告警规则时需要按实际客户端版本区分;仓库测试目录中 test_weaviate_instrumentation_v3/ 与 test_weaviate_instrumentation/ 两套 cassettes 可帮助你理解各自的行为差异。

八、小结

opentelemetry-instrumentation-weaviate 以极低的接入成本(两行初始化代码)为 Weaviate Python 客户端的全部关键操作提供了标准化追踪:从 Schema 管理、数据对象写入、批量导入到 GraphQL 查询,Span 名称、db.system/db.operation 属性以及丰富的参数级属性一应俱全,且同时兼容 v3 与 v4 两代客户端 API。对于构建在 Weaviate 之上的 RAG 应用,它是补齐"向量数据库环节可观测性"最直接的方案。

登录后查看全文
openllmetry