进阶 pydantic.dev 2026-11-20 05:57:40 · 11 阅读

第6章 无需重新部署即可更改 OpenTelemetry 采样策略

本文将一个服务和它所在的主机接入 Pydantic Logfire 的 Fleet Management,然后在两者持续运行的情况下,动态修改服务的日志级别、脱敏规则和采样率,以及主机上的 Collector。

你需要一个 Logfire 项目(所有套餐都自带 Fleet)、一个写入 token、Python 3.11 或更高版本,以及 uv。下面的每个步骤同样适用于 Node.js、Java、.NET 和 Go,差异汇总在一张表里。

为什么要在线修改?

checkout-api 用 debug 级别打日志,某个 span 上还带了卡号 token,流量突然涨了三倍,摄入账单也跟着暴涨。这三个问题你都想立刻解决,而不是等下次发版。

服务本身:一个带 fleet=True 的 FastAPI 应用

下面是 checkout-api,一个基于 Logfire SDK 的 FastAPI 应用。与 Fleet 相关的代码只有 fleet=True 这一处:

import logfire from fastapi import FastAPI

logfire.configure(service_name='checkout-api', fleet=True)

app = FastAPI() logfire.instrument_fastapi(app)

@app.post('/checkout/{order_id}') async def checkout(order_id: str, card_token: str) -> dict[str, str]: logfire.debug('cart loaded for {order_id}', order_id=order_id) with logfire.span('charge card', order_id=order_id, card_token=card_token): logfire.info('charged {order_id}', order_id=order_id) return {'status': 'ok'}

fleet=True 需要 Logfire 5.5.0 及以上版本,并安装 fleet extra。设置环境变量 LOGFIRE_FLEET=true 可以不改动代码达到同样效果。如果没有配置 Fleet endpoint,configure() 会发出警告,应用以非托管方式运行,所以你可以先部署代码,再配置 Fleet。

uv venv source .venv/bin/activate uv pip install --upgrade 'logfire[fleet,fastapi]' fastapi uvicorn

把应用接入 Fleet

在 Fleet management 中打开 SDKs,选择 Add application。命名为 checkout-api,选择 Python with Logfire,然后点击 Get setup instructions。

Logfire 会展示一次 Fleet connection key,请把它存入你的密钥管理工具。然后按设置页面所示配置环境变量并启动应用:

export OTEL_SERVICE_NAME=checkout-api export OTEL_OPAMP_ENDPOINT=... # 来自设置页面 export OTEL_OPAMP_HEADERS=... # 带连接密钥的 Authorization uvicorn app:app

应用会输出 OpAMP: connected to ...;当它出现在 Fleet 中时,显示为以 checkout-api 名义受管。点击设置页面中的 Check connection,服务就会显示为已连接并已应用策略。

连接密钥只用于管理配置。你的应用仍用原有的写入 token 发送遥测数据。

其他语言的接入方式相同,只是启动时略有差异:

Python + 原生 OpenTelemetry:运行 uv pip install logfire-fleet-otel,然后用 opentelemetry-instrument 启动。 Node.js 22+ + Logfire SDK:运行 npm install @pydantic/logfire-node @pydantic/logfire-fleet-otel,然后在 logfire.configure() 中传入 fleet: true(0.22.0 及以上)。 Node.js 22+ + 原生 OpenTelemetry:运行 npm install @pydantic/logfire-fleet-otel,然后用 node --import @pydantic/logfire-fleet-otel/register app.js 启动。 Java 17+:通过 -Dotel.javaagent.extensions=logfire-fleet-javaagent-extension.jar 把 Fleet 扩展加到 OpenTelemetry Java agent。 .NET 8+:把 Logfire.Fleet.AutoInstrumentation 插件加到 OpenTelemetry 自动探针。 Go 1.25+:在 main 里调用 opampotel.Setup(ctx),替代你的 SDK 初始化。

各语言的完整命令见应用管理指南。

改动一:止住 debug 日志洪流

在 SDKs 标签页打开 checkout-api 的 SDK 策略。每个配置项都标注为 Set by policy(由策略设定)或 Application controlled(由应用自控)。初始状态下全部是 Application controlled:策略只改变你明确指定的项。

在 Volume controls 下,把 Minimum log level 设为 Warn。点击 Review policy,确认变更并发布。

几秒内,debug 和 info 日志就不再出现在 Live 视图中。进程没有重启,应用自身的日志级别也没变:Fleet 是在导出环节丢弃这些记录的,之后改一下策略就能恢复。

Fleet 中该应用的页面会列出每项配置的策略要求和各实例当前的实际状态。

改动二:脱敏 token

