APM 实体和关系建模说明-云监控(CMS)-阿里云帮助中心

APM 实体和关系建模以观测数据的上报特征为基础：CMS2.0 平台自动发现应用、接口、实例和外部依赖等实体，并在实体之间建立拓扑关系。自动关联依赖规范、完整且稳定的上报信息，不需要用户预先或手动维护拓扑；当上报数据无法稳定识别关系，或目标对象未接入实体发现时，需要通过 StarOps 手动补充关联。理解实体类型、关系语义和关联成立的条件，有助于判断拓扑关联缺失的原因，并选择正确的修复方式。

支持的实体

APM 域当前支持 15 类实体，分为核心实体、外部依赖实体和 AI 实体。上述分类按实体的使用场景划分，因此 apm.external.model（大模型）和 apm.external.tool（工具）虽由 AI 应用或 Agent 调用、entity_type 采用 apm.external. 前缀，仍归入 AI 实体。本清单覆盖 APM 域的实体类型，跨域关联中出现的 Kubernetes、基础设施和阿里云产品实体（如 k8s.pod、infra.server、acs.rds.instance）不属于 APM 域。

核心实体

实体	entity_type	定义
应用	`apm.service`	被监控的应用或服务，是 APM 拓扑的核心节点。
接口	`apm.operation`	应用对外或对内提供的 HTTP、RPC、消息消费、定时任务等操作入口。
实例	`apm.instance`	应用的实际运行单元，例如主机进程或 Kubernetes Pod 中的应用实例。

外部依赖实体

实体	entity_type	定义
数据库	`apm.external.database`	应用访问的关系型数据库。
NoSQL / 缓存	`apm.external.nosql`	应用访问的 NoSQL、缓存或搜索服务。
HTTP 外部服务	`apm.external.http_client`	应用通过 HTTP 调用的外部目标。
消息队列	`apm.external.message`	应用生产消息时访问的消息实例或 Topic。
RPC 客户端	`apm.external.rpc_client`	应用通过 RPC 协议调用的外部目标。
其他外部依赖	`apm.external.others`	无法归入上述类别的其他出站调用目标。

AI 实体

实体	entity_type	定义
AI 应用	`apm.genai.service`	具备推理能力的 AI 应用。
模型服务	`apm.genai.model_service`	提供模型推理能力的推理服务。
AI Agent	`apm.genai.agent`	执行复杂推理过程的 Agent，可能为 main agent、sub agent 等。
大模型	`apm.external.model`	AI 应用或 Agent 调用的大语言模型。
工具	`apm.external.tool`	AI 应用或 Agent 调用的外部工具。
技能	`apm.genai.skill`	Agent 按需加载或调用的技能。

实体关系类型

APM 拓扑中的实体关系包括 contains、calls、related_to、same_as 和 hosts 五种类型，语义与典型实体对如下。

关系	语义	典型实体对
`contains`	包含关系。	应用包含接口；应用包含实例。
`calls`	调用关系，由调用方指向被调用方。	应用调用应用；应用或接口调用外部依赖；GenAI 应用或 Agent 调用模型和工具。
`related_to`	关联关系。	AI 应用关联 Agent。
`same_as`	等价关系，两个实体为同一对象。	APM 外部依赖与对应云资源等价；GenAI 应用与普通 APM 应用等价。
`hosts`	承载关系，由资源指向其承载的应用或实例。	Kubernetes Workload 承载 APM 应用；Pod 承载 APM 实例；ECS 承载 APM 实例。

自动发现与自动关联

自动识别机制

CMS2.0 平台根据应用指标、链路 Trace、Agent 实例信息及资源属性中的数据特征，自动识别应用、接口、实例和外部依赖，并建立实体关系。自动识别仅依赖规范、完整且稳定的上报信息，不需要用户预先或手动维护拓扑。自动生成的关系包括 contains、calls、related_to、same_as 和 hosts，语义与典型实体对见实体关系类型，各类实体所需的最低上报特征见数据上报要求。

