NerdGraphチュートリアル。エンティティデータを見る

New Relic のエンティティとは、テレメトリを生成または含む、当社が監視するあらゆるものを指します。エンティティは、New Relic で追跡したいデータを見つけるのに役立ちます。エンティティと他のエンティティとの関係を理解すれば、データについてさらに多くの洞察を得ることができます。エンティティの例をいくつか示します。

APMで監視するアプリケーション.
クラウドの統合、サービス、ホストは、当社のインフラ監視によって監視されています。

UI で直接エンティティを操作するか ( 「New Relic エンティティについて学ぶ」を参照)、NerdGraph API を介してエンティティを操作する方法について、こちらの手順に従うことができます。NerdGraph の使用を開始する際にサポートが必要な場合は、 New Relic NerdGraph の紹介を参照してください。

重要

エンティティのゴールデンメトリックとタグを操作するには、ゴールデンメトリック API チュートリアルを参照してください。

始める前に

エンティティを操作する前に、「エンティティについて学ぶ」を読むことをお勧めします。

エンティティを操作するときは、次の重要な点に留意してください。

一意の GUID はエンティティ (entity.guid または entityGuid) を識別します。
エンティティは、特定の期間New Relic に存在します。
エンティティは、特定のメトリックやイベントに関するデータを探索したり、他のエンティティに関連するデータを文脈化するための便利なエントリポイントを提供します。

エンティティの検索

New Relic は、エンティティの属性（主に名前）を中心に、エンティティの種類やその他の値で検索します。検索では、検索条件に一致するエンティティの基本データが返されます。そして、基本的な検索結果から、特定のエンティティをGUIDで照会することができます。

domainTypeの他に、他の一般的なエンティティ属性は次のとおりです。

id
accountId
name
domainId
alertSeverity
reporting

上記の属性のいずれかでフィルタリングできます。さらに、タグを使用してフィルタリングすることもできます。

注意

カスタム、ルートレベルのエンティティプロパティではフィルタリングできません。カスタムプロパティは、実際の検索レスポンスにおいて、エンティティのメタデータの一部としてのみ取得されます。カスタムフィールドでフィルタリングするには、そのフィールドをエンティティタグに変換します。

クエリを作成するには、2つの方法があります。

queryBuilder引数を使用して、クエリを作成します。
自由形式のquery引数を使用して、独自の検索を作成します。

NerdGraphを使って1つまたは複数のエンティティを照会するには、属性またはGUIDで検索することができます。

ヒント

NerdGraphでは、1つのクエリで返すことのできるエンティティの総数を200に設定しています。1つのクエリですべてのエンティティを取得する必要がある場合は、例で説明しているようにカーソルページネーションを使用してください。

以下の例に加えて、 NerdGraph エクスプローラーを使用して API を試すことをお勧めします。クエリとミューテーションの作成に役立つインラインドキュメントがあります。

で検索 `queryBuilder`

queryBuilder引数は、単純なクエリを作成するのに役立ちます。これにより、事前定義された属性のリストとその一般的な値からクエリにフィルターを追加できます。より高度なクエリの場合は、代わりにquery引数を使用してください。

NerdGraphにアクセスする GraphiQL explorer.
基本的なクエリを実行して、検索条件に一致するエンティティを見つけます。例えば、以下のようになります。

{
  actor {
    entitySearch(queryBuilder: { domain: APM, type: APPLICATION }) {
      query
      results {
        entities {
          name
          entityType
          guid
        }
      }
    }
  }
}

自由形式で検索 `query`

これは、より複雑なクエリを作成するのに便利です。

NerdGraphにアクセスする GraphiQL explorer.
基本的なクエリを実行して、検索条件に一致するエンティティを見つけます。例えば、以下のようになります。

query($query: String!) {
  actor {
    entitySearch(query: $query) {
      count
      results {
        entities {
          name
          entityType
          guid
        }
      }
    }
  }
}

以下の変数を NerdGraph の Query variables セクションに追加します。
```
{ "query": "name LIKE 'nerd-graph' AND domainType IN ('APM-APPLICATION')" }
```

GUIDによるエンティティの取得

フェッチするエンティティのGUIDがわかっている場合は、 entity属性を使用できます。

{
  actor {
    entity(guid: "ENTITY_GUID") {
      name
      entityType
    }
  }
}

これは、検索クエリとしても書くことができます。

{
  actor {
    entitySearch(query: "id = 'ENTITY_GUID'") {
      query
      results {
        entities {
          name
          entityType
        }
      }
    }
  }
}

または、複数のエンティティを同時にフェッチするには、 entities属性を使用できます。

{
  actor {
    entities(guids: ["ENTITY_GUID_1", "ENTITY_GUID_2"]) {
      name
      entityType
    }
  }
}

それ以外の場合は、検索クエリを使用します。

