New RelicのNerdGraphでEC2のメタ情報をCSV出力するツールを作った話

記事タイトルとURLをコピーする

みなさんこんにちは。マネージドサービス課の塩野です。

EC2インスタンスの情報を確認したいだけなのに、AWSコンソールにログインして、必要であればOSにもログインして、という作業を繰り返した経験はないでしょうか。プライベートIPやインスタンスID、リージョンといった基本的な情報を数台分まとめて確認したいだけでも、地味に手間がかかりますよね。

New Relicでインフラ監視を行っていると、実はこうしたEC2のメタ情報の多くがすでにNew Relic側に送られています。であれば、AWSやOSに毎回ログインしなくても、New Relicから情報を引っ張ってくれば効率化できるのではと考え、NerdGraph(New RelicのGraphQL API)を使ってEC2の情報をCSVに出力するツールを作ってみました。この記事ではその仕組みと使い方を紹介します。

New Relic NerdGraphとEntity Searchについて

NerdGraphは、New Relicが提供しているGraphQL APIです。ダッシュボードやアラートの管理、キーの発行など、New Relicの操作を幅広くプログラムから行えます。

今回利用したのは、その中のentitySearchという機能です。New Relicでは監視対象のホストやアプリケーションを「エンティティ」として扱っており、domain = 'INFRA' AND type = 'HOST'という条件で検索すると、インフラ監視対象のホストエンティティを取得できます。公式ドキュメントでも、この条件を使ったエンティティ検索の例が紹介されています。

エンティティにはタグという形でさまざまな属性が紐づいており、EC2の場合はaws.ec2.InstanceIdやaws.region、aws.ec2.privateIpAddressといったタグが自動的に付与されます。OSに関する情報(linuxDistributionなど)やNew Relic Agentのバージョン(agentVersion)もタグとして取得可能です。今回作ったツールは、これらのタグをまとめてCSVに書き出す仕組みになっています。

作ったツールの概要

ツールの目的はシンプルで、指定したNew RelicアカウントのEC2ホストについて、アカウント情報・EC2の属性・OS情報・Agentのバージョンを一括でCSVに出力することです。取得している主な項目は次のとおりです。

  • アカウント情報(accountId, accountName, entityName)
  • EC2の属性(aws.ec2.InstanceId, aws.ec2.privateIpAddress, aws.region など)
  • OS情報(linuxDistribution, windowsPlatform, kernelVersion など)
  • New Relic Agentのバージョン(agentVersion) 認証にはUser API keyを使用しています。New RelicにはUser key、License key(Ingest key)などいくつかのキー種別がありますが、License keyはテレメトリデータの送信(Ingest)専用で、NerdGraphのようなデータ取得・操作系のAPIにはUser keyを使う必要があります。この点は公式ドキュメントでも明確に区別されているので、間違えないよう注意が必要です。
entity_query = f"accountId = {account_id} AND domain = 'INFRA' AND type = 'HOST'"

クエリ自体はこのようにシンプルで、あとはレスポンスに含まれるtags配列から必要な項目を取り出してCSVの行として整形しているだけです。検索結果が多い場合はnextCursorが返ってくるので、それがなくなるまでページングを繰り返す形にしています。

作ったツールの実際のコード

#!/usr/bin/env python3
"""Display EC2 instance metadata reported to New Relic."""

import argparse
import csv
import json
import os
import sys
import urllib.error
import urllib.request
from typing import Optional

ENDPOINTS = {
    "US": "https://api.newrelic.com/graphql",
    "EU": "https://api.eu.newrelic.com/graphql",
    "JP": "https://api.jp.newrelic.com/graphql",
}

QUERY = """
query GetEc2Instances($entityQuery: String!, $cursor: String) {
  actor {
        entitySearch(query: $entityQuery) {
            results(cursor: $cursor) {
                entities {
                    name
                    tags {
                        key
                        values
                    }
                    account {
                        id
                        name
                    }
                }
                nextCursor
      }
    }
  }
}
"""

