Signaler une trace via l'API de trace (format New Relic)

Si vous souhaitez créer votre propre implémentation de tracing, vous pouvez utiliser notre API Trace. Ce document explique comment envoyer une trace dans notre format général, également connu sous le nom de format newrelic . (Pour envoyer des données au format Zipkin, voir Zipkin.)

Démarrer

Utiliser notre API de trace est aussi simple que :

• Envoi des données de trace au format attendu (dans ce cas, notre format newrelic ).
• Envoi de ces données au point de terminaison approprié.

Avant d’utiliser l’API de trace, vous devez décider si vous souhaitez utiliser Infinite Tracing. Pour en savoir plus, consultez Introduction à Infinite Tracing et Considérations relatives à l'échantillonnage.

Pour commencer à utiliser l’API de trace, suivez l’un de ces chemins :

• Vous souhaitez utiliser Infinite Tracing? Suivez les instructions pour configurer un observateur de trace . Cela vous guide tout au long de la création d’un observateur de trace et de l’envoi d’un exemple de charge utile au point de terminaison de l’observateur de trace.
• Vous ne voulez pas d'Infinite Tracing ? Découvrez comment envoyer un exemple de charge utile (ci-dessous).

Envoyer un échantillon de charge utile de trace (non-Infinite Tracing)

Ce qui suit explique comment envoyer une charge utile standard (nonInfinite Tracing) à l'API Trace à l'aide de notre format newrelic .

1. Obtenez un clé de licencepour le compte auquel vous souhaitez signaler des données.

2. Insérez cette clé dans le JSON suivant, puis envoyez le JSON à notre point de terminaison. Remarque : si vous disposez d'un compte New Relic UE, utilisez plutôt le point de terminaison UE .

   bash

   Copier

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

   Conseil

   Si vous envoyez plusieurs POST, remplacez le trace.id par une valeur unique. L'envoi de la même charge ou de la même portée id plusieurs fois pour le même trace.id peut entraîner une trace fragmentée dans l'UI.

3. Si votre test a renvoyé HTTP/1.1 202 Accepted, accédez à notre UI pour voir une requête de vos données de test à l'aide de l'attribut span service.name = Test Service A.

   Conseil

   Le traitement de la trace par l'observateur de trace et l'API de trace peut prendre jusqu'à une minute.

trace des frais d'API (format New Relic)

L'API de trace JSON charge est un ensemble d'objets, chaque objet représentant une seule trace. Chacun de ces objets nécessite une clé spans et peut également inclure une clé common . spans (obligatoire) contient un éventail d'objets, chaque objet représentant une étendue. common (facultatif) partage des informations sur plusieurs étendues.

L'objet Span dans l'éventail spans

Les demandes sans les clés requises ci-dessus seront rejetées et un NrIntegrationError sera généré.

L'objet common (facultatif)

Attribut hautement recommandé

Bien que cela ne soit pas obligatoire, ces attributs doivent être inclus pour une expérience optimale avec vos données dans l'objet attributes pour chaque plage.

Attribut réservé

Ces attributs sont actuellement réservés à l'utilisation interne de New Relic. Bien qu'ils ne soient pas explicitement bloqués, nous vous recommandons de ne pas les utiliser.

Autre attribut

Vous pouvez ajouter n'importe quel attribut arbitraire que vous souhaitez dans l'objet attributes dans common ou dans chaque objet span, à l'exception de l' attribut restreint. Par exemple, vous souhaiterez peut-être ajouter un attribut tel que customer.id ou user.id pour vous aider à analyser vos données trace .

Exigences et directives pour trace JSON à l'aide du format newrelic :

• Chaque charge JSON est un ensemble d'objets.
• Chaque objet doit contenir une clé spans obligatoire.
• Chaque objet peut contenir une clé common facultative. Utilisez ceci si vous souhaitez partager des informations sur plusieurs zones d’un objet.
• Toutes les clés d’un segment ont la priorité sur la même clé dans le bloc common .
• La valeur d'une clé spans est une liste d'objets span .
• Certains attributs sont obligatoires et doivent être inclus soit dans le bloc facultatif common, soit dans chaque étendue.
• Les attributs recommandés et personnalisés peuvent être éventuellement inclus dans une liste de paires valeur-clé sous une clé nommée attributes, dans le bloc facultatif common et/ou dans chaque étendue.

Dans l'exemple suivant POST, il y a deux étendues, toutes deux dotées du trace.id 12345 et de l'attribut personnalisé host: host123.example.com. Le premier span n'a pas parent.id, il s'agit donc de la racine de la trace ; le parent.id du deuxième span pointe vers l'ID du premier.

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

Pour savoir comment contrôler la manière dont les étendues s'affichent dans New Relic (par exemple, en ajoutant des erreurs ou en définissant une étendue comme étendue de datastore ), consultez Décorer les étendues.

En savoir plus sur le tracing distribué :

• Découvrez où les données de l'API de trace s'affichent dans l'UI.
• Découvrez comment décorer les étendues pour une expérience d' UI plus riche et plus détaillée. Par exemple, vous pouvez faire en sorte que les étendues s'affichent comme des étendues datastore ou afficher des erreurs.
• En savoir plus sur les limites générales des données, les métadonnées requises et la validation des réponses.
• Si vous ne voyez pas vos données trace, consultez dépannage.