Relatar rastreamento por meio da API trace (formato New Relic)

Se quiser criar sua própria implementação de rastreamento, você pode usar nossa API Trace. Este documento explica como enviar trace em nosso formato geral, também conhecido como formato newrelic . (Para enviar dados no formato Zipkin, consulte Zipkin.)

Iniciar

Usar nossa API trace é tão simples quanto:

• Enviando dados trace no formato esperado (neste caso, nosso formato newrelic).
• Enviando esses dados para o endpoint apropriado.

Antes de usar a API trace , você deve decidir se deseja usar o Infinite Tracing. Para saber mais sobre isso, consulte Introdução às considerações sobre rastreamento e amostragem infinita .

Para começar a usar a API trace , siga um destes caminhos:

• Quer usar o rastreamento infinito? Siga as instruções Configurar um observador de rastreamento . Isso orienta você na criação de um observador trace e no envio de uma carga útil de amostra para o endpoint do observador trace .
• Não quer rastreamento infinito? Veja como enviar um exemplo de carga útil (abaixo).

Enviar carga útil trace de amostra (rastreamento não infinito)

Veja a seguir como enviar uma carga padrão (nãoInfinite Tracing) para a API Trace usando nosso formato newrelic .

1. Obtenha um chave de licençapara a conta para a qual você deseja relatar dados.

2. Insira essa chave no JSON a seguir e envie o JSON para nosso endpoint. Observação: se você tiver uma conta EU New Relic, use o endpoint EU .

   bash

   Copiar

   $
   curl -i -H 'Content-Type: application/json' \
   >
       -H 'Api-Key: YOUR_LICENSE_KEY' \
   >
       -H 'Data-Format: newrelic' \
   >
       -H 'Data-Format-Version: 1' \
   >
       -X POST \
   >
       -d '[
   $
               {
   $
                   "common": {
   $
                       "attributes": {
   $
                           "service.name": "Test Service A",
   $
                           "host": "host123.example.com"
   $
                       }
   $
                   },
   $
                   "spans": [
   $
                       {
   $
                           "trace.id": "123456",
   $
                           "id": "ABC",
   $
                           "attributes": {
   $
                               "duration.ms": 12.53,
   $
                               "name": "/home"
   $
                           }
   $
                       },
   $
                       {
   $
                           "trace.id": "123456",
   $
                           "id": "DEF",
   $
                           "attributes": {
   $
                               "error.message": "Invalid credentials",
   $
                               "service.name": "Test Service A",
   $
                               "host": "host456.example.com",
   $
                               "duration.ms": 2.97,
   $
                               "name": "/auth",
   $
                               "parent.id": "ABC"
   $
                           }
   $
                       }
   $
                   ]
   $
               }
   $
           ]' 'https://trace-api.newrelic.com/trace/v1'

   Dica

   Se você estiver enviando mais de um POST, altere trace.id para um valor exclusivo. Enviar a mesma carga útil ou intervalo id diversas vezes para o mesmo trace.id pode resultar em rastreio fragmentado na interface.

3. Se o seu teste retornou HTTP/1.1 202 Accepted, acesse nossa interface para ver uma consulta dos seus dados de teste usando o atributo span service.name = Test Service A.

   Dica

   Trace pode levar até um minuto para ser processado pelo observador trace e pela API trace .

Carga de API trace (formato New Relic)

A carga útil JSON da API trace é uma matriz de objetos, com cada objeto representando um único trace. Cada um desses objetos requer uma chave spans e também pode incluir uma chave common . spans (obrigatório) contém uma matriz de objetos, com cada objeto representando um intervalo. common (opcional) compartilha informações em vários períodos.

O objeto Span na matriz spans

Solicitações sem as chaves exigidas acima serão rejeitadas e um NrIntegrationError será gerado.

O objeto common (opcional)

Atributo altamente recomendado

Embora não sejam obrigatórios, esses atributos devem ser incluídos para obter a melhor experiência com seus dados no objeto attributes de cada período.

Atributo reservado

Esses atributos estão atualmente reservados para uso interno da New Relic. Embora não estejam explicitamente bloqueados, recomendamos não usá-los.

Outro atributo

Você pode adicionar qualquer atributo arbitrário desejado no objeto attributes em common ou em cada objeto span, com exceção do atributo restrito. Por exemplo, talvez você queira adicionar um atributo como customer.id ou user.id para ajudá-lo a analisar seus dados trace .

Requisitos e diretrizes para trace JSON usando o formato newrelic:

• Cada carga JSON é uma matriz de objetos.
• Cada objeto deve conter uma chave spans obrigatória.
• Cada objeto pode conter uma chave common opcional. Use isto se quiser compartilhar informações entre vários spans em um objeto.
• Quaisquer chaves em um intervalo têm precedência sobre a mesma chave no bloco common .
• O valor de uma chave spans é uma lista de objetos span .
• Determinados atributo são obrigatórios e devem ser incluídos no bloco opcional common ou em cada período.
• Recomendado e atributo personalizado podem ser incluídos opcionalmente em uma lista de pares de valores principais sob uma chave denominada attributes, no bloco opcional common e/ou em cada intervalo.

No exemplo a seguir POST, existem dois spans, ambos possuem o trace.id 12345 e o atributo personalizado host: host123.example.com. O primeiro intervalo não tem parent.id, então essa é a raiz do trace; o parent.id do segundo intervalo aponta para o ID do primeiro.

[
  {
    "common": {
      "attributes": {
        "host": "host123.example.com"
      }
    },
    "spans": [
      {
        "trace.id": "12345",
        "id": "abc",
        "timestamp": 1603336834823,
        "attributes": {
          "user.email": "bob@newr.com",
          "service.name": "my-service",
          "duration.ms": 750,
          "name": "my-span"
        }
      },
      {
        "trace.id": "12345",
        "id": "def",
        "timestamp": 1603336834899,
        "attributes": {
          "parent.id": "abc",
          "service.name": "second-service",
          "duration.ms": 750,
          "name": "second-span"
        }
      }
    ]
  }
]

Para saber como controlar como os spans aparecem no New Relic (por exemplo, adicionando erros ou definindo um span como um span de armazenamento de dados), consulte Decorar spans.

Explore mais sobre distributed tracing:

• Saiba onde os dados da API trace aparecem na interface.
• Aprenda como decorar vãos para obter uma experiência de interface mais rica e detalhada. Por exemplo, você pode fazer com que os intervalos apareçam como intervalos de armazenamento de dados ou exibam erros.
• Saiba mais sobre limites gerais de dados, metadados necessários e validação de resposta.
• Se você não vir seus dados de rastreamento, consulte resolução de problemas.