service-graph-diagnosis

服务图诊断

概述

此技能提供了一套系统方法，用于诊断和解决 ServiceNow 中的 Service Graph Connector 问题。涵盖以下内容：

• 验证 Service Graph Connector 配置和连接状态
• 排查从外部数据源经由 cmdb_ci 和 cmdb_rel_ci 流入 CMDB 的数据
• 诊断发现模式故障，以及识别/协调规则不匹配问题
• 分析导入集运行日志中的数据摄取错误
• 检测由错误协调导致、在 cmdb_inst_duplicate 中创建的重复 CI
• 验证 cmdb_ci_service 和 svc_ci_assoc 中的服务映射数据完整性
• 监控连接器运行状况、计划任务和转换映射准确性

适用场景： Service Graph Connector 无法填充或更新 CI、发现流程产生重复项或缺失关系、服务映射显示的数据不完整或过时，或者连接器集成报告错误时。

价值主张： 快速诊断服务图问题可防止 CMDB 数据质量下降，确保变更和事件管理所用的服务映射准确，并缩短集成故障的 MTTR。

先决条件

• 插件： sn_cmdb_ws（CMDB Workspace）、sn_itom_pattern（Discovery Patterns）、com.snc.service-mapping（Service Mapping）
• 角色： cmdb_admin、itil_admin 或 discovery_admin
• 访问权限： 对 cmdb_ci、cmdb_rel_ci、svc_graph_connector、discovery_status 和导入集表具有读写权限
• 知识要求： 了解 CMDB 识别规则、协调引擎和 Service Graph Connector 架构

操作步骤

第 1 步：检查连接器状态和配置

查询 Service Graph Connector 表以验证连接器运行状况。

使用 MCP（Claude Code/Desktop）：

Tool: SN-Query-Table
Parameters:
  table_name: svc_graph_connector
  query: active=true
  fields: sys_id,name,connector_type,state,last_run,last_run_status,schedule,data_source,error_message,total_records_processed,total_errors
  limit: 25
  order_by: -last_run

使用 REST API：

GET /api/now/table/svc_graph_connector?sysparm_query=active=true^ORDERBYDESClast_run&sysparm_fields=sys_id,name,connector_type,state,last_run,last_run_status,schedule,data_source,error_message,total_records_processed,total_errors&sysparm_limit=25&sysparm_display_value=true

识别故障连接器：

Tool: SN-Query-Table
Parameters:
  table_name: svc_graph_connector
  query: active=true^last_run_status=error^ORlast_run_status=warning
  fields: sys_id,name,connector_type,last_run,last_run_status,error_message,total_errors
  limit: 10

第 2 步：分析导入集运行日志

连接器运行时会创建导入集记录。检查这些记录中的数据摄取错误。

使用 MCP：

Tool: SN-Query-Table
Parameters:
  table_name: sys_import_set_run
  query: set.nameLIKE[connector_name]^ORDERBYDESCsys_created_on
  fields: sys_id,number,set,state,rows_inserted,rows_updated,rows_ignored,rows_error,completion_code,error_message
  limit: 10

使用 REST API：

GET /api/now/table/sys_import_set_run?sysparm_query=set.nameLIKE[connector_name]^ORDERBYDESCsys_created_on&sysparm_fields=sys_id,number,set,state,rows_inserted,rows_updated,rows_ignored,rows_error,completion_code,error_message&sysparm_limit=10&sysparm_display_value=true

深入检查错误行：

Tool: SN-Query-Table
Parameters:
  table_name: sys_import_set_row
  query: sys_import_set=[import_set_sys_id]^sys_import_state=error
  fields: sys_id,sys_import_state,sys_import_state_comment,sys_target_sys_id,sys_row_error
  limit: 25

第 3 步：验证识别和协调规则

检查 CI 识别规则是否能将传入数据正确匹配到现有 CI。

使用 MCP：

Tool: SN-Query-Table
Parameters:
  table_name: cmdb_identifier_entry
  query: active=true^applies_to=[ci_class_name]
  fields: sys_id,name,identifier,applies_to,criterion_attributes,search_on_insert,search_on_update,order
  limit: 20

