Tutoriel NerdGraph : diffusez vos données vers un AWS Kinesis Firehose ou Azure Event Hub

Avec notre fonctionnalité d'exportation en streaming, disponible avec Data Plus, vous pouvez envoyer vos données vers un AWS Kinesis Firehose ou Azure événement Hub au fur et à mesure qu'elles sont ingérées par New Relic. Nous expliquerons comment créer et mettre à jour une règle de streaming à l'aide de NerdGraph et comment afficher les règles existantes. Vous pouvez utiliser l'explorateur NerdGraph pour effectuer ces appels.

Qu'est-ce que l'exportation en streaming ?

Au fur et à mesure que les données sont ingérées par votre organisation New Relic , notre fonctionnalité d'exportation en streaming envoie ces données à un AWS Kinesis Firehose ou à Azure événement Hub. Vous pouvez configurer des règles personnalisées, définies à l'aide de NRQL, pour régir les types de données New Relic que vous exporterez. Vous pouvez également choisir de compresser ces données avant de les exporter, à l'aide de notre nouvelle fonctionnalité de compression d'exportation .

Quelques exemples de choses pour lesquelles vous pouvez utiliser l’exportation en streaming :

• Pour peupler un lac de données
• Améliorer la formation IA/ML
• Conservation à long terme pour des raisons de conformité, juridiques ou de sécurité

Vous pouvez désactiver ou activer les règles d'exportation en streaming quand vous le souhaitez. Mais notez que l'exportation en streaming n'envoie que les données actuellement ingérées, ce qui signifie que si vous la désactivez et la réactivez, les données ingérées lorsqu'elle était désactivée ne seront pas envoyées avec cette fonctionnalité. Pour exporter des données passées, vous pouvez utiliser l'exportation de données historiques.

Exigences et limites

Limites des données diffusées en continu : la quantité de données que vous pouvez diffuser par mois est limitée par le total de vos données ingérées par mois. Si la quantité de vos données de streaming dépasse la quantité de données ingérées, nous pouvons suspendre votre accès et votre utilisation de l'exportation en streaming.

Exigences relatives aux autorisations :

• Pro ou édition Entreprise avec option Data Plus
• type d'utilisateur : core utilisateur ou full plateforme utilisateur
• L'autorisation de diffusion des données

Vous devez disposer d’un AWS Kinesis Firehose ou d’ Azure Event Hub configuré pour recevoir les données New Relic . Si vous ne l’avez pas déjà fait, vous pouvez suivre nos étapes ci-dessous pour AWS ou Azure.

Exigences NRQL :

• Doit être une requête plate, sans agrégation. Par exemple, les formulaires SELECT * ou SELECT column1, column2 sont pris en charge.
• Applicable à tout ce qui se trouve dans la clause WHERE , à l'exception des sous-requêtes.
• La requête ne peut pas avoir de clause FACET , COMPARE WITH ou LOOKUP.
• Les requêtes imbriquées ne sont pas prises en charge.
• Prend en charge les types de données stockés dans NRDB, et non les données d'intervalle de temps métrique.

Configurer un AWS Kinesis Firehose

Pour configurer l'exportation de données de streaming vers AWS, vous devez d'abord configurer un Amazon Kinesis Firehose. Nous vous guiderons tout au long de cette procédure au cours des trois étapes suivantes.

Une fois ces étapes terminées, vous pouvez configurer vos règles d’exportation à l’aide de NerdGraph. Pour en savoir plus, accédez à Champs importants pour les appels NerdGraph.

Configurer un Azure événement Hub

Pour configurer l’exportation de données de streaming vers Azure, vous devez d’abord configurer un événement Hub. Nous vous guiderons tout au long de cette procédure au cours des trois étapes suivantes.

Vous pouvez également suivre le guide Azure ici.

Une fois ces étapes terminées, consultez la section suivante sur les champs importants pour vos appels Nerdgraph.

Champs importants pour les appels NerdGraph

La plupart des appels NerdGraph d'exportation de données de streaming que nous aborderons utilisent quelques champs liés à votre compte :

Pour AWS Kinesis Firehose :

• awsAccountId: L'ID de compte AWS. Par exemple: 10000000000
• deliveryStreamName:Le nom du flux Kinesis. Par exemple : firehose-test-stream.
• region:La région AWS. Par exemple : us-east-1.
• role:Le rôle AWS IAM pour Kinesis Firehose. Ce sera toujours firehose-role.

