New Relic を利用していて、こんな状況になったことはないでしょうか。
「全アカウントのダッシュボードをまとめて管理したいけど、UI で確認するのは限界を感じる」
「使われていないダッシュボードを一括で棚卸ししたい」
New Relic が公式で提供している機能でご要望を満たせなくなってきた場合、自動化により業務を効率化するチャンスかもしれません。New Relic では、お客様が New Relic データにクエリを実行するための Web API として、NerdGraph API をご提供しています。NerdGraph API を利用することで、New Relic に関する処理を自動化することが可能になります。本ブログでは、New Relic の NerdGraph API を用いて New Relic プラットフォーム上のエンティティを取得する手順に関して解説します。まずは、誰もが一度は触れるであろう『ダッシュボードの一覧取得』を例に、その基本をマスターしましょう。
NerdGraph API とは
New Relic NerdGraph API は、New Relic のプラットフォーム全体にわたるデータを照会および操作するための GraphQL API です。NerdGraph API を利用することで、スクリプトやアプリケーションから、New Relic プラットフォーム上の様々なデータにアクセスしたり、設定を変更したりすることが可能です。NerdGraph API を利用することで、必要な情報のみをプログラマブルに New Relic プラットフォームから取得できるため、New Relic 上での処理を自動化する際には必要不可欠なツールです。
NerdGraph API は、GraphQL API の柔軟性を活用しています。GraphQL API では、データを取得する際に、サーバがレスポンスに含めるデータのフィールドをクライアントがリクエスト内のクエリで指定します。これにより、サーバはクライアントが必要とする属性のみをレスポンスに含めることができます。結果として、必要以上のフィールドを取得してしまうオーバーフェッチングを防ぎ、API 呼び出しを最適化できます。NerdGraph API では、entitySearch などのクエリを利用することにより、New Relic アカウント内のエンティティを検索し、その属性や関連情報を一括で取得することができるようになります。
エンティティとは
New Relic プラットフォームに保存されているログやメトリクスなどのデータは、エンティティに関連付けて保存されています。New Relic プラットフォームにおけるエンティティは幅広い意味を持ち、アプリケーション、ホスト、ダッシュボード、アラートなど、New Relic にデータを送る、あるいは New Relic 上で作成されるあらゆるものを「エンティティ」と呼びます。各エンティティには一意の識別子(GUID)が付与されており、この GUID を用いて個別のエンティティの詳細情報の取得や、操作を実行できます。
NerdGraph API を利用したエンティティの検索(entitySearch)
NerdGraph API の entitySearch は、New Relic プラットフォーム上の様々なエンティティを検索するための強力なツールです。entitySearch を使用することで、指定した条件に一致するエンティティを柔軟に一覧することができます。たとえば、「特定のタグを持つエンティティ」「特定のタイプのエンティティ（例：APM や HOST）」または「特定の名前のエンティティ」といった条件を指定して検索することが可能です。大量のエンティティをプログラムで効率的に管理したり、特定のエンティティの情報を取得して独自のレポートを作成したりする際には entitySearch API をご活用いただけます。
entitySearch は、検索結果が多数にわたる場合に備え、ページネーションの機能を提供しています。ページネーションにより、一度にすべての結果を取得するのではなく、ページと呼ばれる小さな単位で少しずつ分割して結果を取得することができ、APIのパフォーマンスと効率を向上させます。例えば、entitySearch のような一覧(List) API の呼び出しを行う際に何らかのエラーが発生した場合を想定します。ページネーションの機能がない場合には、たとえエラーが発生したのがリストの後半を取得している際であったとしても、「リストのどこまでを取得したか」を示す情報を API サーバとクライアントの間で共有していないため、リトライを実行する際に再度リストの先頭から結果を取得し直す必要があります。ページネーション API では、次に取得するページを示す「カーソル」と呼ばれる目印になる情報を API サーバとクライアントの間で共有しているため、リトライを行う際にも取得に失敗したページから API 呼び出しを実行することができます。
実践 - NerdGraph API を利用してダッシュボードの一覧を取得してみよう
それでは、実際に entitySearch を利用してみましょう。今回の例では、ダッシュボードの一覧を取得することを想定します。また、ダッシュボードエンティティのフィールドとしては、名前(name) とパーマリンク(permalink) を取得します。
NerdGraph API をお試しいただくには、NerdGraph API explorer をご利用いただくのが簡易です。
NerdGraph API explorer tutorial
ダッシュボードエンティティを取得するクエリの例としては、以下のようなクエリとなります。{ actor { entitySearch(queryBuilder: { type: DASHBOARD # entitySearch で取得されるエンティティのタイプ(DASHBOARD)を指定 }) { results { nextCursor # 次ページのカーソルをレスポンスに含めるように要求 entities { # エンティティに関する情報(name, permalink)をレスポンスに含めるように要求 name permalink } } } }}
entitySearch は、引数として query 変数をとります。今回は queryBuilder 引数を指定し、type として DASHBOARD を指定するクエリを作成しています。これにより、直接 query 引数を記述することなく、ダッシュボードタイプのエンティティを検索することができます。また、results 内では、取得対象として nextCursor と entities を指定します。nextCursor を指定することにより、レスポンスされたエンティティ数が単一ページに収まらなかった場合のカーソル情報を要求します。
上記のクエリを New Relic に送信した際に得られる結果の例としては以下になります。
{ "actor": { "entitySearch": { "results": { "entities": [ { "name": "dashboard000", "permalink": "https://one.newrelic.com/redirect/entity/XXXXX" },
...
], "nextCursor": "sampleNextCursor" # nextCursor に次ページのカーソル情報が含まれる } } }}
上記のレスポンスデータには、リクエスト内で要求した "nextCursor" というフィールドが含まれていることがお分かりいただけるかと思います。後続のページが存在しない場合には、nextCursor の値は null となり、存在する場合には null 以外の値となります。
上記のレスポンスで得られた nextCursor の値を用いて再度 entitySearch を実行すると、先ほどのクエリで取得した一覧の続きから再度一覧を取得できます。その際のクエリの例は以下のようになります。
{ actor { entitySearch(queryBuilder: { type: DASHBOARD }) { results(cursor: "sampleNextCursor") { # results の cursor 引数により、次に取得するページのカーソルを指定 nextCursor entities { name permalink } } } }}
最初のクエリとの差分は、results の cursor 引数に、レスポンスで得られた nextCursor の値を指定しているところです。この変更により、カーソルで指定された箇所からリスト取得を再開することが可能になります。上記のような処理を nextCursor の値が「null」になるまで繰り返します。nextCursor が null になった場合には、取得可能なダッシュボードを全て取得できたとご判断いただけます。
自動化にあたっての考慮点
前章では手動で entitySearch を実行していただきましたが、手順を自動化するにあたっていくつか注意点があります。本章では、自動化手順を実装する際にご注意いただきたい点を3点示します。
(1) HTTP クライアントのセットアップ
前章での例では、NerdGraph API explorer をご利用いただいた方が多いかと思います。実際にアプリケーションを構築していただく際には、NerdGraph API のサービスエンドポイントに接続するための、HTTP クライアントをセットアップしていただく必要があります。詳細については、以下のドキュメントをご参照ください。
(2) エラーハンドリングとリトライ
前述の通り、ページネーション API のメリットの一つとして、エラー発生時の影響が小さい点が挙げられます。ページネーション API のメリットを最大限活かすためにも、エラー発生時のリトライのメカニズムを導入していただくことをお勧めします。リトライのシナリオとして代表的な状況は、以下のような状況です。
- リクエストレートリミット(スロットリングエラー)の発生 (HTTP ステータスコード 429 等)
- HTTP ステータスコード 500 番台の一時的なサーバエラーの発生
- DNS 名前解決エラーや接続タイムアウトエラーなど、ネットワークレベルでの一時的なエラーの発生
リトライロジックは、ライブラリを用いていただくことも、自前で実装していただくことも可能です。自前でリトライロジックを実装される場合には、Exponential Backoff アルゴリズムを用いたリトライが一般的です。
(3) 初回リクエスト時のカーソル指定
前章で手動で体験していただいた手順では、初回リクエストのみ results に cursor 変数を指定せず、カーソルを入手した2回目以降のリクエストで cursor 変数を指定していました。初回リクエスト時のカーソル指定方法には、主に以下2つのアプローチがあります。
アプローチ1: 初回リクエストではクエリ内でカーソルを渡さない
リクエスト中でのカーソルの指定方法については、最初のリクエストでは cursor 変数を指定せず、カーソルを得た2回目以降のリクエストで cursor 変数を指定していただく手順がより標準的なアプローチです。このような処理を実装する場合には、文字列処理を行うことも可能ですが、各言語の GraphQL ライブラリを用いてクエリを構築することもできます。「アプリケーションにどの程度の柔軟性を求めるか」など、要件に合わせて実装方針を立てていただけますと幸いです。
利用可能なライブラリが限られた環境等で、クエリ構築に文字列処理を行う場合でも、カーソル情報をまだ取得していない初回リクエスト時の results の引数に対応することは可能です。たとえば、Python の場合、以下のような文字列フォーマットを作成します。
query = """{{... results{} {{ # この行がフォーマットの対象... }}...}}"""
results の後の部分を、引数を受け付けるための丸括弧も含めて全てフォーマット対象としている点にご注意ください。上記の query 変数を、以下の条件でフォーマットします。
- (nextCursor をまだ取得していない初期状態) 空文字列でフォーマットを行う
- (nextCursor を取得した後) 「f'(cursor: "{next_cursor}")'」のような、引数のフォーマットに従ってカーソルを埋めた文字列でフォーマットを行う。
これにより、nextCursor が取得されていない場合には、当該の行は「results {」のようなクエリとなり、nextCursor が存在する場合には「results(cursor: "sampleNextCursor")」のようなクエリを構築することができます。
アプローチ2: 初回リクエストでは cursor 変数に null を渡す
初回リクエスト時の cursor 変数の指定方法については、別の選択肢が確認されています。以下はあくまで 2025/09 時点での動作となり、将来的に動作に変更が生じる可能性がある点にご注意ください。2025/09 時点での entitySearch API の動作上、API エンドポイントに投入されるクエリ文字列内で cursor 変数に null を指定することが許容されます。
例えば、以下のようなクエリは有効です。
{ actor { entitySearch(queryBuilder: { type: DASHBOARD }) { results(cursor: null) { # cursor に null を指定 nextCursor entities { name permalink } } } }}
あくまで現時点での動作とはなりますが、上記のように1回目の entitySearch のクエリでも cursor 変数に null を指定することで、クエリ内でのカーソル指定の処理を単純化することが可能です。
まとめ
本記事では、NerdGraph API の entitySearch を使って、New Relic 上のエンティティ（特にダッシュボード）を効率的に取得する方法を解説しました。
特に、大量のエンティティを扱う際には、ページネーションとカーソルの概念が非常に重要になります。ぜひ、本記事で学んだ知識を活かして、New Relic の運用を自動化・効率化していただけますと幸いです。
API 処理に習熟するためには、まずはご自身の環境で試してみることが一番の近道です。NerdGraph API Explorer を使って、さまざまなエンティティ検索クエリを試してみてはいかがでしょうか。
本ブログに掲載されている見解は著者に所属するものであり、必ずしも New Relic 株式会社の公式見解であるわけではありません。また、本ブログには、外部サイトにアクセスするリンクが含まれる場合があります。それらリンク先の内容について、New Relic がいかなる保証も提供することはありません。