使用 REST API：

GET /api/now/table/cmdb_identifier_entry?sysparm_query=active=true^applies_to=[ci_class_name]&sysparm_fields=sys_id,name,identifier,applies_to,criterion_attributes,search_on_insert,search_on_update,order&sysparm_limit=20&sysparm_display_value=true

检查协调失败是否生成了重复 CI：

Tool: SN-Query-Table
Parameters:
  table_name: cmdb_inst_duplicate
  query: sys_created_on>=javascript:gs.daysAgoStart(7)
  fields: sys_id,duplicate_of,duplicate_of.name,ci,ci.name,ci.sys_class_name,rule_used,confidence,sys_created_on
  limit: 50
  order_by: -sys_created_on

第 4 步：诊断发现模式问题

验证发现模式是否正在运行并产生预期结果。

使用 MCP：

Tool: SN-Query-Table
Parameters:
  table_name: discovery_status
  query: sys_created_on>=javascript:gs.daysAgoStart(3)^state!=complete
  fields: sys_id,number,dname,state,phase,ip_address,cmdb_ci,error,sys_created_on,discover
  limit: 25
  order_by: -sys_created_on

使用 REST API：

GET /api/now/table/discovery_status?sysparm_query=sys_created_on>=javascript:gs.daysAgoStart(3)^state!=complete&sysparm_fields=sys_id,number,dname,state,phase,ip_address,cmdb_ci,error,sys_created_on,discover&sysparm_limit=25&sysparm_display_value=true

检查模式执行日志：

Tool: SN-Query-Table
Parameters:
  table_name: discovery_log
  query: status=[discovery_status_sys_id]^levelINerror,warning
  fields: sys_id,level,message,source,sys_created_on
  limit: 50
  order_by: -sys_created_on

第 5 步：验证服务映射完整性

确保服务与其支持的 CI 正确映射。

使用 MCP：

Tool: SN-Query-Table
Parameters:
  table_name: cmdb_ci_service
  query: operational_status=1
  fields: sys_id,name,operational_status,business_criticality,owned_by,support_group,used_for,service_status
  limit: 25
  order_by: name

检查服务与 CI 的关联：

Tool: SN-Query-Table
Parameters:
  table_name: svc_ci_assoc
  query: service_id=[service_sys_id]
  fields: sys_id,service_id.name,ci_id,ci_id.name,ci_id.sys_class_name,ci_id.operational_status
  limit: 50

使用 REST API：

GET /api/now/table/svc_ci_assoc?sysparm_query=service_id=[service_sys_id]&sysparm_fields=sys_id,service_id.name,ci_id,ci_id.name,ci_id.sys_class_name,ci_id.operational_status&sysparm_limit=50&sysparm_display_value=true

第 6 步：运行全面运行状况检查

执行后台脚本以生成完整诊断报告。

使用 MCP：

Tool: SN-Execute-Background-Script
Parameters:
  description: Service Graph Connector health check
  script: |
    var report = {
      timestamp: new GlideDateTime().getDisplayValue(),
      connectors: [],
      duplicates_last_7d: 0,
      failed_discoveries_last_3d: 0,
      orphaned_cis: 0,
      services_missing_cis: []
    };

    // Check connector status
    var conn = new GlideRecord('svc_graph_connector');
    conn.addQuery('active', true);
    conn.query();
    while (conn.next()) {
      report.connectors.push({
        name: conn.name.toString(),
        status: conn.last_run_status.toString(),
        last_run: conn.last_run.getDisplayValue(),
        errors: parseInt(conn.total_errors) || 0
      });
    }

    // Count recent duplicates
    var dup = new GlideAggregate('cmdb_inst_duplicate');
    dup.addQuery('sys_created_on', '>=', gs.daysAgoStart(7));
    dup.addAggregate('COUNT');
    dup.query();
    if (dup.next()) report.duplicates_last_7d = parseInt(dup.getAggregate('COUNT'));

    // Count failed discoveries
    var disc = new GlideAggregate('discovery_status');
    disc.addQuery('sys_created_on', '>=', gs.daysAgoStart(3));
    disc.addQuery('state', 'error');
    disc.addAggregate('COUNT');
    disc.query();
    if (disc.next()) report.failed_discoveries_last_3d = parseInt(disc.getAggregate('COUNT'));

    // Find services with no CI associations
    var svc = new GlideRecord('cmdb_ci_service');
    svc.addQuery('operational_status', 1);
    svc.query();
    while (svc.next()) {
      var assoc = new GlideAggregate('svc_ci_assoc');
      assoc.addQuery('service_id', svc.sys_id);
      assoc.addAggregate('COUNT');
      assoc.query();
      if (assoc.next() && parseInt(assoc.getAggregate('COUNT')) === 0) {
        report.services_missing_cis.push(svc.name.toString());
      }
    }

    gs.info(JSON.stringify(report, null, 2));