Pour les hubs d'événements Azure :

• eventHubConnectionString:La chaîne de connexion du hub d'événementsAzure . Ressemble à : Endpoint=sb://<NamespaceName>.servicebus.windows.net/;SharedAccessKeyName=<KeyName>;SharedAccessKey=<KeyValue>;EntityPath=<EventHubName>
• eventHubName:Le nom de l'événement Hub. Par exemple : my-event-hub.

Comment créer une règle d'exportation en streaming

Tout d’abord, décidez quelles données vous souhaitez exporter. Ensuite, avec un appel NerdGraph, vous créerez les règles de streaming souhaitées à l'aide de NRQL. Nous allons donner quelques exemples.

Créer un flux

Lorsque vous créez une nouvelle règle de streaming, vous aurez besoin de tous les champs suivants. Voici un exemple de création d'une règle de streaming exportée vers un AWS Kinesis Firehose :

mutation {
  streamingExportCreateRule(
    accountId: YOUR_NR_ACCOUNT_ID
    ruleParameters: {
      description: "ADD_RULE_DESCRIPTION"
      name: "PROVIDE_RULE_NAME"
      nrql: "SELECT * FROM NodeStatus"
      payloadCompression: DISABLED
    }
    awsParameters: {
      awsAccountId: "YOUR_AWS_ACCOUNT_ID"
      deliveryStreamName: "FIREHOSE_STREAM_NAME"
      region: "SPECIFY_AWS_REGION"
      role: "firehose-role"
    }
  ) {
    id
    status
  }
}

Voici un exemple de création d’une règle de streaming exportée vers un hub d’événements Azure :

mutation {
  streamingExportCreateRule(
    accountId: YOUR_NR_ACCOUNT_ID
    ruleParameters: {
      description: "ADD_RULE_DESCRIPTION"
      name: "PROVIDE_RULE_NAME"
      nrql: "SELECT * FROM NodeStatus"
      payloadCompression: DISABLED
    }
    azureParameters: {
      eventHubConnectionString: "YOUR_EVENT_HUB_SAS_CONNECTION_STRING"
      eventHubName: "YOUR_EVENT_HUB_NAME"
    }
  ) {
    id
    status
  }
}

Vous obtiendrez immédiatement un résultat avec un identifiant de règle et un statut. Le statut sera affiché comme CREATION_IN_PROGRESS. Vous pouvez utiliser l'ID de règle pour vérifier si la règle est créée avec succès.

La création de la règle peut prendre jusqu'à six minutes en raison du temps nécessaire à la validation de la politique.

Avant que la règle ne termine l'enregistrement, vous ne pouvez pas lancer une autre action de mutation (comme Enable, Disable ou Update) car la règle est verrouillée pour le processus de création. Si vous essayez une autre action de mutation avant que la règle ne termine le processus d'enregistrement, vous recevrez un message du type : « La règle d'exportation est actuellement mise à jour par une autre demande, veuillez patienter et réessayer plus tard. »

Vous pouvez utiliser Delete à tout moment.

La création peut être terminée et le statut peut être modifié à tout moment dans les six minutes environ nécessaires à la création de la règle. Le statut passera à ENABLED, DISABLED ou CREATION_FAILED.

Voir ces détails sur les valeurs :

• ENABLED signifie que la règle a été créée avec succès et que les données ont commencé à être diffusées.
• CREATION_FAILED signifie que la règle a échoué lors de la création. Cela peut se produire pour plusieurs raisons, mais est souvent dû à l’échec de la politique AWS ou de la validation Azure SAS.
• DISABLED signifie que la règle est créée mais n'est pas encore activée pour des raisons telles que la limite du flux de filtrage atteinte ou l'échec de la création de la règle de flux de filtrage. Si le statut reste CREATION_IN_PROGRESS après six minutes, cela signifie que la création de la règle a échoué en raison d'une erreur système sur notre service. Vous pouvez supprimer la règle et essayer d'en créer une nouvelle.

Une fois qu'une règle de streaming est créée, vous pouvez la visualiser.

Mettre à jour un flux

Lorsque vous mettez à jour une nouvelle règle de streaming, vous aurez besoin de tous les champs suivants. Voici un exemple de mise à jour d’une règle de streaming :

AWS Kinesis Firehose :

