Tutorial do NerdGraph: Transmita seus dados para um AWS Kinesis Firehose ou Azure Event Hub

Com nosso recurso de exportação de streaming, disponível com Data Plus, você pode enviar seus dados para um AWS Kinesis Firehose ou Azure Event Hub à medida que são ingeridos pelo New Relic. Explicaremos como criar e atualizar uma regra de streaming usando NerdGraph e como visualizar as regras existentes. Você pode usar o explorador NerdGraph para fazer essas chamadas.

O que é exportação de streaming?

À medida que os dados são ingeridos pela sua organização New Relic, nosso recurso de exportação de streaming envia esses dados para um AWS Kinesis Firehose ou Azure Event Hub. Você pode configurar regras personalizadas, que são definidas usando NRQL, para controlar quais tipos de dados do New Relic você exportará. Você também pode optar por compactar esses dados antes de exportá-los, usando nosso novo recurso Export Compression .

Alguns exemplos de coisas para as quais você pode usar a exportação de streaming:

• Para preencher um data lake
• Aprimore o treinamento de IA/ML
• Retenção de longo prazo por motivos de conformidade, legais ou de segurança

Você pode desativar ou ativar regras de exportação de streaming sempre que desejar. Mas observe que a exportação de streaming envia apenas os dados ingeridos no momento, o que significa que se você desativá-lo e reativá-lo, os dados ingeridos quando estava desativado não serão enviados com esse recurso. Para exportar dados anteriores, você pode usar Exportação de dados históricos.

Requisitos e limites

Limites de dados transmitidos: a quantidade de dados que você pode transmitir por mês é limitada pelo total de dados ingeridos por mês. Se a quantidade de dados de streaming exceder a quantidade de dados ingeridos, poderemos suspender seu acesso e uso da exportação de streaming.

Requisitos relacionados às permissões:

• Pro ou edição Enterprise com opção Data Plus
• Tipo de usuário: usuário principal ou usuário de plataforma completa
• A permissão de dados de streaming

Você deve ter um AWS Kinesis Firehose ou Azure Event Hub configurado para receber dados do New Relic. Se ainda não fez isso, você pode seguir nossas etapas abaixo para AWS ou Azure.

Requisitos NRQL:

• Deve ser consulta plana, sem agregação. Por exemplo, formulários SELECT * ou SELECT column1, column2 são suportados.
• Aplicável a qualquer coisa na cláusula WHERE , exceto subconsultas.
• A consulta não pode ter uma cláusula FACET , COMPARE WITH ou LOOKUP.
• Consultas aninhadas não são suportadas.
• Suporta tipos de dados armazenados em NRDB e não dados métricos de fração de tempo.

Configurar um AWS Kinesis Firehose

Para configurar a exportação de dados de streaming para a AWS, primeiro você deve configurar um Amazon Kinesis Firehose. Orientaremos você nesse procedimento nas próximas três etapas.

Quando terminar essas etapas, você poderá configurar suas regras de exportação usando o NerdGraph. Para mais informações, vá para Campos importantes para chamadas NerdGraph.

Configurar um Azure Event Hub

Para configurar a exportação de dados de streaming para o Azure, primeiro você deve configurar um Event Hub. Orientaremos você nesse procedimento nas próximas três etapas.

Alternativamente, você pode seguir o guia do Azure aqui.

Quando terminar essas etapas, consulte a próxima seção sobre campos importantes para suas chamadas do Nerdgraph.

Campos importantes para chamadas NerdGraph

A maioria das chamadas NerdGraph de exportação de dados de streaming que abordaremos usam alguns campos relacionados à sua conta:

Para AWS Kinesis Firehose:

• awsAccountId: o ID da conta da AWS. Por exemplo: 10000000000
• deliveryStreamName: o nome do fluxo do Kinesis. Por exemplo: firehose-test-stream.
• region: A região da AWS. Por exemplo: us-east-1.
• role: a função AWS IAM para Kinesis Firehose. Será sempre firehose-role.

Para Azure Event Hubs:

• eventHubConnectionString: A Azure Event Hub Connection String. É semelhante a: Endpoint=sb://<NamespaceName>.servicebus.windows.net/;SharedAccessKeyName=<KeyName>;SharedAccessKey=<KeyValue>;EntityPath=<EventHubName>
• eventHubName: o nome do Event Hub. Por exemplo: my-event-hub.

Como criar uma regra de exportação de streaming

Primeiro, decida quais dados você deseja exportar. Então, com uma chamada NerdGraph, você criará as regras de streaming desejadas usando NRQL. Daremos alguns exemplos.

Crie um fluxo

Ao criar uma nova regra de streaming, você precisará de todos os campos a seguir. Aqui está um exemplo de criação de uma regra de streaming exportando para um 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
  }
}

Aqui está um exemplo de criação de uma regra de streaming exportando para um Hub de eventos do 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
  }
}

Você obterá um resultado imediatamente com um ID de regra e status. O status será mostrado como CREATION_IN_PROGRESS. Você pode usar o ID da regra para verificar se a regra foi criada com sucesso.

A criação da regra pode levar até seis minutos para ser concluída, pois a validação da política demora algum tempo.

Antes de a regra terminar de ser registrada, você não pode iniciar outra ação de mutação (como Enable, Disable ou Update) porque a regra está bloqueada para o processo de criação. Se você tentar outra ação de mutação antes que a regra conclua o processo de registro, você receberá uma mensagem como: "A regra de exportação está sendo atualizada por outra solicitação. Aguarde e tente novamente mais tarde".

Você pode usar Delete a qualquer momento.

A criação pode ser concluída e o status alterado a qualquer momento dentro dos cerca de seis minutos necessários para a criação da regra. O status mudará para ENABLED, DISABLED ou CREATION_FAILED.

Veja estes detalhes sobre os valores:

• ENABLED significa que a regra foi criada com sucesso e os dados começaram a ser transmitidos.
• CREATION_FAILED significa que a regra falhou na criação. Isso pode acontecer por vários motivos, mas geralmente ocorre devido à falha na política da AWS ou na validação do Azure SAS.
• DISABLED significa que a regra foi criada, mas ainda não está habilitada devido a motivos como limite de fluxo de filtro atingido ou falha na criação da regra de fluxo de filtro. Se o status ainda permanecer como CREATION_IN_PROGRESS após seis minutos, isso significa que a criação da regra falhou devido a um erro de sistema em nosso serviço. Você pode excluir a regra e tentar criar uma nova novamente.

Depois que uma regra de streaming for criada, você poderá visualizá-la.

Atualizar um fluxo

Ao atualizar uma nova regra de streaming, você precisará de todos os campos a seguir. Aqui está um exemplo de atualização de uma regra 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
  }
}

Ao atualizar, você receberá uma mensagem no campo de mensagem: “A regra de exportação está sendo atualizada e o processo pode demorar alguns minutos para ser concluído. Por favor, verifique novamente mais tarde.” Pode levar até seis minutos para ser totalmente atualizado.

Você pode verificar se a regra está atualizada chamando streamingRule para recuperá-la. Durante o período em que a regra está em atualização, a regra fica bloqueada e nenhuma outra ação de mutação pode atuar na regra. Se você estiver tentando executar outra ação de mutação na mesma regra, receberá uma mensagem dizendo: “A regra de exportação está sendo atualizada por outra solicitação, aguarde e tente novamente mais tarde”. Um usuário pode atualizar uma regra com qualquer status, exceto uma regra excluída.

Desabilitar um stream

Para desabilitar uma regra, você só precisa fornecer o ID da regra. Aqui está um exemplo de desabilitação de um stream:

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

Você só pode desativar a regra quando ela tiver o status ENABLED. Se você estiver tentando desabilitar uma regra que está em outro estado, ela retornará a mensagem de erro: "A regra de exportação não pode ser habilitada ou desabilitada porque o status não é permitido". Você não pode desativar a regra se ela estiver bloqueada devido a outra mutação estar sendo realizada.

Habilitar um fluxo

Se quiser ativar uma regra, você só precisa fornecer o ID da regra. Aqui está um exemplo de ativação de um stream:

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