{
  actor {
    entitySearch(query: "id IN ('ENTITY_GUID_1', 'ENTITY_GUID_2')") {
      query
      results {
        entities {
          name
          entityType
        }
      }
    }
  }
}

クエリの例

クエリとは、データを取得することだけを目的とした（他の効果を持たない）リクエストのことである。NerdGraphのクエリは固定されていないため、必要に応じてデータを増やしたり減らしたりすることができます。各クエリでは、スキーマでサポートされている限り、取得したいデータを正確に指定することができます。

NerdGraph のエンティティは、 GraphQL インターフェースに依存しています。は、オブジェクトが共通のフィールドを共有することを可能にするコンセプトです。インターフェイスは、NerdGraphのクエリ例の多くに見られるように、特定のエンティティタイプのデータを提供するために使用されます。

エンティティ検索クエリの作成をどのように始めたらよいかわからない場合は、NerdGraphを使って構築してみましょう。次に、エンティティデータと、作成したクエリ文字列を取得します。

結果のクエリフィールドをリクエストして、 queryBuilder引数によって作成されたクエリ文字列を確認します。
query }引数とqueryBuilder引数を同時に使用することはできません。

NerdGraph GraphiQL explorer を使ってAPIを探索し、そのインラインドキュメントを使って利用可能なクエリオプションを確認することを強くお勧めします。

{
  actor {
    entitySearch(queryBuilder: { domain: APM, type: APPLICATION }) {
      query
      results {
        entities {
          reporting
          ... on AlertableEntityOutline {
            alertSeverity
          }
        }
      }
    }
  }
}

インフラストラクチャ統合エンティティにはさまざまなタイプがあり、それらは他のエンティティタイプとは別にリストされています。それらを調べるには、入力引数 infrastructureIntegrationType を使用します。

query }引数とqueryBuilder引数を同時に使用することはできません。
type入力引数の代わりにinfrastructureIntegrationTypeを使用してください。

NerdGraph GraphiQL explorer を使ってAPIを探索し、そのインライン・ドキュメントを使って利用可能なクエリ・オプションを確認することを強くお勧めします。

{
  actor {
    entitySearch(queryBuilder: { infrastructureIntegrationType: F5_NODE }) {
      query
      results {
        entities {
          entityType
          domain
        }
      }
    }
  }
}

NewRelicのアラートで監視できるエンティティのアラートの重大度を取得します。このNerdGraphクエリは、現在アプリケーションからデータを受信しているかどうかを示します（ reportingフィールドを使用）。

エンティティが警告可能なタイプである場合、結果にはエンティティの警告の深刻度が含まれます。

結果にアラートのないエンティティが含まれている場合、 AlertableEntityOutlineフィールドは含まれません。

{
  actor {
    entitySearch(query: "name like 'nerdgraph' and alertSeverity is not null") {
      results {
        entities {
          reporting
          ... on AlertableEntityOutline {
            alertSeverity
          }
        }
      }
    }
  }
}

さまざまなエンティティタイプには、特定のデータが関連付けられています。次の NerdGraph クエリの例は、使用可能なフィールドの選択を示しています。アプリケーションエンティティ:

より詳細なサマリーデータは、お問い合わせの際にご請求いただけます。

他のタイプのエンティティが検索結果として返された場合、これらのフィールドは含まれません。

{
  actor {
    entitySearch(
      query: "name like 'nerdgraph' and domainType = 'APM-APPLICATION'"
    ) {
      results {
        entities {
          name
          ... on ApmApplicationEntityOutline {
            apmSummary {
              errorRate
              apdexScore
              webResponseTimeAverage
              responseTimeAverage
            }
          }
        }
      }
    }
  }
}

エンティティの種類によって、特定のデータが関連付けられています。このNerdGraphのクエリ例では、どのエンティティタイプであるかに関わらず、すべてのエンティティの名前と、APM、ブラウザモニタリング、モバイルエンティティのエラーレートを要求しています。

他のタイプのエンティティが検索結果として返された場合、エラーレートフィールドは含まれません。

{
  actor {
    entitySearch(query: "name like 'nerdgraph'") {
      results {
        entities {
          name
          ... on ApmApplicationEntityOutline {
            apmSummary {
              errorRate
            }
          }
          ... on BrowserApplicationEntityOutline {
            browserSummary {
              jsErrorRate
            }
          }
          ... on MobileApplicationEntityOutline {
            mobileSummary {
              httpErrorRate
            }
          }
        }
      }
    }
  }
}

この NerdGraph クエリの例では、検索結果で返されたすべてのエンティティのタグを取得しています。詳細については、 NerdGraph GraphiQL tagging tutorial をご覧ください。

{
  actor {
    entitySearch(query: "name like 'nerdgraph'") {
      results {
        entities {
          name
          tags {
            key
            values
          }
        }
      }
    }
  }
}

