Tutorial NerdGraph: Retorne respostas NRQL maiores com exportação de dados históricos

Ao executar uma consulta NRQL, você fica restrito a vários limites, como um limite no número de pontos de dados retornados em uma resposta e um tempo limite de consulta. Nosso recurso de exportação de dados históricos pode ser usado para executar uma consulta NRQL que retorna 200 milhões de pontos de dados em uma resposta (em vez do limite usual de 5.000) e não tem tempo limite de consulta. Os resultados são retornados como um ou mais arquivos JSON.

Requisitos

Requer Dados Plus
Para exportar dados, você deve ser um usuário principal ou completo da plataforma

Limites e restrições

Aqui estão alguns limites e restrições do recurso:

Limites de uso

A seguir estão os limites de uso padrão para uma exportação:

Estima-se que as exportações retornem menos de 200 milhões de eventos
As exportações devem ser estimadas em menos de 5 bilhões de eventos
Não mais do que duas exportações simultâneas por conta

Se desejar limites mais altos, fale com seu representante de conta.

Restrições de tipo de dados

Nenhum dos seguintes tipos de dados está disponível para exportação:

Restrições de intervalo de tempo

O recurso de exportação de dados históricos não oferece suporte à consulta de dados em tempo real ou das últimas 12 horas. O intervalo de tempo deve terminar pelo menos 12 horas atrás.

Requisitos de sintaxe de consulta

Este recurso suporta a seleção de nomes de atributos específicos e curingas (SELECT *). Por exemplo, apoiamos consultas como estas:

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'

Os seguintes componentes NRQL cannot serão usados na consulta:

Funções de agregação (sum, count, average, max)
Funções avaliáveis (numeric, log, concat) são suportadas apenas na cláusula WHERE
FACET
TIMESERIES
COMPARE WITH
JOIN
Agregações aninhadas
Subconsultas
Ligações de variáveis
Consulta entre contas

Detalhes endpoint

O recurso de exportação de dados históricos usa nossa API NerdGraph e faz uso de três endpoints:

O endpoint create permite que um usuário especifique o ID da conta e o NRQL que deseja executar como uma exportação.
O endpoint get details for export permite que um usuário especifique um ID de conta e um ID de exportação (encontrado no corpo da resposta do endpoint de criação) e use-os para recuperar o status da exportação. Quando a exportação for concluída, os resultados, na forma de um ou mais URLs de download, poderão ser encontrados na resposta deste endpoint.
O endpoint get details for account exports permite que um usuário especifique um ID de conta e recupere os detalhes de todas as exportações ativas e não expiradas dessa conta.

Exemplo de consulta

Criar exportação

Uma maneira de usar o NerdGraph é com o explorador NerdGraph. As instruções nesta seção se concentrarão no uso do explorador NerdGraph. Se você estiver interessado em executar seu próprio script, consulte script.

No esquema NerdGraph, o endpoint historicalDataExportCreateExport pode ser encontrado em mutation > historicalDataExport. Use uma consulta como a abaixo para executar uma exportação.

Recomenda-se selecionar o ID para o corpo da resposta, pois ele será usado para obter detalhes para a exportação e recuperar resultados.

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

Resposta de exemplo

Aqui está um exemplo de resposta para criar uma exportação:

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

Cancelar exportação

No esquema NerdGraph, o endpoint historicalDataExportCancelExport pode ser encontrado em mutation > historicalDataExport. Use uma consulta como a abaixo para executar uma exportação.

É recomendado selecionar o status no corpo da resposta para verificar se a exportação foi cancelada com sucesso.

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

Resposta de exemplo

Aqui está um exemplo de resposta para cancelar uma exportação:

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

Obtenha detalhes de uma exportação específica

Use o ID de exportação encontrado na resposta do endpoint de criação para consultar os detalhes da exportação, conforme mostrado abaixo. Este endpoint pode ser encontrado no NerdGraph em 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
        }
      }
    }
  }
}

Resposta de exemplo

Aqui está a resposta para obter os detalhes de uma exportação específica:

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

Obtenha detalhes de exportação de uma conta