mutation {
  streamingExportUpdateRule(
    id: RULE_ID
    ruleParameters: {
      description: "ADD_RULE_DESCRIPTION"
      name: "PROVIDE_RULE_NAME"
      nrql: "YOUR_NRQL_QUERY"
      payloadCompression: DISABLED
    }
    awsParameters: {
      awsAccountId: "YOUR_AWS_ACCOUNT_ID"
      deliveryStreamName: "FIREHOSE_STREAM_NAME"
      region: "SPECIFY_AWS_REGION"
      role: "firehose-role"
    }
  ) {
    id
    status
  }
}

Azure Event Hub :

mutation {
  streamingExportUpdateRule(
    id: RULE_ID
    ruleParameters: {
      description: "ADD_RULE_DESCRIPTION"
      name: "PROVIDE_RULE_NAME"
      nrql: "YOUR_NRQL_QUERY"
      payloadCompression: DISABLED
    }
    azureParameters: {
      eventHubConnectionString: "YOUR_EVENT_HUB_SAS_CONNECTION_STRING"
      eventHubName: "YOUR_EVENT_HUB_NAME"
    }
  ) {
    id
    status
  }
}

Lors de la mise à jour, vous recevrez un message dans le champ de message : « La règle d'exportation est en cours de mise à jour et le processus peut prendre quelques minutes. Veuillez vérifier à nouveau plus tard. » La mise à jour complète peut prendre jusqu’à six minutes.

Vous pouvez vérifier si la règle est mise à jour en appelant streamingRule pour récupérer la règle. Pendant la période de mise à jour de la règle, la règle est verrouillée et aucune autre action de mutation ne peut agir sur la règle. Si vous essayez d'effectuer une autre action de mutation sur la même règle, vous recevrez un message indiquant : « La règle d'exportation est actuellement mise à jour par une autre demande, veuillez patienter et réessayer plus tard. » Un utilisateur peut mettre à jour une règle de n’importe quel statut, à l’exception d’une règle supprimée.

Désactiver un flux

Pour désactiver une règle, il vous suffit de fournir l'ID de la règle. Voici un exemple de désactivation d’un flux :

mutation {
  streamingExportDisableRule(id: RULE_ID) {
    id
    status
    message
  }
}

Vous ne pouvez désactiver la règle que lorsque celle-ci a le statut ENABLED. Si vous essayez de désactiver une règle qui se trouve dans un autre état, le message d'erreur « La règle d'exportation ne peut pas être activée ou désactivée car le statut n'est pas autorisé » est renvoyé. Vous ne pouvez pas désactiver la règle si la règle est verrouillée en raison d'une autre mutation en cours.

Activer un flux

Si vous souhaitez activer une règle, il vous suffit de fournir l'ID de la règle. Voici un exemple d’activation d’un flux :

mutation {
  streamingExportEnableRule(id: RULE_ID) {
    id
    status
    message
  }
}

Vous ne pouvez activer la règle que lorsqu'elle a le statut DISABLED. Si vous essayez d'activer une règle qui se trouve dans un autre état, elle renvoie un message d'erreur du type : « La règle d'exportation ne peut pas être activée ou désactivée car le statut n'est pas autorisé. » Vous ne pouvez pas activer la règle si la règle est verrouillée en raison d'une autre mutation en cours.

Supprimer un flux

Vous devrez fournir un ID de règle pour supprimer un flux. Voici un exemple :

mutation {
  streamingExportDeleteRule(id: RULE_ID) {
    id
    ...
  }
}

La suppression peut être effectuée sur une règle de n'importe quel statut, sauf si elle est déjà supprimée. Une fois qu'une règle est supprimée, elle ne peut plus être réactivée. La règle peut toujours être consultée dans les 24 premières heures après la suppression en appelant l'API steamingRule avec l'ID de règle. Après 24 heures, la règle ne sera plus consultable via NerdGraph.

Voir les flux

Vous pouvez interroger des informations sur une règle de flux spécifique en interrogeant l'ID de compte et l'ID de règle. Voici un exemple :

AWS Kinesis Firehose :

{
  actor {
    account(id: YOUR_NR_ACCOUNT_ID) {
      streamingExport {
        streamingRule(id: "RULE_ID") {
          aws {
            awsAccountId
            deliveryStreamName
            region
            role
          }
          createdAt
          description
          id
          message
          name
          nrql
          status
          updatedAt
          payloadCompression
        }
      }
    }
  }
}