TAG_ALIASES = {
    "agentVersion": ("agentVersion",),
    "aws.accountId": ("aws.accountId",),
    "aws.availabilityZone": ("aws.availabilityZone",),
    "aws.ec2.privateIpAddress": ("aws.ec2.privateIpAddress",),
    "aws.ec2.publicIpAddress": ("aws.ec2.publicIpAddress",),
    "aws.ec2.InstanceId": ("aws.ec2.InstanceId", "aws.ec2.instanceId"),
    "aws.ec2.subnetId": ("aws.ec2.subnetId",),
    "aws.region": ("aws.region",),
    "aws.vpcId": ("aws.vpcId",),
    "aws.ec2VpcId": ("aws.ec2VpcId",),
    "kernelVersion": ("kernelVersion",),
    "fullHostname": ("fullHostname",),
    "tags.Name": ("tags.Name",),
    "label.Name": ("label.Name",),
    "linuxDistribution": ("linuxDistribution",),
    "windowsPlatform": ("windowsPlatform",),
    "windowsFamily": ("windowsFamily",),
    "windowsVersion": ("windowsVersion",),
}

OUTPUT_FIELDS = ("accountId", "accountName", "entityName", *TAG_ALIASES)


def get_config(account_id_option: Optional[str] = None) -> tuple[str, int, str]:
    api_key = os.getenv("NEW_RELIC_API_KEY")
    account_id_text = account_id_option or os.getenv("NEW_RELIC_ACCOUNT_ID")
    region = os.getenv("NEW_RELIC_REGION", "US").upper()

    if not api_key:
        raise ValueError("NEW_RELIC_API_KEY is required")
    if not account_id_text:
        raise ValueError("NEW_RELIC_ACCOUNT_ID is required")
    try:
        account_id = int(account_id_text)
    except ValueError as error:
        raise ValueError("NEW_RELIC_ACCOUNT_ID must be an integer") from error
    if account_id <= 0:
        raise ValueError("NEW_RELIC_ACCOUNT_ID must be positive")
    if region not in ENDPOINTS:
        raise ValueError("NEW_RELIC_REGION must be one of US, EU, or JP")

    return api_key, account_id, region


def normalize_tag_key(key: str) -> str:
    return "".join(character.lower() for character in key if character.isalnum())


def extract_tag(tags: list[dict], aliases: tuple[str, ...]) -> str:
    values_by_key = {
        normalize_tag_key(tag.get("key", "")): tag.get("values", []) for tag in tags
    }
    for alias in aliases:
        values = values_by_key.get(normalize_tag_key(alias), [])
        if values:
            return str(values[0])
    return "-"


def fetch_results(api_key: str, account_id: int, region: str) -> list[dict]:
    entity_query = (
        f"accountId = {account_id} AND domain = 'INFRA' AND type = 'HOST'"
    )
    entities = []
    cursor = None

    while True:
        payload = json.dumps(
            {
                "query": QUERY,
                "variables": {"entityQuery": entity_query, "cursor": cursor},
            }
        ).encode("utf-8")
        request = urllib.request.Request(
            ENDPOINTS[region],
            data=payload,
            headers={"API-Key": api_key, "Content-Type": "application/json"},
            method="POST",
        )

        try:
            with urllib.request.urlopen(request, timeout=30) as response:
                body = json.loads(response.read().decode("utf-8"))
        except urllib.error.HTTPError as error:
            raise RuntimeError(f"New Relic API returned HTTP {error.code}") from error
        except urllib.error.URLError as error:
            raise RuntimeError(f"Could not connect to New Relic: {error.reason}") from error

        if body.get("errors"):
            messages = "; ".join(
                item.get("message", "unknown error") for item in body["errors"]
            )
            raise RuntimeError(f"NerdGraph error: {messages}")

        results = body.get("data", {}).get("actor", {}).get("entitySearch", {}).get("results")
        if not results or not isinstance(results.get("entities"), list):
            raise RuntimeError("The entity search response did not contain results")
        entities.extend(results["entities"])
        cursor = results.get("nextCursor")
        if not cursor:
            break

    return [
        {
            "accountId": str(entity.get("account", {}).get("id", "-")),
            "accountName": str(entity.get("account", {}).get("name", "-")),
            "entityName": str(entity.get("name", "-")),
            **{
                field: extract_tag(entity.get("tags", []), aliases)
                for field, aliases in TAG_ALIASES.items()
            },
        }
        for entity in entities
    ]


def write_csv(results: list[dict], output_path: str) -> None:
    with open(output_path, "w", encoding="utf-8-sig", newline="") as output_file:
        writer = csv.DictWriter(output_file, fieldnames=OUTPUT_FIELDS)
        writer.writeheader()
        writer.writerows(results)