このNerdGraphクエリの例では、 INFRAドメインに属し、awsRegion us-east-1に属するエンティティをフィルタリングし、検索結果にその名前を返します。

{
  actor {
    entitySearch(
      query: "domain = 'INFRA' and tags.aws.awsRegion = 'us-east-1'"
    ) {
      results {
        entities {
          name
        }
      }
    }
  }
}

さらに、特定のタグが存在するかどうかによってフィルタリングを実行できます。次のクエリは、domainType BROWSER-APPLICATIONのエンティティをフィルタリングし、タグclusterAgentIdを定義しています。

{
  actor {
    entitySearch(
      query: "domainType = 'BROWSER-APPLICATION' and tags.clusterAgentId is not null"
    ) {
      results {
        entities {
          name
        }
      }
    }
  }
}

詳細については、 NerdGraph GraphiQL tagging tutorial をご覧ください。

このNerdGraphクエリの例では、awsRegion us-east-1に属するdomainType APM-APPLICATIONドメインのエンティティをフィルタリングし、検索結果にその名前を返します。次に、結果を集計して、NewRelicアカウントIDでグループ化されたエンティティの総数を取得します。

{
  actor {
    entitySearch(query: "domainType = 'APM-APPLICATION'") {
      facetedCounts(facets: { facetCriterion: { facet: ACCOUNT_ID } }) {
        counts {
          count
          facet
        }
      }
    }
  }
}

さらに、集計はタグでも実行できます。次のクエリは、awsRegion us-east-1に属する domainType APM-APPLICATIONドメインのエンティティをフィルタリングし、結果を集計して、エージェント言語別にグループ化されたエンティティの総数を取得します。

{
  actor {
    entitySearch(
      query: "domainType = 'APM-APPLICATION' and tags.aws.awsRegion = 'us-east-1'"
    ) {
      facetedCounts(facets: { facetCriterion: { tag: "language" } }) {
        counts {
          count
          facet
        }
      }
    }
  }
}

詳細については、 NerdGraph GraphiQL tagging tutorial をご覧ください。

NerdGraph GraphiQLエクスプローラは、エンティティ検索の結果をページングして表示します。

検索条件で1回の応答でAPI制限の200エンティティを超え、残りの結果を表示したい場合は、最初のリクエストでnextCursorをリクエストし、その値を別のクエリで使用して、結果の次の「ページ」。

これ以上結果がない場合、 nextCursorはnullになります。

{
  actor {
    entitySearch(query: "name like 'nerd-graph'") {
      results {
        nextCursor
        entities {
          name
        }
      }
    }
  }
}

次の検索でnextCursorの値を使用します。

{
  actor {
    entitySearch(query: "name like 'nerd-graph'") {
      results(cursor: "next_cursor_value") {
        nextCursor
        entities {
          name
        }
      }
    }
  }
}

NerdGraph GraphiQLエクスプローラでは、alertable is true|falseでエンティティをフィルタリングし、エンティティがalertableプロパティを持っているかどうかを表示することができます。参照：エンティティ定義

上記の属性のいずれかでフィルタリングすることができます。さらに、タグを使ったフィルタリングも可能です。

Alertableはエンティティタイプの設定なので、結果に存在しないのはそのためです。

{
  actor {
    entitySearch(query: "alertable is TRUE") {
      results {
        entities {
          name
        }
      }
    }
  }
}

クエリの中で他のフィルターと組み合わせることもできます。

{
  actor {
    entitySearch(query: "domain='APM' and alertable is TRUE") {
      results {
        entities {
          name
        }
      }
    }
  }
}

NerdGraph GraphiQLエクスプローラーを使用すると、レポートがtrue|falseおよびlastReportingChangeAt日付フィールドでエンティティーをフィルター処理できます。

過去数時間で報告を停止した（何かが起こった）エンティティを取得できます

{
  actor {
    entitySearch(
      query: "reporting is false and lastReportingChangeAt > 1651708800000"
    ) {
      results {
        entities {
          name
        }
      }
    }
  }
}

エンティティ関係の作成または削除

エンティティは、別のエンティティと関係を持つ場合があります。一部のリレーションシップは New Relic によって自動的に作成されますが、ミューテーションを使用してカスタムリレーションシップを作成または削除することもできます。これを行う方法については以下に説明がありますが、New Relic でのさまざまな関係タイプを理解するのに助けが必要な場合は、エンティティ関係をご覧ください。

追加の関係を手動で作成または削除する前に、次の点に注意してください。

2つのエンティティは、関係タイプごとに1つずつ、複数の関係を持つことができます。
同じ信頼できるアカウントに属している場合、2つのエンティティは関係を保持できます。
各エンティティに対して、最大2000の関係を手動で定義できます。制限に達すると、APIはLIMIT_EXCEEDEDエラーを返します。
2つのエンティティ（ソース/ターゲット）のいずれにもアクセスできない場合、各ミューテーションは失敗する可能性があります。

