NerdGraphチュートリアルNRQLコンディションアラート

アラート条件は、GraphQL NerdGraph APIを使って管理できます。ここでは、 NerdGraph API エクスプローラーで開発できる条件クエリとミューテーションをご紹介します。

ヒント

NerdGraph API explorerの使用方法については、 NerdGraph introduction を参照してください。

本ドキュメントでは、以下の内容をカバーしています。

NRQLの条件を作成する手順
NRQLの静的条件
NRQLベースライン条件
条件の更新
変異点の更新
NRQL条件のリストアップとフィルタリング
単数形のNRQL条件検索
説明を作成する
条件の削除

NRQLの条件を作成する手順

以下の手順に従ってください。

作成する条件タイプを決定します（ NRQL 条件しきい値タイプを参照）。
以下のいずれかの方法で、関連する policyID を見つけてください。
- NerdGraphポリシーAPIを使用する.
- one.newrelic.com にアクセスし、トップナビで Alerts& AI をクリックし、次に Policies をクリックします。ポリシーを選択します。ポリシー名の下に ID があります。
NRQL の条件タイプに適したミューテーションと関連する値を提供してください。

ヒント

NerdGraph GraphiQLエクスプローラは、NerdGraph NRQL Conditions APIのフィールドごとの仕様に関する最新のドキュメントを探すのに最適な場所です。たとえば、"What does the valueFunction field accept?" のような質問には、インラインのNerdGraphドキュメントで答えるのが一番です。

NRQLの静的条件

ここでは、静的な条件を作成する例を紹介します。

mutation {
  alertsNrqlConditionStaticCreate(accountId: YOUR_ACCOUNT_ID, policyId: YOUR_POLICY_ID, condition: {
    name: "Low Host Count - Catastrophic"
    enabled: true
    nrql: {
      query: "SELECT uniqueCount(host) FROM Transaction WHERE appName='my-app-name'"
    }
    signal: {
      aggregationWindow: 60
      aggregationMethod: EVENT_FLOW
      aggregationDelay: 120
    }
    terms: {
      threshold: 2
      thresholdOccurrences: AT_LEAST_ONCE
      thresholdDuration: 600
      operator: BELOW
      priority: CRITICAL
    }
    valueFunction: SINGLE_VALUE
    violationTimeLimitSeconds: 86400
  }) {
    id
    name
  }
}

NRQLベースライン条件

ここでは、ベースラインの状態を作成する例を紹介します。

mutation {
  alertsNrqlConditionBaselineCreate(accountId: YOUR_ACCOUNT_ID, policyId: YOUR_POLICY_ID, condition: {
    name: "Baseline Condition"
    enabled: true
    baselineDirection: UPPER_ONLY
    nrql: {
      query: "SELECT average(duration) FROM Transaction"
    }
    signal: {
      aggregationWindow: 60
      aggregationMethod: EVENT_FLOW
      aggregationDelay: 120
    }
    terms: {
      threshold: 13
      thresholdDuration: 180
      thresholdOccurrences: ALL
      operator: ABOVE
      priority: CRITICAL
    }
    violationTimeLimitSeconds: 86400
  }) {
    id
    name
    baselineDirection
  }
}

条件の更新

次の項目を完了します。

次のような nrqlConditionsSearch クエリで type フィールドを要求して、既存の条件のタイプを決定します。
```
{
  actor {
    account(id: YOUR_ACCOUNT_ID) {
      alerts {
        nrqlConditionsSearch {
          nrqlConditions {
            id
            type
          }
        }
      }
    }
  }
}
```
ヒント
返された 型 は、更新変異に使用するものです。たとえば、返されたタイプが STATIC の場合、 alertsNrqlConditionStaticUpdate を使用します。返されたタイプが BASELINE の場合、 alertsNrqlConditionBaselineUpdate を使用します。
条件の id を、関連する条件タイプのミューテーションに提供してください。なお、更新できるのは、関連するタイプの条件のみです。

更新したいフィールドの更新変異のみを提供します。アップデートに提供していないフィールドはタッチされません。

変異点の更新

アップデートで提供したフィールドのみが変更されます。次の例では、 baselineDirection は変更されずに戻りますが、 name は更新されます。