def main() -> int:
    parser = argparse.ArgumentParser()
    parser.add_argument(
        "--account-id",
        help="New Relic account ID (overrides NEW_RELIC_ACCOUNT_ID)",
    )
    parser.add_argument(
        "--output",
        default="ec2_information.csv",
        help="CSV output path (default: ec2_information.csv)",
    )
    args = parser.parse_args()

    try:
        api_key, account_id, region = get_config(args.account_id)
        results = fetch_results(api_key, account_id, region)
        write_csv(results, args.output)
    except (OSError, ValueError, PermissionError, RuntimeError) as error:
        print(f"ERROR: {error}", file=sys.stderr)
        return 1

    print(f"Wrote {len(results)} entities to {args.output}")
    return 0


if __name__ == "__main__":
    raise SystemExit(main())

使い方

使い方も難しくありません。まず環境変数でAPIキーとアカウントID、リージョンを設定します。

export NEW_RELIC_API_KEY='NRAK-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
export NEW_RELIC_ACCOUNT_ID='12345678'
export NEW_RELIC_REGION='US'

リージョンはUS・EU・JPを切り替えられる作りにしており、それぞれapi.newrelic.com、api.eu.newrelic.com、api.jp.newrelic.comのエンドポイントを使い分けます。なお、New Relicの日本データリージョンは本記事執筆時点でプレビュー提供の位置づけで、公式ドキュメントでも一部機能やレガシーAPIが利用できない場合があるとされています。JPリージョンのアカウントで使う場合は、この前提を踏まえておくとよさそうです。設定が済んだら、あとはスクリプトを実行するだけです。

python3 get_ec2_information.py

デフォルトではカレントディレクトリにec2_information.csvが生成されます。出力先やアカウントIDはオプションでも指定できるので、複数アカウントを順番に処理したい場合にも使いやすい構成にしています。

実際に使ってみて

実際に運用しているEC2に対して使ってみると、AWSコンソールやOSへログインする手間がなくなり、複数台の情報をまとめて確認できる点はかなり便利でした。棚卸しや構成確認の作業がぐっと楽になった印象です。

一方で使ってみて気づいた注意点もあります。ひとつは、このツールが取得できるのはあくまでNew Relicにタグとして登録されている情報だけだということです。New Relic Infrastructure Agentが収集・送信していない項目や、そもそも監視対象になっていないホストの情報は当然ながら取得できません。「New Relicで見えている範囲の情報を素早く引ける」ツールであって、AWS APIを直接叩くような網羅性はない、という前提で使う必要があります。

もうひとつは、New RelicのアカウントID(NEW_RELIC_ACCOUNT_ID)とAWSのアカウントID(結果に含まれるaws.accountId)は別物だという点です。似た名前なので混同しやすいのですが、New Relic側の組織アカウントとAWS側のアカウントは当然独立しているので、集計や比較を行う際は取り違えないよう気をつけたいところです。

面白かったのは、今回使ったentitySearchのクエリを変更するだけで、EC2以外のエンティティにも簡単に応用できることです。たとえばdomain = 'INFRA' AND type = 'HOST'の部分を変えれば、Lambda関数やRDSなど、New Relicが監視している他のリソースのメタ情報を同じ仕組みで取得できます。EC2用に作ったツールですが、クエリ部分とタグの対応表を差し替えるだけで、他のリソースの棚卸しツールにも展開できそうです。

まとめ

New RelicのNerdGraphを使うと、AWSコンソールやOSに個別にログインしなくても、監視データとしてすでに送られているEC2のメタ情報をまとめて取得できます。今回作ったツールはEC2に絞った内容でしたが、Entity Searchのクエリを工夫すれば他のリソースにも応用できる汎用性の高い仕組みだと感じました。日々の構成確認や棚卸し作業を効率化したい方には、ぜひ一度試してみてほしいアプローチです。

この記事がどなたかのお役に立てれば幸いです。

◆ 塩野 正人
◆ マネージドサービス部 所属
◆ X(Twitter):@shioccii
◆ 過去記事はこちら

前職ではオンプレミスで仮想化基盤の構築や運用に従事。現在は運用部隊でNew Relicを使ってサービス改善に奮闘中。New Relic User Group運営。