Prefect 本地 OpenTelemetry 可观测性栈实战指南用 Jaeger 与 Prometheus 调试 Prefect Server【免费下载链接】prefectPrefect is a workflow orchestration framework for building resilient data pipelines in Python.项目地址: https://gitcode.com/GitHub_Trending/pr/prefect在 Prefect 的load_testing/local-telemetry目录下仓库为开发者预置了一套开箱即用的 OpenTelemetryOTel观测栈可以一键在本机启动 Jaeger链路追踪前端与 Prometheus指标监控用于在加载测试场景中可视化 Prefect Server 的 Trace 与 Metrics。读完本文你将掌握该观测栈的启动方式、每个容器的端口与作用、Collector 与 Prometheus 的完整配置语义以及如何把带 OTLP 导出的 Prefect Server 跑起来并观察真实请求链路。local-telemetry为加载测试而生的本地观测栈load_testing/目录承载的是仓库维护者用于调查服务器性能investigating server performance的整套工具链其中 load_testing/local-telemetry/README.md 所描述的local-telemetry子目录专门提供一套可在本地运行、用于测试与调试的 OpenTelemetry 栈。它由 4 个文件组成职责清晰文件作用start一键启动脚本创建telemetryDocker 网络并拉起整套 compose 服务docker-compose.yml定义 Prometheus、Jaeger、OpenTelemetry Collector 三个容器otelcol-config.yamlOpenTelemetry Collector 的接收、处理、导出管道配置prometheus.ymlPrometheus 的抓取任务配置整套栈遵循标准 OTLP 数据通路Prefect Server 通过 gRPC 把 Trace/Metrics 发送到 Collector端口 4317Collector 再将 Trace 转发给 Jaeger、将 Metrics 暴露给 Prometheus 抓取最终在 Web 前端上可视化。快速开始一条命令拉起整个观测栈根据 local-telemetry 的 README启动方式只有一条命令$ ./local-telemetry/start该命令会在后台启动本地 OpenTelemetry 栈运行环境需已安装 Docker。启动后会有若干服务同时运行Jaeger用于查看 Trace 的前端访问地址http://localhost:16686Prometheus采集指标前端地址http://localhost:9090随后按 load_testing/README.md 中的指引运行本地 Prefect Server。当你对本地服务器发起请求时就能在 Jaeger 前端http://localhost:16686实时看到 Trace 出现。这里有一个容易被忽略的前提start是 shell 脚本首次使用前需要赋予执行权限。仓库在 load_testing/README.md 中明确提示允许以下脚本通过chmod x运行./load_testing/local-telemetry/start ./load_testing/run-server.sh ./load_testing/populate-server.shstart 脚本做了什么查看 start 源码可以发现它只有两段逻辑#!/bin/bash if ! docker network inspect telemetry /dev/null 21; then docker network create telemetry fi docker compose --project-directory $(dirname $0) up -d即先检查名为telemetry的 Docker 网络是否存在不存在则创建然后以脚本所在目录为项目目录执行docker compose up -d。显式创建独立网络的目的是让容器之间通过服务名如collector、jaeger、prometheus互相解析——这一点在后续 Collector 的 exporter 配置中会体现。三个容器组成的观测栈端口与职责全解析docker-compose.yml 定义了 3 个服务它们之间存在明确的依赖链collector依赖jaeger与prometheusjaeger依赖prometheus。Prometheusprom/prometheus:v3.14.0负责指标存储与查询暴露以下端口9090:9090Prometheus 自身 Web 前端用于查询与告警可视化挂载./prometheus.yml为只读配置容器内路径/etc/prometheus/prometheus.ymlJaegerjaegertracing/all-in-one:1.76.0all-in-one镜像把 Collector、Query、UI 打包在一起这里主要作为 Trace 的后端存储与前端展示暴露了一整套 Jaeger 经典端口端口协议用途5775udpzipkin.thriftlegacy旧版协议6831udpjaeger.thriftcompact 压缩格式6832udpjaeger.thriftbinary 二进制格式5778tcpconfigs 配置服务16686tcpWeb 前端查询 Trace 的主入口14250tcpmodel.protogRPC 数据接入14268tcpjaeger.thriftdirect直接 HTTP 接入14269tcpJaeger 自身健康检查9411tcpzipkinHTTP 兼容接入OpenTelemetry Collectorotel/opentelemetry-collector-contrib:0.159.0这是整套栈的中枢暴露端口4317:4317OTLP gRPC 接收端口——Prefect Server 上报数据的入口8888:8888Collector 自身指标供 Prometheus 抓取8889:8889Prometheus exporter 暴露的指标端口挂载./otelcol-config.yaml为只读配置容器内路径/etc/otelcol-contrib/config.yamlCollector 管道配置逐项解读otelcol-config.yaml 是这套栈的数据路由核心采用 OpenTelemetry Collector 标准的 receivers / processors / exporters / service 四段结构receivers: otlp: protocols: grpc: endpoint: 0.0.0.0:4317 processors: batch: exporters: otlp_grpc/jaeger: endpoint: jaeger:4317 tls: insecure: true debug: prometheus: endpoint: 0.0.0.0:8889 send_timestamps: true metric_expiration: 180m resource_to_telemetry_conversion: enabled: true service: telemetry: metrics: readers: - pull: exporter: prometheus: host: 0.0.0.0 port: 8888 pipelines: traces: receivers: [otlp] processors: [batch] exporters: [otlp_grpc/jaeger, debug] metrics: receivers: [otlp] processors: [batch] exporters: [prometheus, debug] logs: receivers: [otlp] processors: [batch] exporters: [debug]receiversOTLP gRPC 入口otlpreceiver 只开启了grpc协议监听0.0.0.0:4317。这意味着 Prefect Server 只要把OTEL_EXPORTER_OTLP_PROTOCOL设为grpc、OTEL_EXPORTER_OTLP_ENDPOINT指向http://localhost:4317即可接入。processors批处理batch处理器会将多条遥测数据批量聚合后再交给 exporter减少网络往返与后端压力是生产级 Collector 配置的标配。exportersTrace 流向 Jaeger、Metrics 暴露给 Prometheusotlp_grpc/jaeger以 gRPC 协议转发到jaeger:4317利用 docker compose 服务名解析到 Jaeger 容器tls.insecure: true表示本地环境不走 TLS。这条链路就是Trace 出现在 Jaeger 前端的底层通路。prometheus在0.0.0.0:8889上以 Prometheus 文本格式暴露指标send_timestamps: true附带时间戳metric_expiration: 180m表示 180 分钟内无更新的指标自动过期resource_to_telemetry_conversion.enabled: true将 OTel 的 resource 属性如service.name转换为指标标签便于在 Prometheus 中按服务维度过滤。debug把数据打印到 Collector 日志便于本地排查数据有没有到达 Collector这类问题。service三条管道与自身指标pipelines.tracesotlp → batch → otlp_grpc/jaeger debugTrace 最终落在 Jaegerpipelines.metricsotlp → batch → prometheus debugMetrics 由 Prometheus 在 8889 抓取pipelines.logsotlp → batch → debug日志只做调试输出service.telemetry.metrics段配置了 Collector 自身的 Prometheus pull 端点0.0.0.0:8888供下面的 Prometheus 抓取任务监控 Collector 运行状态。Prometheus 抓取配置prometheus.yml 内容非常精简global: scrape_interval: 15s scrape_configs: - job_name: opentelemetry static_configs: - targets: - collector:8888 - collector:8889它每 15 秒抓取一次名为opentelemetry的任务目标为collector:8888Collector 自身指标与collector:8889Prometheus exporter 暴露的业务指标。可以看到整个 compose 网络内通过服务名互相访问的编排方式在这里形成了闭环。完整实战从零跑一个带追踪的 Prefect Serverlocal-telemetry 的 README 把运行本地服务器的细节指向了 load_testing/README.md该文件描述了一条完整的加载测试工作流。前置条件为Docker 与 OpenTelemetry 相关库。第一步安装 OpenTelemetry 依赖uv pip install opentelemetry-api \ opentelemetry-sdk \ opentelemetry-exporter-otlp \ opentelemetry-instrumentation-sqlalchemy \ opentelemetry-instrumentation-fastapi其中opentelemetry-instrumentation-sqlalchemy与opentelemetry-instrumentation-fastapi用于自动插桩 Prefect Server 底层的 SQLAlchemy 数据库访问与 FastAPI 请求处理是让 Trace 中能看到 API 调用和 SQL 细节的关键。第二步启动观测栈./load_testing/local-telemetry/start即前文介绍的一条命令启动 Jaeger Prometheus Collector。第三步带追踪运行 Prefect Serverrun-server.sh 支持 SQLite默认与 PostgreSQL 两种后端# Run with SQLite (default) ./load_testing/run-server.sh # Run with PostgreSQL 15 ./load_testing/run-server.sh postgres:15脚本的执行逻辑SQLite沿用默认配置PostgreSQL启动指定版本的 Docker 容器容器名prefect-postgres、卷名prefectdb、端口 5432用户postgres密码yourTopSecretPassword库名prefect并通过prefect config set PREFECT_API_DATABASE_CONNECTION_URLpostgresqlasyncpg://postgres:yourTopSecretPasswordlocalhost:5432/prefect配置连接脚本会做容器生命周期管理——版本一致则复用版本变化则删除容器与卷重建并用pg_isready轮询等待数据库就绪最多重试 30 次每次 1 秒。数据库类型参数非法时输出Invalid database type. Use sqlite or postgres:version并退出。随后脚本携带一组环境变量通过opentelemetry-instrument启动插桩后的 uvicorn 服务器PREFECT_API_URLhttp://localhost:4200/api \ OTEL_SERVICE_NAMEprefect-server \ OTEL_TRACES_EXPORTERotlp \ OTEL_EXPORTER_OTLP_ENDPOINThttp://localhost:4317 \ OTEL_EXPORTER_OTLP_PROTOCOLgrpc \ OTEL_LOG_LEVELdebug \ PREFECT_SERVER_ANALYTICS_ENABLEDfalse \ PREFECT_API_SERVICES_SCHEDULER_ENABLEDtrue \ PREFECT_API_SERVICES_LATE_RUNS_ENABLEDtrue \ PREFECT_UI_ENABLEDtrue \ PYTHONPATHsrc \ opentelemetry-instrument \ python -c import uvicorn from prefect.server.api.server import create_app app create_app(finalTrue, webserver_onlyeval(${NO_SERVICES}.title())) uvicorn.run(appapp, app_dirsrc, host127.0.0.1, port4200, timeout_keep_alive5, log_level${SERVER_LOGGING_LEVEL}) 这些环境变量的含义正是理解Prefect 如何接入本观测栈的钥匙环境变量值作用OTEL_SERVICE_NAMEprefect-server设置服务名Trace 在 Jaeger 中按此名分组指标也带此标签OTEL_TRACES_EXPORTERotlp指定 Trace 导出方式为 OTLPOTEL_EXPORTER_OTLP_ENDPOINThttp://localhost:4317指向本地 Collector 的 OTLP gRPC 端口OTEL_EXPORTER_OTLP_PROTOCOLgrpc使用 gRPC 协议与 Collector receiver 对应OTEL_LOG_LEVELdebug打开 OpenTelemetry 的调试日志PREFECT_SERVER_ANALYTICS_ENABLEDfalse关闭 Prefect 自身遥测避免干扰本地观测PREFECT_API_SERVICES_SCHEDULER_ENABLED/LATE_RUNS_ENABLEDtrue开启调度与迟到运行检测服务模拟真实运行行为脚本还支持两个可选参数第二个参数NO_SERVICES控制webserver_only默认False即包含完整后台服务第三个参数SERVER_LOGGING_LEVEL控制 uvicorn 日志级别默认warning。如果希望手动运行服务器load_testing/README.md 给出了等价的环境变量设置方式注意其中unset $(env | grep OTEL_ | cut -d -f1)用于清掉环境中可能残留的其他 OTel 配置避免干扰。第四步填充服务器数据要让观测栈有东西可看需要先造一些负载./load_testing/populate-server.sh该脚本见 populate-server.sh执行两条命令prefect --no-prompt work-pool create local --type process --overwrite prefect --no-prompt deploy --all --prefect-file load_testing/prefect.yaml即创建一个名为local、类型为process的工作池已存在则覆盖并依据load_testing/prefect.yaml部署所有流程。第五步启动 Worker 产生真实负载prefect worker start --pool localWorker 启动后会从local工作池拉取并执行流程运行flow run这些运行产生的 API 请求、数据库操作都会被插桩并上报于是 Jaeger 前端http://localhost:16686中就能看到成串的 Trace。源码侧印证Prefect Server 的遥测接入点观测栈之所以能看到 Prefect Server是因为服务器内部确实接入了 OpenTelemetry。在src/prefect下检索opentelemetry相关引用可以看到遥测能力散落在多个核心模块中src/prefect/_internal/metrics.py内置指标定义与采集是 Metrics 数据的来源之一src/prefect/telemetry/run_telemetry.py运行态遥测的组装与导出逻辑src/prefect/flow_engine.py、src/prefect/task_engine.py、src/prefect/states.py、src/prefect/deployments/flow_runs.py、src/prefect/utilities/engine/init.py在流程执行、任务执行、状态转换、流程运行等关键路径上埋点。结合run-server.sh中通过opentelemetry-instrument启动进程的做法可以推断本观测栈主要依赖自动插桩FastAPI、SQLAlchemy instrumentation捕获 HTTP 与数据库 Span同时叠加 Prefect 内部模块的遥测点共同构成加载测试时可观测的完整数据面。如果你对某一类 Trace如某个流程运行的完整链路的来源存疑可以直接在上述模块中检索对应埋点来核对。常见排查思路Jaeger 前端16686没有 Trace优先检查 Collector 的debugexporter 日志确认 OTLP 数据是否到达 4317再确认OTEL_EXPORTER_OTLP_ENDPOINT、OTEL_EXPORTER_OTLP_PROTOCOLgrpc两个环境变量是否生效手动运行时不要漏掉unset $(env | grep OTEL_ ...)清环境。Prometheus9090查不到指标检查collector:8889是否可被抓取以及指标是否因超过metric_expiration: 180m而过期必要时可先在 8889 端口直接 curl 验证 exporter 是否在输出文本指标。端口冲突4317、8888、8889、9090、16686 均为宿主端口映射若本机已有服务占用需调整 compose 端口映射。PostgreSQL 容器被反复重建run-server.sh在检测到请求版本与现有容器版本不一致时会删除容器与卷这是预期行为用于保证干净的加载测试环境配合 track_cnx.py 还可以实时监控数据库连接状态按pg_stat_activity轮询高亮显示卡在ClientRead超过 5 秒、事务超过 10 秒或等待锁的连接。小结load_testing/local-telemetry用一套极简的 compose 编排把本地查看 Prefect Server 的 Trace 与 Metrics这件事压缩成了一条./local-telemetry/start命令。理解它的关键在于把握数据通路Prefect ServerOTLP gRPC→ Collector4317→ 按管道分发 → JaegerTrace16686 查看与 PrometheusMetrics9090 查看。配合 run-server.sh 与 populate-server.sh 使用即可在本地完整复现启动服务器 → 注入负载 → 观察链路的加载测试闭环为定位性能瓶颈提供最直接的观测依据。【免费下载链接】prefectPrefect is a workflow orchestration framework for building resilient data pipelines in Python.项目地址: https://gitcode.com/GitHub_Trending/pr/prefect创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Prefect 本地 OpenTelemetry 可观测性栈实战指南：用 Jaeger 与 Prometheus 调试 Prefect Server
Prefect 本地 OpenTelemetry 可观测性栈实战指南用 Jaeger 与 Prometheus 调试 Prefect Server【免费下载链接】prefectPrefect is a workflow orchestration framework for building resilient data pipelines in Python.项目地址: https://gitcode.com/GitHub_Trending/pr/prefect在 Prefect 的load_testing/local-telemetry目录下仓库为开发者预置了一套开箱即用的 OpenTelemetryOTel观测栈可以一键在本机启动 Jaeger链路追踪前端与 Prometheus指标监控用于在加载测试场景中可视化 Prefect Server 的 Trace 与 Metrics。读完本文你将掌握该观测栈的启动方式、每个容器的端口与作用、Collector 与 Prometheus 的完整配置语义以及如何把带 OTLP 导出的 Prefect Server 跑起来并观察真实请求链路。local-telemetry为加载测试而生的本地观测栈load_testing/目录承载的是仓库维护者用于调查服务器性能investigating server performance的整套工具链其中 load_testing/local-telemetry/README.md 所描述的local-telemetry子目录专门提供一套可在本地运行、用于测试与调试的 OpenTelemetry 栈。它由 4 个文件组成职责清晰文件作用start一键启动脚本创建telemetryDocker 网络并拉起整套 compose 服务docker-compose.yml定义 Prometheus、Jaeger、OpenTelemetry Collector 三个容器otelcol-config.yamlOpenTelemetry Collector 的接收、处理、导出管道配置prometheus.ymlPrometheus 的抓取任务配置整套栈遵循标准 OTLP 数据通路Prefect Server 通过 gRPC 把 Trace/Metrics 发送到 Collector端口 4317Collector 再将 Trace 转发给 Jaeger、将 Metrics 暴露给 Prometheus 抓取最终在 Web 前端上可视化。快速开始一条命令拉起整个观测栈根据 local-telemetry 的 README启动方式只有一条命令$ ./local-telemetry/start该命令会在后台启动本地 OpenTelemetry 栈运行环境需已安装 Docker。启动后会有若干服务同时运行Jaeger用于查看 Trace 的前端访问地址http://localhost:16686Prometheus采集指标前端地址http://localhost:9090随后按 load_testing/README.md 中的指引运行本地 Prefect Server。当你对本地服务器发起请求时就能在 Jaeger 前端http://localhost:16686实时看到 Trace 出现。这里有一个容易被忽略的前提start是 shell 脚本首次使用前需要赋予执行权限。仓库在 load_testing/README.md 中明确提示允许以下脚本通过chmod x运行./load_testing/local-telemetry/start ./load_testing/run-server.sh ./load_testing/populate-server.shstart 脚本做了什么查看 start 源码可以发现它只有两段逻辑#!/bin/bash if ! docker network inspect telemetry /dev/null 21; then docker network create telemetry fi docker compose --project-directory $(dirname $0) up -d即先检查名为telemetry的 Docker 网络是否存在不存在则创建然后以脚本所在目录为项目目录执行docker compose up -d。显式创建独立网络的目的是让容器之间通过服务名如collector、jaeger、prometheus互相解析——这一点在后续 Collector 的 exporter 配置中会体现。三个容器组成的观测栈端口与职责全解析docker-compose.yml 定义了 3 个服务它们之间存在明确的依赖链collector依赖jaeger与prometheusjaeger依赖prometheus。Prometheusprom/prometheus:v3.14.0负责指标存储与查询暴露以下端口9090:9090Prometheus 自身 Web 前端用于查询与告警可视化挂载./prometheus.yml为只读配置容器内路径/etc/prometheus/prometheus.ymlJaegerjaegertracing/all-in-one:1.76.0all-in-one镜像把 Collector、Query、UI 打包在一起这里主要作为 Trace 的后端存储与前端展示暴露了一整套 Jaeger 经典端口端口协议用途5775udpzipkin.thriftlegacy旧版协议6831udpjaeger.thriftcompact 压缩格式6832udpjaeger.thriftbinary 二进制格式5778tcpconfigs 配置服务16686tcpWeb 前端查询 Trace 的主入口14250tcpmodel.protogRPC 数据接入14268tcpjaeger.thriftdirect直接 HTTP 接入14269tcpJaeger 自身健康检查9411tcpzipkinHTTP 兼容接入OpenTelemetry Collectorotel/opentelemetry-collector-contrib:0.159.0这是整套栈的中枢暴露端口4317:4317OTLP gRPC 接收端口——Prefect Server 上报数据的入口8888:8888Collector 自身指标供 Prometheus 抓取8889:8889Prometheus exporter 暴露的指标端口挂载./otelcol-config.yaml为只读配置容器内路径/etc/otelcol-contrib/config.yamlCollector 管道配置逐项解读otelcol-config.yaml 是这套栈的数据路由核心采用 OpenTelemetry Collector 标准的 receivers / processors / exporters / service 四段结构receivers: otlp: protocols: grpc: endpoint: 0.0.0.0:4317 processors: batch: exporters: otlp_grpc/jaeger: endpoint: jaeger:4317 tls: insecure: true debug: prometheus: endpoint: 0.0.0.0:8889 send_timestamps: true metric_expiration: 180m resource_to_telemetry_conversion: enabled: true service: telemetry: metrics: readers: - pull: exporter: prometheus: host: 0.0.0.0 port: 8888 pipelines: traces: receivers: [otlp] processors: [batch] exporters: [otlp_grpc/jaeger, debug] metrics: receivers: [otlp] processors: [batch] exporters: [prometheus, debug] logs: receivers: [otlp] processors: [batch] exporters: [debug]receiversOTLP gRPC 入口otlpreceiver 只开启了grpc协议监听0.0.0.0:4317。这意味着 Prefect Server 只要把OTEL_EXPORTER_OTLP_PROTOCOL设为grpc、OTEL_EXPORTER_OTLP_ENDPOINT指向http://localhost:4317即可接入。processors批处理batch处理器会将多条遥测数据批量聚合后再交给 exporter减少网络往返与后端压力是生产级 Collector 配置的标配。exportersTrace 流向 Jaeger、Metrics 暴露给 Prometheusotlp_grpc/jaeger以 gRPC 协议转发到jaeger:4317利用 docker compose 服务名解析到 Jaeger 容器tls.insecure: true表示本地环境不走 TLS。这条链路就是Trace 出现在 Jaeger 前端的底层通路。prometheus在0.0.0.0:8889上以 Prometheus 文本格式暴露指标send_timestamps: true附带时间戳metric_expiration: 180m表示 180 分钟内无更新的指标自动过期resource_to_telemetry_conversion.enabled: true将 OTel 的 resource 属性如service.name转换为指标标签便于在 Prometheus 中按服务维度过滤。debug把数据打印到 Collector 日志便于本地排查数据有没有到达 Collector这类问题。service三条管道与自身指标pipelines.tracesotlp → batch → otlp_grpc/jaeger debugTrace 最终落在 Jaegerpipelines.metricsotlp → batch → prometheus debugMetrics 由 Prometheus 在 8889 抓取pipelines.logsotlp → batch → debug日志只做调试输出service.telemetry.metrics段配置了 Collector 自身的 Prometheus pull 端点0.0.0.0:8888供下面的 Prometheus 抓取任务监控 Collector 运行状态。Prometheus 抓取配置prometheus.yml 内容非常精简global: scrape_interval: 15s scrape_configs: - job_name: opentelemetry static_configs: - targets: - collector:8888 - collector:8889它每 15 秒抓取一次名为opentelemetry的任务目标为collector:8888Collector 自身指标与collector:8889Prometheus exporter 暴露的业务指标。可以看到整个 compose 网络内通过服务名互相访问的编排方式在这里形成了闭环。完整实战从零跑一个带追踪的 Prefect Serverlocal-telemetry 的 README 把运行本地服务器的细节指向了 load_testing/README.md该文件描述了一条完整的加载测试工作流。前置条件为Docker 与 OpenTelemetry 相关库。第一步安装 OpenTelemetry 依赖uv pip install opentelemetry-api \ opentelemetry-sdk \ opentelemetry-exporter-otlp \ opentelemetry-instrumentation-sqlalchemy \ opentelemetry-instrumentation-fastapi其中opentelemetry-instrumentation-sqlalchemy与opentelemetry-instrumentation-fastapi用于自动插桩 Prefect Server 底层的 SQLAlchemy 数据库访问与 FastAPI 请求处理是让 Trace 中能看到 API 调用和 SQL 细节的关键。第二步启动观测栈./load_testing/local-telemetry/start即前文介绍的一条命令启动 Jaeger Prometheus Collector。第三步带追踪运行 Prefect Serverrun-server.sh 支持 SQLite默认与 PostgreSQL 两种后端# Run with SQLite (default) ./load_testing/run-server.sh # Run with PostgreSQL 15 ./load_testing/run-server.sh postgres:15脚本的执行逻辑SQLite沿用默认配置PostgreSQL启动指定版本的 Docker 容器容器名prefect-postgres、卷名prefectdb、端口 5432用户postgres密码yourTopSecretPassword库名prefect并通过prefect config set PREFECT_API_DATABASE_CONNECTION_URLpostgresqlasyncpg://postgres:yourTopSecretPasswordlocalhost:5432/prefect配置连接脚本会做容器生命周期管理——版本一致则复用版本变化则删除容器与卷重建并用pg_isready轮询等待数据库就绪最多重试 30 次每次 1 秒。数据库类型参数非法时输出Invalid database type. Use sqlite or postgres:version并退出。随后脚本携带一组环境变量通过opentelemetry-instrument启动插桩后的 uvicorn 服务器PREFECT_API_URLhttp://localhost:4200/api \ OTEL_SERVICE_NAMEprefect-server \ OTEL_TRACES_EXPORTERotlp \ OTEL_EXPORTER_OTLP_ENDPOINThttp://localhost:4317 \ OTEL_EXPORTER_OTLP_PROTOCOLgrpc \ OTEL_LOG_LEVELdebug \ PREFECT_SERVER_ANALYTICS_ENABLEDfalse \ PREFECT_API_SERVICES_SCHEDULER_ENABLEDtrue \ PREFECT_API_SERVICES_LATE_RUNS_ENABLEDtrue \ PREFECT_UI_ENABLEDtrue \ PYTHONPATHsrc \ opentelemetry-instrument \ python -c import uvicorn from prefect.server.api.server import create_app app create_app(finalTrue, webserver_onlyeval(${NO_SERVICES}.title())) uvicorn.run(appapp, app_dirsrc, host127.0.0.1, port4200, timeout_keep_alive5, log_level${SERVER_LOGGING_LEVEL}) 这些环境变量的含义正是理解Prefect 如何接入本观测栈的钥匙环境变量值作用OTEL_SERVICE_NAMEprefect-server设置服务名Trace 在 Jaeger 中按此名分组指标也带此标签OTEL_TRACES_EXPORTERotlp指定 Trace 导出方式为 OTLPOTEL_EXPORTER_OTLP_ENDPOINThttp://localhost:4317指向本地 Collector 的 OTLP gRPC 端口OTEL_EXPORTER_OTLP_PROTOCOLgrpc使用 gRPC 协议与 Collector receiver 对应OTEL_LOG_LEVELdebug打开 OpenTelemetry 的调试日志PREFECT_SERVER_ANALYTICS_ENABLEDfalse关闭 Prefect 自身遥测避免干扰本地观测PREFECT_API_SERVICES_SCHEDULER_ENABLED/LATE_RUNS_ENABLEDtrue开启调度与迟到运行检测服务模拟真实运行行为脚本还支持两个可选参数第二个参数NO_SERVICES控制webserver_only默认False即包含完整后台服务第三个参数SERVER_LOGGING_LEVEL控制 uvicorn 日志级别默认warning。如果希望手动运行服务器load_testing/README.md 给出了等价的环境变量设置方式注意其中unset $(env | grep OTEL_ | cut -d -f1)用于清掉环境中可能残留的其他 OTel 配置避免干扰。第四步填充服务器数据要让观测栈有东西可看需要先造一些负载./load_testing/populate-server.sh该脚本见 populate-server.sh执行两条命令prefect --no-prompt work-pool create local --type process --overwrite prefect --no-prompt deploy --all --prefect-file load_testing/prefect.yaml即创建一个名为local、类型为process的工作池已存在则覆盖并依据load_testing/prefect.yaml部署所有流程。第五步启动 Worker 产生真实负载prefect worker start --pool localWorker 启动后会从local工作池拉取并执行流程运行flow run这些运行产生的 API 请求、数据库操作都会被插桩并上报于是 Jaeger 前端http://localhost:16686中就能看到成串的 Trace。源码侧印证Prefect Server 的遥测接入点观测栈之所以能看到 Prefect Server是因为服务器内部确实接入了 OpenTelemetry。在src/prefect下检索opentelemetry相关引用可以看到遥测能力散落在多个核心模块中src/prefect/_internal/metrics.py内置指标定义与采集是 Metrics 数据的来源之一src/prefect/telemetry/run_telemetry.py运行态遥测的组装与导出逻辑src/prefect/flow_engine.py、src/prefect/task_engine.py、src/prefect/states.py、src/prefect/deployments/flow_runs.py、src/prefect/utilities/engine/init.py在流程执行、任务执行、状态转换、流程运行等关键路径上埋点。结合run-server.sh中通过opentelemetry-instrument启动进程的做法可以推断本观测栈主要依赖自动插桩FastAPI、SQLAlchemy instrumentation捕获 HTTP 与数据库 Span同时叠加 Prefect 内部模块的遥测点共同构成加载测试时可观测的完整数据面。如果你对某一类 Trace如某个流程运行的完整链路的来源存疑可以直接在上述模块中检索对应埋点来核对。常见排查思路Jaeger 前端16686没有 Trace优先检查 Collector 的debugexporter 日志确认 OTLP 数据是否到达 4317再确认OTEL_EXPORTER_OTLP_ENDPOINT、OTEL_EXPORTER_OTLP_PROTOCOLgrpc两个环境变量是否生效手动运行时不要漏掉unset $(env | grep OTEL_ ...)清环境。Prometheus9090查不到指标检查collector:8889是否可被抓取以及指标是否因超过metric_expiration: 180m而过期必要时可先在 8889 端口直接 curl 验证 exporter 是否在输出文本指标。端口冲突4317、8888、8889、9090、16686 均为宿主端口映射若本机已有服务占用需调整 compose 端口映射。PostgreSQL 容器被反复重建run-server.sh在检测到请求版本与现有容器版本不一致时会删除容器与卷这是预期行为用于保证干净的加载测试环境配合 track_cnx.py 还可以实时监控数据库连接状态按pg_stat_activity轮询高亮显示卡在ClientRead超过 5 秒、事务超过 10 秒或等待锁的连接。小结load_testing/local-telemetry用一套极简的 compose 编排把本地查看 Prefect Server 的 Trace 与 Metrics这件事压缩成了一条./local-telemetry/start命令。理解它的关键在于把握数据通路Prefect ServerOTLP gRPC→ Collector4317→ 按管道分发 → JaegerTrace16686 查看与 PrometheusMetrics9090 查看。配合 run-server.sh 与 populate-server.sh 使用即可在本地完整复现启动服务器 → 注入负载 → 观察链路的加载测试闭环为定位性能瓶颈提供最直接的观测依据。【免费下载链接】prefectPrefect is a workflow orchestration framework for building resilient data pipelines in Python.项目地址: https://gitcode.com/GitHub_Trending/pr/prefect创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考