第 7 步：修复常见问题

根据诊断结果，实施有针对性的修复。

通过重置并重新运行来修复过时的连接器：

Tool: SN-Update-Record
Parameters:
  table_name: svc_graph_connector
  sys_id: [connector_sys_id]
  fields:
    state: ready
    error_message: ""

合并第 3 步中识别出的重复 CI：

Tool: SN-Execute-Background-Script
Parameters:
  description: Merge duplicate CI into canonical record
  script: |
    var canonical = new GlideRecord('cmdb_ci');
    canonical.get('[canonical_sys_id]');

    var duplicate = new GlideRecord('cmdb_ci');
    duplicate.get('[duplicate_sys_id]');

    // Re-point relationships from duplicate to canonical
    var rel = new GlideRecord('cmdb_rel_ci');
    rel.addQuery('parent', duplicate.sys_id);
    rel.query();
    while (rel.next()) {
      rel.parent = canonical.sys_id;
      rel.update();
    }

    rel = new GlideRecord('cmdb_rel_ci');
    rel.addQuery('child', duplicate.sys_id);
    rel.query();
    while (rel.next()) {
      rel.child = canonical.sys_id;
      rel.update();
    }

    duplicate.operational_status = 7; // Retired
    duplicate.update();

    gs.info('Merged ' + duplicate.name + ' into ' + canonical.name);

工具用法

MCP 工具参考

工具	使用场景
SN-Query-Table	查询连接器、导入集、发现状态、重复项和服务
SN-Get-Record	按 sys_id 检索特定连接器或 CI 的详细信息
SN-Natural-Language-Search	通过自然语言描述查找连接器或 CI
SN-Execute-Background-Script	运行运行状况检查和批量修复脚本
SN-Discover-Table-Schema	探索连接器和 CMDB 表架构

REST API 参考

端点	方法	用途
/api/now/table/svc_graph_connector	GET/PATCH	查询并更新连接器配置
/api/now/table/cmdb_ci	GET	搜索受连接器问题影响的 CI
/api/now/table/cmdb_rel_ci	GET	验证连接器中的关系数据
/api/now/table/cmdb_ci_service	GET	验证服务映射完整性
/api/now/table/discovery_status	GET	检查发现运行状态和错误
/api/now/table/sys_import_set_run	GET	分析导入集处理结果
/api/now/table/cmdb_inst_duplicate	GET	查找协调过程中产生的重复 CI

最佳实践

• 每天监控连接器运行情况： 设置定时作业，检查 last_run_status，并在数据过时前针对失败发出警报
• 添加新连接器前检查识别规则： 确保 IRE 规则与连接器数据源提供的数据属性匹配
• 使用小型数据集进行测试： 配置新连接器时，限制初始运行仅处理一小部分记录，以验证转换映射
• 跟踪重复项趋势： cmdb_inst_duplicate 记录突然增加，表明识别规则失效或源数据存在质量问题
• 升级后进行验证： ServiceNow 升级可能会改变协调行为；每次实例升级后都应运行健康检查
• 记录连接器依赖关系： 维护连接器与其提供数据的 CI 类和服务之间的映射
• 分阶段推出： 先在预生产实例中启用新连接器，并比较前后的 CMDB 状态
• 保留审计记录： 在规范 CI 的工作备注中记录合并情况之前，切勿删除重复记录

故障排除

