NerdGraphチュートリアル。エンティティのゴールデンメトリクスの表示と設定

ゴールデンメトリクス と ゴールデンタグ は、エンティティについての情報のうち、そのエンティティにとって最も重要と思われるビットです。この情報を使って、New Relic 全体でエンティティの簡単な概要を表示しています。ゴールデンメトリクスとタグの標準的な定義は、この公開リポジトリで確認、貢献することができます。

このドキュメントでは、 NerdGraph を使用して、エンティティのカスタムメトリクスを照会する方法を説明します。

ヒント

NerdGraph APIを使用してエンティティを照会する方法の詳細については、 our tutorial を参照してください。

ゴールデンメトリクスの取得

特定のGUIDまたはGUIDのリストに対するゴールデンメトリクスを取得する場合、提供されるクエリはすでにフィルタリングされています。得られたクエリは、そのままクエリビルダーで実行できます。結果のメトリックは、 タイムスケール または単一の値のいずれかになります。

以下は、GUID のAWS DynamoDBテーブルエンティティに対する1つのゴールデンメトリッククエリの例です。 ExampleGUID.

SELECT average(provider.getSuccessfulRequestLatency.Average)
FROM DatastoreSample
WHERE entityGuid IN ('ExampleGUID') AND provider='DynamoDbTable'
TIMESERIES

NerdGraphを使って、特定のエンティティのゴールデンメトリクスを照会することができます（例）。

{
  actor {
    entity(guid: "ENTITY-GUID") {
      goldenMetrics {
        metrics {
          query
          title
        }
      }
    }
  }
}

ゴールデンタグの取得

ゴールデンタグは、 GUID や entityType でリクエストしても、常に同じように表現されます。エンティティについて最も重要と考えられるタグキーのリストを常に受け取ることができます。

{
  actor {
    entity(guid: "ENTITY-GUID") {
      goldenTags {
        tags {
          key
        }
      }
    }
  }
}

ゴールデンメトリクスとゴールデンタグのカスタマイズ

環境の特性に応じてゴールデンメトリクスやゴールデンタグを変更したい場合は、アカウントまたはワークロードの2つの異なるコンテキストで上書きすることができます。

アカウント全体で特定のエンティティタイプのゴールデンメトリクスやゴールデンタグを上書きする

この場合、新しいゴールデンメトリクスまたは新しいゴールデンタグがすべてのNew Relic Oneで適用され、指定したエンティティタイプのデフォルトとして新しいメトリクスやタグが変換されます。

そのためには、NerdGraphのミューテーションを使って、特定のエンティティのゴールデンメトリクスをオーバーライドすることができます。

mutation {
  entityGoldenMetricsOverride(
    context: {account: ACCOUNT_TO_OVERRIDE_GOLDEN METRICS},
    domainType: {domain: DOMAIN, type: TYPE},
    metrics: [
      {eventId: EVENT_ID,
      select: NRDB_QUERY_SELECT,  
      from: NRDB_QUERY_EVENT,
      where: NRDB_QUERY_WHERE,
      title: TITLE_OF_THE_METRIC,
      facet: FACET, 
      name: NAME_OF_THE_METRIC},
      ...]) {
    errors {
      message
      type
    }
    metrics {
      context {
        account
        guid
      }
      domainType {
        domain
        type
      }
      metrics {
        definition {
          eventId
          facet
          from
          select
          where
        }
        name
        query
        title
      }
    }
  }
}

どこで？

domainType: オーバーライドするメトリクスのエンティティタイプ。
コンテキスト: ゴールデンメトリクスを取得するためのコンテキストです。この場合、オーバーライドしたいアカウントを設定する必要があります。
metrics: 新しいNRDBクエリがゴールデンメトリクスとして表示されます。
- eventId: メトリックのエンティティをフィルタリングするために使用されるフィールドです。エンティティ GUID がイベントでどのように定義されているか。
- select: NRDB クエリの SELECT 節です。このフィールドは必須。
- from: NRDB クエリの FROM 節です。
- where: エンティティタイプフィールドを特定するための補完的なwhere句。
- facet: FACET へのフィールドです。
- title: ゴールデン・メトリックのタイトル。このフィールドはオプションです。
- 名前: ゴールデン・メトリックの名前。このフィールドは 必須です.