Você pode usar o ID da conta para obter os detalhes de todas as exportações dessa conta, conforme mostrado abaixo. O endpoint pode ser encontrado no esquema NerdGraph em query > actor > account > historicalDataExport > exports.

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

Resposta de exemplo

Aqui está um exemplo de resposta para obter detalhes de exportação de uma conta:

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

Usar roteiro

Pode ser útil consultar os dados históricos das exportações de forma programática, a partir de um script. Os seguintes comandos curl podem ser úteis para começar. Para exemplos de respostas, consulte as respostas na seção Exemplo de consulta.

Importante

Você deve escapar de todas as instâncias de aspas simples (') em sua consulta NRQL de exportação com uma barra invertida (\'). Os comandos curl abaixo dependem de um $ inicial no argumento --data-raw , cuja funcionalidade a citação ANSI-C fornece. Mais informações estão disponíveis através do manual oficial do GNU.

Criar exportação

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":{}}'

Cancelar exportação

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":{}}'

Obtenha detalhes para exportação

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":{}}'

Obtenha detalhes para exportações de conta

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":{}}'

Exportar formato de resultados

Os resultados da consulta estão no campo de resultados de qualquer um dos dois pontos de extremidade get details . Eles estão na forma de um ou mais links para download. Os próprios arquivos de resultados são válidos por uma semana a partir da execução da exportação e contêm aproximadamente 100 MB ou menos de JSON compactado GZIP. Cada link é pré-assinado para ser válido por 6 horas. Se o link expirar, você poderá obter um novo consultando novamente o objeto de detalhes de exportação no NerdGraph para obter os resultados.

Um exemplo de arquivo de resultados descompactado está abaixo:

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

Consulta e alerta sobre evento relacionado à exportação

Este recurso irá gerar um evento personalizado na conta New Relic em que a exportação foi realizada. Pode ser útil consultar ou criar alertas sobre estes eventos para obter informações sobre as exportações que foram realizadas numa conta.

O tipo de evento HistoricalDataExport contém informações como o status da exportação (Created, Completed, Failed, Canceled), o ID da exportação, a string NRQL a partir da qual a exportação é gerada e muito mais.

A consulta a seguir, que você pode executar no criador de consulta ou adicionar em um dashboard, retornará todas as exportações criadas na última semana e a quantidade daquelas que foram concluídas com sucesso e não tiveram erro:

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

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

Resolução de problemas

Conta ainda não ativada

Ao tentar criar uma exportação, você poderá ver uma mensagem de erro que diz:

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

Se você receber isso, provavelmente significa que o recurso de exportação de dados históricos ainda não foi habilitado para a conta da qual você está tentando exportar. Caso tenha dúvidas, revise os requisitos e fale com seu representante de conta para perguntar sobre o acesso.

O link dos resultados expirou

Ao tentar fazer download dos resultados usando um URL pré-assinado, você poderá ver um erro como este:

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

Um erro como esse indica que o URL de resultados expirou e você precisará consultar novamente o objeto de exportação para obter um novo URL de resultados. Você não precisa executar novamente a exportação, basta obter um novo conjunto de URLs para os resultados.

Esta tradução de máquina é fornecida para sua comodidade.

Tutorial NerdGraph: Retorne respostas NRQL maiores com exportação de dados históricos

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

Limites e restrições

Limites de uso

Restrições de tipo de dados

Restrições de intervalo de tempo

Requisitos de sintaxe de consulta

Detalhes endpoint

Exemplo de consulta

Criar exportação

Resposta de exemplo

Cancelar exportação

Resposta de exemplo

Obtenha detalhes de uma exportação específica

Resposta de exemplo

Obtenha detalhes de exportação de uma conta

Resposta de exemplo

Usar roteiro

Importante

Criar exportação

Cancelar exportação

Obtenha detalhes para exportação

Obtenha detalhes para exportações de conta

Exportar formato de resultados

Consulta e alerta sobre evento relacionado à exportação

Resolução de problemas

Conta ainda não ativada

O link dos resultados expirou

Requisitos