Backstage 后端如何启用 OpenTelemetry 追踪与指标导出【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstageBackstage 的各个组件如 catalog通过 OpenTelemetry API 上报 traces 和 metrics但 Backstage 本身不负责初始化 OpenTelemetry SDK——你需要在自己的后端包里安装 SDK 与 exporter、创建 instrumentation 文件并在后端启动前加载它。完成后指标可以通过 Prometheus exporter 在http://localhost:9464/metrics暴露trace 可以通过 OTLP/HTTP exporter 推送到 Jaeger 等接收端。本文基于 Backstage 官方教程 Setup OpenTelemetry走一遍从安装依赖到本地验证、再到 Docker 生产配置的完整路径。原理为什么必须用--require加载有一个关键顺序约束NodeSDK 和自动插桩必须在导入任何业务库之前初始化否则 Express 等库的调用不会被自动创建 span。这就是教程要求在启动 Node 进程时使用--require参数提前加载 instrumentation 文件的原因本文的本地开发和 Docker 两条路径都围绕这一点展开。安装依赖在仓库根目录执行yarn --cwd packages/backend add \ opentelemetry/sdk-node \ opentelemetry/auto-instrumentations-node \ opentelemetry/exporter-prometheus \ opentelemetry/exporter-trace-otlp-http其中sdk-node提供 NodeSDKauto-instrumentations-node会为 Express 等库自动创建 spanexporter-prometheus用于指标导出exporter-trace-otlp-http用于将 trace 通过 OTLP/HTTP 协议推送到接收端。教程以 Prometheus Jaeger 作为演示组合你可以按自己的技术栈替换 exporter但依赖安装、instrumentation 文件和--require加载这三步结构不变。作为版本参考本仓库 packages/backend/package.json 当前使用的版本是opentelemetry/sdk-node ^0.221.0、opentelemetry/auto-instrumentations-node ^0.79.0、opentelemetry/exporter-prometheus ^0.221.0、opentelemetry/api ^1.9.0。创建 instrumentation.js在packages/backend/src下创建instrumentation.js文件内容如下来自教程的完整示例可直接使用// Prevent from running more than once (due to worker threads) const { isMainThread } require(node:worker_threads); if (isMainThread) { const { NodeSDK } require(opentelemetry/sdk-node); const { getNodeAutoInstrumentations, } require(opentelemetry/auto-instrumentations-node); const { PrometheusExporter } require(opentelemetry/exporter-prometheus); const { OTLPTraceExporter, } require(opentelemetry/exporter-trace-otlp-http); // By default exports the metrics on localhost:9464/metrics const prometheusExporter new PrometheusExporter(); // We post the traces to localhost:4318/v1/traces const otlpTraceExporter new OTLPTraceExporter({ // Default Jaeger URL trace endpoint. url: http://localhost:4318/v1/traces, }); const sdk new NodeSDK({ metricReader: prometheusExporter, traceExporter: otlpTraceExporter, instrumentations: [getNodeAutoInstrumentations()], }); sdk.start(); }两点说明开头的isMainThread判断是为了防止 worker 线程导致 SDK 重复初始化不要省略。OTLPTraceExporter的url是 Jaeger 的默认 trace 接收端点如果你的接收端不同需要替换getNodeAutoInstrumentations()会启用一组自动插桩教程提醒按需裁剪避免启用用不到的插桩。本仓库自带了一份只启用指标导出的参考实现 packages/backend/src/instrumentation.js它只配置了PrometheusExportertraceExporter一行处于注释状态。如果你只需要 Prometheus 抓指标、暂不推 trace可以参考这份更精简的写法要同时导出 trace则按上面的教程版本补全 OTLP exporter。本地开发接入 start 脚本并验证教程要求修改packages/backend/package.json的start脚本加上--require参数scripts: { start: backstage-cli package start --require ./src/instrumentation.js, ... }本仓库 packages/backend/package.json 中的 start 脚本已经是这个形态说明教程路径与仓库实际配置一致。接下来按常规方式启动实例yarn start验证指标导出打开http://localhost:9464/metrics能看到 Prometheus 格式的指标即表示 PrometheusExporter 工作正常。验证 trace 导出trace 被推送到http://localhost:4318/v1/traces需要在接收端确认。若按教程使用 Jaeger可在 Jaeger UI 中查看由自动插桩和 Backstage 组件产生的 span。可选用本地 Prometheus 抓取指标仓库提供了示例抓取配置 packages/backend/prometheus.yml抓host.docker.internal:9464该目标地址针对 Docker for MacOS其他 OS 和 Docker 引擎可能要换 host 地址。在 Backstage 根目录执行以下命令会启动一个本地 Prometheus 容器监听 9090 端口docker run --mount typebind,source./packages/backend/prometheus.yml,destination/etc/prometheus/prometheus.yml --publish published9090,target9090,protocoltcp prom/prometheus启动后访问http://localhost:9090即可查询抓到的指标packages/backend的start:prometheus脚本执行的也是同一条命令。可选调整直方图分桶ViewsOpenTelemetry 默认直方图分桶单位是毫秒但 Catalog 处理流程产生的直方图指标单位是秒分桶可能对不上。教程建议用 Views 功能调整聚合方式以下两个片段均为文档示例演示整体替换与针对性调整两种写法注意它们是 NodeSDK 构造参数片段的示意View、ExplicitBucketHistogramAggregation的引入方式参照主代码块中的 require 写法补齐// 文档示例所有直方图使用同一套分桶 const prometheus new PrometheusExporter(); const sdk new NodeSDK({ metricReader: prometheus, views: [ new View({ instrumentName: catalog.test, aggregation: new ExplicitBucketHistogramAggregation([ 0.01, 0.1, 0.5, 1, 5, 10, 25, 50, 100, 500, 1000, ]), }), ], });// 文档示例更有针对性的分桶 const prometheus new PrometheusExporter(); const sdk new NodeSDK({ metricReader: prometheus, views: [ new View({ instrumentName: catalog.test, aggregation: new ExplicitBucketHistogramAggregation([ 0, 0.01, 0.05, 0.1, 0.25, 0.5, 1, 2, 5, 10, 30, 60, 120, 300, 1000, ]), }), ], });生产环境Docker 构建接入Docker 部署需要两处改动在.dockerignore中加一行防止构建时把 instrumentation 文件过滤掉前提是你在用推荐的.dockerignore配置!packages/backend/src/instrumentation.js在Dockerfile中把instrumentation.js拷进工作目录根并在 CMD 中加--requireCOPY --chown${NOT_ROOT_USER}:${NOT_ROOT_USER} packages/backend/src/instrumentation.js ./ CMD [node, --require, ./instrumentation.js, packages/backend, --config, app-config.yaml]对照本仓库的 packages/backend/Dockerfile当前 CMD 是[node, packages/backend, --config, app-config.yaml]既没有拷贝 instrumentation.js也没有--require参数——也就是说示例镜像默认不带 OpenTelemetry 导出需要按教程自行补上这两处。如果运行时需要开关或调整某些 OpenTelemetry 行为可以使用 OpenTelemetry SDK 支持的标准环境变量来配置。指标或 trace 不生效时的排查教程给出的诊断手段是打开 OpenTelemetry 自带的 debug 日志。先安装 API 包yarn --cwd packages/backend add opentelemetry/api然后在instrumentation.js中sdk.start()调用之前加入const { diag, DiagConsoleLogger, DiagLogLevel } require(opentelemetry/api); diag.setLogger(new DiagConsoleLogger(), DiagLogLevel.DEBUG);这样 OpenTelemetry 会输出 debug 日志帮助判断是 SDK 没启动、exporter 配置错误还是数据没被采集。教程明确不建议在生产环境保留这段代码因为日志密度太高。启动后应该能在指标端点看到什么Prometheus exporter 启动后http://localhost:9464/metrics会暴露 Backstage 内置的一组指标教程列出的完整清单catalog_entities_countcatalog 中实体总数catalog_registered_locations_count已注册 location 总数catalog_relations_count实体间关系总数catalog.processed.entities.count已处理实体数catalog.processing.duration完整处理流程耗时catalog.processors.durationcatalog 处理器执行耗时catalog.processing.queue.delay调度处理与实际开始处理之间的延迟catalog.stitched.entities.count已 stitched 实体数catalog.stitching.duration完整 stitching 流程耗时catalog.stitching.queue.length当前 stitching 队列长度catalog.stitching.queue.delay调度 stitching 与开始 stitching 之间的延迟scaffolder.task.count/scaffolder.task.duration任务运行次数与耗时scaffolder.step.count/scaffolder.step.duration步骤运行次数与耗时backend_tasks.task.runs.count任务总运行次数backend_tasks.task.runs.duration任务运行耗时直方图backend_tasks.task.runs.started各任务taskId标签最近一次启动的 Unix 时间秒backend_tasks.task.runs.completed各任务最近一次完成的 Unix 时间秒具体能收到哪些指标取决于你安装了哪些插件及其版本。与插件级 Metrics / Tracing 服务的关系Backstage 还内置了 alpha 阶段的 Metrics Service 和 Tracing Service供后端插件发出应用级指标和 span例如处理器处理了多少实体、单个任务执行细节。两者都不初始化 OpenTelemetry SDK依赖本文配置的 SDK、exporter 和自动插桩先就绪自动插桩负责基础设施层信号HTTP 请求数与耗时等这两个服务负责只有插件自身能提供的应用级信号。所以完成本文的 SDK 接入是插件级指标和 trace 上报的前提。生产部署的监控视角关键告警指标、健康检查端点等可继续参考 Monitoring your deployment。【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