Azure Event Hub :

{
  actor {
    account(id: YOUR_NR_ACCOUNT_ID) {
      streamingExport {
        streamingRule(id: "RULE_ID") {
          azure {
            eventHubConnectionString
            eventHubName
          }
          createdAt
          description
          id
          message
          name
          nrql
          status
          updatedAt
          payloadCompression
        }
      }
    }
  }
}

Vous pouvez également interroger tous les flux existants. Voici un exemple :

{
  actor {
    account(id: YOUR_NR_ACCOUNT_ID) {
      streamingExport {
        streamingRules {
          aws {
            awsAccountId
            region
            deliveryStreamName
            role
          }
          azure {
            eventHubConnectionString
            eventHubName
          }
          createdAt
          description
          id
          message
          name
          nrql
          status
          updatedAt
          payloadCompression
        }
      }
    }
  }
}

Comprendre la compression des exportations

En option, nous pouvons compresser les charges avant qu'elles ne soient exportées, bien que cette option soit désactivée par défaut. Cela peut vous aider à éviter d’atteindre votre limite de données ingérées et à économiser de l’argent sur les coûts de sortie.

Vous pouvez activer la compression en utilisant le champ payloadCompression sous ruleParameters. Ce champ peut avoir l'une des valeurs suivantes :

• DISABLED: la charge ne sera pas compressée avant d'être exportée. Si non spécifié, payloadCompression prendra par défaut cette valeur.
• GZIP:Compressez la charge avec le format GZIP avant l'exportation

GZIP est le seul format de compression actuellement disponible, mais nous pouvons choisir de rendre davantage de formats disponibles à l'avenir.

Lorsque la compression est activée sur une règle d'exportation AWS existante, le message suivant de Kinesis Firehose peut contenir des données compressées et non compressées. Cela est dû à la mise en mémoire tampon dans Kinesis Firehose. Pour éviter cela, vous pouvez désactiver temporairement la règle d'exportation avant d'activer la compression ou créer un nouveau flux Kinesis Firehose pour que seules les données compressées circulent.

Si vous rencontrez ce problème et que vous exportez vers S3 ou un autre système de stockage de fichiers, vous pouvez afficher la partie compressée des données en suivant ces étapes :

1. Téléchargez manuellement l'objet.
2. Séparez l'objet en deux fichiers distincts en copiant les données compressées dans un nouveau fichier.
3. Décompressez le nouveau fichier de données compressé uniquement.

Une fois que vous avez les données compressées, vous pouvez les télécharger à nouveau sur S3 (ou tout autre service que vous utilisez) et supprimer l'ancien fichier.

Veuillez noter que dans S3 ou un autre système de stockage de fichiers, les objets peuvent être constitués de plusieurs fichiers codés GZIP qui sont ajoutés consécutivement. Par conséquent, votre bibliothèque de décompression doit avoir la capacité de gérer de telles charges GZIP concaténées.

Décompression automatique dans AWS

Une fois vos données arrivées dans AWS, vous souhaiterez peut-être disposer d'options permettant de les décompresser automatiquement. Si vous diffusez ces données vers un bucket S3, il existe deux manières d'activer la décompression automatique :

Décompression automatique dans Azure

Si vous exportez des données vers Azure, il est possible d’afficher les versions décompressées des objets stockés dans votre hub d’événements à l’aide d’une tâche Stream Analytics. Pour ce faire, suivez ces étapes :

1. Suivez ce guide jusqu'à l'étape 16.

• À l'étape 13, vous pouvez choisir d'utiliser le même hub d'événements que la sortie sans rien casser, bien que nous ne le recommandons pas si vous avez l'intention de passer à l'étape 17 et de démarrer le travail, car cela n'a pas été testé.

2. Dans le volet gauche de votre tâche d’analyse de streaming, cliquez sur Inputs, puis cliquez sur l’entrée que vous avez configurée.
3. Faites défiler vers le bas du volet qui apparaît à droite et configurez l'entrée avec ces paramètres :

• format de sérialisation des événements : JSON
• Codage : UTF-8
• Type de compression d'événement : GZip

4. Cliquez sur Save en bas du volet.
5. Cliquez sur Query sur le côté de l’écran. En utilisant l'onglet Input preview , vous devriez maintenant pouvoir interroger le hub d'événements à partir de cet écran.