エンティティの関係を一覧表示する

relatedEntities フィールドを使用して、エンティティのペアがどのように相互作用し、どのように関連しているかを確認できます。これは、サービスマップの使用方法と同様に、アップストリームサービスとダウンストリームサービスのトラブルシューティングを行い、小さな問題が大きな影響を与える可能性があることを理解するのに役立ちます。

次の例は、特定の GUID でエンティティをクエリする方法を示しています。

query {
  actor {
    entity(guid: "ENTITY_GUID") {
      name
      relatedEntities {
        results {
          source {
            entity {
              guid
              name
            }
          }
          target {
            entity {
              guid
              name
            }
          }
          type
        }
      }
    }
  }
}

リレーションシップの作成または置換

ミューテーション entityRelationshipUserDefinedCreateOrReplaceを使用してエンティティ関係を作成または置換します。その名前が示すように、特定のタイプの 2 つのエンティティ間の関係を作成できます。2 つのエンティティ間に関係が既に存在する場合は、更新された特定の値 (作成時間と作成者のユーザー ID) で再度追加されます。

mutation {
  entityRelationshipUserDefinedCreateOrReplace(
    sourceEntityGuid: "SOURCE_ENTITY_GUID"
    targetEntityGuid: "TARGET_ENTITY_GUID"
    type: BUILT_FROM
  ) {
    errors {
      message
      type
    }
  }
}

関係を削除する

ミューテーション entityRelationshipUserDefinedDeleteを使用してエンティティ関係を削除します。ソースとターゲットは必須ですが、タイプは必須ではありません。タイプなしでミューテーションを実行すると、2 つのエンティティ間のすべての関係が削除されます。

mutation {
  entityRelationshipUserDefinedDelete(
    sourceEntityGuid: "SOURCE_ENTITY_GUID"
    targetEntityGuid: "TARGET_ENTITY_GUID"
    type: BUILT_FROM
  ) {
    errors {
      message
      type
    }
  }
}

エンティティの削除

NerdGraph API を使用して、アカウント内のエンティティを手動で削除することができます。そのためには、 NerdGraph GraphiQL explorer で、エンティティのGUIDを使ってこのクエリを実行してください。

mutation {
  entityDelete(guids: ["ENTITY_GUID_1", "ENTITY_GUID_2"]) {
    deletedEntities
    failures
  }
}

重要

現在、Nerdgraph APIを使用して削除できるのは、 APM-APPLICATION 、 EXT-SERVICE 、およびREF-REPOSITORYのエンティティタイプのみです。

削除されたエンティティがNew Relicエージェントによって再びインデックスされると、UIに表示されることがあります。

この機械翻訳は参考用に提供されます。

NerdGraphチュートリアル。エンティティデータを見る

重要

始める前に

エンティティの検索

注意

ヒント

で検索 `queryBuilder`

自由形式で検索 `query`

GUIDによるエンティティの取得

クエリの例

queryBuilderによるエンティティデータの取得

検索結果でインフラ統合エンティティのデータを取得

アラート可能なエンティティのアラート情報を検索結果に表示する

検索結果にAPMエンティティのサマリーデータを表示する

エンティティタイプごとのデータを検索結果に表示

検索結果の各エンティティのすべてのタグを取得

タグを使ってエンティティの結果をフィルタリング

属性やタグで結果を集約する

ページ分割された検索結果のnextCursorを取得する

警告可能なエンティティの取得

1日以上前にレポートを停止したエンティティを取得する

エンティティ関係の作成または削除

エンティティの関係を一覧表示する

リレーションシップの作成または置換

関係を削除する

エンティティの削除

重要

この機械翻訳は参考用に提供されます。

NerdGraphチュートリアル。エンティティデータを見る

重要

始める前に

エンティティの検索

注意

ヒント

で検索 queryBuilder

自由形式で検索 query

GUIDによるエンティティの取得

クエリの例

検索結果でインフラ統合エンティティのデータを取得

アラート可能なエンティティのアラート情報を検索結果に表示する

検索結果にAPMエンティティのサマリーデータを表示する

エンティティタイプごとのデータを検索結果に表示

検索結果の各エンティティのすべてのタグを取得

タグを使ってエンティティの結果をフィルタリング

属性やタグで結果を集約する

ページ分割された検索結果のnextCursorを取得する

警告可能なエンティティの取得

1日以上前にレポートを停止したエンティティを取得する

エンティティ関係の作成または削除

エンティティの関係を一覧表示する

リレーションシップの作成または置換

関係を削除する

エンティティの削除

重要

で検索 `queryBuilder`

自由形式で検索 `query`