Serverless Framework Node.js 可观测性 SDK 深度指南捕获错误、设置 Tag 与自定义 Span【免费下载链接】serverless⚡ Serverless Framework – Effortlessly build apps that auto-scale, incur zero costs when idle, and require minimal maintenance using AWS Lambda and other managed cloud services.项目地址: https://gitcode.com/GitHub_Trending/se/serverlessServerless Framework Dashboard 的自动插桩虽然能采集 Metrics 与 Traces但要捕获函数内已处理的错误handled errors、记录警告并打上自定义 Tag需要在 AWS Lambda handler 中引入 Node.js 版本的 Serverless SDK。本篇完整讲解serverless/sdk与serverless/aws-lambda-sdk两个包的安装与选型、bundler 场景下的手动插桩、Source Maps 配置、错误/警告捕获、Tag 层级继承规则、结构化日志输出与自定义 Span 的创建方法并结合仓库中 Dashboard 集成与 Trace 数据处理的源码说明 SDK 生成的数据最终如何进入平台。核心概念Event、Captured Error、Captured Warning 与 TagSDK 生成的所有数据都挂在一次调用的 Trace 之下理解四个基本术语是使用 SDK 的前提EventTrace 中被捕获的 error、warning 或 notice 实例一次 Trace 中可以有多个 EventCaptured Error以 Event 形式发送到 Serverless Dashboard 的错误实例可以在 Trace Explorer 的 Details 视图中查看Captured WarningNode.js 中以字符串形式发送的警告实例处理方式与 Captured Error 类似Tag可以设置在 Trace 或单个 Event 上的键值对同样显示在 Trace Explorer 的 Details 中。这些 Event 类型在平台侧是有明确定义的。从 Trace 文档 可以看到 Dashboard 区分五类事件未捕获错误ERROR_TYPE_UNCAUGHT、通过 SDK/结构化日志/标准输出捕获的用户错误ERROR_TYPE_CAUGHT_USER、用户警告WARNING_TYPE_USER、因误用 SDK 而报告的 SDK 错误ERROR_TYPE_CAUGHT_SDK_USER以及 SDK 警告WARNING_TYPE_SDK_USER。后两类错误不会导致 handler 失败只是提示 SDK 使用有误可能导致部分数据缺失——例如setTag传入非法输入时Tag 不会被设置但会在 Trace Details 中出现一条 SDK 错误记录。安装与包选型基础场景安装 serverless/sdk当在 Serverless Dashboard 中开启 Tracing 后平台会自动向目标 AWS Lambda 函数附加一个包含serverless/sdk的 AWS Lambda Layer。但由于手动部署或某些 IaC 工具可能临时移除该 Layer官方建议将 SDK 直接 bundle 进 handler以避免对 SDK 的引用无法解析npm install serverless/sdk --save # 或 yarn add serverless/sdkSDK 本身不需要任何配置开启 Tracing 时认证凭据会自动写入 AWS Lambda 函数的环境变量。Bundler 场景serverless/aws-lambda-sdk如果 handler 使用了 esbuild 等打包工具情况会有所不同。Dashboard 的 AWS Lambda Layer 会自动插桩原生 Node.js API如http、console以及运行时可用的 AWS SDK 等 API但一旦 bundler 把express或 AWS SDK 这类依赖打包进了函数代码平台就无法再自动插桩它们。此时需要改用serverless/aws-lambda-sdk包它取代serverless/sdk两者不必同时安装npm install serverless/aws-lambda-sdk --save # 或 yarn add serverless/aws-lambda-sdk使用它手动插桩 AWS 客户端库和 Express.jsconst express require(express) const serverlessSdk require(serverless/aws-lambda-sdk) // 插桩 AWS SDK v2 serverlessSdk.instrumentation.awsSdkV2.install(AWS) // 插桩 AWS SDK v3 client serverlessSdk.instrumentation.awsSdkV3Client.install(client) // 插桩 Express.js const expressApp express() // 注意必须在安装任何 express 中间件之前完成插桩 serverlessSdk.instrumentation.expressApp.install(expressApp)两个关键细节插桩时机Express 的插桩必须在挂载任何中间件之前执行否则后续注册的路由不会被捕获保留函数名很多插桩依赖函数名来解析 Span 名称与 Tag因此不能允许 bundler 改写函数名。以 esbuild 为例可通过其官方的--keep-names选项保证。仓库中配套的 esbuild 打包插件即为serverless-esbuild见下文 Source Maps 一节配置该插件时可一并启用这一行为。别忘了开启 InstrumentationSDK 只负责生成 Tags、Spans 和 Events数据能否被平台摄入取决于是否对每个函数单独开启了 InstrumentationDashboard UI 的 Instrument 开关或通过 CLI 在serverless.yml的stages下设置observability详见 监控总览文档。这一机制在框架源码中可以得到印证部署时 Dashboard 可观测性集成服务 会通过instrumentResources接口按每批 50 个函数发送插桩请求并轮询getInstrumentationFlow等待插桩完成。也就是说即使你的 handler 里已经写好了captureError调用只要平台侧未对该函数执行插桩附加 Layer 与环境变量这些数据就不会出现在 Dashboard 中。使用 SDK在 handler 中引入const serverlessSdk require(serverless/sdk)如前所述凭据来自平台开启 Tracing 时注入的 Lambda 环境变量无需显式配置。配置 Source Maps让压缩/转译后的堆栈可读Source map 文件将转译或编译后的代码映射回原始源码。当代码经过 TypeScript、ESBuild、Babel 等工具压缩、转译或打包后错误堆栈通常难以阅读而 Source Maps 可以让 Dashboard 展示还原后的堆栈。若使用的 Serverless Framework 版本低于 3.36.0需要通过disableWrapping移除 Dashboard SDK Wrappercustom: enterprise: disableWrapping: true第一步生成 source map 文件配置转译器/打包器输出.js.map文件。推荐通过serverless-esbuild插件支持 ESBuild并在serverless.yml中添加sourcemap选项plugins: - serverless-esbuild custom: esbuild: bundle: true minify: true sourcemap: true仓库内即内置了 esbuild 插件的实现与集成测试可参考 esbuild 插件源码 以及 esbuild 集成测试 了解该插件在打包阶段的处理方式。第二步确保 source map 被打进函数包Serverless Framework 默认会把服务目录下的所有文件和目录包括生成的.js.map打进部署包.gitignore与.npmignore中列出的除外。如果使用了package.include或package.exclude务必确认*.js.map文件仍被包含。第三步让 Node 使用 Source MapsNode 14 通过修改 stack trace handler 原生支持 Source Maps需要给node传入--enable-source-mapsCLI 选项可通过NODE_OPTIONS环境变量实现provider: environment: NODE_OPTIONS: --enable-source-maps捕获错误Capturing Errors捕获已处理错误handled errors是 SDK 最常见的用途有两种方式方式一captureErrortry { // an error is thrown } catch (ex) { serverlessSdk.captureError(ex) }方式二console.errortry { // an error is thrown } catch (ex) { console.error(ex) }SDK 自动插桩了console.error如果你本来就用它打印错误几乎零成本即可获得捕获能力。行为细节只传Error对象时Dashboard 中显示该Error对象自身的堆栈传字符串或字符串与Error的组合时捕获的是console.error调用处的堆栈字符串参数也支持任意组合。捕获警告Capturing Warnings方式一captureWarningserverlessSdk.captureWarning(Something bad will happen soon)方式二console.warnconsole.warn(My Warning)console.warn同样被自动插桩且会捕获该console.warn调用的堆栈便于在 Dashboard 中定位。两点约束与最佳实践只支持捕获字符串避免在字符串中使用唯一实例值。如果需要带上userId、email、request ID 等每次调用可能不同的值应改用 Tagging见下节。这样相同的警告可以按消息聚合而唯一的上下文信息通过 Tag 检索。Tagging给 Trace 与 Event 打标签在 Trace 级别设置 TagserverlessSdk.setTag(userId, bd86489cf036)setTag创建的是整个 Trace 级别的 Tag显示在 Trace Explorer 的 Trace Details 页。所有通过setTag设置的 Tag 会被该 Trace 下的所有 Captured Errors 和 Captured Warnings继承。约束Tag 的 key 只能包含字母、数字、.、-和_value 可以是任意字符串。非法的 key 不会抛出异常而是产生一条 SDK 错误记录显示在 Trace Details 中对应 Trace 文档中提到的ERROR_TYPE_CAUGHT_SDK_USER类型Tag 本身不会被设置。与 console.error / console.warn 配合serverlessSdk.setTag(userId, bd86489cf036) console.warn(warning message) console.error(new Error(some error))由于 Captured Errors 和 Captured Warnings 可以经由console.error/console.warn产生setTag设置的 Tag 会应用到之后所有用这两种方式创建的 Captured Errors 与 Captured Warnings 上。在单个 Captured Error 上设置 TagserverlessSdk.captureError(ex, { tags: { userId: 1b8b4c6b4b14 } })也可以在单个错误上直接设置 Tag。若此前已通过setTag设置过同名 Tag则captureError中传入的 Tag 会覆盖该 Captured Error 上的同名 Tag但 Trace 级别的 Tag 保持不变。captureError的 Tag key 校验规则与setTag一致。在单个 Captured Warning 上设置 TagserverlessSdk.captureWarning(warning message, { tags: { userId: eb661c69405c }, })与 Captured Errors 相同警告也可以携带自己的 Tagkey 校验规则也一致。结构化日志输出captureError和captureWarning会以二进制格式把内容发送给 Dashboard为了兼顾人类可读性这两个方法会同时向标准输出打印一段结构化 JSON 日志例如{ source: serverlessSdk, type: ERROR_TYPE_CAUGHT_USER, message: User not found, stackTrace: ..., tags: { userId: eb661c69405c } }其中type字段与 Dashboard 的 Event 类型体系如 Trace 文档中列出的ERROR_TYPE_CAUGHT_USER一一对应。这段 JSON 除了易读还可被 CloudWatch Log Insights 等其他工具解析检索。如果不需要标准输出在运行时设置以下环境变量即可关闭SLS_DISABLE_CAPTURED_EVENTS_STDOUTtrue创建自定义 SpanSpan 是 Trace 中记录某件事何时开始、何时结束的单元可以嵌套、可以包含 Event。SDK 会自动为 AWS 服务调用和 HTTP 请求创建 Span平台侧也支持通过SLS_DISABLE_AWS_SDK_MONITORING、SLS_DISABLE_HTTP_MONITORING等环境变量关闭这两类采集详见 监控总览文档。如果需要记录业务逻辑的执行区间可以手动创建基础用法const customSpan1 serverlessSdk.createSpan(mySpan) // do some work customSpan1.close()回调形式可以把回调传给createSpanSpan 会随回调的开始/结束自动开闭serverlessSdk.createSpan(mySpan, () { // do some work })回调形式同样支持asyncserverlessSdk.createSpan(mySpan, async () { // do some work })嵌套 Span在 Span 实例上调用createSpan即可创建子 Spanconst span1 serverlessSdk.createSpan(span1) const span2 span1.createSpan(span2) // do some work span2.close() // do additional work span1.close()关闭顺序有约束子 Span 必须先于父 Span 关闭如果父 Span 被关闭其所有子 Span 会被一并关闭。设置自定义 Endpoint在 mono-lambda 架构中——单个 Lambda 函数搭配 Express.js 等框架、由 API Gateway 的单一路由端点转发——API Gateway 收到的请求会被记为 proxy 端点于是请求可能显示为/{proxy}而不是真实路径。SDK 会自动插桩 Express.js、KOA 等框架以捕获正确的 endpoint使你可以按预期路径过滤 HTTP 请求。在自动插桩不够用的场景下可以用setEndpoint手动指定serverlessSdk.setEndpoint(/my/custom/endpoint)数据流向小结SDK 数据如何到达 Dashboard从仓库源码可以完整拼出 SDK 数据的路径平台集成 AWS 账号时创建 IAM Role 并搭建 Kinesis Firehose将各函数 CloudWatch Logs 的日志汇入 Firehose每次调用时插桩层会在 CloudWatch Logs 中写入以SERVERLESS_TELEMETRY开头的压缩 Trace payload平台从 Firehose 摄入这些数据机制说明见 监控总览文档。这也解释了前文两条看似矛盾的设计其一SDK 无配置可用——凭据与路由都由插桩阶段注入其二SDK 必须与 Instrumentation 配套——没有插桩就没有 Layer 包装SDK 产生的数据也就没有上报通道。部署侧的插桩流程则由 Dashboard 集成服务 在部署钩子中驱动包含集成状态检查、按 50 个函数一批下发插桩请求、以及等待插桩完成超时后转入后台继续等步骤。适用前提与限制平台监控目前支持的 Node.js 运行时为 nodejs14.x / nodejs16.x / nodejs18.xPython 3.8 亦支持且仅限 AWS 商业区不含 GovCloud 与中国区集成后 Metrics 与 Traces 通常有最长约 10 分钟的可见延迟高流量函数默认启用 20% 的 Trace 采样产生错误/警告事件的调用永不被采样也可用SLS_DISABLE_TRACE_SAMPLING环境变量关闭采样本文所有配置与代码示例以当前仓库 docs/sf/guides/dashboard/monitoring/sdk/nodejs.md 文档为准Python 版本可参考同目录的 python.md。【免费下载链接】serverless⚡ Serverless Framework – Effortlessly build apps that auto-scale, incur zero costs when idle, and require minimal maintenance using AWS Lambda and other managed cloud services.项目地址: https://gitcode.com/GitHub_Trending/se/serverless创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考