mutation {
  alertsNrqlConditionBaselineUpdate(id: YOUR_CONDITION_ID, accountId: YOUR_ACCOUNT_ID, condition: {
    name: "Your updated name"
  }) {
    id
    name
    baselineDirection
  }
}

NRQL条件のリストアップとフィルタリング

NRQL の条件をリストアップしたりフィルタリングしたりするには、NerdGraph の nrqlConditionsSearch クエリをご利用ください。

NRQL条件の基本的なリスト機能では、NRQL条件をページングしたり、アカウントごとの条件の合計数を要求したりすることができます。

nrqlConditionsSearch クエリは、リソースをページングするためにカーソルページングを利用しています。カーソル・ページネーションの考え方は、クライアントがプログラム・ループでカーソルを要求し、カーソルが空になるまで繰り返すというものです。

初期のリスト対応は以下のようになります。

{
  actor {
    account(id: YOUR_ACCOUNT_ID) {
      alerts {
        nrqlConditionsSearch {
          nextCursor
          nrqlConditions {
            id
            name
            type
          }
          totalCount
        }
      }
    }
  }
}

この例では、次のようなJSONレスポンスを返します。

{
  "data": {
    "actor": {
      "account": {
        "alerts": {
          "nrqlConditionsSearch": {
          "nextCursor": "WOwfJ4+TWm9QTFeKMGyg+w==:QqkI8S4+Wwnpno6z+uk8kQ==",
          "nrqlConditions": [
            {
              "id": "4432",
              "name": "Baseline Condition",
              "type": "BASELINE"
            },
            {
              "id": "443",
              "name": "A static condition",
              "type": "STATIC"
            },
            // more conditions here in reality
          ],
          "totalCount": 435
          }
        }
      }
    }
  }
}

レスポンス内の条件をページングするために、クライアントは、 nextCursor がレスポンスから null を返すまで、カーソルを返すように要求します。

{
  actor {
    account(id: YOUR_ACCOUNT_ID) {
      alerts {
        nrqlConditionsSearch(cursor: "WOwfJ4+TWm9QTFeKMGyg+w==:QqkI8S4+Wwnpno6z+uk8kQ==",
        ) {
          nextCursor
          nrqlConditions {
            id
            name
            type
          }
          totalCount
        }
      }
    }
  }
}

特定のフィールドは、特定のNRQL条件タイプでしか利用できません。異なる条件タイプの間で変異が分割されている主な理由は、受け入れられるフィールドの間に細かい違いがあるからです。

例えば、 valueFunction は静的な NRQL 条件にのみ関連し、 baselineDirection はベースラインの NRQL 条件にのみ関連します。

しかし、これらのフィールドが特定の条件タイプでしか利用できない場合、すべての条件タイプのリストでそれらを返すにはどうすればよいのでしょうか？その答えは、インライン・フラグメントと呼ばれるGraphQLの慣習です。インライン・フラグメントでは、特定のタイプのNRQL条件のデータにアクセスすることができます。

{
  actor {
    account(id: YOUR_ACCOUNT_ID) {
      alerts {
        nrqlConditionsSearch {
          nrqlConditions {
            id
            name
            type
            ...on AlertsNrqlStaticCondition {
              valueFunction
            }
            ...on AlertsNrqlBaselineCondition {
              baselineDirection
            }
          }
        }
      }
    }
  }
}

前述のクエリ例では、どのNRQL条件が正しいタイプなのかを判断するために、GraphQLにハードワークを依頼しています。

そのため、返された型が静的条件の場合は、オブジェクト内の valueFunction を返し、返された型がベースライン条件の場合は、代わりに baselineDirection を返します。以下は応答例である。

{
  "data": {
    "actor": {
      "account": {
        "alerts": {
          "nrqlConditionsSearch": {
            "nrqlConditions": [
              {
                "baselineDirection": "UPPER_ONLY",
                "id": "342",
                "name": "My baseline condition",
                "type": "BASELINE"
              },
              {
                "id": "553",
                "name": "My static condition",
                "type": "STATIC",
                "valueFunction": "SINGLE_VALUE"
              }
            ]
          }
        }
      }
    }
  }
}