Você só pode ativar a regra quando ela tiver o status DISABLED. Se você estiver tentando ativar uma regra que está em outro estado, ela retornará uma mensagem de erro como "A regra de exportação não pode ser ativada ou desativada porque o status não é permitido". Você não pode ativar a regra se ela estiver bloqueada devido a outra mutação estar sendo realizada.

Excluir um fluxo

Você precisará fornecer um ID de regra para excluir um stream. Aqui está um exemplo:

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

A exclusão pode ser executada em uma regra de qualquer status, a menos que já tenha sido excluída. Depois que uma regra for excluída, ela não poderá ser reativada novamente. A regra ainda poderá ser visualizada nas primeiras 24 horas após a exclusão, chamando a API steamingRule com o ID da regra. Após 24 horas, a regra não poderá mais ser pesquisada pelo NerdGraph.

Ver transmissões

Você pode consultar informações sobre uma regra de fluxo específica consultando o ID da conta e o ID da regra. Aqui está um exemplo:

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
        }
      }
    }
  }
}

Você também pode consultar todos os streams existentes. Aqui está um exemplo:

{
  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
        }
      }
    }
  }
}

Entenda a compressão de exportação

Opcionalmente, podemos compactar as cargas antes de exportá-las, embora isso esteja desabilitado por padrão. Isso pode ajudar a evitar atingir o limite de dados ingeridos e economizar dinheiro em custos de saída.

Você pode ativar a compactação usando o campo payloadCompression em ruleParameters. Este campo pode ter qualquer um dos seguintes valores:

• DISABLED: a carga não será compactada antes de ser exportada. Se não for especificado, payloadCompression assumirá esse valor como padrão.
• GZIP: Compacte a carga com o formato GZIP antes de exportar

GZIP é o único formato de compactação disponível atualmente, embora possamos optar por disponibilizar mais formatos no futuro.

Quando a compactação está habilitada em uma regra de exportação existente da AWS, a próxima mensagem do Kinesis Firehose pode conter dados compactados e descompactados. Isso se deve ao buffer no Kinesis Firehose. Para evitar isso, você pode desativar temporariamente a regra de exportação antes de ativar a compactação ou criar um novo fluxo do Kinesis Firehose para que apenas os dados compactados possam fluir.

Se você encontrar esse problema e estiver exportando para S3 ou outro sistema de armazenamento de arquivos, poderá visualizar a parte compactada dos dados seguindo estas etapas:

1. Baixe manualmente o objeto.
2. Separe o objeto em dois arquivos separados, copiando os dados compactados em um novo arquivo.
3. Descompacte o novo arquivo de dados somente compactado.

Depois de ter os dados compactados, você pode carregá-los novamente para o S3 (ou qualquer outro serviço que esteja usando) e excluir o arquivo antigo.

Esteja ciente de que no S3 ou outro sistema de armazenamento de arquivos, os objetos podem consistir em vários carregamentos codificados em GZIP que são anexados consecutivamente. Portanto, sua biblioteca de descompactação deve ter a capacidade de lidar com essa carga GZIP concatenada.

Descompactação automática na AWS

Assim que seus dados chegarem à AWS, você pode querer opções para descompactá-los automaticamente. Se você estiver transmitindo esses dados para um bucket S3, há duas maneiras de habilitar a descompactação automática:

Descompactação Automática no Azure

Se você estiver exportando dados para o Azure, será possível visualizar versões descompactadas dos objetos armazenados no hub de eventos usando um Stream Analytics Job. Para fazer isso, siga estas etapas:

1. Siga este guia até a etapa 16.

• Na etapa 13, você pode optar por usar o mesmo hub de eventos que a saída sem quebrar nada, embora não recomendamos isso se você pretende prosseguir para a etapa 17 e iniciar o trabalho, pois isso não foi testado.

2. No painel esquerdo do seu trabalho de análise de streaming, clique em Inputs e, em seguida, clique na entrada que você configurou.
3. Role para baixo até a parte inferior do painel que aparece à direita e configure a entrada com estas configurações:

• formato de serialização de eventos: JSON
• Codificação: UTF-8
• Tipo de compactação de evento: GZip

4. Clique em Save na parte inferior do painel.
5. Clique em Query na lateral da tela. Usando a guia Input preview , agora você poderá consultar o hub de eventos nesta tela.