← 文章 / 数据与数据库
signoz 9天前 · 2026-11-12 22:15:29 · 12 阅读

使用 OpenTelemetry 实现 Pixeltable 的可观测性与监控

Pixeltable 是面向多模态 AI 应用的声明式数据基础设施。图片、视频、音频、文档和模型调用都存放在表中,计算列会在插入和更新时自动执行转换。Pixeltable 的可观测性功能通过 OpenTelemetry 记录这些工作,并发送到 SigNoz。

Pixeltable OpenTelemetry 桥接器会为每次表操作生成一条 trace。设置 span_level='debug' 后,trace 会包含行数据、每次 UDF 调用,如果还添加了 LLM instrumentor,还会包含模型请求的子 span:

Copy
pixeltable.insert
└─ pixeltable.store.insert_rows
   ├─ pixeltable.row
   ├─ pixeltable.udf.chat_completions
   │  └─ ChatCompletion
   └─ pixeltable.sa.insert_rows

UDF span 带有 pxt.udf_path、pxt.column、pxt.resource_pool 和 pxt.retries 属性,pixeltable.store.write_column span 带有 pxt.column。模型名称、提示词、补全结果和 token 数量则作为 LLM 子 span 的属性。SigNoz 的 AI Observability 会读取该子 span 上的 gen_ai.* 属性。

前置条件

  • 一个拥有有效 ingestion key 的 SigNoz Cloud 账号,或一个 自托管 SigNoz 实例
  • Python 3.11 或更高版本
  • 如果要运行下面的示例,需要一个 OpenAI API key(OPENAI_API_KEY)

以下环境测试通过:Python 3.11、pixeltable 0.7.23、opentelemetry-instrumentation-pixeltable 0.2.0 和 openinference-instrumentation-openai 0.1.69。

用 OpenTelemetry 监控 Pixeltable

在首次 Pixeltable 操作之前,每个进程调用一次 pxt_otel.init()。它会创建 OTLP/HTTP exporter 并对 Pixeltable 进行插桩。添加 OpenAIInstrumentor 后,每个 openai.chat_completions 单元格都会获得一个子 span。Pixeltable API 详情请参阅 Pixeltable 文档。

使用自建 SigNoz?

大多数步骤相同。将端点设置为 http://<signoz-host>:4318,其中 <signoz-host> 是你 SigNoz collector 的地址,并省略 signoz-ingestion-key 请求头,如Cloud → Self-Hosted所示。

步骤 1:安装软件包

安装带 OpenTelemetry extra 的 Pixeltable、openai 客户端以及 OpenAI instrumentor。

复制
pip install 'pixeltable[otel]' openai openinference-instrumentation-openai

pixeltable[otel] 会同时安装 opentelemetry-instrumentation-pixeltable、OpenTelemetry SDK 和 OTLP exporters。Pixeltable 和 instrumentor 均不会安装 openai,而 chat_completions() 需要调用它。

步骤 2:将 exporter 指向 SigNoz

通过环境变量设置端点,或在代码中将其传递给 init()。init() 会在端点后追加 /v1/traces 和 /v1/metrics,因此传入的 URL 不要包含路径。

环境变量代码

当省略对应参数时,init() 会读取这些变量。OTEL_SPAN_LEVEL=debug 保留按行和按 UDF 的 spans。默认的 info 保留操作 span 及其相关的 catalog、store 和 SQL spans。

复制
export OTEL_SERVICE_NAME=pixeltable-app
export OTEL_EXPORTER_OTLP_ENDPOINT="https://ingest.<region>.signoz.cloud:443"
export OTEL_EXPORTER_OTLP_HEADERS="signoz-ingestion-key=<your-ingestion-key>"
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
export OTEL_SPAN_LEVEL=debug
export OPENAI_API_KEY=<your-openai-api-key>

请确认这些值:

将 SigNoz 端点传递给 init()。保持 metrics 为默认值,以便将 token counters 导出至 /v1/metrics。

Copy
pxt_otel.init(
    endpoint='https://ingest.<region>.signoz.cloud:443',
    headers='signoz-ingestion-key=<your-ingestion-key>',
    service_name='pixeltable-app',
    span_level='debug',
)

请确认以下配置值:

headers 采用 OTEL_EXPORTER_OTLP_HEADERS 的格式:多个 key=value 对之间用逗号分隔。如果使用自托管的 SigNoz,则调用 pxt_otel.init(endpoint='http://<signoz-host>:4318', service_name='pixeltable-app', span_level='debug'),并省略 headers。把 <signoz-host> 替换为你 SigNoz collector 的地址。运行 insert 之前,记得在环境中设置 OPENAI_API_KEY。

第 3 步:初始化桥接并插入数据

初始化桥接、对 OpenAI 插桩,然后插入一行数据。如果你在第 2 步用的是 Code 标签页,请用你自己的 init() 调用替换这里的 pxt_otel.init()。

