Tutoriel NerdGraph : renvoyer des réponses NRQL plus volumineuses avec l'exportation de données historiques

Lorsque vous exécutez une requête NRQL, vous êtes limité par diverses limites, telles qu'une limite sur le nombre de points de données renvoyés dans une réponse et un délai d'expiration de la requête. Notre fonctionnalité d'exportation de données historiques peut être utilisée pour exécuter une requête NRQL qui renvoie 200 000 000 points de données dans une réponse (au lieu de la limite habituelle de 5 000) et n'a pas de délai d'expiration de requête. Les résultats sont renvoyés sous la forme d’un ou plusieurs fichiers JSON.

Exigences

Nécessite Data Plus
Pour exporter des données, vous devez être un utilisateur de la plateforme principale ou complète

Limites et restrictions

Voici quelques limites et restrictions concernant cette fonctionnalité :

Limites d'utilisation

Voici les limites d’utilisation par défaut pour une exportation :

Les exportations devraient rapporter moins de 200 millions d'événements
Les exportations devraient être estimées à moins de 5 milliards d'événements
Pas plus de deux exportations simultanées par compte

Si vous souhaitez des limites plus élevées, parlez-en à votre représentant de compte.

Restrictions de type de données

Aucun des types de données suivants n'est disponible pour l'exportation :

Restrictions de plage horaire

La fonctionnalité d'exportation de données historiques ne prend pas en charge l'interrogation des données en direct ou des données des 12 heures précédentes. La plage horaire doit se terminer au moins 12 heures dans le passé.

Exigences en matière de syntaxe de requête

Cette fonctionnalité prend en charge la sélection de noms d'attributs spécifiques et de caractères génériques (SELECT *). Par exemple, nous prenons en charge les requêtes telles que celles-ci :

SELECT * FROM MobileRequest SINCE 3 days ago until 2 days ago

SELECT duration, appId FROM Transaction
WHERE appName = 'interesting-application'
SINCE '2022-06-11 11:05:00-0600' UNTIL '2022-06-11 11:10:00-0600'

Les composants NRQL suivants cannot doivent être utilisés dans la requête :

Fonctions d'agrégation (sum, count, average, max)
Les fonctions évaluables (numeric, log, concat) ne sont prises en charge que dans la clause WHERE
FACET
TIMESERIES
COMPARE WITH
JOIN
Agrégations imbriquées
Subqueries
Liaisons variables
Requête inter-comptes

détails du point de terminaison

La fonctionnalité d'export de données historiques utilise notre API NerdGraph et utilise trois points de terminaison :

Le point de terminaison create permet à un utilisateur de spécifier l'ID de compte et le NRQL qu'il souhaite exécuter en tant qu'exportation.
Le point de terminaison get details for export permet à un utilisateur de spécifier un ID de compte et un ID d'exportation (trouvé dans le corps de la réponse du point de terminaison de création) et de l'utiliser pour récupérer l'état de l'exportation. Une fois l’exportation terminée, les résultats, sous la forme d’une ou plusieurs URL de téléchargement, peuvent être trouvés dans la réponse de ce point de terminaison.
Le point de terminaison get details for account exports permet à un utilisateur de spécifier un ID de compte et de récupérer les détails de toutes les exportations actives et non expirées pour ce compte.

Exemple de requête

Créer une exportation

Une façon d'utiliser NerdGraph est d'utiliser l'explorateur NerdGraph. Les instructions de cette section se concentreront sur l’utilisation de l’explorateur NerdGraph. Si vous souhaitez exécuter votre propre script, consultez script.

Dans le schéma NerdGraph, le point de terminaison historicalDataExportCreateExport peut être trouvé sous mutation > historicalDataExport. Utilisez une requête comme celle ci-dessous pour exécuter une exportation.

Il est recommandé de sélectionner l'ID pour le corps de la réponse, car il sera utilisé pour obtenir les détails de l'exportation et récupérer les résultats.

mutation {
  historicalDataExportCreateExport(
    accountId: YOUR_ACCOUNT_ID
    nrql: "FROM Transaction SELECT duration, appId WHERE appName = 'interesting-application' SINCE '2022-06-11 11:05:00-0600' UNTIL '2022-06-11 11:10:00-0600'"
  ) {
    percentComplete
    nrql
    status
    id
    message
  }
}

Exemple de réponse

Voici un exemple de réponse pour créer une exportation :

{
  "data": {
    "historicalDataExportCreateExport": {
      "id": "609b6916-8ca9-417c-bbf8-02e4cdc3afd2",
      "message": null,
      "nrql": "FROM Transaction SELECT duration, appId WHERE appName = 'interesting-application' SINCE '2022-06-11 11:05:00-0600' UNTIL '2022-06-11 11:10:00-0600'",
      "percentComplete": 5,
      "status": "WAITING"
    }
  }
}

Annuler l'exportation

Dans le schéma NerdGraph, le point de terminaison historicalDataExportCancelExport peut être trouvé sous mutation > historicalDataExport. Utilisez une requête comme celle ci-dessous pour exécuter une exportation.

