Serverless Framework Dashboard 可观测性排障手册Metrics 与 Traces 缺失的完整诊断流程【免费下载链接】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 的 Monitoring Observability 功能自动完成 AWS 账号集成Integration与 AWS Lambda 函数的插桩Instrumentation省去手动接入监控的大量工作。但这一自动化过程依赖 IAM Role、CloudFormation Stack、Lambda Layer、Wrapper 环境变量、CloudWatch Logs 订阅等多个环节任何一个环节异常都会导致 Dashboard 中看不到 Metrics 或 Traces。本文基于官方排障文档 troubleshoot.md按官方推荐的顺序给出完整的排障 Runbook并结合本仓库中 CLI 部署流程的源码实现deploy-function.js解释为什么插桩配置会在本地部署时被破坏、以及 CLI 做了哪些保护帮助你从“现象”定位到“根因”。适用前提与数据可见性边界在开始排查前先确认两个前提避免把正常行为误判为故障数据只在集成与插桩完成之后才开始产生。Metrics 和 Traces 只有在 AWS 账号集成创建完成、且目标函数处于 Instrumented 状态之后并实际发生调用时才会出现。集成完成之前发生的调用其 Metrics/Traces 不会补显这是数据边界而非数据丢失。支持范围根据同目录的总览文档 README.md当前仅支持 Node.js 与 Python 商业区域Commercial Regions的 AWS Lambda 运行时不支持 GovCloud 与中国区域支持的运行时列表为 nodejs14.x/16.x/18.x、python3.8–3.11。函数使用了不受支持的运行时自然不会有数据。排障 Runbook按顺序执行第 1 步产生调用并等待 10 分钟重建集成则 20 分钟确认集成已创建、函数已 Instrumented 之后实际触发一次 AWS Lambda 调用让 Metrics 和 Traces 有数据可展示。集成创建后至少等待 10 分钟并在这 10 分钟之后再触发调用才会生成并展示数据。如果你刚刚移除过某个集成并立即在同一 AWS 账号中重建了新集成由于部分 AWS 资源需要较长时间删除后再重建新集成最多可能需要20 分钟才能完成设置。第 2 步确认函数已启用 Instrument启用可观测性需要两个独立步骤1) 集成 AWS 账号2) 在单个 AWS Lambda 函数上开启插桩。两步缺一不可。检查方法在 Serverless Framework Dashboard 中进入Settings Integrations点击包含缺失数据函数的 AWS Account Integration 上的Edit按钮。该视图会列出该 AWS 账号所有区域内的 AWS Lambda 函数。确认你期望看到数据的函数 Instrument 开关处于开启状态——如果未开启Metrics 与 Traces 不会出现。开启后再次调用函数并回到 Dashboard 查看。若你确定函数存在于受支持的 AWS 区域内却没有出现在这个列表中需要通过 Dashboard 内的支持渠道联系官方支持团队。第 3 步检查集成用的 CloudFormation StackStack 是否存在AWS 账号内应存在名为Serverless-Inc-Role-Stack或形似该名称的 CloudFormation Stack。它是整个集成的载体内含 Serverless Framework 平台所需的 IAM Role。Stack 是否在 us-east-1该 Stack 必须创建于us-east-1区域否则集成无法正常建立。第 4 步查看账号级集成错误在Settings Integrations视图中检查 AWS Account Integration 的卡片tile上是否显示错误。如果集成过程中发生错误会在该视图中直接呈现。若看到错误按官方建议通过 Dashboard 内的支持渠道联系支持团队处理。第 5 步处理函数级插桩错误如果Settings Integrations Edit视图中一个或多个 AWS Lambda 函数上列出了错误说明这些函数未被成功插桩Metrics 和 Traces 不会出现在 Dashboard。官方文档列举了两类常见错误错误一Rate Limit Exceeded.../Rate ExceededAWS Lambda 函数上挂载的 CloudWatch Logs 订阅Subscription Filter上限为2 个。该错误通常意味着函数已经挂满了 2 个 CloudWatch Logs 订阅插桩流程无法再添加自己的订阅。解决方法在 Dashboard 的 Integration 视图中对报此错误的函数先关闭Instrument 开关再重新打开然后记得点击Save让平台重新执行插桩。错误二Code uncompressed size is greater than the max allowed size...这意味着函数达到了未压缩代码大小上限——该上限是函数自身未压缩代码与所有 Layer 的总和。官方说明 Serverless Framework SDK 的 Layer 大约 600KB正常情况下不应成为超限原因除非你的函数本来就贴着上限。此时需要清理代码中未使用的依赖。出现其他类型错误时同样建议通过 Dashboard 内的支持渠道反馈。第 6 步排查 Trace Sampling 导致的 Trace 缺失Trace 抽样Sampling是函数级、而非账号级的自动机制当某个函数接收高流量典型阈值为每月 100 万200 万次调用或出现突发流量时该函数会自动启用抽样未命中的调用不产生 Trace 数据。如果你的函数调用量远未达到每月 100 万200 万、也没有突发流量可以排除采样因素。如需对某个函数关闭抽样可手动设置环境变量SLS_DISABLE_TRACE_SAMPLING。该变量可以在serverless.yml的 provider 或单个函数级别配置provider: environment: SLS_DISABLE_TRACE_SAMPLING: true同目录总览文档 README.md 还给出了采样机制的更细粒度说明高流量函数默认按 20% 抽样冷启动后前 5 次调用不采样平均低于每秒 1 次且调用平稳时不采样产生错误或警告事件的调用永不采样。第 7 步手动检查 Trace 载荷SERVERLESS_TELEMETRY函数被正确插桩后每次调用都会在 AWS CloudWatch Logs 中输出一段大型压缩载荷它以SERVERLESS_TELEMETRY开头承载该次调用的 Trace 数据。平台正是通过集成时创建的 Kinesis Firehose CloudWatch Logs 订阅链路摄入这类日志详见 README.md 的 How Integration Works 一节。如果 CloudWatch Logs 中看不到SERVERLESS_TELEMETRY开头的载荷Trace 就不会出现在 Dashboard——此时问题几乎一定出在插桩本身应转入第 8 步逐项核查。第 8 步逐项核查插桩四要素若 Dashboard 没有报错则需要进入 AWS 账号针对每个未上报数据的函数逐项检查1. Monitoring Observability 的 Lambda Layer 是否挂载Layer 名称形如sls-sdk-node-v0-15-12Node.js或sls-sdk-python-v0-2-3Python。AWS 对单个函数可挂载的 Layer 数量有上限Dashboard 的自动集成可能因触顶而失败。解决方法是删除一个 Layer然后在 Dashboard Integration 视图中对该函数先关闭、再打开 Instrument 开关让平台重新插桩包括重新添加 Layer。2. Wrapper 环境变量AWS_LAMBDA_EXEC_WRAPPER是否设置正确函数环境变量中必须存在AWS_LAMBDA_EXEC_WRAPPER且取值应为Node.js/opt/sls-sdk-node/exec-wrapper.shPython/opt/sls-sdk-python/exec_wrapper.py该变量是 SDK 以 Internal Extension 方式包裹你的函数入口、采集 Metrics/Traces 的前提。若另一个 Lambda Layer 也试图通过此变量包裹你的代码会发生覆盖冲突。官方明确提到Sentry的 Error Management 库曾出现此类覆盖问题。解决方式是移除所有会覆写该变量的库或自动化流程再在 Integration 视图中重新开启 Instrument 开关让平台重新写入正确配置。3. 其他必需环境变量是否齐全SLS_ORG_ID函数上还要求存在SLS_ORG_ID等环境变量。如果你已挂满或接近 AWS 对单个函数环境变量的数量/体积上限插桩流程可能无法写入所需变量。清理掉多余的环境变量后重新开启 Instrument 开关即可。4. 是否存在与其他工具、Layer、库或自定义代码的冲突任何可能影响 AWS Lambda 运行时启动方式的行为自定义 Layer、第三方库、自定义代码都可能干扰 SDK 正常工作官方指出这类冲突在 Python 运行时中更为常见。此外 Sentry 相关工具也出现过冲突官方表示在尽力修复兼容性。第 9 步开启SLS_SDK_DEBUG验证 SDK 是否初始化最后一步是验证 SDK 本身能否正常初始化为问题函数添加环境变量SLS_SDK_DEBUGtrue可以通过 Serverless Framework 配置或直接在 AWS Lambda Console 添加。随后调用该函数并检查其 CloudWatch Logs若看到日志SDK: Wrapper initialization说明 SDK 初始化成功、所需环境变量全部就位。此时问题大概率是某个工具/库/自定义代码覆写了 SDK 逻辑或平台侧摄入ingest环节有问题。若没有该日志回到第 8 步逐项核对 Layer 与四个环境变量。源码纵深为什么插桩配置会被本地部署“抹掉”排障文档反复出现一个操作模式修改后重新开启 Instrument 开关、或清理冲突后重新插桩。这个模式背后有一个常见根因——你用自己的工具如 CLIserverless deploy function重新部署函数时会用本地serverless.yml的 Layer 列表和环境变量整体覆盖远端配置从而把平台注入的 SDK Layer 和AWS_LAMBDA_EXEC_WRAPPER、SLS_ORG_ID等变量抹掉。本仓库的 CLI 已针对这一问题实现了保护逻辑阅读源码可以更准确地判断“为什么我的部署让监控数据消失了”Layer 保护deploy-function.js 中updateFunctionConfiguration()会用正则177335420605|321667558080:layer:sls-识别远端函数上属于 Serverless Console 的 SDK Layer即sls-sdk-node/sls-sdk-python系列在发出updateFunctionConfiguration请求前把这些远端 Layer ARN合并回本地 Layer 列表避免被删除// 识别远端 Serverless Console 托管的 SDK Layer const isConsoleSdkLayerArn RegExp.prototype.test.bind( /(?:177335420605|321667558080):layer:sls-/u, ) // ... if (hasServerlessConsoleLayers) { for (const layer of serverlessConsoleLayerArns) { if (!params.Layers.includes(layer)) { params.Layers.push(layer) } } }环境变量保护同文件 进一步维护了一份 Console 托管环境变量白名单——AWS_LAMBDA_EXEC_WRAPPER、SLS_ORG_ID、SLS_DEV_MODE_ORG_ID、SLS_DEV_TOKEN、SERVERLESS_PLATFORM_STAGE——只要远端存在而本地配置中没有就自动回填保证本地部署不会把插桩所需的变量冲掉。这与排障文档第 8 步中要求函数上必须存在的AWS_LAMBDA_EXEC_WRAPPER、SLS_ORG_ID完全对应。对应的单元测试 deploy-function.test.js用例 should preserve Serverless Console environment variables if layers are present 及 should preserve Console Layers when updating layers验证了当远端函数挂着arn:aws:lambda:us-east-1:177335420605:layer:sls-sdk-node:1时即使本地配置只改了自己的变量/Layer最终发出的updateFunctionConfiguration参数仍会带上远端的 Console 环境变量与 Layer。从源码结构看这一保护仅在远端已检测到 Console SDK Layer 时生效。因此排查顺序上应记住如果是从未插桩成功远端根本没有sls-sdk-*LayerCLI 的保护逻辑不会凭空替平台创建插桩配置仍需在 Dashboard 的 Integration 视图中开启 Instrument 让平台完成首次注入而一旦插桩成功用serverless deploy function更新该函数一般不会破坏监控链路——若此时数据消失应优先怀疑第 8 步中的冲突类问题如 Sentry 等第三方 Layer 覆盖AWS_LAMBDA_EXEC_WRAPPER。关键环境变量速查环境变量作用设置方式AWS_LAMBDA_EXEC_WRAPPERWrapper 入口Node.js 指向/opt/sls-sdk-node/exec-wrapper.shPython 指向/opt/sls-sdk-python/exec_wrapper.py是插桩生效的核心由平台在开启 Instrument 时写入冲突时需手动纠正SLS_ORG_ID标识函数所属 Serverless Framework 组织必需变量之一由平台写入SLS_DISABLE_TRACE_SAMPLING对单个函数关闭 Trace 抽样手动设置provider 或函数级environmentSLS_SDK_DEBUG设为true后SDK 初始化成功会在 CloudWatch Logs 输出SDK: Wrapper initialization排障时临时添加排查路径总结按依赖关系从外到内确认数据边界集成后 调用 等待 10/20 分钟→ 确认函数处于 Instrumented 状态 → 确认Serverless-Inc-Role-Stack存在于us-east-1且账号级集成无错误 → 处理函数级插桩错误订阅数超限、代码体积超限→ 排除 Trace 抽样 → 到 CloudWatch Logs 检查SERVERLESS_TELEMETRY载荷是否存在 → 逐项核对 SDK Layer、AWS_LAMBDA_EXEC_WRAPPER、SLS_ORG_ID及第三方冲突 → 用SLS_SDK_DEBUG二分定位 SDK 侧或平台侧问题。每一步都有明确的检查入口Dashboard 的 Integrations 视图、AWS CloudFormation Console、Lambda Console、CloudWatch Logs按序执行即可覆盖官方列出的全部已知故障形态更深入的 Trace 数据结构分析可参考 traces.md 与 metrics.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），仅供参考