Serverless Framework Monitoring Observability：AWS 账户接入、Lambda 埋点与 Trace 采样控制全解析

Serverless Framework Monitoring ObservabilityAWS 账户接入、Lambda 埋点与 Trace 采样控制全解析【免费下载链接】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本文围绕 Serverless Framework 的 Monitoring Observability监控与可观测性功能展开先讲清它能在 Dashboard 中提供什么跨账户 Metrics/Traces/Logs/Errors 全局视图再完整覆盖两条官方接入路径——Dashboard UI 与 CLI serverless.yml配置最后深入源码解释stages.stage.observability的解析逻辑、集成底层原理IAM Role、Kinesis Firehose、Lambda Layer 包装器以及 Trace 采样、AWS SDK/HTTP Span 的关闭方式。读完本文你可以在自己的 AWS 账户上完成从接入、验证数据到按需关闭全部功能的操作并能排查常见的埋点失败问题。功能概览Serverless Framework 的 Monitoring Observability 让你无需自己搭建复杂的埋点链路就能在 Dashboard 中跨所有已接入的 AWS 账户和 Serverless Framework Service 查看 Lambda 函数的运行数据。其核心能力包括跨所有已接入 AWS 账户的 Metrics、Traces、Logs、Errors 全局视图通过强力的过滤器检索数据即时错误告警Instant error alerts自动对高流量函数进行 Trace 采样以控制成本能识别代码中定义的 API 路由例如 Express.js 的路由而不是 API Gateway 层的/{proxy}无需手动埋点或复杂 instrumentation开箱即用。一个重要的适用前提该功能不依赖你是否通过 Serverless Framework 部署——只要把 AWS 账户接入平台即使函数是用其他部署工具发布的也能开启监控。支持范围与接入前提在动手之前先确认你的环境满足以下支持范围以当前仓库文档为准支持的 AWS Lambda Runtime见 monitoring/README.mdnodejs14.x / nodejs16.x / nodejs18.xpython3.8 / python3.9 / python3.10 / python3.11文档同时声明整体支持 Node.js 12 与 Python 3.8 的 Lambda runtime且仅支持 AWS 商业区域Commercial Regions不支持 GovCloud 与中国区。接入的前提条件先注册一个 Serverless Framework 平台账户在 Serverless Framework 官网创建通过 IAM Role 把 AWS 账户直接连接给 Serverless Framework 平台。该 IAM Role 所需权限在官方 Dashboard 仓库中以 CloudFormation 模板形式公开可自行审阅注意开启功能会在被接入的 AWS 账户中创建少量资源如 CloudFormation Stack、Kinesis Firehose会带来少量额外 AWS 成本。接入方式一通过 Dashboard UI适合多账户 / 大量函数官方文档认为对于多个 AWS 账户或单账户内大量 Lambda 函数的场景Dashboard UI 是最方便的接入方式。完整步骤如下在 Dashboard 左侧导航栏点击 Settings 图标进入 Integrations 标签页——这是连接 AWS 账户的入口在另一个浏览器窗口中登录你想接入的 AWS 账户需要有权创建带所需权限的 IAM Role在 Integrations 视图点击 Add Integrations。这会弹出一个新的浏览器窗口打开 AWS Console 的 CloudFormation Stack 创建页面模板中已预置了包含 IAM Role含监控所需全部权限的 CloudFormation Stack 模板在页面底部点击 CreateStack 创建期间切回 DashboardIntegrations 视图会实时检测 Stack 创建状态并持续刷新直到集成完成无需其他操作重复以上步骤即可接入任意数量的 AWS 账户。接入后还需要选择要开启监控的 Lambda 函数在 Integrations 视图中能看到新建的 AWS Integration建议先给它命名例如 production、development方便在 Dashboard 查询过滤器中识别点击该 Integration 的 Edit 按钮会列出该账户内所有 AWS Lambda 函数对单个函数点击 Instrument 开关或点击表头开关一次开启当前页全部函数多页时需逐页操作然后点击 Save。埋点instrumentation在后台异步进行可以逐页继续开启之后前往 Metrics 或 Explorer 视图确保函数确实在被调用几分钟后数据就会显示出来。注意账户集成完成后Metrics、Traces 等数据通常需要最多 10 分钟才能在 Dashboard 中可见。接入方式二通过 CLI 与serverless.yml按 Stage 精确控制如果你的 Service 已经连接 Dashboard可以直接在serverless.yml中控制每个 stage 的可观测性开关。CLI 方式会自动把 Serverless Framework 平台连接到 AWS 账户并针对所选 stages 内的所有 Lambda 函数启用监控。首先确认 Service 已连接 Dashboard——判断依据是serverless.yml中存在org和app属性若尚未连接先在该 Service 的工作目录中运行一次serverless命令完成连接。连接后在stages属性下控制各 stage 的 observability 配置# Ensure these properties are present to connect to the Dashboard org: my-org app: my-app # Control observability instrumentation settings under stages stages: dev: observability: true # Turn on observability in the dev stage prod: observability: true # Turn on observability in the prod stage default: observability: false # Turn off observability in all other stages此后每次部署observability 都会按目标 stage 的取值自动开启或关闭。上面这个例子中dev 和 prod 开启其余 stage 关闭。部署完成后到 Dashboard 的 Settings Integrations 中确认应能看到刚接入的 AWS 账户强烈建议命名以便在查询过滤器中查找点击该 Integration 的 Edit 按钮可以看到账户内所有 Lambda 函数以及各自处于启用/禁用状态。同样地数据出现前可能需要等待最多 10 分钟。源码视角observability配置是如何被解析的上面的 stage 优先、default 兜底 行为并非约定俗成而是由源码显式实现的。在 observability 插件入口 中determineObservabilityProviderFromConfig函数先读取stages[stageName].observability若为空再回退到stages.default.observability这与文档描述完全一致。进一步看determineStageSpecificObservabilityProvider的实现可以确认几种取值的处理规则从源码结构看实际支持的范围比本文档示例更多布尔值true映射为dashboardproviderfalse映射为disabled若设置为布尔值但未配置app属性会抛出OBSERVABILITY_APP_NOT_SET错误To instrument your service, you must set the app property in your config file.字符串支持axiom、dashboard、disabled三种已知 provider未知名称会抛出UNKNOWN_OBSERVABILITY_PROVIDER对象支持{ provider: name }形式例如接入 Axiom 后端 的 observability 配置。而在 Dashboard provider 判定模块 中isDashboardObservabilityEnabled正是通过 provider 解析结果等于DASHBOARD 来判断当前 stage 是否启用 Dashboard 监控它被部署等流程如 deploy 插件调用来决定本次部署是否为函数打上埋点。这解释了为什么文档强调 部署时 observability 才会按 stage 生效它是部署链路中的一道判定而不是运行时的动态开关。集成底层原理How Integration Works理解集成原理对排查问题和评估成本都很有帮助。官方文档说明整个机制由一个在集成时创建的 AWS IAM Role 驱动且你可以随时删除该 IAM Role但更推荐在 Dashboard 的 Integration 上点 Remove因为那会自动解除所有函数的埋点、删除平台创建的资源。数据链路Kinesis Firehose CloudWatch Logs 订阅集成完成后平台会先在你的 AWS 账户内创建一个 Kinesis Firehose并为每个 Lambda 函数建立 CloudWatch Logs 订阅把日志发布到该 FirehoseServerless Framework 平台从 Firehose 摄取日志数据。每次函数调用期间SDK 会在 CloudWatch Logs 中记录一个压缩的 Trace 负载日志行以SERVERLESS_TELEMETRY开头便于人工核查。一个明确的边界平台摄取日志但不存储日志只是扫描其中特定信息与 SDK 生成的 Trace 负载日志存储目前不是 Dashboard 提供的能力。埋点机制Lambda Layer 环境变量Internal Extension对开启 Instrument 的每个函数平台会自动追加一个 AWS Lambda Layer 和若干环境变量关闭开关时这些又会被自动移除。这个 Layer 被设计为Internal Extension——通过包装器脚本与环境变量AWS_LAMBDA_EXEC_WRAPPER把你的代码包装进 SDK。需要注意文档中的强提示如果有其他工具也在用该变量包装你的函数代码Serverless Framework会覆盖它那个工具将不再工作官方强调其 Layer 是 Internal Extension 而非 External Extension。文档称经过大量研究与基准测试通过 External Extension 增加可观测性工具几乎总是带来可感知的性能与成本惩罚冷启动、调用时长、后处理时长。文档对该 Layer 的优化效果不增加冷启动/调用/后处理时延属于官方描述可结合 troubleshoot 文档 中给出的 Layer 命名如sls-sdk-node-v0-15-12、sls-sdk-python-v0-2-3与包装器路径Node.js 为/opt/sls-sdk-node/exec-wrapper.shPython 为/opt/sls-sdk-python/exec_wrapper.py在 AWS 控制台逐一核对。CloudTrail 事件监听集成还会监听 CloudTrail 事件在每次函数更新后自动检查 Layer 与环境变量是否仍然挂载仅针对开启 Instrument 的函数。这意味着你可以继续用任意部署工具同时平台保证 一旦标记 Instrument就一定完成埋点从而降低部署/配置失误的影响。Trace 采样机制How Trace Sampling WorksTrace 采样按单个函数而非账户级自动生效设计目标是对高流量函数按默认 20% 的速率采样对低流量函数则完全关闭采样。具体触发规则是当同一容器内相邻两次调用的平均间隔连续 5 次调用低于 1 秒/次时采样开启反之以下场景采样会被禁用冷启动后的前 5 次调用不采样平均调用频率低于 1.0 次/秒且流量平稳非尖峰型时平均频率远低于 1.0 次/秒、但出现 5 秒内最多 5 次调用的尖峰时调用产生了 error 或 warning 事件时从不采样保证问题调用一定有 Trace通过环境变量SLS_DISABLE_TRACE_SAMPLING显式关闭。官方给出的经验值月调用量低于约 250 万次的大多数情况下采样会自动关闭但实际取决于调用分布、冷启动率与错误/警告率。采样何时生效的量化口径1-2 百万次/月或突发流量触发可参见 troubleshoot 文档。通过 SDK 做高级埋点在开箱即用的自动埋点之外官方提供 Node.js 与 Python 两个 Serverless SDK用于更丰富的场景优雅捕获 handled error不让函数失败也能上报、自定义 Trace Span、捕获 Error/Warning 事件、给 Trace 打自定义 Tag 提升可检索性、与结构化日志库集成。完整用法见Node.js SDK 文档Python SDK 文档SDK 总览还说明了自动注入机制开启 Instrumentation 后框架会自动把 SDK 模块注入 lambda 包并包装 handler由于 Layer 在手工部署时可能被移除官方建议把 SDK 直接打进函数包npm install serverless/sdk --save。若使用 esbuild 等 bundler 打包了 express / AWS SDKLayer 无法自动 instrument 被打包的依赖需改用serverless/aws-lambda-sdk手动调用instrumentation.awsSdkV2/V3Client/expressApp.install(...)完成接入。此外SDK 配置文档 提供了三个 HTTP Span 抓取的细粒度环境变量SERVERLESS_ENTERPRISE_SPANS_CAPTURE_HOSTS—— 默认*设为逗号分隔的主机名列表可只抓取指定主机SERVERLESS_ENTERPRISE_SPANS_IGNORE_HOSTS—— 默认未设置设为逗号分隔列表排除指定主机SERVERLESS_ENTERPRISE_SPANS_CAPTURE_AWS_SDK_HTTP—— 默认未设置设任意值可额外抓取来自botocore/aws-sdk的 HTTP Span。关闭与降级账户级、Service 级、采样级、Span 级关闭整个 AWS 账户进入 Settings Integrations对目标账户点击 Remove。断开后平台会自动移除所有函数的埋点Layer 与环境变量、删除集成时创建的资源、销毁包含 IAM Role 的 CloudFormation Stack。注意若移除后立刻重建 Integration由于 AWS 资源删除再创建的时序问题新集成可能需要最多 20 分钟才完全生效。关闭某个 Service在stages属性下将目标 stage 置为false。该操作会阻止函数被埋点如果函数已埋点还会解除已有埋点org: my-org app: my-app stages: prod: observability: false注意如果已经建立了针对一个或多个 AWS 账户的 Observability Integration仍需到 Serverless Framework Dashboard 中把这些 Integration 手动删除。关闭 Trace 采样采样默认自动进行、按函数独立计量在函数月调用量达到约 1-2 百万次或出现突发流量时触发。若要关闭在serverless.yml中设置环境变量SLS_DISABLE_TRACE_SAMPLINGprovider: environment: SLS_DISABLE_TRACE_SAMPLING也可以在该属性上对单个函数设置environment实现函数级粒度。关闭 AWS SDK Span 采集SDK 默认会 instrument AWS SDK 调用从而在 Trace 中可视化函数对 DynamoDB、S3 等服务的访问及各自耗时。若不需要这类 Span设置provider: environment: SLS_DISABLE_AWS_SDK_MONITORING: true关闭 HTTP Span 采集同理函数发起的 HTTP(s) 外部请求会被采集为 Span含会话时长。如需关闭provider: environment: SLS_DISABLE_HTTP_MONITORING: true以上三个环境变量都可以在provider.environment全局设置也可以下沉到单个函数的environment属性做细粒度控制。常见问题速查来自官方排障 Runbook当 Metrics/Traces 缺失或部分函数没有数据时troubleshoot 文档 提供了一份有序排障清单核心检查项包括先产生调用集成完成且函数标记为 Instrumented 之后才产生的调用才会有数据集成前的调用不会回填。等 10 分钟移除后立即重建的集成需等最长 20 分钟。确认函数 Instrument 开关已打开在 Settings Integrations Edit 中核对。确认 CloudFormation Stack 存在且位于 us-east-1Stack 名形如Serverless-Inc-Role-Stack。核对两类常见埋点错误Rate Limit Exceeded该函数已挂满 2 个 CloudWatch Logs 订阅上限需先移除一个订阅再在 Dashboard 中关闭并重新打开 Instrument 开关记得点 SaveCode uncompressed size is greater than the max allowed size函数代码 Layer 未压缩体积超限SDK 体积约 600KB通常需精简自身依赖。手动核查埋点三要素Layer 是否挂载sls-sdk-node-*/sls-sdk-python-*、AWS_LAMBDA_EXEC_WRAPPER是否指向正确路径、SLS_ORG_ID等必需环境变量是否齐全——文档特别提到 Sentry 等工具会争抢AWS_LAMBDA_EXEC_WRAPPER导致冲突。开启 SDK 调试设置SLS_SDK_DEBUGtrue后调用函数CloudWatch 日志中若出现SDK: Wrapper initialization说明 SDK 初始化成功问题更可能出在外部工具覆盖或平台摄取侧。人工确认遥测负载正确埋点的函数会在 CloudWatch Logs 输出以SERVERLESS_TELEMETRY开头的压缩负载若没有该行日志说明埋点链路未走通。小结Serverless Framework 的 Monitoring Observability 通过 IAM Role 集成 Kinesis Firehose 日志管道 Lambda Layer 包装器 三件套把跨账户的 Metrics/Traces/Logs/Errors 聚合到 Dashboard且明确不存储原始日志、可按 stage 与环境变量精细控制开启范围与采样行为。配置面记住三处即可stages.stage.observability部署时按 stage 决定埋点、SLS_DISABLE_TRACE_SAMPLING关闭采样、SLS_DISABLE_AWS_SDK_MONITORING/SLS_DISABLE_HTTP_MONITORING关闭对应 Span 采集排障时优先核对 Instrument 开关、Serverless-Inc-Role-Stackus-east-1、AWS_LAMBDA_EXEC_WRAPPER与SERVERLESS_TELEMETRY日志这四项。更多细节可继续阅读 Metrics 视图、Trace Explorer 与 排障 Runbook 三篇文档。【免费下载链接】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），仅供参考