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 の重複が作成される

症状： 同じ物理アセットが、異なる sys_id で CMDB に複数回登録されます
原因： 識別ルールの基準属性が受信データの形式と一致していません（例：ホスト名の大文字と小文字の区別、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 - アラートをサービスグラフのトポロジと関連付けます