在 Attribute redaction 下,把 *token* 加入要掩码的属性列表并发布。SDK 会在 span 导出前把每个匹配属性的值替换为 [REDACTED],因此这些数据永远不会到达 Logfire 或 SDK 发送的其他后端。Scrubbing 功能更进一步,不仅匹配键名还匹配值本身,使用的是 Logfire SDK 默认的脱敏模式。

改动三:只采样十分之一的流量

在 Trace sampling 下把采样率设为 10%。在 Sampling rules 下添加一条规则,将 /health* 完全丢弃;新 trace 的根 span 命中的第一条规则决定其采样率,优先生效于总体采样率。父 span 被采样的子 span 仍会被采样,所以 trace 保持完整。

发布。未采样的 trace 不会到达 Logfire,所以发布前的确认步骤值得仔细看。

先在两个实例上试

最后一项改动最好先小范围验证。Rollouts 目前处于早期访问阶段。如果你能用,在 Fleet management 中打开 Settings,开启 Use rollouts。之后发布新版本时,除非你主动发起 rollout,否则不会有任何实例收到:

发布策略,然后选择 Roll out policy。 选择参与试点的实例数量,比如两个,然后启动。 在 Policies › Rollouts 观察:它会统计已应用新版本的实例数以及失败的实例。

试点不会自动扩大。如果那两个实例表现正常,就发起更大规模的 rollout;如果不对劲,从策略历史中打开上一个版本,选择 Restore into editor,再发布即可回滚。

接入主机的 Collector

checkout-api 跑在一台 Linux VM 上,你还想要这台 VM 的指标和 nginx 日志。在 Collectors 中选择 Add Collector,再选 Host。在 What to collect 下选择 host monitoring,然后点击 Get install command。

复制注册密钥(Logfire 只显示一次),在主机上执行命令。对于美区项目:

uvx --from 'logfire-cli>=0.1.19' logfire-cli --beta --region us --org collector install \ --project --token-stdin --yes

--token-stdin 会在不回显的情况下提示输入密钥,避免密钥留在 shell 历史里。安装程序会请求管理员权限,并把 OpenTelemetry Collector 配置为系统服务。主机不需要登录 Logfire:密钥只负责把它归入你的项目。设置页面会显示首批数据到达的时间。主机的指标随后会显示在 Hosts 视图中,《The OOM that was not your agent》一文对此有介绍。

要加入 nginx 日志,打开该主机的 Collector 策略,把 /var/log/nginx/*.log 加入 file logs,然后选择 Review version。如果该策略下的某个 Collector 缺少新版本所需的组件,review 会指出来。发布后 Collector 会自动加载。无法运行新版本的 Collector 会拒绝更新并保持现有配置,Fleet 会显示 Failed 及原因。

Kubernetes 和你已有的 Collector

对于集群,Add Collector › Kubernetes 会安装一个小型 bridge 来驱动 OpenTelemetry Operator。Fleet 的策略描述集群中各 Collector 的配置,bridge 则据此创建、更新和删除 OpenTelemetryCollector 资源。设置流程分四步,从检查 kubectl context 到执行 kubectl apply -f fleet-bridge.yaml。

如果你的 Collector 已由 Helm 或 GitOps 管理,或者像《Observability with Logfire and OpenTelemetry Collector》中那样手动搭建的,那就保持现状。选择 Add Collector › Existing Collector,获取连接密钥和一段用于 Collector Contrib 中 opamp extension 的配置片段。之后每个 Collector 都会出现在 Fleet 中,显示健康状态、组件和当前配置,标记为 Report only。Fleet 不会修改这类配置。详见 Connect an existing Collector。

查看策略带来的变化

Overview 会按 Collector 和按策略对比当前与之前的数据发送量,让你看清某次 Collector 策略变更对流量的影响。Flows 则展示每个 Collector 从哪里接收数据、发往何处。

连不上时

现象 排查方向

应用始终连不上 确认 Fleet 包在你的应用启动之前已加载,且 OTEL_OPAMP_ENDPOINT 和 OTEL_OPAMP_HEADERS 已设置。应用日志中应有连接和认证错误信息。

策略状态显示 Failed 在 Fleet 中打开该应用或 Collector,它会说明是哪项配置或组件未能应用。

收不到遥测数据 Fleet 本身不传输遥测。检查写入 token 和区域。

入门指引

Manage applications:包含各语言的完整命令。 Manage Collectors:主机和 Kubernetes 相关。 Change policies:rollouts 和版本历史。 pydantic/opamp-clients 中的各语言指南,附框架和部署示例。

下一篇:《What we found testing OpAMP clients against the spec》,介绍我们如何对照规范测试 Fleet 背后的 OpAMP 客户端,包括我们自己开发的和上游的。

评论 (0)