跨域关联的必要条件

跨域关联是指 APM 实体与 Kubernetes、阿里云产品或基础设施实体之间的关系。自动关联需同时满足以下条件：

两侧实体均已被发现。 APM 数据已正常上报，同时对应的 Kubernetes、云产品或基础设施实体已接入实体发现。
关联标识完整。 上报数据包含用于匹配的集群、命名空间、Pod、Workload、实例 ID、IP、连接地址或应用名称等标识。
标识值一致。 APM 侧上报值与资源侧登记值在语义和格式上保持一致。
实体处于同一可见范围。 两侧数据应进入可共同查询和构建拓扑的工作空间或资源管理范围。
数据持续有效。 关联标识不应被采集链路删除、覆盖或改写为无法匹配的值。

重要

满足上述条件后，若 k8s.pod 实体数量过大导致实体超限，与 APM 域的跨域关联展示仍会受到影响，需要提交工单或联系技术支持协助扩容。

常见自动跨域关系如下。表中 → 表示关系由前者指向后者，↔ 表示两侧实体相互对应：

关联场景	实体关系	关键识别条件
Pod 承载实例	`k8s.pod` → `apm.instance`，`hosts`	集群标识、命名空间和 Pod 名称一致；APM 实例身份完整。
Deployment 承载应用	`k8s.deployment` → `apm.service`，`hosts`	Pod 关联成立，并能识别 Deployment 名称。
StatefulSet 承载应用	`k8s.statefulset` → `apm.service`，`hosts`	Pod 关联成立，并能识别 StatefulSet 名称。
数据库关联 RDS / PolarDB	`apm.external.database` ↔ 云数据库实体，`same_as`	数据库调用类型正确，连接地址与云产品连接地址及端口一致。
NoSQL 关联 Redis / Elasticsearch	`apm.external.nosql` ↔ 云产品实体，`same_as`	NoSQL 调用类型正确，连接地址一致。
消息关联 Kafka	`apm.external.message` ↔ Kafka 实例或 Topic，`same_as`	消息调用类型、实例端点或 Topic 名称一致。
实例关联 ECS	`infra.server` → `apm.instance`，`hosts`	ECS 实例 ID 或 IP 一致。
应用关联 API 网关 / PAI-EAS	`apm.service` ↔ 云产品实体	应用名称与对应云产品实例名称一致。

Kubernetes 场景的推荐接入方式

本节细化上表中 Kubernetes 相关的关联场景，Kubernetes 环境下建议上报的资源属性见数据上报要求。

使用 ARMS 探针时，建议通过 ACK OnePilot 接入。应用部署过程中，OnePilot 可补充 Kubernetes 环境信息，CMS2.0 平台可以根据上报特征自动完成关联。
使用 OpenTelemetry 接入时，应随 Span Resource 持续上报标准 Kubernetes 资源属性，以便基于数据自动建立应用层和基础设施层的实体映射关联。

数据上报要求

自动关联能否成立，取决于上报数据是否规范、完整且稳定。埋点时应满足以下要求。

通用埋点规范

应用标识保持稳定。 同一逻辑应用使用固定的 service.name，不要拼接 Pod 名、IP、版本号等易变信息。
资源信息放入 Resource。 Kubernetes 集群、命名空间、Pod、Workload、主机等属性应作为资源属性随所有 Span 上报。
使用真实资源标识。 集群使用 UID，Pod 和 Workload 使用 Kubernetes 实际名称，不使用控制台展示别名。
完整保留调用语义。 数据库、消息、RPC 和 HTTP 出站调用应保留协议类型、调用方向以及目标地址。
统一目标地址格式。 数据库和中间件地址建议使用与云控制台一致的域名或连接串及端口，并统一大小写和附加字符格式。
避免高基数实体标识。 URL 查询参数、请求 ID、容器临时 ID 等不应作为应用、接口或外部依赖的稳定标识。

