企业官网建设流程全解析

• 可观测性
• 后端

本文基于 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>' }, ), )

关键参数说明:

其中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返回的包装函数在每次调用时执行以下流程:

1. 惰性初始化:若H.isInitialized()为假,则用你传入的options自动调用H.init(options)。这意味着即使忘记显式初始化,函数内的错误与日志也不会丢失;
2. 上下文传播:若有请求头,则通过H.runWithHeaders(name, headers, fn)执行原处理器,把secureSessionId/requestId放入当前执行上下文,使函数体内任何H调用(日志、错误)都能自动带上会话关联信息;
3. 错误捕获:处理器抛出Error时,走processErrorImpl(handlers.ts#L23-L42)——先H.parseHeaders从请求头解析出secureSessionId与requestId,再调用H.consumeError(error, secureSessionId, requestId, metadata)完成错误上报(含你传入的metadata标签);
4. 强制刷新:await H.flush()在 finally 中执行。这一点在 Cloud Functions 这类短生命周期运行时中尤为重要——函数执行环境随时会被冻结/回收,不显式 flush 可能丢失尚未发往 ingest 端点的遥测数据;
5. 原样重抛:上报完成后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 在本地复现。

• 可观测性
• 后端