尧图网页设计 
SkyWalking Service Hierarchy 配置完全指南深入解析 hierarchy-definition.yml 服务层级定义【免费下载链接】skywalkingAPM, Application Performance Monitoring System项目地址: https://gitcode.com/gh_mirrors/sk/skywalkingSkyWalking v10 引入了Service Hierarchy服务层级概念用于定义同一逻辑服务在不同监控层Layer之间的关联关系从而把来自 Service Mesh、Kubernetes、数据库中间件、虚拟数据库等不同观测面的服务实例串联成一张完整的拓扑图。本文以 service-hierarchy-configuration.md 为骨架结合仓库内真实配置文件与源码实现完整讲解config/hierarchy-definition.yml中hierarchy、auto-matching-rules、layer-levels三个核心段落的语法、语义与自定义方法帮助你掌握如何按自己的服务命名规则定义和调优服务层级关系。概念层面的整体设计可先阅读 service-hierarchy.md。配置文件位置与整体结构所有服务层级关系都定义在config/hierarchy-definition.yml文件中。该文件随 OAP 发行包分发源码中的模板位于 oap-server/server-starter/src/main/resources/hierarchy-definition.yml启动时由 OAP Core 模块加载。你可以按需自定义它。整个文件由三个顶层段落组成段落作用hierarchy定义服务层Layer之间的上下级关系以及每个关系使用的自动匹配规则auto-matching-rules定义可复用的匹配规则表达式输入参数为上层服务u与下层服务l返回布尔值layer-levels为每个服务层定义层级数值用于 UI 展示排序并约束上下级关系必须满足上大下小下面给出仓库中实际配置文件的完整示例比文档示例更完整覆盖了全部已注册的层级关系hierarchy: MESH: MESH_DP: name K8S_SERVICE: short-name MESH_DP: K8S_SERVICE: short-name GENERAL: APISIX: lower-short-name-remove-ns K8S_SERVICE: lower-short-name-remove-ns KONG: lower-short-name-remove-ns MYSQL: K8S_SERVICE: short-name POSTGRESQL: K8S_SERVICE: short-name APISIX: K8S_SERVICE: short-name NGINX: K8S_SERVICE: short-name SO11Y_OAP: K8S_SERVICE: short-name ROCKETMQ: K8S_SERVICE: short-name RABBITMQ: K8S_SERVICE: short-name KAFKA: K8S_SERVICE: short-name CLICKHOUSE: K8S_SERVICE: short-name PULSAR: K8S_SERVICE: short-name ACTIVEMQ: K8S_SERVICE: short-name KONG: K8S_SERVICE: short-name AIRFLOW: K8S_SERVICE: short-name VIRTUAL_DATABASE: MYSQL: lower-short-name-with-fqdn POSTGRESQL: lower-short-name-with-fqdn CLICKHOUSE: lower-short-name-with-fqdn VIRTUAL_MQ: ROCKETMQ: lower-short-name-with-fqdn RABBITMQ: lower-short-name-with-fqdn KAFKA: lower-short-name-with-fqdn PULSAR: lower-short-name-with-fqdn CILIUM_SERVICE: K8S_SERVICE: short-name auto-matching-rules: # the name of the upper service is equal to the name of the lower service name: { (u, l) - u.name l.name } # the short name of the upper service is equal to the short name of the lower service short-name: { (u, l) - u.shortName l.shortName } # remove the k8s namespace from the lower service short name # this rule is only works on k8s env. lower-short-name-remove-ns: { (u, l) - { if(l.shortName.lastIndexOf(.) 0) return u.shortName l.shortName.substring(0, l.shortName.lastIndexOf(.)); return false; } } # the short name of the upper remove port is equal to the short name of the lower service with fqdn suffix # this rule is only works on k8s env. lower-short-name-with-fqdn: { (u, l) - { if(u.shortName.lastIndexOf(:) 0) return u.shortName.substring(0, u.shortName.lastIndexOf(:)) l.shortName.concat(.svc.cluster.local); return false; } } layer-levels: MESH: 3 GENERAL: 3 SO11Y_OAP: 3 VIRTUAL_DATABASE: 3 VIRTUAL_MQ: 3 MYSQL: 2 POSTGRESQL: 2 APISIX: 2 NGINX: 2 ROCKETMQ: 2 CLICKHOUSE: 2 RABBITMQ: 2 KAFKA: 2 PULSAR: 2 ACTIVEMQ: 2 KONG: 2 AIRFLOW: 2 MESH_DP: 1 CILIUM_SERVICE: 1 K8S_SERVICE: 0hierarchy定义服务层之间的上下级关系hierarchy段落是服务层级关系的核心声明。其结构为上层 Layer → 下层 Layer → 匹配规则名的嵌套映射hierarchy: MESH: MESH_DP: name K8S_SERVICE: short-name上述声明的含义是MESH层的服务是MESH_DP层与K8S_SERVICE层的上层upper service并且这两对关系分别使用name与short-name两个自动匹配规则。需要理解的关键点某个 Layer 下面列出的层都是该 Layer 的相关下层lower layer。每对关系可以指定一个匹配规则规则定义在auto-matching-rules段落中用于自动匹配没有配置匹配规则的关系需要通过内部 API 手工建立OAP 不会自动为它们建立关联所有 Layer 都必须存在于 Layer.java 枚举中例如MESH_DP、K8S_SERVICE分别注册于该文件的第 130、160 行附近。如果hierarchy段中没有定义任何关系服务层级关系将不会被构建若想新增一段关系你必须确认它能被 auto-matching-rules 中的某个规则自动匹配否则需要借助内部 API 或特定 Agent 构建注意部分层级关系和自动匹配规则只在 Kubernetes 环境下生效例如依赖 Service 短名中带命名空间后缀、FQDN 等 k8s 特征的规则。从 service-hierarchy.md 中可以看到默认配置下自动匹配覆盖的上层与下层包括GENERAL → K8S_SERVICE、VIRTUAL_DATABASE → MYSQL/POSTGRESQL/CLICKHOUSE、VIRTUAL_MQ → RABBITMQ/ROCKETMQ/KAFKA/PULSAR、MESH → MESH_DP、MESH → K8S_SERVICE、MESH_DP → K8S_SERVICE以及各中间件层MYSQL、POSTGRESQL、CLICKHOUSE、NGINX、APISIX、ROCKETMQ、RABBITMQ、KAFKA、PULSAR、SO11Y_OAP、KONG、AIRFLOW到K8S_SERVICE的关系。仓库配置文件 hierarchy-definition.yml 还额外补充了GENERAL → APISIX、GENERAL → KONG、CILIUM_SERVICE → K8S_SERVICE、ACTIVEMQ → K8S_SERVICE等关系。auto-matching-rules自动匹配规则自动匹配规则定义在auto-matching-rules段落中。每个规则是一个表达式输入参数是上层服务u和下层服务l返回值是布尔值用于判定不同 Layer 上的两个服务是否可以建立父子关系。规则表达式支持属性访问如u.name、l.shortName、String 方法调用substring、lastIndexOf、concat、if/else、return、比较运算、!、、、逻辑运算、||、!、算术运算、-以及字符串/数字/布尔字面量这一点在 hierarchy-definition.yml 的注释中有明确说明。四个默认规则详解1.name上层服务 name 等于下层服务 namename: { (u, l) - u.name l.name }匹配表达式u.name l.name说明上层服务的完整名称name与下层服务的完整名称相等典型应用MESH → MESH_DP例如MESH.service.name mesh-svr::songs.sample-services与MESH_DP.service.name mesh-svr::songs.sample-services2.short-name上层服务短名等于下层服务短名short-name: { (u, l) - u.shortName l.shortName }匹配表达式u.shortName l.shortName说明上层服务的短名shortName与下层服务的短名相等典型应用MYSQL → K8S_SERVICE等绝大多数xx → K8S_SERVICE关系。例如MYSQL.service.name mysql::mysql.skywalking-showcase短名为mysql.skywalking-showcase与K8S_SERVICE.service.name skywalking-showcase::mysql.skywalking-showcase短名同为mysql.skywalking-showcase3.lower-short-name-remove-ns去掉下层服务短名中的 k8s 命名空间lower-short-name-remove-ns: { (u, l) - { if(l.shortName.lastIndexOf(.) 0) return u.shortName l.shortName.substring(0, l.shortName.lastIndexOf(.)); return false; } }匹配逻辑当下层服务短名中存在.即包含命名空间前缀时截取最后一个.之前的子串与上层服务短名比较否则返回false该规则仅适用于 k8s 环境典型应用GENERAL → K8S_SERVICE。例如GENERAL.service.name agent::songs短名songs与K8S_SERVICE.service.name skywalking-showcase::songs.sample-services短名去掉.sample-services后为songs匹配4.lower-short-name-with-fqdn上层去掉端口后与下层 FQDN 短名比较lower-short-name-with-fqdn: { (u, l) - { if(u.shortName.lastIndexOf(:) 0) return u.shortName.substring(0, u.shortName.lastIndexOf(:)) l.shortName.concat(.svc.cluster.local); return false; } }匹配逻辑上层服务短名去掉:端口之后与下层服务短名拼接.svc.cluster.local后缀的结果比较上层短名不含端口时返回false该规则仅适用于 k8s 环境典型应用VIRTUAL_DATABASE → MYSQL、VIRTUAL_MQ → RABBITMQ/ROCKETMQ/KAFKA/PULSAR。例如VIRTUAL_DATABASE.service.name mysql.skywalking-showcase.svc.cluster.local:3306去掉:3306后为mysql.skywalking-showcase.svc.cluster.local与MYSQL.service.name mysql::mysql.skywalking-showcase短名拼接后为mysql.skywalking-showcase.svc.cluster.local匹配匹配规则的适用范围与前提默认匹配规则要求服务名称遵循 SkyWalking 默认命名方式且以 SkyWalking Showcase 的默认部署为示例基准。在 SkyWalking 中服务名可由group与short name通过::分隔符组成例如agent::songs其中 group 为agent、short name 为songs。如果你在任意 Layer 上自定义了服务命名就必须根据你的命名规则同步定制相关的匹配规则否则自动匹配将失效。layer-levelsUI 展示顺序与服务层校验layer-levels段落为每个服务层定义层级数值其作用是决定 UI 中服务层的展示顺序约束层级关系的合法性在hierarchy段落中上层服务的 level 必须大于下层服务的 level。默认配置中K8S_SERVICE为最底层level 0MESH_DP、CILIUM_SERVICE为 level 1各数据库/中间件层为 level 2MESH、GENERAL、SO11Y_OAP、VIRTUAL_DATABASE、VIRTUAL_MQ为 level 3。文档给出的示意省略了VIRTUAL_MQ、APISIX、NGINX等行的简化版与仓库完整配置一致均遵循这一分级原则。启用与关闭服务层级服务层级功能由 Core 模块的enableHierarchy开关控制默认开启配置文件application.yml 中enableHierarchy: ${SW_CORE_ENABLE_HIERARCHY:true}第 144-147 行附近环境变量SW_CORE_ENABLE_HIERARCHY默认值为true源码默认值CoreModuleConfig.java 中private boolean enableHierarchy true;。如果关闭该开关服务与实例的层级关系将不会被构建层级查询接口会返回空结果。源码实现配置如何被加载、编译与校验hierarchy-definition.yml的加载与解析集中在 HierarchyDefinitionService.java 中整个处理流程可以概括为四步读取 YAML通过ResourceUtils.readToStream(hierarchy-definition.yml)读取配置文件不存在时抛出hierarchy-definition.yml not found异常用 SnakeYAML 解析出hierarchy、auto-matching-rules、layer-levels三个段落编译匹配规则通过 Java SPIServiceLoader发现HierarchyRuleProvider实现由 hierarchy 模块的 CompiledHierarchyRuleProvider.java 提供把每条规则表达式编译为可执行的BiFunctionService, Service, Boolean匹配器。如果 classpath 中没有 provider启动会快速失败组装层级结构把编译后的规则与hierarchy段落中的上层 → 下层 → 规则名映射绑定生成hierarchyDefinition启动期校验checkLayers逐一校验所有出现在layer-levels中的层必须是 Layer.java 中的合法层校验hierarchy中出现的每个层都在layer-levels中定义了 level并强制要求上层 level 大于下层 level否则抛出形如hierarchy-definition.yml hierarchy: MESH layer-level should be greater than MESH_DP layer-level.的启动异常。规则的表达式编译依赖 ANTLR4 语法定义与运行时类生成相关文件位于 oap-server/analyzer/hierarchy 模块中包括词法/语法文件 HierarchyRuleLexer.g4 与 HierarchyRuleParser.g4以及负责生成匹配器字节码的 HierarchyRuleClassGenerator.java 和 HierarchyRuleScriptParser.java。运行时匹配由MatchingRule.match(upper, lower)触发HierarchyService消费编译结果完成实际的服务匹配。仓库还提供了配套的单元测试用于验证规则编译与执行行为例如 HierarchyRuleExecutionTest.java、HierarchyRuleScriptParserTest.java 与 HierarchyProviderCoordinateTest.java可以作为你自定义规则时的行为参照。实例层级Instance Hierarchy实例层级的定义与规则完全沿用服务层级一旦服务层级关系建立成功实例层级关系便会按以下规则自动检测见 service-hierarchy.md上层实例名等于下层实例名上层实例属性pod/hostname等于下层实例属性pod/hostname上层实例属性pod/hostname等于下层实例名上层实例名等于下层实例属性pod/hostname。因此在配置服务层级时无需为实例单独配置任何规则。自定义配置的注意事项清单综合原文档与源码约束自定义hierarchy-definition.yml时请重点核对以下几点层名合法性所有层名必须是 Layer.java 中注册的层非法层名会导致启动失败level 约束每个出现于hierarchy的层都必须出现在layer-levels中且上层 level 必须严格大于下层 level规则可用性新增关系时务必确认该关系可被auto-matching-rules中某个规则自动匹配否则需通过内部 API 或特定 Agent如 eBPF、Operator、Agent Injector构建命名一致性默认规则以 SkyWalking 默认命名与 Showcase 部署为基准自定义任意一层的服务命名后必须同步改写对应匹配规则环境限制lower-short-name-remove-ns与lower-short-name-with-fqdn依赖 k8s 的命名空间与 FQDN 特征仅在 k8s 环境有效未定义即不构建如果hierarchy段落完全未定义或enableHierarchy关闭服务层级关系将不会被构建。通过合理配置这三个段落你可以在多观测面Service Mesh、K8s Service、虚拟数据库、消息队列、数据库中间件等之间建立完整的服务归属关系让 SkyWalking 拓扑视图更准确地还原真实的架构调用链。【免费下载链接】skywalkingAPM, Application Performance Monitoring System项目地址: https://gitcode.com/gh_mirrors/sk/skywalking创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 SkyWalking Service Hierarchy 配置完全指南：深入解析 hierarchy-definition.yml 服务层级定义
SkyWalking Service Hierarchy 配置完全指南深入解析 hierarchy-definition.yml 服务层级定义【免费下载链接】skywalkingAPM, Application Performance Monitoring System项目地址: https://gitcode.com/gh_mirrors/sk/skywalkingSkyWalking v10 引入了Service Hierarchy服务层级概念用于定义同一逻辑服务在不同监控层Layer之间的关联关系从而把来自 Service Mesh、Kubernetes、数据库中间件、虚拟数据库等不同观测面的服务实例串联成一张完整的拓扑图。本文以 service-hierarchy-configuration.md 为骨架结合仓库内真实配置文件与源码实现完整讲解config/hierarchy-definition.yml中hierarchy、auto-matching-rules、layer-levels三个核心段落的语法、语义与自定义方法帮助你掌握如何按自己的服务命名规则定义和调优服务层级关系。概念层面的整体设计可先阅读 service-hierarchy.md。配置文件位置与整体结构所有服务层级关系都定义在config/hierarchy-definition.yml文件中。该文件随 OAP 发行包分发源码中的模板位于 oap-server/server-starter/src/main/resources/hierarchy-definition.yml启动时由 OAP Core 模块加载。你可以按需自定义它。整个文件由三个顶层段落组成段落作用hierarchy定义服务层Layer之间的上下级关系以及每个关系使用的自动匹配规则auto-matching-rules定义可复用的匹配规则表达式输入参数为上层服务u与下层服务l返回布尔值layer-levels为每个服务层定义层级数值用于 UI 展示排序并约束上下级关系必须满足上大下小下面给出仓库中实际配置文件的完整示例比文档示例更完整覆盖了全部已注册的层级关系hierarchy: MESH: MESH_DP: name K8S_SERVICE: short-name MESH_DP: K8S_SERVICE: short-name GENERAL: APISIX: lower-short-name-remove-ns K8S_SERVICE: lower-short-name-remove-ns KONG: lower-short-name-remove-ns MYSQL: K8S_SERVICE: short-name POSTGRESQL: K8S_SERVICE: short-name APISIX: K8S_SERVICE: short-name NGINX: K8S_SERVICE: short-name SO11Y_OAP: K8S_SERVICE: short-name ROCKETMQ: K8S_SERVICE: short-name RABBITMQ: K8S_SERVICE: short-name KAFKA: K8S_SERVICE: short-name CLICKHOUSE: K8S_SERVICE: short-name PULSAR: K8S_SERVICE: short-name ACTIVEMQ: K8S_SERVICE: short-name KONG: K8S_SERVICE: short-name AIRFLOW: K8S_SERVICE: short-name VIRTUAL_DATABASE: MYSQL: lower-short-name-with-fqdn POSTGRESQL: lower-short-name-with-fqdn CLICKHOUSE: lower-short-name-with-fqdn VIRTUAL_MQ: ROCKETMQ: lower-short-name-with-fqdn RABBITMQ: lower-short-name-with-fqdn KAFKA: lower-short-name-with-fqdn PULSAR: lower-short-name-with-fqdn CILIUM_SERVICE: K8S_SERVICE: short-name auto-matching-rules: # the name of the upper service is equal to the name of the lower service name: { (u, l) - u.name l.name } # the short name of the upper service is equal to the short name of the lower service short-name: { (u, l) - u.shortName l.shortName } # remove the k8s namespace from the lower service short name # this rule is only works on k8s env. lower-short-name-remove-ns: { (u, l) - { if(l.shortName.lastIndexOf(.) 0) return u.shortName l.shortName.substring(0, l.shortName.lastIndexOf(.)); return false; } } # the short name of the upper remove port is equal to the short name of the lower service with fqdn suffix # this rule is only works on k8s env. lower-short-name-with-fqdn: { (u, l) - { if(u.shortName.lastIndexOf(:) 0) return u.shortName.substring(0, u.shortName.lastIndexOf(:)) l.shortName.concat(.svc.cluster.local); return false; } } layer-levels: MESH: 3 GENERAL: 3 SO11Y_OAP: 3 VIRTUAL_DATABASE: 3 VIRTUAL_MQ: 3 MYSQL: 2 POSTGRESQL: 2 APISIX: 2 NGINX: 2 ROCKETMQ: 2 CLICKHOUSE: 2 RABBITMQ: 2 KAFKA: 2 PULSAR: 2 ACTIVEMQ: 2 KONG: 2 AIRFLOW: 2 MESH_DP: 1 CILIUM_SERVICE: 1 K8S_SERVICE: 0hierarchy定义服务层之间的上下级关系hierarchy段落是服务层级关系的核心声明。其结构为上层 Layer → 下层 Layer → 匹配规则名的嵌套映射hierarchy: MESH: MESH_DP: name K8S_SERVICE: short-name上述声明的含义是MESH层的服务是MESH_DP层与K8S_SERVICE层的上层upper service并且这两对关系分别使用name与short-name两个自动匹配规则。需要理解的关键点某个 Layer 下面列出的层都是该 Layer 的相关下层lower layer。每对关系可以指定一个匹配规则规则定义在auto-matching-rules段落中用于自动匹配没有配置匹配规则的关系需要通过内部 API 手工建立OAP 不会自动为它们建立关联所有 Layer 都必须存在于 Layer.java 枚举中例如MESH_DP、K8S_SERVICE分别注册于该文件的第 130、160 行附近。如果hierarchy段中没有定义任何关系服务层级关系将不会被构建若想新增一段关系你必须确认它能被 auto-matching-rules 中的某个规则自动匹配否则需要借助内部 API 或特定 Agent 构建注意部分层级关系和自动匹配规则只在 Kubernetes 环境下生效例如依赖 Service 短名中带命名空间后缀、FQDN 等 k8s 特征的规则。从 service-hierarchy.md 中可以看到默认配置下自动匹配覆盖的上层与下层包括GENERAL → K8S_SERVICE、VIRTUAL_DATABASE → MYSQL/POSTGRESQL/CLICKHOUSE、VIRTUAL_MQ → RABBITMQ/ROCKETMQ/KAFKA/PULSAR、MESH → MESH_DP、MESH → K8S_SERVICE、MESH_DP → K8S_SERVICE以及各中间件层MYSQL、POSTGRESQL、CLICKHOUSE、NGINX、APISIX、ROCKETMQ、RABBITMQ、KAFKA、PULSAR、SO11Y_OAP、KONG、AIRFLOW到K8S_SERVICE的关系。仓库配置文件 hierarchy-definition.yml 还额外补充了GENERAL → APISIX、GENERAL → KONG、CILIUM_SERVICE → K8S_SERVICE、ACTIVEMQ → K8S_SERVICE等关系。auto-matching-rules自动匹配规则自动匹配规则定义在auto-matching-rules段落中。每个规则是一个表达式输入参数是上层服务u和下层服务l返回值是布尔值用于判定不同 Layer 上的两个服务是否可以建立父子关系。规则表达式支持属性访问如u.name、l.shortName、String 方法调用substring、lastIndexOf、concat、if/else、return、比较运算、!、、、逻辑运算、||、!、算术运算、-以及字符串/数字/布尔字面量这一点在 hierarchy-definition.yml 的注释中有明确说明。四个默认规则详解1.name上层服务 name 等于下层服务 namename: { (u, l) - u.name l.name }匹配表达式u.name l.name说明上层服务的完整名称name与下层服务的完整名称相等典型应用MESH → MESH_DP例如MESH.service.name mesh-svr::songs.sample-services与MESH_DP.service.name mesh-svr::songs.sample-services2.short-name上层服务短名等于下层服务短名short-name: { (u, l) - u.shortName l.shortName }匹配表达式u.shortName l.shortName说明上层服务的短名shortName与下层服务的短名相等典型应用MYSQL → K8S_SERVICE等绝大多数xx → K8S_SERVICE关系。例如MYSQL.service.name mysql::mysql.skywalking-showcase短名为mysql.skywalking-showcase与K8S_SERVICE.service.name skywalking-showcase::mysql.skywalking-showcase短名同为mysql.skywalking-showcase3.lower-short-name-remove-ns去掉下层服务短名中的 k8s 命名空间lower-short-name-remove-ns: { (u, l) - { if(l.shortName.lastIndexOf(.) 0) return u.shortName l.shortName.substring(0, l.shortName.lastIndexOf(.)); return false; } }匹配逻辑当下层服务短名中存在.即包含命名空间前缀时截取最后一个.之前的子串与上层服务短名比较否则返回false该规则仅适用于 k8s 环境典型应用GENERAL → K8S_SERVICE。例如GENERAL.service.name agent::songs短名songs与K8S_SERVICE.service.name skywalking-showcase::songs.sample-services短名去掉.sample-services后为songs匹配4.lower-short-name-with-fqdn上层去掉端口后与下层 FQDN 短名比较lower-short-name-with-fqdn: { (u, l) - { if(u.shortName.lastIndexOf(:) 0) return u.shortName.substring(0, u.shortName.lastIndexOf(:)) l.shortName.concat(.svc.cluster.local); return false; } }匹配逻辑上层服务短名去掉:端口之后与下层服务短名拼接.svc.cluster.local后缀的结果比较上层短名不含端口时返回false该规则仅适用于 k8s 环境典型应用VIRTUAL_DATABASE → MYSQL、VIRTUAL_MQ → RABBITMQ/ROCKETMQ/KAFKA/PULSAR。例如VIRTUAL_DATABASE.service.name mysql.skywalking-showcase.svc.cluster.local:3306去掉:3306后为mysql.skywalking-showcase.svc.cluster.local与MYSQL.service.name mysql::mysql.skywalking-showcase短名拼接后为mysql.skywalking-showcase.svc.cluster.local匹配匹配规则的适用范围与前提默认匹配规则要求服务名称遵循 SkyWalking 默认命名方式且以 SkyWalking Showcase 的默认部署为示例基准。在 SkyWalking 中服务名可由group与short name通过::分隔符组成例如agent::songs其中 group 为agent、short name 为songs。如果你在任意 Layer 上自定义了服务命名就必须根据你的命名规则同步定制相关的匹配规则否则自动匹配将失效。layer-levelsUI 展示顺序与服务层校验layer-levels段落为每个服务层定义层级数值其作用是决定 UI 中服务层的展示顺序约束层级关系的合法性在hierarchy段落中上层服务的 level 必须大于下层服务的 level。默认配置中K8S_SERVICE为最底层level 0MESH_DP、CILIUM_SERVICE为 level 1各数据库/中间件层为 level 2MESH、GENERAL、SO11Y_OAP、VIRTUAL_DATABASE、VIRTUAL_MQ为 level 3。文档给出的示意省略了VIRTUAL_MQ、APISIX、NGINX等行的简化版与仓库完整配置一致均遵循这一分级原则。启用与关闭服务层级服务层级功能由 Core 模块的enableHierarchy开关控制默认开启配置文件application.yml 中enableHierarchy: ${SW_CORE_ENABLE_HIERARCHY:true}第 144-147 行附近环境变量SW_CORE_ENABLE_HIERARCHY默认值为true源码默认值CoreModuleConfig.java 中private boolean enableHierarchy true;。如果关闭该开关服务与实例的层级关系将不会被构建层级查询接口会返回空结果。源码实现配置如何被加载、编译与校验hierarchy-definition.yml的加载与解析集中在 HierarchyDefinitionService.java 中整个处理流程可以概括为四步读取 YAML通过ResourceUtils.readToStream(hierarchy-definition.yml)读取配置文件不存在时抛出hierarchy-definition.yml not found异常用 SnakeYAML 解析出hierarchy、auto-matching-rules、layer-levels三个段落编译匹配规则通过 Java SPIServiceLoader发现HierarchyRuleProvider实现由 hierarchy 模块的 CompiledHierarchyRuleProvider.java 提供把每条规则表达式编译为可执行的BiFunctionService, Service, Boolean匹配器。如果 classpath 中没有 provider启动会快速失败组装层级结构把编译后的规则与hierarchy段落中的上层 → 下层 → 规则名映射绑定生成hierarchyDefinition启动期校验checkLayers逐一校验所有出现在layer-levels中的层必须是 Layer.java 中的合法层校验hierarchy中出现的每个层都在layer-levels中定义了 level并强制要求上层 level 大于下层 level否则抛出形如hierarchy-definition.yml hierarchy: MESH layer-level should be greater than MESH_DP layer-level.的启动异常。规则的表达式编译依赖 ANTLR4 语法定义与运行时类生成相关文件位于 oap-server/analyzer/hierarchy 模块中包括词法/语法文件 HierarchyRuleLexer.g4 与 HierarchyRuleParser.g4以及负责生成匹配器字节码的 HierarchyRuleClassGenerator.java 和 HierarchyRuleScriptParser.java。运行时匹配由MatchingRule.match(upper, lower)触发HierarchyService消费编译结果完成实际的服务匹配。仓库还提供了配套的单元测试用于验证规则编译与执行行为例如 HierarchyRuleExecutionTest.java、HierarchyRuleScriptParserTest.java 与 HierarchyProviderCoordinateTest.java可以作为你自定义规则时的行为参照。实例层级Instance Hierarchy实例层级的定义与规则完全沿用服务层级一旦服务层级关系建立成功实例层级关系便会按以下规则自动检测见 service-hierarchy.md上层实例名等于下层实例名上层实例属性pod/hostname等于下层实例属性pod/hostname上层实例属性pod/hostname等于下层实例名上层实例名等于下层实例属性pod/hostname。因此在配置服务层级时无需为实例单独配置任何规则。自定义配置的注意事项清单综合原文档与源码约束自定义hierarchy-definition.yml时请重点核对以下几点层名合法性所有层名必须是 Layer.java 中注册的层非法层名会导致启动失败level 约束每个出现于hierarchy的层都必须出现在layer-levels中且上层 level 必须严格大于下层 level规则可用性新增关系时务必确认该关系可被auto-matching-rules中某个规则自动匹配否则需通过内部 API 或特定 Agent如 eBPF、Operator、Agent Injector构建命名一致性默认规则以 SkyWalking 默认命名与 Showcase 部署为基准自定义任意一层的服务命名后必须同步改写对应匹配规则环境限制lower-short-name-remove-ns与lower-short-name-with-fqdn依赖 k8s 的命名空间与 FQDN 特征仅在 k8s 环境有效未定义即不构建如果hierarchy段落完全未定义或enableHierarchy关闭服务层级关系将不会被构建。通过合理配置这三个段落你可以在多观测面Service Mesh、K8s Service、虚拟数据库、消息队列、数据库中间件等之间建立完整的服务归属关系让 SkyWalking 拓扑视图更准确地还原真实的架构调用链。【免费下载链接】skywalkingAPM, Application Performance Monitoring System项目地址: https://gitcode.com/gh_mirrors/sk/skywalking创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考