连接器显示“Error”状态

症状： 连接器的 last_run_status 为“error”，且未创建任何新 CI 原因： 身份验证失败、网络超时，或数据源 API 返回错误 解决方案： 检查连接器记录中的 error_message。验证连接别名中的凭据。独立测试数据源 URL。查看 sys_import_set_run 中的详细错误行。

创建了重复 CI

症状： 同一物理资产在 CMDB 中出现多次，且 sys_id 不同 原因： 识别规则的条件属性与传入数据格式不匹配（例如，主机名大小写敏感，或使用 FQDN 而非短名称） 解决方案： 查询 cmdb_inst_duplicate 中的近期条目。检查受影响 CI 类的识别规则。在 IRE 处理前，通过转换映射规范化传入数据。

服务映射显示缺少组件

症状： 业务服务映射不完整；已知的基础设施 CI 未显示 原因： 服务映射模式尚未发现这些 CI，或缺少 svc_ci_assoc 记录 解决方案： 确认发现流程已针对目标 IP 范围运行。检查该服务的 svc_ci_assoc。如果关联记录存在，但 CI 显示 operational_status != 1，则这些 CI 可能已退役或处于非运行状态。

导入集行卡在“Pending”

症状： 导入集中的行处于待处理状态；未创建或更新 CI 原因： 转换映射错误、业务规则冲突，或 IRE 队列积压 解决方案： 检查 sys_import_set_row 中的错误消息。验证转换映射中的字段映射。通过 cmdb_ire_output_queue 检查 IRE 队列大小。

示例

示例 1：诊断 AWS 连接器故障

# 1. Find the AWS connector
Tool: SN-Query-Table
Parameters:
  table_name: svc_graph_connector
  query: nameLIKEAWS
  fields: sys_id,name,state,last_run,last_run_status,error_message,total_errors

# 2. Check the last import set run
Tool: SN-Query-Table
Parameters:
  table_name: sys_import_set_run
  query: set.nameLIKEAWS^ORDERBYDESCsys_created_on
  fields: sys_id,number,state,rows_inserted,rows_updated,rows_error,error_message
  limit: 5

# 3. Look for duplicate EC2 instances
Tool: SN-Query-Table
Parameters:
  table_name: cmdb_inst_duplicate
  query: ci.sys_class_name=cmdb_ci_vm_instance^sys_created_on>=javascript:gs.daysAgoStart(7)
  fields: ci.name,duplicate_of.name,rule_used,confidence,sys_created_on
  limit: 20

示例 2：发现后验证服务映射

# 1. Check discovery status for recent runs
Tool: SN-Query-Table
Parameters:
  table_name: discovery_status
  query: sys_created_on>=javascript:gs.daysAgoStart(1)^dnameLIKE[service_name]
  fields: number,dname,state,phase,cmdb_ci,error
  limit: 10

# 2. Verify service-CI associations
Tool: SN-Query-Table
Parameters:
  table_name: svc_ci_assoc
  query: service_id=[service_sys_id]
  fields: ci_id.name,ci_id.sys_class_name,ci_id.operational_status,ci_id.ip_address
  limit: 50

# 3. Check relationships for completeness
Tool: SN-Query-Table
Parameters:
  table_name: cmdb_rel_ci
  query: parent=[service_sys_id]
  fields: child.name,child.sys_class_name,type.name,type.child_descriptor
  limit: 50

示例 3：健康检查仪表板数据

# Run full health check script (see Step 6) and generate summary:
# - Active connectors: 12 (10 healthy, 2 with errors)
# - Duplicates (7 days): 23 records
# - Failed discoveries (3 days): 5
# - Services without CIs: 3 ("Email Service", "VPN Gateway", "Legacy CRM")

相关技能

• cmdb/cmdb-search-analysis - 搜索和分析 CMDB 数据
• cmdb/relationship-mapping - 创建并验证 CI 关系
• cmdb/data-quality - CMDB 数据的准确性和完整性
• cmdb/ci-discovery - CI 创建和分类
• cmdb/impact-analysis - 使用服务图数据评估影响
• itom/alert-analysis - 根据服务图拓扑关联告警