Il est recommandé de sélectionner le statut dans le corps de la réponse pour vérifier que l'exportation a été annulée avec succès.

mutation {
  historicalDataExportCancelExport(
    accountId: YOUR_ACCOUNT_ID
    id: "YOUR_EXPORT_ID"
  ) {
    status
    id
  }
}

Exemple de réponse

Voici un exemple de réponse pour annuler une exportation :

{
  "data": {
    "historicalDataExportCancelExport": {
      "id": "YOUR_EXPORT_ID",
      "status": "CANCELED"
    }
  }
}

Obtenir des détails sur une exportation spécifique

Utilisez l'ID d'exportation trouvé dans la réponse du point de terminaison de création aux détails de la requête pour l'exportation, comme indiqué ci-dessous. Ce point de terminaison peut être trouvé dans NerdGraph sous query > actor > account > historicalDataExport > export.

{
  actor {
    account(id: YOUR_ACCOUNT_ID) {
      historicalDataExport {
        export(id: "YOUR_EXPORT_ID") {
          availableUntil
          eventCount
          eventTypes
          id
          message
          nrql
          percentComplete
          results
          status
        }
      }
    }
  }
}

Exemple de réponse

Voici la réponse pour obtenir les détails d’une exportation spécifique :

{
  "data": {
    "actor": {
      "account": {
        "historicalDataExport": {
          "export": {
            "availableUntil": 1655499642845,
            "eventCount": 1291,
            "eventTypes": ["MobileRequest"],
            "id": "4776677a-1e0f-4ad5-a790-cdbe40a1f348",
            "message": null,
            "nrql": "SELECT * FROM MobileRequest SINCE 3 days ago UNTIL 2 days ago",
            "percentComplete": 100,
            "results": ["downloadLink1", "downloadLink2"],
            "status": "COMPLETE_SUCCESS"
          }
        }
      }
    }
  }
}

Obtenir les détails d'exportation pour un compte

Vous pouvez utiliser l'ID de compte pour obtenir les détails de toutes les exportations de ce compte, comme indiqué ci-dessous. Le point de terminaison peut être trouvé dans le schéma NerdGraph sous query > actor > account > historicalDataExport > exports.

{
  actor {
    account(id: YOUR_ACCOUNT_ID) {
      historicalDataExport {
        exports {
          availableUntil
          eventCount
          eventTypes
          id
          message
          nrql
          percentComplete
          results
          status
        }
      }
    }
  }
}

Exemple de réponse

Voici un exemple de réponse pour obtenir les détails d’exportation d’un compte :

{
  "data": {
    "actor": {
      "account": {
        "historicalDataExport": {
          "exports": [
            {
              "availableUntil": 1655499642845,
              "eventCount": 1291,
              "eventTypes": ["MobileRequest"],
              "id": "4776677a-1e0f-4ad5-a790-cdbe40a1f348",
              "message": null,
              "nrql": "SELECT * FROM MobileRequest SINCE 3 days ago UNTIL 2 days ago",
              "percentComplete": 100,
              "results": ["downloadLink1", "downloadLink2"],
              "status": "COMPLETE_SUCCESS"
            }
          ]
        }
      }
    }
  }
}

Utiliser un script

Il peut être utile de requêter les exportations de données historiques par programmation, à partir d'un script. Les commandes curl suivantes peuvent être utiles pour commencer. Pour des exemples de réponse, consultez les réponses dans la section Exemple de requête.

Important

