OneUptime Serverless 函数监控指南：基于 OpenTelemetry 与 `faas.name` 的零配置 FaaS 可观测性接入

OneUptime Serverless 函数监控指南：基于 OpenTelemetry 与faas.name的零配置 FaaS 可观测性接入

【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime

OneUptime 会自动识别接入的Serverless 函数（FaaS）：只要函数通过 OpenTelemetry SDK 上报带有faas.name资源属性的 traces、logs 与 metrics，它就会自动出现在Serverless Functions页面，无需任何手动创建。本文以 OneUptime 官方文档为骨架，结合仓库中的摄取服务、数据模型与前端页面源码，完整讲解其识别原理、OTLP 导出器配置、AWS Lambda 接入步骤，以及落地后你能获得的监控能力。

概述：为什么无需手动注册函数

OneUptime 的 Serverless 监控走的是"零配置自动发现"路线。核心触发条件只有一个：当 OneUptime 收到带有faas.name资源属性的 OpenTelemetry 数据时，就自动识别出一个 Serverless 函数。

这意味着你的接入流程只有三步：

1. 用函数语言的 OpenTelemetry SDK（或自动埋点层）对函数进行插桩；
2. 将函数的 OTLP 导出器指向 OneUptime；
3. 函数首次上报 span、log 或 metric 后，自动出现在Serverless Functions（Serverløse funktioner）页面下，并关联其 traces、logs 和 metrics。

该机制对任何能够输出 OpenTelemetry 的 FaaS 运行时均有效，包括但不限于：

• AWS Lambda
• Google Cloud Functions
• Azure Functions
• Cloudflare Workers
• 其他任何支持 OpenTelemetry 导出的 FaaS 运行时

前置条件

在开始之前，你需要准备两样东西：

1. OneUptime Telemetry Ingestion Token（遥测摄取令牌）：在 _Project Settings → Telemetry & APM → Ingestion Keys（项目设置 → 遥测与 APM → 摄取密钥）中创建，并复制其中的x-oneuptime-token值。它是 OTLP 请求的鉴权头。
2. 函数语言对应的 OpenTelemetry SDK（或自动插桩层），用于在函数内生成和导出遥测数据。

OneUptime 如何识别一个函数：faas.name资源属性

OneUptime 以 OpenTelemetry 的faas.name资源属性作为每个函数的身份键（identity key）。下表完整列出了识别过程中涉及的资源属性及其用途：

注意：如果一个函数同时设置了service.name，它仍然会出现在 Services（服务）下。Serverless Functions视图是以 FaaS 为聚焦视角的呈现方式，其范围限定于faas.name。

从源码层面看，这一识别逻辑在摄取管线中有明确的落点。在 OtelIngestBaseService.ts 的selectPrimaryEntity中，当批次被判定为 Serverless 函数时，服务名解析优先取faas.name，缺省时回退到service.name，并组装为serverless/<name>的服务名，最终以ServiceType.ServerlessFunction作为主实体类型写入遥测行：

if (data.serverlessFunctionId) { const faasName: string | null = this.getStringAttribute(data.attributes, "faas.name") || this.getStringAttribute(data.attributes, "service.name"); return await OTelIngestService.buildResourceMetadataForNonService({ serviceName: faasName ? `serverless/${faasName}` : "Serverless Function", resourceId: data.serverlessFunctionId, primaryEntityType: ServiceType.ServerlessFunction, ... }); }

在数据模型侧，ServerlessFunction.ts 用functionIdentifier字段承载来自faas.name的稳定标识，并对(projectId, functionIdentifier)建立了数据库级唯一索引，确保同一 FaaS 函数并发首次上报时收敛为单一行，而不是竞争创建出重复记录。模型还持久化了cloudPlatform、cloudProvider、cloudRegion、cloudAccountId、functionVersion（来自faas.version）、runtimeName、runtimeVersion（来自process.runtime.*）等"最后一次见到"的资源属性，以及lastSeenAt（最后收到遥测的时间）和otelCollectorStatus（连接/断开状态）。

而 ServerlessFunctionService.ts 中的findOrCreateByFunctionIdentifier则采用大小写不敏感查找（QueryHelper.findWithSameText）来避免因faas.name大小写漂移导致的重复创建，并在创建失败（并发竞争）时重新查询已存在的行，保证摄取流程不被重复行卡住。

步骤 1：设置 OTLP 导出器的环境变量

大多数语言自动插桩库都遵循 OpenTelemetry 标准的三个环境变量约定，你只需要在函数运行环境中设置它们：

OTEL_EXPORTER_OTLP_ENDPOINT="https://oneuptime.com/otlp" OTEL_EXPORTER_OTLP_HEADERS="x-oneuptime-token=YOUR_TELEMETRY_INGESTION_TOKEN" OTEL_RESOURCE_ATTRIBUTES="faas.name=checkout-handler,faas.version=1.4.2"

参数说明：