Kubernetes 资源属性

Kubernetes 环境建议至少提供以下信息：

目的	推荐属性
识别应用	`service.name`、工作空间标识；如已分配应用 ID，应保持应用 ID 一致。
识别实例	`host.name` 或 `host.ip`。
关联 Pod	`k8s.cluster.uid`、`k8s.namespace.name`、`k8s.pod.name`。
关联 Deployment	Pod 关联所需属性，以及 `k8s.deployment.name`。
关联 StatefulSet	Pod 关联所需属性，以及 `k8s.statefulset.name`。

外部调用的最低识别特征

CMS2.0 平台根据出站调用的数据特征识别外部依赖，最低识别特征如下：

外部实体	最低识别特征
`apm.external.database`	数据库调用类型 + `endpoint`。
`apm.external.nosql`	NoSQL 或缓存调用类型 + `endpoint`。
`apm.external.http_client`	HTTP 客户端调用类型 + `destId`。
`apm.external.message`	消息生产调用类型 + `endpoint`。
`apm.external.rpc_client`	RPC 客户端调用类型 + `endpoint`。
`apm.external.others`	通用客户端调用类型 + `endpoint`。

关联失败排查

排查顺序与处理方式

发现拓扑缺失时，建议按以下顺序检查：

确认来源实体和目标实体是否均已生成。
确认调用或承载关系对应的数据是否已经产生并成功上报。
确认关键标识是否完整、稳定，并与目标资源登记信息一致。
Kubernetes 场景重点检查 Pod 三元组、实例身份和 Workload 名称。
外部依赖场景重点检查调用类型以及 endpoint 或 destId。
自动关联条件无法满足时，再通过 StarOps 写入手动拓扑关系。
定位原因类别后，按下表选择处理方式：

定位结果	处理方式
实体未生成：Kubernetes 实体未接入，或目标系统未接入实体发现、目标实体本身尚不存在。	先完成实体发现或接入，确认相关实体对当前工作空间可见。
关联标识缺失或不一致：`k8s.*` 资源属性缺失、连接地址与资源侧登记不一致，或目标地址被代理、网关、负载均衡、Service 地址、NAT 地址改写。	按数据上报要求规范埋点并统一标识，恢复自动关联。
实体规模超限：`k8s.pod` 实体数量过大。	提交工单或联系技术支持协助扩容。
客观上无法提供可匹配特征：目标为第三方系统或自建资源，历史数据、特殊埋点无法补齐所需字段。	通过 StarOps 手动补充关联。

Kubernetes 场景的典型原因

Kubernetes 实体未接入或缺失
- 表现：实体列表中检索不到集群或工作负载等实体；APM 应用和实例正常，但拓扑中没有可关联的 Pod 或 Workload。
- 原因：Kubernetes 侧未完成实体发现，或相关集群资源和实体对当前工作空间不可见。
- 处理：先完成 Kubernetes 的实体发现，并确认相关集群资源和实体对当前工作空间可见。可以访问 CMS2.0 控制台，进入接入中心 > 容器洞察，显式针对某个容器集群开启接入，确保实体列表中可以正常查看。
OpenTelemetry 接入的应用无法定位容器实体
- 表现：拓扑中 APM 无法直接定位到容器相关实体。
- 原因：OpenTelemetry 场景上报的 Span 数据不完整，导致指标中缺少 Pod 相关 Label。
- 处理：为 OpenTelemetry 场景上报的 Span 数据附上标准 k8s.* Resource 属性，例如 k8s.pod.name。同时，Kubernetes 环境下至少保证 host.name 为 Pod Name，否则会导致无法关联。
ARMS 探针接入的应用无法定位容器实体
- 表现：拓扑中 APM 无法直接定位到容器相关实体。
- 原因：ARMS 探针接入场景需要通过 ACK OnePilot 接入，才能自动识别 Kubernetes 环境信息并注入到探针上报的数据中。
- 处理：通过 ACK OnePilot 完成接入，并检查探针上报心跳日志中是否包含 Kubernetes 运行环境信息，确认是否生效。
实体超限导致无法关联
- 表现：容器洞察已接入，APM 实例中也包含 Kubernetes Pod Name 信息，但依然无法关联到 Kubernetes 实体。
- 原因：k8s.pod 实体数量可能过大导致实体超限，从而影响与 APM 域的跨域关联展示。
- 处理：提交工单或联系技术支持协助扩容解决。

