可观测性后端【免费下载链接】highlighthighlight.io: The open source, full-stack monitoring platform. Error monitoring, session replay, logging, distributed tracing, and more.项目地址https://gitcode.com/gh_mirrors/hi/highlight点击查看免费下载本文基于 highlight.io 官方的 Firebase 快速上手文档(docs-content/getting-started/4_server/2_js/firebase.md),讲解如何在 Firebase Cloud Functions(HTTP 函数与 Callable 函数)中集成 Node.js 版本的 Highlight SDK,实现错误监控、日志采集与分布式 Traces 三大产品能力,并结合开源仓库中 SDK 的 Handler 源码 与 e2e 示例工程,深入剖析其底层封装机制与完整可运行的验证方式。文档定位与内容来源该快速上手文档通过 Docusaurus 前端渲染组件展示,其正文内容定义在仓库内 highlight.io/components/QuickstartContent/server/js/firebase.tsx 中的JSFirebaseReorganizedContent配置里。组件元信息声明了本指南覆盖的产品范围为[Errors, Logs, Traces],副标题为 Learn how to set up highlight.io in Firebase Cloud Functions.。下文的完整操作步骤即按该组件渲染的顺序(可选前端配置 → 安装 SDK → 初始化 SDK → 接入 Firebase 集成 → 验证错误 → 验证日志 → 验证 Traces)逐项展开,并保留其中的全部代码示例与关键参数。前置步骤(可选):配置前端 Highlight如果你已经在应用前端使用了 highlight.io 的浏览器 SDK,官方文档建议先确保前端已正确初始化,并按照 fullstack mapping(全栈会话映射)指南完成前后端映射配置,这样后端记录到的错误与请求才能关联到对应的前端用户会话。该步骤对应组件中的frontendInstallSnippet,属于可选项,纯后端服务可以跳过。第一步:安装 Node 版 Highlight SDK使用 npm 安装highlight-run/node:npm install --save highlight-run/node该步骤由仓库中的jsGetSnippet([node])片段生成(见 highlight.io/components/QuickstartContent/server/js/shared-snippets-monitoring.tsx),会按传入的 slug 拼接出npm install --save highlight-run/node命令。当前仓库中该 SDK 的包版本为3.12.1(以 sdk/highlight-node/package.json 为准),依赖prisma/instrumentation与require-in-the-middle,构建产物同时提供 ESM(dist/index.js)与 CJS(dist/index.cjs)入口,因此 CommonJS 风格的require写法(下文官方示例所用)同样可用。第二步:初始化 Node SDK初始化需要传入你的项目 ID,推荐同时指定服务名与环境,便于在控制台按服务、按环境过滤数据:import { H } from highlight-run/node H.init({ projectID: YOUR_PROJECT_ID, serviceName: YOUR_SERVICE_NAME, environment: production, })需要说明的是:在 Firebase 场景中,即使你不调用H.init,Handler 封装层也会做惰性初始化(后文源码分析中会详述),但显式初始化仍然是官方文档推荐的标准做法,可以让你在 Handler 之外(例如在函数冷启动阶段、定时触发器中)上报错误与日志。第三步:添加 Firebase Highlight 集成这是本指南的核心步骤。官方提供了两个封装函数,分别对应 Firebase 的两类函数类型:Handlers.firebaseCallableFunctionHandler:用于functions.https.onCall定义的Callable Functions;Handlers.firebaseHttpFunctionHandler:用于functions.https.onRequest定义的HTTP Functions。完整集成示例(与 highlight.io/components/QuickstartContent/server/js/firebase.tsx 中给出的代码一致):const highlightNode require(highlight-run/node) // Callable function wrapper exports.exampleCallable functions.https.onCall( highlightNode.Handlers.firebaseCallableFunctionHandler( (data, context) { // ... your handler code here return { result: useful result! } }, { projectID: YOUR_PROJECT_ID, serviceName: my-firebase-app, serviceVersion: git-sha, environment: production }, ), ) // Http function wrapper exports.exampleHttp functions.https.onRequest( highlightNode.Handlers.firebaseHttpFunctionHandler( (req, res) { // ... your handler code here res.json({ result: useful result! }) }, { projectID: YOUR_PROJECT_ID }, ), )关键参数说明:参数说明projectID必填。Highlight 项目的 ID,数据将上报到该项目下serviceName服务名,用于在控制台按服务区分数据,建议与实际部署的函数组对应serviceVersion服务版本,官方示例中建议传 git sha,便于把错误与具体代码版本关联environment环境标识,如production、staging,用于多环境数据过滤metadata(第三个可选参数)结构化标签,会附加到每次上报的错误上,可用于打标如触发来源、租户 ID 等其中metadata参数在官方渲染代码中未展示,但可以在源码中得到确认:两个 Handler 的函数签名均带有可选的第三个参数metadata?: Attributes,其 JSDoc 明确写着 accepts structured tags that should be attached to every error(见 sdk/highlight-node/src/handlers.ts#L175-L214)。第四步:验证错误上报官方文档的验证方式是:在 Firebase 函数处理器中主动抛出一个异常,然后在 Highlight 控制台的错误页面确认该错误出现。对应的示例是把处理器体改为抛出错误:exports.exampleCallable functions.https.onCall( highlightNode.Handlers.firebaseCallableFunctionHandler( (data, context) { throw new Error(example error!) return { result: useful result! } }, { projectID: YOUR_PROJECT_ID, serviceName: my-firebase-app, serviceVersion: git-sha, environment: production }, ), )部署或本地启动函数后触发一次调用,即可在控制台的 Errors 页面看到example error!这条错误记录。第五步:验证日志与 Traces日志:访问 Highlight 控制台的 Logs 页面,确认来自 Firebase 函数的后端日志正在进入。Node 版 SDK 的日志来自对console方法的自动接管,因此在函数体内直接使用console.log等输出即可被采集,无需额外接线。Traces:访问控制台的 Traces 页面,确认后端追踪数据正在进入。SDK 基于 OpenTelemetry 构建(可参考 sdk/highlight-node/package.json 中大量的opentelemetry/*依赖),HTTP 函数中的出站请求与入站调用链路会被自动埋点并上报。源码剖析:两个 Firebase Handler 的底层实现快速上手的两行封装背后,是 Node SDK 中一套通用的 serverless 封装机制。阅读 sdk/highlight-node/src/handlers.ts 可以得到以下实现事实:1. 统一的 makeHandler 工厂firebaseHttpFunctionHandler(handlers.ts#L183-L195)与firebaseCallableFunctionHandler(handlers.ts#L202-L214)都委托给同一个内部工厂makeHandler(handlers.ts#L138-L173)。两者唯一的区别在于请求头提取器:HTTP 函数:从(req, res)中取req.headers,span 命名为firebase.http;Callable 函数:从(data, context)中取ctx.rawRequest(即 context 上挂载的原始请求头),span 命名为firebase.cb。提取请求头之所以关键,是因为 Highlight 的全栈会话映射依赖请求头:请求头中携带前端 SDK 写入的secureSessionId与requestId,后端据此把同一次用户会话中的前端行为与后端错误/日志关联起来。2. 单次调用的完整处理流程makeHandler返回的包装函数在每次调用时执行以下流程:惰性初始化:若H.isInitialized()为假,则用你传入的options自动调用H.init(options)。这意味着即使忘记显式初始化,函数内的错误与日志也不会丢失;上下文传播:若有请求头,则通过H.runWithHeaders(name, headers, fn)执行原处理器,把secureSessionId/requestId放入当前执行上下文,使函数体内任何H调用(日志、错误)都能自动带上会话关联信息;错误捕获:处理器抛出Error时,走processErrorImpl(handlers.ts#L23-L42)——先H.parseHeaders从请求头解析出secureSessionId与requestId,再调用H.consumeError(error, secureSessionId, requestId, metadata)完成错误上报(含你传入的metadata标签);强制刷新:await H.flush()在 finally 中执行。这一点在 Cloud Functions 这类短生命周期运行时中尤为重要——函数执行环境随时会被冻结/回收,不显式 flush 可能丢失尚未发往 ingest 端点的遥测数据;原样重抛:上报完成后throw e把错误抛回给 Firebase 框架,不影响你原有的错误处理与客户端错误响应行为。另外从源码结构看,同一套makeHandler还派生了serverlessFunction(用于 AWS Lambda 等,从event.headers提取请求头),说明 Firebase 封装并非独立实现,而是通用 serverless 封装的特化。仓库内的可运行 e2e 示例仓库提供了一个可直接运行的 Firebase 函数工程 e2e/functions,其 src/index.ts 正是按上述模式接入的 TypeScript 版本:import { Handlers } from highlight-run/node import * as functions from firebase-functions export const helloWorld functions.https.onRequest( Handlers.firebaseHttpFunctionHandler( (req, res) { // ... your handler code here res.json({ result: useful https result! }) }, { projectID: 1 }, ), ) export const hey functions.https.onCall( Handlers.firebaseCallableFunctionHandler( (data, context) { // ... your handler code here return { result: useful call result! } }, { projectID: 1, serviceName: my-firebase-app, serviceVersion: 1.0.0, environment: e2e-test, }, ), )该工程的运行配置(见 e2e/functions/package.json):运行时要求 Node 16;依赖highlight-run/node(workspace 引用)、firebase-functions^4.2.0、firebase-admin^11.5.0;提供一组常用脚本:serve(tsc 构建后启动firebase emulators:start --only functions本地模拟器)、shell/start(firebase functions:shell交互式调试)、deploy(firebase deploy --only functions仅部署函数)、logs(firebase functions:log查看函数日志)。配合根目录的 e2e/firebase.json 模拟器配置,即可在本地用 Firebase Emulator 完整走一遍部署 → 调用 → 控制台验证的闭环,不必真实部署到云端。小结接入只需一个封装:把原有 Firebase 处理器原样传入Handlers.firebaseCallableFunctionHandler或Handlers.firebaseHttpFunctionHandler,错误自动捕获、上下文自动传播、flush自动执行,无需改动业务代码;参数按环境定制:projectID必填,serviceName/serviceVersion/environment建议与部署体系(git sha、环境名)对齐,第三个metadata参数可附加结构化标签;验证路径完整:官方流程覆盖 Errors、Logs、Traces 三条数据链路的验证,且仓库自带e2e/functions工程可用 Firebase Emulator 在本地复现。赞分享可观测性后端【免费下载链接】highlighthighlight.io: The open source, full-stack monitoring platform. Error monitoring, session replay, logging, distributed tracing, and more.项目地址https://gitcode.com/gh_mirrors/hi/highlight点击查看免费下载相关推荐highlight.io Express.js 服务端监控实战用 Node.js SDK 接入错误、日志与 Traceshighlight.io Express.js 服务端监控实战用 Node.js SDK 接入错误、日志与 Traces 本文基于 highlight.io可观测性后端Highlight Go SDK 的 gqlgen 集成指南在 Go GraphQL 后端中采集错误、日志与追踪Highlight Go SDK 的 gqlgen 集成指南在 Go GraphQL 后端中采集错误、日志与追踪 本指南基于 Highlight 仓库中 Go可观测性后端ImageToolbox错误日志分析Firebase Crashlytics实战ImageToolbox错误日志分析Firebase Crashlytics实战 在移动应用开发中错误日志的收集与分析是保障应用稳定性的关键环节。Image移动开发图像处理上一篇如何把自己的QQ空间历史说说备份到本地GetQzonehistory使用教程下一篇Swift宏完全教程用独立宏与附加宏告别重复代码Swift编程语言中文版创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