Vous devez échapper toutes les instances de guillemets simples (') dans votre requête d'exportation NRQL avec une barre oblique inverse (\'). Les commandes curl ci-dessous s'appuient sur un $ de début dans l'argument --data-raw , dont la fonctionnalité est fournie par les guillemets ANSI-C. Plus d'informations sont disponibles dans le manuel officiel GNU.

Créer une exportation

bash

$curl --location --request POST 'https://api.newrelic.com/graphql' \
>     --header 'Content-Type: application/json' \
>     --header 'API-Key: $USER_API_KEY' \
>     --data-raw $'{"query":"mutation {historicalDataExportCreateExport(accountId: $ACCOUNT_ID, nrql: \\"$NRQL_QUERY_TO_EXPORT\\") {percentComplete nrql status message id}}","variables":{}}'

Annuler l'exportation

bash

$curl --location --request POST 'https://api.newrelic.com/graphql' \
>     --header 'Content-Type: application/json' \
>     --header 'API-Key: $USER_API_KEY' \
>     --data-raw $'{"query":"mutation {historicalDataExportCancelExport(accountId: $ACCOUNT_ID, id: \\"$YOUR_EXPORT_ID\\") { status message id}}","variables":{}}'

Obtenir des détails sur l'exportation

bash

$curl --location --request POST 'https://api.newrelic.com/graphql' \
>     --header 'Content-Type: application/json' \
>     --header 'API-Key: $USER_API_KEY' \
>     --data-raw $'{"query":"{actor {account(id: $ACCOUNT_ID) {historicalDataExport {export(id: \\"$YOUR_EXPORT_ID\\") {availableUntil eventCount eventTypes id message nrql percentComplete results status}}}}}","variables":{}}'

Obtenir des détails sur les exportations de compte

bash

$curl --location --request POST 'https://api.newrelic.com/graphql' \
>     --header 'Content-Type: application/json' \
>     --header 'API-Key: $USER_API_KEY' \
>     --data-raw $'{"query":"{actor {account(id: $USER_API_KEY) {historicalDataExport {exports {availableUntil eventCount eventTypes id message nrql percentComplete results status}}}}}","variables":{}}'

Format des résultats d'exportation

Les résultats de la requête se trouvent dans le champ de résultats de l'un des deux points de terminaison get details . Ils se présentent sous la forme d’un ou plusieurs liens de téléchargement. Les fichiers de résultats eux-mêmes sont valables pendant une semaine à compter de la date d'exécution de l'exportation et contiennent environ 100 Mo ou moins de JSON compressé GZIP. Chaque lien est pré-signé pour être valable 6 heures. Si le lien expire, vous pouvez en obtenir un nouveau en interrogeant à nouveau l'objet des détails d'exportation dans NerdGraph pour obtenir les résultats.

Un exemple de fichier de résultats décompressé est ci-dessous :

[
  {
    "attributes": {
      "duration": 36,
      "eventType": "Transaction",
      "accountId": YOUR_ACCOUNT_ID,
      "timestamp": 1655174793213
    }
  },
  {
    "attributes": {
      "duration": 3,
      "eventType": "MobileRequest",
      "accountId": YOUR_ACCOUNT_ID,
      "timestamp": 1655174793215
    }
  }
]

Requête et alerte sur un événement lié à l'export

Cette fonctionnalité générera un événement personnalisé dans le compte New Relic dans lequel l'exportation a été exécutée. Il peut être utile d'interroger ou de créer des alertes sur ces événements pour obtenir des informations sur les exportations qui ont été exécutées dans un compte.

Le type d'événement HistoricalDataExport contient des informations telles que l'état de l'exportation (Created, Completed, Failed, Canceled), l'ID d'exportation, la chaîne NRQL à partir de laquelle l'exportation est générée, etc.

La requête suivante, que vous pouvez exécuter dans le générateur de requêtes ou ajouter à un dashboard, renverra tous les exportations créées au cours de la semaine dernière et le nombre de celles qui ont été réalisées avec succès et n'ont pas eu d'erreur :

FROM HistoricalDataExport SELECT * WHERE status = 'Created' SINCE 1 WEEK AGO

FROM HistoricalDataExport SELECT count(*) WHERE status != 'Completed' FACET status SINCE 1 WEEK AGO

Dépannage

Compte pas encore activé

Lorsque vous essayez de créer une exportation, vous pouvez voir un message d'erreur indiquant :

Cannot query field \"historicalDataExportCreateExport\" on type \"RootMutationType\".

Si vous obtenez ce message, cela signifie probablement que la fonctionnalité d'exportation de données historiques n'a pas encore été activée pour le compte à partir duquel vous essayez d'exporter. Si vous avez des questions, consultez les exigences et parlez à votre représentant de compte pour poser des questions sur l’accès.

Lien vers les résultats expiré

Lorsque vous essayez de télécharger des résultats à l'aide d'une URL pré-signée, vous pouvez voir une erreur comme celle-ci :

<Error>
  <Code>AccessDenied</Code>
  <Message>Request has expired</Message>
  <X-Amz-Expires>120</X-Amz-Expires>
  <Expires>2022-06-24T15:16:45Z</Expires>
  <ServerTime>2022-06-24T17:56:40Z</ServerTime>
  <RequestId>1234567890ABC</RequestId>
  <HostId>ABCD1234HOST-ID098765-XYZ</HostId>
</Error>

Une erreur comme celle-ci indique que l'URL des résultats a expiré et que vous devrez interroger à nouveau l'objet d'exportation pour obtenir une nouvelle URL de résultats. Vous n’avez pas besoin de réexécuter l’exportation, il vous suffit d’obtenir un nouvel ensemble d’URL pour les résultats.

Cette traduction automatique est fournie pour votre commodité.

Tutoriel NerdGraph : renvoyer des réponses NRQL plus volumineuses avec l'exportation de données historiques

Exigences .css-21sua1{background:none;border:none;width:0;padding:0;}

Limites et restrictions

Limites d'utilisation

Restrictions de type de données

Restrictions de plage horaire

Exigences en matière de syntaxe de requête

détails du point de terminaison

Exemple de requête

Créer une exportation

Exemple de réponse

Annuler l'exportation

Exemple de réponse

Obtenir des détails sur une exportation spécifique

Exemple de réponse

Obtenir les détails d'exportation pour un compte

Exemple de réponse

Utiliser un script

Important

Créer une exportation

Annuler l'exportation

Obtenir des détails sur l'exportation

Obtenir des détails sur les exportations de compte

Format des résultats d'exportation

Requête et alerte sur un événement lié à l'export

Dépannage

Compte pas encore activé

Lien vers les résultats expiré

Exigences