mutation {
  entityGoldenMetricsOverride(
    context: {account: ACCOUNT_ID},
    domainType: {domain: "APM", type: "APPLICATION"},
    metrics: [
      {eventId: "entity.guid", from: "Transaction", name: "cpuUsage", select: "max(cpuUsage)", title: "CPU Usage"},
      {eventId: "guid", from: "Metric", where: "metricTimesliceName in ('HttpDispatcher', 'OtherTransaction/all')", facet: "appName", select: "count(newrelic.timeslice.value)", name: "throughput", title: "Throughput"}]) {
    errors {
      message
      type
    }
    metrics {
      context {
        account
        guid
      }
      domainType {
        domain
        type
      }
      metrics {
        definition {
          eventId
          facet
          from
          select
          where
        }
        name
        query
        title
      }
    }
  }
}

メトリクス入力オブジェクトは、NRDBクエリのパーツをセクションに分けて定義しています。これらのセクションの1つは eventId, で、これはゴールデン・メトリックとして使用したい NRDB Event 内部の GUID を定義するフィールドを特定するために使用されます。例えば、以下のようになります。

SELECT average(provider.getSuccessfulRequestLatency.Average)
FROM DatastoreSample
WHERE entityGuid IN ('EntityGuid') AND
      provider='DynamoDbTable'
FACET entityName TIMESERIES

それは次のように定義されています。

{
    eventId: "entityGuid",
    from: "DatastoreSample",
    where: "provider='DynamoDbTable'",
    facet: "entityName",
    select: "average(provider.getSuccessfulRequestLatency.Average)",
    name: GetItem latency (ms),
    title: GetItem latency (ms)
}

結果のオブジェクトを見るとわかるように、 where 節には provider フィールドのみが含まれています。システムは、デフォルトで eventId フィールドを持つ where 節を追加します。

このNerdGraphの突然変異を利用して、ゴールデンタグにも同じことができます。

mutation {
  entityGoldenTagsOverride(
    context: {account: ACCOUNT_ID},
    domainType: {domain: "APM", type: "APPLICATION"},
    tags: [{key: "applicationName"} , {key: "environment"} ]) {
    errors {
      message
      type
    }
    tags {
      context {
        account
      }
      domainType {
        domain
        type
      }
      tags {
        key
      }
    }
  }
}

ワークロード内の特定のエンティティタイプからのゴールデンメトリクスの上書き

New Relic のワークロードでは、エンティティのグループに関するヘルスとパフォーマンスのデータを集約して表示します。ワークロード内の各エンティティタイプについて表示される時系列チャートは、ワークロードアカウントのゴールデンメトリクスによって定義されます。

特定のワークロードにおける特定のエンティティタイプについて、どの時系列を表示するかをさらにカスタマイズしたい場合は、以下の変異でアカウントのゴールデンメトリクスを上書きします。

mutation {
  entityGoldenMetricsOverride(
    context: {guid: WORKLOAD_TO_OVERRIDE_GOLDEN METRICS},
    domainType: {domain: DOMAIN, type: TYPE},
    metrics: [
      {eventId: EVENT_ID,
      select: NRDB_QUERY_SELECT,  
      from: NRDB_QUERY_EVENT,
      where: NRDB_QUERY_WHERE,
      title: TITLE_OF_THE_METRIC,
      facet: FACET, 
      name: NAME_OF_THE_METRIC},
      ...]) {
    errors {
      message
      type
    }
    metrics {
      context {
        account
        guid
      }
      domainType {
        domain
        type
      }
      metrics {
        definition {
          eventId
          facet
          from
          select
          where
        }
        name
        query
        title
      }
    }
  }
}

各フィールドの詳細については上記を参照。この場合、 コンテキスト がワークロードのGUIDとなります。

mutation {
  entityGoldenMetricsOverride(
    context: {guid: WORKLOAD_ENTITY_GUID},
    domainType: {domain: "APM", type: "APPLICATION"},
    metrics: [
       {eventId: "entity.guid", from: "Transaction", name: "cpuUsage", select: "max(cpuUsage)", title: "CPU Usage"},
       {eventId: "guid", from: "Metric", where: "metricTimesliceName in ('HttpDispatcher', 'OtherTransaction/all')", facet: "appName", select: "count(newrelic.timeslice.value)", name: "throughput", title: "Throughput"}]) {
    errors {
      message
      type
    }
    metrics {
      context {
        account
        guid
      }
      domainType {
        domain
        type
      }
      metrics {
        definition {
          eventId
          facet
          from
          select
          where
        }
        name
        query
        title
      }
    }
  }
}