外部依赖场景的典型原因

外部依赖实体已经生成，但无法进一步关联到具体云资源、被监控应用或第三方系统时，常见原因包括：

上报的目标地址是代理、网关、负载均衡、Service 地址或 NAT 地址，与实际目标实体标识不同。
连接地址缺少端口、包含额外字符，或与资源侧登记的公网、私网地址不一致。
HTTP 目标仅包含通用 URL，缺少可唯一定位目标实体的稳定标识。
目标系统未接入实体发现，或目标实体本身尚不存在。
自定义框架或埋点未正确表达调用类型和目标地址。
应优先通过规范埋点和统一标识恢复自动关联；当客观上无法提供可匹配特征时，再使用手动关联补充。

通过 StarOps 手动补充关联

适用场景

以下场景可通过 StarOps 补充 UModel 拓扑关系：

http_client、数据库等外部调用经过代理或地址转换，无法与真实目标自动匹配。
目标为第三方系统、自建资源或其他无法通过标准实体发现接入的对象。
历史数据或特殊埋点无法补齐自动关联所需字段。
业务上已明确两个实体的关系，但上报数据不足以稳定推断。

手动关联要素

手动关联时，应显式指定以下信息：

信息	说明
来源实体	来源实体的 `entity_type` 及唯一标识，例如调用方应用、接口或 APM 外部依赖。
目标实体	目标实体的 `entity_type` 及唯一标识；目标尚不存在时，应先完成实体补录或接入。
关系类型	根据实际语义选择 `calls`、`same_as`、`hosts` 等关系。
作用范围	明确关系所属的工作空间或资源范围，避免跨环境误关联。
生命周期	明确关系的生效、更新和删除机制，避免实体下线后残留无效拓扑。

关系类型应严格遵循实体语义，各关系的语义和方向见实体关系类型。典型示例如下：

场景	来源实体	目标实体	关系
补充应用到 HTTP 外部目标的调用	`apm.service` 或 `apm.operation`	`apm.external.http_client`	`calls`
将数据库调用目标映射到实际 RDS 实例	`apm.external.database`	`acs.rds.instance`	`same_as`
补充 Pod 与应用实例的承载关系	`k8s.pod`	`apm.instance`	`hosts`

说明

手动关联仅补充实体之间的拓扑关系，不替代应用埋点、链路采集和指标上报，也不会自动补齐目标实体的监控数据。能够通过标准上报恢复自动识别时，应优先采用自动关联，以降低人工维护成本并避免关系过期。

手动关联实践

示例场景：CMS2.0 平台识别到某个 AI 应用调用了 Qwen3-8B 模型服务，该模型服务部署于 PAI-EAS。从 AI 应用的客户端视角只能感知到 HTTP 服务地址，无法直接关联到背后的 PAI 推理服务实体，此时可借助 UModel 补充实体关系。从 CMS2.0 控制台唤起 StarOps，以自然语言对话下达写入指令，指令中需要描述清楚来源实体、目标实体、实体关系和保存周期（可以设置为 5 年）。指令示例如下：

apm.external.model：Qwen3-8B 对应的就是 acs.pai.eas：qwen38b，帮我写入这两个实体关联到 topoStore 中，relation_type 为 same_as，关联关系保留 5 年。

等待 StarOps 执行完成后，拓扑架构上会正常体现客户端实体和服务端实体的拓扑关系。