• OTEL_EXPORTER_OTLP_ENDPOINT：OTLP 上报地址。使用 OneUptime 云服务时指向https://oneuptime.com/otlp；如果你自托管 OneUptime，请将其替换为https://YOUR-ONEUPTIME-HOST/otlp（即你自托管实例的/otlp路径）。
• OTEL_EXPORTER_OTLP_HEADERS：携带鉴权头x-oneuptime-token，值为前置条件中复制的 Telemetry Ingestion Token。
• OTEL_RESOURCE_ATTRIBUTES：以逗号分隔的资源属性列表。这里至少应设置faas.name（如checkout-handler），并可按需附加faas.version（如1.4.2）。需要注意：在 AWS Lambda 场景下，faas.name通常会由 Lambda Layer 自动写入，因此这里的属性不是强制必须的。

步骤 2：（AWS Lambda）附加 OpenTelemetry Layer

对于 AWS Lambda，最简单的接入方式是在函数上附加OpenTelemetry Lambda Layer（针对你的运行时选择对应版本的 Layer），然后设置以下环境变量：

AWS_LAMBDA_EXEC_WRAPPER=/opt/otel-handler OTEL_EXPORTER_OTLP_ENDPOINT=https://oneuptime.com/otlp OTEL_EXPORTER_OTLP_HEADERS=x-oneuptime-token=YOUR_TELEMETRY_INGESTION_TOKEN

其中：

• AWS_LAMBDA_EXEC_WRAPPER=/opt/otel-handler：让 Lambda 运行时通过该 wrapper 启动，从而自动注入 OpenTelemetry 的埋点与 span 上下文传播。
• 后两个环境变量与步骤 1 中的含义一致，指向 OneUptime 的 OTLP 端点并携带摄取令牌。

该 Layer 会自动完成两件关键工作：

1. 自动设置faas.name：从 Lambda 函数名派生，无需手工配置；
2. 自动填充云资源属性：资源检测器（resource detector）会自动补齐cloud.platform、cloud.region和cloud.account.id，让概览页直接展示运行平台、区域和账户信息。

其他 FaaS 平台（Google Cloud Functions、Azure Functions、Cloudflare Workers 等）虽然没有统一的 Lambda Layer 机制，但原理一致：只要其 OpenTelemetry 导出器能携带faas.name资源属性并指向 OneUptime 的 OTLP 端点即可被识别。仓库中 CloudPlatform.ts 定义了FAAS_CLOUD_PLATFORM_VALUES枚举，明确支持aws_lambda、gcp_cloud_functions、azure_functions等平台取值，用于归一化与校验cloud.platform。

接入后你能获得什么

一旦函数发出 span、log 或 metric，它就会出现在Serverless Functions列表页。函数概览（Overview）页面提供以下核心能力：

• Invocations（调用次数）、error rate（错误率）和 p95 duration（p95 延迟）：这些指标从你的 traces 中推导得出，支持选择时间范围查看，并配有趋势图（trend charts）。在前端实现中，Overview.tsx 将Invocations与p95 duration渲染为带序列数据的图表卡片，调用次数与 p95 分别通过countSeries与p95Series驱动趋势曲线。
• Instances（实例）：实时统计观测到的faas.instance取值数量。底层由 ServerlessFunctionInstance.ts 承载——这是一张"存活实例清单"表，由遥测摄取管线根据faas.instance自动 upsert（仅收集器显式输出faas.instance资源属性时才填充），对(projectId, serverlessFunctionId, instanceName)建立唯一索引，且不可由用户手工编辑。
• 完整的 Logs（日志）、Traces（链路）和 Metrics（指标）标签页：均以该函数为范围进行过滤，对应仓库中的 Logs.tsx、Traces.tsx、Metrics.tsx 等页面。

标签与负责人的自动应用

除了观测数据，你还可以通过Serverless → Settings → Label Rules / Owner Rules（Serverless → 设置 → 标签规则 / 负责人规则）为函数自动应用标签（labels）和负责人（owners），实现大规模函数资产的自动化归类与责任到人。这一能力在仓库中对应独立的规则引擎服务：

• ServerlessFunctionLabelRuleEngineService.ts：根据规则为 Serverless 函数自动匹配并应用标签；
• ServerlessFunctionOwnerRuleEngineService.ts：按规则自动为函数指派负责人；
• 配套的规则数据模型包括 ServerlessFunctionLabelRule.ts、ServerlessFunctionOwnerRule.ts 等。

结合 ServerlessFunction.ts 中的labels多对多关系字段，标签会直接挂载到函数对象上，从而在列表、过滤与权限控制中生效。

总结

OneUptime 的 Serverless 函数监控是典型的"协议优先、配置为零"设计：以 OpenTelemetry 的faas.name资源属性为唯一身份锚点，通过ServerlessFunction模型的唯一索引与摄取服务的大小写不敏感查找保证自动发现的健壮性，再以faas.version、faas.instance、cloud.*系列属性丰富概览信息，最终在 Dashboard 端呈现调用量、错误率、p95 延迟、实例清单与完整的 logs/traces/metrics 视图。无论你的函数跑在 AWS Lambda、Google Cloud Functions、Azure Functions 还是 Cloudflare Workers 上，接入路径都同样简单：插桩 → 配置 OTLP 端点与令牌 → 等待数据流入。

【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime