Serverless Framework 接入 Axiom 可观测性配置指南与实现原理【免费下载链接】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本篇技术指南以 docs/sf/guides/observability/axiom.md 为主体讲解如何在 Serverless Framework 服务中通过stages.observability配置接入 Axiom 日志平台将 AWS Lambda 函数日志与自定义日志组自动采集到 Axiom。读者读完本文可以独立完成账号准备、API Token 授权、serverless.yml配置、自定义数据集以及故障排查并能结合仓库源码理解其底层的 Layer 注入与 CloudWatch 日志订阅机制。Axiom 是什么为什么接入它Axiom 是一个面向大规模事件数据的可观测性平台核心优势在于对日志、指标与追踪数据的高效摄取、存储与查询。对于运行在 AWS Lambda 上的 Serverless 应用而言Axiom 通常被用作 AWS CloudWatch Logs 的低成本替代方案它提供每月 500GB 的免费额度用一条配置即可为服务内所有函数开通统一的可观测入口适用于成本敏感、日志量大、需要跨服务集中检索的场景。在 Serverless Framework 中Axiom 属于可观测性提供方Observability Provider之一。仓库源码中定义了三种提供方取值export const ObservabilityProvider { DISABLED: disabled, AXIOM: axiom, DASHBOARD: dashboard, }实现见 packages/sf-core/src/lib/observability/index.js。disabled用于显式关闭可观测性axiom即本文介绍的 Axiom 集成dashboard对应框架自带的 Serverless Dashboard。第一步创建 Axiom 账号并生成 API Token如果还没有 Axiom 账号可先完成注册Axiom 提供非常慷慨的免费额度。注册或加入一个组织之后有一个关键注意事项请跳过 Axiom 引导流程中 Creating a Dataset创建数据集的第一步。数据集无需在 Axiom 控制台手动创建Serverless Framework 会在首次部署时自动创建并命名数据集命名规则见后文自定义 Axiom 数据集一节源码见 dataset.js 中的findOrCreateAutogeneratedDataset。正确的操作路径是打开 Axiom Dashboard点击设置settings图标在左侧选择API Tokens点击New API Token新建令牌输入令牌名称Expiration过期时间选择None切换到Advanced 标签页勾选令牌所需权限。令牌必须包含以下五种权限缺一不可权限用途Ingest向数据集写入日志数据Query查询、检索数据集Datasets创建/查找数据集框架会自动建数据集Dashboards读取/管理看板Monitors读取/管理告警监控随后把生成的 API Token 写入环境变量AXIOM_TOKENexport AXIOM_TOKENyour-axiom-access-tokenAXIOM_TOKEN也可以写入.env文件或各阶段stage对应的.env文件中Serverless Framework 会自动读取无需手动 export。第二步在 serverless.yml 中启用 Axiom在配置文件的stages块中添加observability属性并指向axiom即可对全部阶段Stages启用stages: default: observability: axiom配置完成后直接执行serverless deploy部署服务Lambda 产生的日志就会出现在 Axiom 平台。从源码看该配置的解析逻辑位于 packages/serverless/lib/plugins/observability/index.js 的determineObservabilityProviderFromConfig它先取当前 stage 专属的observability配置未命中时回退到stages.default.observability。因此将配置放在default下即可被所有未单独覆盖的阶段继承。observability支持多种写法便于不同场景使用字符串简写observability: axiom布尔值observability: true映射到 Dashboard 提供方要求配置app属性false则映射为disabled对象写法observability: { provider: axiom, dataset: my-custom-dataset }用于附带数据集等参数见下文。如果传入未知提供方名称解析器会抛出Unknown observability provider错误格式非法时会抛出Invalid observability configuration错误。集成后采集哪些日志启用 Axiom 后自动接入的日志包括两类本服务内 Lambda 函数的日志除非某个函数显式设置了disableLogs: true否则其 CloudWatch 日志都会被采集resources块中定义、且不与任何 Lambda 函数关联的日志组它们会被自动插桩auto-instrumented接入 Axiom目前没有开关可以单独关闭这一行为。实现原理Layer 注入 环境变量 日志订阅Axiom 插件通过多个生命周期 Hook 挂接到部署流程中见 packages/serverless/lib/plugins/observability/axiom/index.jsHook触发时机动作after:package:compileFunctions打包编译后addEnvVarsAndLayer为每个函数注入 Axiom Layer 与环境变量after:deploy:deploy部署完成后subscribeLogGroups初始化数据集并订阅日志组before:deploy:function:deploy单函数部署前addEnvVarsAndLayerToFunction仅对目标函数注入 Layer 与环境变量after:deploy:deploy未启用 Axiom 时部署完成后unsubscribeLogGroups清理订阅对每个 Lambda 函数插件会做三件事从 GitHub 拉取 Axiom Lambda ExtensionLayer的最新版本号生成对应架构x86_64 / arm64的 Layer ARN见 layer.js向函数的编译后 CloudFormation 模板注入AXIOM_TOKEN、AXIOM_DATASET两个环境变量与 Axiom Layer见 lambda.js 的getLambdaConfig用nonLambdaLogGroups计算出不属于 Lambda 函数的日志组列表通过订阅栈subscriber将其订阅到转发 Lambdaforwarder最终把 CloudWatch 日志投递到 Axiom 数据集。环境变量的注入对应代码路径如下lambdaResource.Properties.Environment.Variables[AXIOM_TOKEN] lambdaConfig.environment.AXIOM_TOKEN lambdaResource.Properties.Environment.Variables[AXIOM_DATASET] lambdaConfig.environment.AXIOM_DATASET部署时框架会创建三套 AWS CloudFormation 栈完成转发链路{datasetName}-forwarder-axiom日志转发器、{datasetName}-subscriber-axiom日志组订阅与{datasetName}-unsubscriber-axiom订阅清理。转发器栈的创建实现在 forwarder.js 中当前使用版本为AXIOM_CLOUDFORMATION_STACKS_VERSION 1.1.1以AxiomDataset、AxiomToken、DataTags作为栈参数。需要注意的边界条件若某个函数已挂载 5 个 LayerLambda 的层数上限继续注入会抛出MAX_LAYERS_EXCEEDED错误若某函数已接入 Serverless Dashboard则无法再接入 Axiom插件会在validateAndGetToken中校验并报错错误码AXIOM_ALREADY_INTEGRATED_WITH_DASHBOARD单函数部署serverless deploy function -f name同样会为对应函数注入 Layer 与环境变量保证独立部署也能采集日志。自定义 Axiom 数据集名称默认命名规则默认情况下框架会自动创建 Axiom 数据集数据集名称与阶段名有关prod或production阶段数据集名为{stage}-aws-cloudwatch例如prod-aws-cloudwatch其他阶段数据集名为default-aws-cloudwatch。该规则与源码中的阶段前缀逻辑完全一致见 packages/serverless/lib/plugins/observability/axiom/index.js 的getPrefix仅当阶段名小写后是prod或production时使用真实阶段名作为前缀否则一律使用default随后由 dataset.js 中的getGeneratedDatasetName拼接出${prefix}-aws-cloudwatch。指定自定义数据集若希望使用自定义名称可在observability块中通过对象写法添加dataset属性stages: default: observability: provider: axiom dataset: my-custom-dataset插件在 packages/serverless/lib/plugins/observability/axiom/index.js 的getDatasetName中会优先读取当前 stage 下observability.dataset其次回退到stages.default.observability.dataset。dataset的解析不依赖默认命名规则因此自定义名称会原样传给 Axiom 的datasets.create数据集同样在首次部署时自动创建可放心使用自定义名称框架会做查找-不存在则创建的处理。故障排查部署时报 Forbidden 错误部署时若出现 forbidden 错误绝大多数原因是 Axiom API Token 缺少前文列出的权限。请回到 Axiom Dashboard 的 API Tokens 页面逐一核对令牌是否包含Ingest、Query、Datasets、Dashboards、Monitors五种权限。从源码看初始化数据集时对 forbidden 有专门的处理分支findOrCreateAutogeneratedDataset失败且错误信息包含forbidden时会抛出带有提示的ServerlessError错误码AXIOM_INITIALIZE_DATASET_FAILED错误文案会提示检查 Axiom API Token 权限见 packages/sf-core/src/lib/observability/axiom/index.js。GitHub API 限流API rate limit exceededServerless Framework 在部署时会调用 GitHub API 获取 Axiom AWS Lambda Layer 的最新版本号见 layer.js 的fetchLatestLayerVersion它查询axiomhq/axiom-lambda-extension仓库的最新 Release并解析形如v数字的 tag 作为 Layer 版本。GitHub 对未认证请求的限流是每小时 60 次当多个服务连续部署、或与 CI 中的其他 GitHub API 调用叠加时容易触发API rate limit exceeded for IP_ADDRESS.解决办法是配置 GitHub 个人访问令牌Personal Access Token将令牌写入环境变量export GITHUB_TOKENyour-github-personal-access-token认证后的限流上限为每小时 5000 次可有效避免该问题。需要说明的是GitHub 令牌只在拉取 Layer 版本时使用与AXIOM_TOKEN用途不同令牌无效时插件会抛出AXIOM_GITHUB_TOKEN_INVALID错误。关闭 Axiom 可观测性如需停用只需从serverless.yml的stages块中删除observability属性即可。需要注意以下行为差异所有 Lambda 函数日志将在下一次部署后停止发送到 Axiom非 Lambda 函数日志组的订阅不会自动消失需要按下面的方式显式清理保留AXIOM_TOKEN环境变量并重新部署框架会通过 unsubscriber 移除 Axiom 日志订阅此后不再有日志发送到 Axiom对应 Hookafter:deploy:deploy→unsubscribeLogGroups如果先取消AXIOM_TOKEN环境变量再部署订阅会保留日志将继续发送到 Axiom。这一设计在源码中有明确体现unsubscribeLogGroups会先尝试读取AXIOM_TOKEN若令牌缺失错误码AXIOM_TOKEN_NOT_FOUND则直接返回、不执行清理见 packages/sf-core/src/lib/observability/axiom/index.js。另外以下资源不会被自动删除因为它们可能仍被其他服务使用如需释放需在 Axiom 与 AWS 控制台手动处理Axiom 中的数据集Dataset每个数据集对应创建的三套 CloudFormation 栈即 Axiom CloudWatch 转发相关栈{datasetName}-forwarder-axiom、{datasetName}-subscriber-axiom、{datasetName}-unsubscriber-axiom。源码级延伸阅读如果想深入了解 Axiom 集成的完整实现可在当前仓库中按以下路径追踪插件入口与生命周期 Hookpackages/serverless/lib/plugins/observability/axiom/index.js负责配置判断、Hook 注册、环境变量与 Layer 注入、日志订阅编排可观测性配置解析packages/serverless/lib/plugins/observability/index.jsobservability各种写法与提供方枚举的判定核心编排逻辑packages/sf-core/src/lib/observability/axiom/index.jsvalidateAndGetToken、initialize、subscribeLogGroups、unsubscribeLogGroups含全部 Axiom 相关错误码数据集自动创建dataset.js查找或创建数据集、{prefix}-aws-cloudwatch命名Lambda Layer 版本获取layer.jsGitHub 最新 Release 拉取与 Layer ARN 拼装函数注入与日志组归类lambda.jsAXIOM_TOKEN/AXIOM_DATASET环境变量、非函数日志组过滤转发器 CloudFormation 栈forwarder.js{datasetName}-forwarder-axiom栈的创建与查询。结合这些源码可以清楚看到一条完整链路serverless.yml配置 → stage/默认配置解析 → 打包阶段为每个函数注入 Axiom Layer 与环境变量 → 部署后自动创建数据集 → 通过 CloudFormation 栈订阅非函数日志组到转发器 → CloudWatch 日志持续流入 Axiom。掌握这条链路后无论是多阶段共用配置、自定义数据集还是排查限流与权限问题都能快速定位到对应环节。【免费下载链接】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），仅供参考