OneUptime Cloud Environments 完全指南用 OpenTelemetry 自动发现并监控托管云计算环境【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime导读本文基于 OneUptime 官方文档德语版另有内容更完整的 英语版讲解Cloud Environments云环境功能OneUptime 如何把 AWS ECS / Fargate、Google Cloud Run、Azure Container Apps 等托管云计算资源自动聚合为单一环境实体并展示其实例级 CPU、内存、请求、日志与链路追踪。读完本文你将掌握环境识别规则、环境键Resource Identifier的构成、支持的平台清单、Collector / SDK 两种接入形态以及环境、实例、服务三者之间的关系。什么是 Cloud EnvironmentsOneUptime 将托管云计算资源聚合为Cloud Environments云环境。一个环境既不是服务Service也不是机器Host而是你的容器真正运行的地方——例如某个 ECS 集群所在的账户与区域、某个 Cloud Run 项目与区域、某个 Container Apps 环境——它负责把运行在其中的所有工作负载聚合到一处。环境的关键特征同一工作负载的按服务拆解视图仍然保留在Services服务下环境是汇总层roll-up服务的拆分是明细层环境之下通过Instances实例标签页展示正在运行的任务、实例与副本replicas并在平台支持的前提下提供实时 CPU 与内存云环境视图是专门为托管 / PaaS 计算资源设计的。需要特别强调的是纯虚拟机EC2、Compute Engine、Azure VM仍然是 Hosts主机Kubernetes 集群仍然归入Kubernetes。云环境只针对托管 / PaaS 计算。前置条件接入前需要准备两样东西OneUptime Telemetry Ingestion Token遥测摄取令牌——在项目设置 → Telemetry APM → 摄取密钥Ingestion Keys中创建。德语文档建议创建后复制x-oneuptime-token的值该值是机密请存放在对应云平台自己的密钥存储中。一个 OpenTelemetry Collector 或 SDK——运行在工作负载内部或旁边向 OneUptime 导出 OTLP 数据。OneUptime 如何识别一个环境环境键cloud.platform | cloud.account.id | cloud.region每一个唯一组合的cloud.platformcloud.account.idcloud.region即构成一个环境。例如AWS ECS · us-east-1 · 123456789012是一个单一实体聚合运行其上的每个工作负载。属性是否必需作用cloud.platform是必须是受管计算平台例如aws_ecs、gcp_cloud_run、azure_container_appscloud.account.id否环境键的一部分AWS 账户 ID、GCP 项目 ID 或 Azure 订阅 IDcloud.region否环境键的一部分us-east-1、us-central1、eastus…service.instance.id否用于Instances实例标签页中每个任务 / 实例附带实时 CPU / 内存三个值用|拼接成环境键即该环境的Resource Identifier资源标识符aws_ecs|123456789012|us-east-1 gcp_cloud_run|my-project|us-central1 azure_container_apps|00000000-0000-0000-0000-000000000000|eastus德语文档明确提醒缺失的部分不会丢弃而是保留为空段——例如aws_ecs||us-east-1。因此一个省略了cloud.account.id的工作负载会落在与设置了该属性的工作负载不同的环境里。这是你明明预期只有一个环境、却看到两个环境的常见原因。显示名称由同样的值生成AWS ECS · us-east-1 · 123456789012。这些属性通常由 OpenTelemetry 的Resource Detectors资源探测器自动填充。摄取ingest端会自动铸造环境键与显示名无需手工注册如果你手工创建环境摄取只按环境键匹配因此手工环境的 Resource Identifier 必须严格等于platform|account|region。源码层面的佐证环境键只在一处构造从源码看环境键与显示名由 Common/Types/Cloud/CloudPlatform.ts 统一构造buildCloudEnvironmentKey与buildCloudEnvironmentName见 L320-L372。该文件注释明确它是以下四处的单一事实来源single source of truth遥测摄取入口OtelIngestBaseService.autoDiscoverCloudResource的环境发现门槛摄取铸造的环境键 / 显示名仪表盘 Cloud Resources 的创建表单文档页面及将文档与产品锁定的测试。buildCloudEnvironmentKey的实现正是把三部分trim()后用|连接缺失段保留空串buildCloudEnvironmentName则用·拼接平台标签 区域 账户 ID。平台标签存放在MANAGED_CLOUD_PLATFORMS描述符中代码注释提醒更改标签会重命名之后发现的每一个环境请保持其稳定。摄取入口的实现位于 App/FeatureSet/Telemetry/Services/OtelIngestBaseService.tsautoDiscoverCloudResource它先对cloud.platform做normalizeCloudPlatform规范化若不在受管平台集合内则直接返回null即不归入云环境随后用cloud.provider或由平台推断出 provider读取 region 与 account id构造环境键后调用CloudResourceService.findOrCreateByResourceIdentifier按键查重/创建并通过缓存 数据库唯一索引(projectId, resourceIdentifier)保证并发批次不会产生重复行。实例身份谁是一条实例记录在一个环境内每个运行中的任务 / 实例 / 副本对应一行实例记录取自以下第一个出现的资源属性aws.ecs.task.idaws.ecs.task.arn缩写为 task idfaas.instanceazure.container_app.instance.idservice.instance.idcontainer.idhost.idhost.name平台自身的任务 / 实例身份有意排在前面sidecar Collector 与应用 SDK 都能看到它且它能在进程重启后存续而 SDK 铸造的service.instance.id通常是每个进程一个随机 IDNode SDK 默认的serviceinstance探测器正是如此若以它为准awsecscontainermetricsreceiver 按 task id 上报时同一个 ECS 任务会被拆成两行。只有当平台没有自身身份时才使用service.instance.id。该回退链在源码中的常量定义见 Common/Utils/Telemetry/CloudInstanceIdentity.tsCLOUD_INSTANCE_IDENTITY_ATTRIBUTES解析函数resolveCloudInstanceName会按序取第一个非空属性并在命中aws.ecs.task.arn时通过shortenEcsTaskArn把完整 ARN 缩写为任务 IDarn:aws:ecs:us-east-1:123456789012:task/my-cluster/1a2b3c4d5e6f→1a2b3c4d5e6f。文件注释还指出在这条链出现之前只有service.instance.id被读取导致 ECS 环境的 Instances 标签页为空、CPU / 内存瓦片永不填充——因为 ECS 探测器从不设置该属性。摄取路径按原样键与指标快照折叠路径resource.前缀键共用同一常量保证两边对什么是实例的判定永远不会不一致。实例行由CloudResourceInstanceService.recordInstance写入 CloudResourceInstance 表该表对(projectId, cloudResourceId, instanceName)建立唯一索引不可用户编辑。支持的平台与属性来源平台cloud.platformcloud.*由谁填充实例身份AWS ECS / Fargateaws_ecs资源探测器resource detectoraws.ecs.task.arnAWS Elastic Beanstalkaws_elastic_beanstalk资源探测器host.idAWS App Runneraws_app_runner手工设置host.nameGoogle Cloud Rungcp_cloud_run资源探测器faas.instanceGoogle App Enginegcp_app_engine资源探测器faas.instanceAzure Container Appsazure_container_apps资源探测器azure.container_app.instance.idAzure Container Instancesazure_container_instances手工设置host.nameAzure App Serviceazure_app_service资源探测器host.id资源探测器SDK 内的探测器或 Collector 的resourcedetectionprocessor 读取平台元数据自动填充cloud.*属性。手工设置上游没有对应探测器需要你在OTEL_RESOURCE_ATTRIBUTES中自行写入各平台页面给出了精确写法。这条受管平台清单在源码中对应 Common/Types/Cloud/CloudPlatform.ts 的MANAGED_CLOUD_PLATFORMS描述符数组每一项都携带detection: detector | manual与instanceAttribute。此外该文件还有两个值得注意的实现细节Azure 平台名的点号改写Node / .NET 的 Azure SDK 探测器把平台拼成点号形式azure.container_apps、azure.app_service而语义约定与 Collector 探测器使用下划线。CLOUD_PLATFORM_ALIASES表L217-L224让摄取在入口处把这些值改写为下划线形式——否则同一订阅里Node 应用与 Collector sidecar 会落入两个不同环境。改写是在normalizeCloudPlatformL231-L253中完成的它还会先trim()并使用hasOwnProperty查找避免constructor之类的原型链注入。FaaS 与托管平台互不抢占FaasCloudPlatformaws_lambda、gcp_cloud_functions、azure_functions等单独枚举确保 Serverless 产品与云环境产品不会意外认领同一资源。什么不属于云环境你运行在会出现在原因EC2、Compute Engine、Azure VMaws_ec2、gcp_compute_engine、azure_vmHosts虚拟机就是主机EKS、GKE、AKS、自管理 KubernetesKubernetes由k8s.*属性路由Lambda、Cloud Functions、Azure Functionsaws_lambda、gcp_cloud_functions、azure_functionsServerless Functions由faas.name路由Cloud Run 与 App Engine 是**有意跨界**的它们的探测器同时设置受管的cloud.platform和faas.name因此每个服务既独立出现在Serverless Functions下又由Cloud Environment把该项目与区域内的所有服务聚合起来。接入配置两步走Step 1 — 激活云资源探测器Collector 形态在 OpenTelemetry Collector 中增加resourcedetectionprocessorprocessors: resourcedetection: detectors: [env, ecs] # Cloud Run 上用 [gcp]Azure 上用 [azure] timeout: 5sSDK 形态设置OTEL_RESOURCE_DETECTORSOTEL_RESOURCE_DETECTORSenv,ecs英语版文档对两种形态做了更细的展开值得参考形态 A —— SDK 直连 OneUptime启用平台的资源探测器NodeOTEL_NODE_RESOURCE_DETECTORSenv,host,os,aws/gcp/azurePythonOTEL_EXPERIMENTAL_RESOURCE_DETECTORSaws_ecs或gcp_resource_detectorJava-Dotel.resource.providers.aws.enabledtrue/gcpGo 的 contrib 探测器.NET 的OpenTelemetry.Resources.*包并把 OTLP exporter 指向 OneUptime。无需额外容器也没有容器级 CPU / 内存。形态 B —— sidecar OpenTelemetry Collector在任务 / 实例 / 副本中再跑一个容器。应用向localhost:4318导出Collector 的resourcedetectionprocessor 给所有数据打上cloud.*戳记、持有令牌并且在 ECS 上还能顺带上报每个任务的 CPU / 内存。Step 2 — 向 OneUptime 导出 OTLPexporters: otlphttp/oneuptime: endpoint: https://oneuptime.com/otlp headers: x-oneuptime-token: YOUR_TELEMETRY_INGESTION_TOKEN service: pipelines: traces: receivers: [otlp] processors: [resourcedetection] exporters: [otlphttp/oneuptime] metrics: receivers: [otlp] processors: [resourcedetection] exporters: [otlphttp/oneuptime] logs: receivers: [otlp] processors: [resourcedetection] exporters: [otlphttp/oneuptime]如果你自托管 OneUptime把 endpoint 换成https://YOUR-ONEUPTIME-HOST/otlp。三条 pipelinetraces / metrics / logs都必须保留resourcedetectionprocessor——指标如果没有cloud.platform会被归档到其他地方环境里的 CPU / 内存瓦片就不会填充。SDK 形态则直接在应用进程上设置OTEL_EXPORTER_OTLP_ENDPOINThttps://oneuptime.com/otlp OTEL_EXPORTER_OTLP_HEADERSx-oneuptime-tokenYOUR_TELEMETRY_INGESTION_TOKEN接入后的验证第一条 span / 日志 / 指标到达后一分钟内环境就会出现在Cloud → All Environments中。若想先确认令牌有效可用curl -i https://oneuptime.com/otlp/v1/validate \ -H x-oneuptime-token: YOUR_TELEMETRY_INGESTION_TOKEN200且返回valid: true令牌解析到某个项目继续401令牌缺失、格式错误、未知或已撤销请重新创建。环境概览视图你能得到什么环境概览德语文档 Was Sie erhalten展示CPU 与内存每个运行中任务 / 实例的实时 CPU 与内存来自container.cpu.utilization/container.memory.usage外加一个Top instances by CPUCPU 最高的实例列表Instances实例任务的实时数量Anfragen请求与趋势图从你的 traces 推导而来完整的Protokolle日志、Traces链路追踪、Metriken指标、Instanzen实例标签页。同一批工作负载的按服务拆解视图在Services下查看。英语版补充了三点重要细节CPU / 内存瓦片只由指标填充不来自 traces并且要求指标数据携带与 traces相同的实例身份在 ECS 上由 sidecar Collector 中的awsecscontainermetricsreceiver 以ecs.task.cpu.utilized/ecs.task.memory.utilized提供。Cloud Run、Container Apps 等其他 PaaS 不向 sidecar 暴露容器统计除非你自己上报这两个指标名否则那里的 CPU / 内存瓦片保持为空——此时应以Requests瓦片为准。形态 ASDK 直连永远不会发送容器指标所以 CPU / 内存为空是预期行为。环境在连续 15 分钟收不到遥测后会显示Disconnected下一条 span / 日志 / 指标到达即恢复。实例另有Stale过期标签与清扫器实例行若在CLOUD_INSTANCE_STALE_MINUTES默认 15最小 10内未出现会被硬删除该时钟以环境自身的最后遥测时间为基准因此 Collector 宕机只会冻结时钟而不会清空已知任务列表。常见问题与排查要点德语文档本身指向平台各自的接线文档与 Cloud Troubleshooting云环境故障排查后者按失败实际发生的顺序列出排查层级核心要点可提前掌握环境没出现先查cloud.platform是否缺失或非受管值常见原因SDK 未启用探测器、Collector pipeline 跳过了resourcedetection、无探测器平台上OTEL_RESOURCE_ATTRIBUTES拼写错误其次查令牌401时 Collector 日志表现为Permanent error: ... 401最后查出口网络ECS 私有子网需要 NAT 网关或assignPublicIpENABLED安全组放行 TCP 443Cloud Run 需要 Cloud NAT。出现在 Hosts 下资源带的是虚拟机平台aws_ec2等通常是探测器顺序问题——detectors: [ec2, elastic_beanstalk]时第一个设置cloud.platform的探测器胜出把elastic_beanstalk放到最前面。只出现在 Serverless Functions 下有faas.name但没有受管的cloud.platform注意 Cloud Run / App Engine 本应同时出现在两处。实例为空遥测没带任何实例身份属性CPU / 内存为空指标缺失或指标与 traces 的实例身份不一致。出现了两个环境环境键逐字符精确匹配aws_ecs|123456789012|us-east-1与aws_ecs||us-east-1是不同环境检查每个环境的 Resource Identifier 找出差异段。手工创建的环境从不匹配摄取只按 Resource Identifier匹配必须与遥测携带的platform|account|region完全一致同一拼写、无多余空格创建表单会从 Cloud Platform / Cloud Account ID / Cloud Region 三个字段推导出该键因此这三者必须与遥测逐字符一致。数据模型一览CloudResource表名CloudResource一个环境一行resourceIdentifier即环境键aws_ecs|123456789012|us-east-1name为显示名AWS ECS · us-east-1 · 123456789012另有cloudPlatform/cloudProvider/cloudRegion/cloudAccountId等最近一次看到的取值、otelCollectorStatus、lastSeenAt、可覆盖的遥测保留天数retainTelemetryDataForDays与标签。代码注释明确(projectId, resourceIdentifier)唯一索引用于让并发首见摄取批次折叠为单行cloud.*字段创建后可写、之后不可更新摄取心跳updateLastSeen负责回填与刷新手工编辑只会与 Collector 实际上报值漂移。CloudResourceInstance表名CloudResourceInstance一个运行实例一行由摄取管线 upsert不可用户编辑(projectId, cloudResourceId, instanceName)唯一。小结Cloud Environments 是 OneUptime 遥测体系中对托管 / PaaS 计算的聚合视图摄取端依据cloud.platform、cloud.account.id、cloud.region三元组自动发现并命名环境实例身份则通过一条精心排序的属性回退链统一判定。接入只需在 Collector 或 SDK 中启用资源探测器、把 OTLP 指向/otlp端点并在指标 pipeline 中保留resourcedetection。排查时从令牌验证开始按cloud.platform值、出口网络、实例身份、指标来源逐层排除即可快速定位绝大多数问题。【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考