カスタムゴールデンメトリクスとゴールデンタグの取得

前のセクションで定義したクエリは、常にデフォルトのゴールデン・メトリクスとゴールデン・タグを返します。カスタムのゴールデンメトリクスやゴールデンタグを取得したい場合は、例えば、クエリで定義したコンテキストを送信する必要があります。

{
  actor {
    entity(guid: INFRA-AWSDYNAMODBTABLE-GUID) {
      goldenMetrics(
        context: {account: ACCOUNT_ID,
        guid: WORKLOAD_ENTITY_GUID}) {
        metrics {
          title
          query
          name
        }
      }
    }
  }
}

金色のタグに

{
  actor {
    entity(guid: INFRA-AWSDYNAMODBTABLE-GUID) {
      goldenTags(context: {account: ACCOUNT_ID, guid: WORKLOAD_ENTITY_GUID}) {
        tags {
          key
        }
      }
    }
  }
}

メトリクスやタグがワークロード内のコンテキストを持っている場合は、両方のコンテキストを同時に送信して問い合わせを行うことができます。APIは、リクエストで定義したコンテキストに基づいて、最も具体的なゴールデンメトリックまたはゴールデンタグを返します。優先順位は、ワークロードとアカウントです。

カスタムメトリクスとゴールデンタグのリセット

カスタマイズしたゴールデンメトリクスが自分にとって意味のないものになった場合、New Relic が定義したデフォルト値に戻すことができます。コンテキストパラメーターに、目的のアカウントまたはワークロードの guid を設定します (guid パラメーター内)。

アカウントのゴールデンメトリクスを復元するには、次のクエリを実行します。

mutation {
  entityGoldenMetricsReset(
    context: {guid: ACCOUNT_TO_OVERRIDE_GOLDEN_METRICS},
    domainType: {domain: DOMAIN, type: TYPE}) {
    errors {
      message
      type
    }
    metrics {
      context {
        account
        guid
      }
      domainType {
        domain
        type
      }
      metrics {
        definition {
          eventId
          facet
          from
          select
          where
        }
        name
        query
        title
      }
    }
  }
}

どこで？

domainType: オーバーライドするメトリクスのエンティティタイプ。
context: ゴールデンメトリクスを取得するためのコンテキストです。この場合、リセットしたいアカウントを設定する必要があります。

ワークロードのゴールデンメトリクスを復元するには、次のクエリを実行します。

mutation {
  entityGoldenMetricsReset(
    context: {guid: GUID_TO_OVERRIDE_GOLDEN_METRICS},
    domainType: {domain: DOMAIN, type: TYPE}) {
    errors {
      message
      type
    }
    metrics {
      context {
        account
        guid
      }
      domainType {
        domain
        type
      }
      metrics {
        definition {
          eventId
          facet
          from
          select
          where
        }
        name
        query
        title
      }
    }
  }
}

カスタムゴールデンタグにも同様のことができます。

mutation {
  entityGoldenTagsReset(
    context: {guid: WORKLOAD_ENTITY_GUID},
    domainType: {domain: "APM", type: "APPLICATION"}) {
    errors {
      message
      type
    }
    tags {
      context {
        account
        guid
      }
      domainType {
        domain
        type
      }
      tags {
        key
      }
    }
  }
}

想定されたエラー

これらの変異はすべて、操作の結果またはエラーのリストで答えることができます。

これらはすべて、あなたが受け取ることのできる予想されるエラーです。

INVALID_CONTEXT: コンテキストが有効ではありません。コンテキストは、アカウントまたはワークロードのGUIDのいずれか1つのみです。両方を使用したり、他の概念を使用したり、ワークロードに属さないGUIDを使用すると、このエラーが発生します。
INVALID_DOMAIN_TYPE: ドメインタイプが有効ではありません。
LIMIT_EXCEEDED: メトリクスの最大量は9です。この制限を超えると、このエラーが発生します。
NOT_AUTHORIZED: ユーザーはこのアクションを実行する権限を持っていません。

本書は、お客様のご参考のために原文の英語版を機械翻訳したものです。