searchCriteria nrqlConditionsSearch クエリの引数でNRQL条件をフィルタリングできます。

ここでは、名前によるマッチングでNRQL条件をフィルタリングする例を紹介します。このクエリは、指定された名前にマッチする NRQL 条件を返します。このマッチは大文字と小文字を区別しないことに注意してください。

{
  actor {
    account(id: YOUR_ACCOUNT_ID) {
      alerts {
        nrqlConditionsSearch(searchCriteria: {
          name: "Baseline Condition"
        }) {
          nrqlConditions {
            id
            name
            type
          }
        }
      }
    }
  }
}

単数形のNRQL条件検索

NRQL 条件 API を使用して、単数の条件を照会できます。 nrqlCondition クエリを alerts ネームスペースで実行します。

nrqlConditionSearch クエリのタイプ指定フィールドと同様に、これらのインライン・フラグメントを使用して、NRQL 条件タイプに限定されたフィールドを要求することもできます。

{
  actor {
    account(id: YOUR_ACCOUNT_ID) {
      alerts {
        nrqlCondition(id: YOUR_CONDITION_ID) {
          id
          name
          ...on AlertsNrqlStaticCondition {
            valueFunction
          }
        }
      }
    }
  }
}

説明文の更新

ここでは、NRQLのアラート条件に説明文を作成する手順を説明します。

保険契約の条件をすべて把握する。

{
  actor {
    account(id: YOUR_ACCOUNT_ID) {
      alerts {
        nrqlConditions(policyId: YOUR_POLICY_ID) {
          nextCursor
          results {
            id
            name
            description
            enabled
            nrql {
              query
            }
            signal {
              aggregationWindow
              aggregationMethod
              aggregationDelay
              aggregationTimer
            }
            policyId
            runbookUrl
            terms {
              duration
              operator
              priority
              timeFunction
              threshold
            }
            type
            violationTimeLimitSeconds
          }
        }
      }
    }
  }
}

1つの条件の詳細を取得します。

{
  actor {
    account(id: YOUR_ACCOUNT_ID) {
      alerts {
        nrqlCondition(id: "YOUR_CONDITION_ID") {
          description
          id
          enabled
          name
          nrql {
            query
          }
          signal {
            aggregationWindow
            aggregationMethod
            aggregationDelay
            aggregationTimer
          }
          policyId
          runbookUrl
          terms {
            operator
            priority
            threshold
            thresholdDuration
            thresholdOccurrences
          }
          type
          violationTimeLimitSeconds
        }
      }
    }
  }
}

説明文で変異を作成します。

ここには空の変異テンプレートがあります。

mutation {
  alertsNrqlConditionStaticUpdate(accountId: YOUR_ACCOUNT_ID, id: "YOUR_CONDITION_ID", condition: {description: ""}) {
    description
  }
}

ここでは、記述例を含む変異の例を紹介します。

mutation {
  alertsNrqlConditionStaticUpdate(accountId: 123456, id: "123456", condition: {
    description: "timestamp : {{timestamp}} \n accountId : {{accountId}} \n type : {{type}} \n event : {{event}} \n description : {{description}} \n policyId : {{policyId}} \n policyName: {{policyName}} \n conditionName : {{conditionName}} \n conditionId : {{conditionId}} \n product : {{product}} \n conditionType : {{conditionType}} \n RunbookUrl : {{runbookUrl}} \n nrqlQuery : {{nrqlQuery}} \n nrqlEventType : {{nrqlEventType}} \n targetID : {{targetId}} \n targetName : {{targetName}} \n commandLine : {{tag.commandLine}} \n entityGuid : {{tag.entityGuid}} \n entityName : {{tag.entityName}} \n fullHostname : {{tag.fullHostname}} \n instanceType : {{tag.instanceType}} \n processDisplayName : {{tag.processDisplayName}}"}
  ) {
    description
  }
}

条件の削除

alertsConditionDelete 変異を使って、あらゆるタイプの条件を削除することができます。delete変異では、 id フィールドのみを要求することができます。

mutation {
  alertsConditionDelete(accountId: YOUR_ACCOUNT_ID, id: YOUR_CONDITION_ID) {
    id
  }
}

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