Copy
import opentelemetry.instrumentation.pixeltable as pxt_otel
from openinference.instrumentation.openai import OpenAIInstrumentor
from opentelemetry import trace
 
pxt_otel.init()
OpenAIInstrumentor().instrument()
 
import pixeltable as pxt
from pixeltable.functions import openai
 
table = pxt.create_table('articles', {'id': pxt.Int, 'body': pxt.String}, if_exists='replace')
table.add_computed_column(
    summary=openai.chat_completions(
        messages=[{'role': 'user', 'content': 'Summarize in one sentence: ' + table.body}],
        model='gpt-4o-mini',
    ).choices[0].message.content
)
table.insert([{'id': 1, 'body': 'Pixeltable is declarative data infrastructure for multimodal AI apps.'}])
trace.get_tracer_provider().force_flush()

force_flush() 会立即发送已缓存的 span。不调用它的话,SDK 要等进程正常退出时才会发送。指标则由周期性 reader 定时发送,大约每分钟一次。如果想立即发送,同样要 flush meter provider:

Copy
from opentelemetry import metrics
 
metrics.get_meter_provider().force_flush()

init() 会复用你应用中已注册的 tracer provider。

使用 opentelemetry-instrument?

使用 opentelemetry-instrument 需要 opentelemetry-distro(执行 pip install opentelemetry-distro),而 pixeltable[otel] 不会自动安装它。缺少该包将导致 span 无法导出。配合 opentelemetry-instrument 时,Pixeltable 入口点以 span 级 info 进行插桩,且会忽略 OTEL_SPAN_LEVEL,后续调用 instrument() 或 init() 也无法改变此行为。若需调整 row 和 UDF span,请设置 OTEL_PYTHON_DISABLED_INSTRUMENTATIONS=pixeltable,并调用 pxt_otel.init(span_level='debug')。init() 将复用 opentelemetry-instrument 注册的 provider。

OpenInference 会在 ChatCompletion span 上设置 llm.model_name、llm.provider 及 llm.token_count.*。Attribute Mapping 中默认的 gen_ai.llm 组会将这些字段映射到 AI Observability 读取的 gen_ai.* 属性。若需从进程内直接输出 gen_ai.*,请设置 OPENINFERENCE_ENABLE_GENAI_SEMCONV=true。

验证

打开 Traces Explorer,按服务名和操作进行过滤:

Copy
service.name = 'pixeltable-app' AND name = 'pixeltable.insert'
Traces Explorer 中的 pixeltable.insert span

打开 trace,waterfall 视图显示 pixeltable.udf.chat_completions 位于 pixeltable.store.insert_rows 之下,而 ChatCompletion 又位于 UDF span 之下。prompt 和 completion 作为属性挂在 ChatCompletion 上。

包含 UDF span 和嵌套 LLM span 的 pixeltable.insert

配置端点后,Pixeltable 还会导出 metrics。在 Metrics Explorer 中查询:

  • pixeltable.udf.input_tokens 和 pixeltable.udf.output_tokens,带有属性 pxt.model(及 pxt.udf_path)
  • pixeltable.udf.calls 和 pixeltable.udf.latency
  • pixeltable.rows.written,附带属性 pxt.table

指标范围(scope)名称为 pixeltable。同一次 insert 还在 pxt.model=gpt-4o-mini 上记录了输入和输出 token。

collect() 会写入一条 pixeltable.collect trace,不会再次调用模型,计算结果会被存储下来。新的 LLM span 会在 insert、update 时出现,也会在 add_computed_column 回填已有行时出现。

在 AI Observability 中查看

AI Observability 展示 Pixeltable 计算列所发起 LLM 调用的成本、token 用量、延迟和错误信息。在 SigNoz 中打开 AI Observability,然后在 service_name 筛选器中选择你的服务。

AI Observability 会把 ChatCompletion span 计为一次 LLM 调用。执行一次 insert 后,它会显示 gpt-4o-mini-2024-07-18(OpenAI 返回的模型名)的 1 次 LLM 调用,以及对应的输入和输出 token。SigNoz 会根据该模型的内置价格计算成本。单次调用成本不到一美分,所以 Total cost 卡片将其四舍五入为 $0,Cost breakdown 面板则展示输入和输出的成本占比。如果某个模型没有定价信息,成本会显示为 $0,直到你为该模型名称添加 model pricing 规则。非流式调用的时间到首 token 显示为 0s。

一次 Pixeltable insert 后的 AI Observability

要查询单条 trace,请打开 Explorer 标签页。Trace View 为每条 trace 显示一行,包含 token、成本、调用次数等汇总指标。你可以按这些指标进行筛选、聚合和排序,例如 trace.total_tokens > 1000。详情参见 AI Observability Explorer。

如果面板一直为空,请检查你的 span 是否带有 Telemetry Requirements 中要求的属性。如需映射其他属性名称,可以使用 Attribute Mapping。

原始来源: signoz

评论 (0)