Signaler une trace au format Zipkin via l'API de trace

Si vous souhaitez créer votre propre implémentation de tracing, vous pouvez utiliser notre API Trace. Ce document explique comment envoyer des données trace au format Zipkin à notre API de trace. (Pour notre format de données général, voir le format New Relic.)

Configuration requise pour la version Zipkin

L'API de trace prend en charge les données de Zipkin JSON v2 (ou supérieur) sans aucune modification. Pour plus de détails sur cette version, voir les détails de la sortieZipkin v2 et le schémaZipkin v2.

Présentation de l'utilisation de l'API de trace

Utiliser notre API de trace est aussi simple que :

Envoi des données de trace au format attendu (dans ce cas, le format zipkin ).
Envoi de ces données au point de terminaisonapproprié

Nos instructions d'envoi de données disposent d'options permettant d'activer l'Infinite Tracing. Pour en savoir plus, consultez Introduction à Infinite Tracing et Considérations relatives à l'échantillonnage.

Pour commencer à utiliser l'API de trace, choisissez une option :

Envoyer un exemple de trace: ceci montre un exemple curl d’envoi d’une trace à New Relic. Ceci est utile pour comprendre le fonctionnement de l'API de trace et pour vérifier que vous voyez des données dans New Relic.
Rapport de données provenant d'une instrumentation Zipkin existante: si vous disposez d'une implémentation Zipkin existante, vous pouvez simplement modifier le point de terminaison vers lequel vos données sont envoyées.

Envoyer un échantillon de charge utile de trace Zipkin

Cette section décrit comment envoyer une trace simple au format Zipkin à notre API de trace via une requête curl . Vous pouvez choisir de le faire afin d’apprendre comment fonctionne notre API et de vérifier que les données s’affichent dans New Relic avant de procéder à une instrumentation approfondie.

Pour commencer à envoyer un exemple de charge utile :

(Facultatif, pour activer l'Infinite Tracing) Tout d'abord, vous devez configurer un observateur de trace. Cette procédure comprend des instructions pour envoyer un exemple de trace en utilisant notre format général new-relic . Lorsque vous arrivez à cette étape, revenez ici pour apprendre à envoyer une trace au format Zipkin.
Envoyez une charge utile au format Zipkin en suivant les instructions ci-dessous.

Envoyer une charge utile au format Zipkin

Pour envoyer un exemple de trace au format Zipkin :

Obtenez le pour le compte auquel vous souhaitez signaler des données.

Vous exécuterez une requête curl ci-dessous. Remarques à ce sujet :

Remplacez l’espace réservé à la clé de licence par votre clé de licence.
Si vous utilisez Infinite Tracing, utilisez la valeur YOUR_TRACE_OBSERVER_URL à la place du point de terminaison standard.
Si vous souhaitez envoyer plusieurs messages, modifiez l'ID de trace par une valeur différente. L'envoi de la même charge ou de la même portée id plusieurs fois pour le même traceId peut entraîner une trace fragmentée dans l'UI.

bash

$curl -i -H 'Content-Type: application/json' \
>    -H 'Api-Key: NEW_RELIC_API_KEY' \
>    -H 'Data-Format: zipkin' \
>    -H 'Data-Format-Version: 2' \
>    -X POST \
>    -d '[
$        {
$            "traceId": "test-zipkin-trace-id-1",
$            "id": "3e0f5885710776cd",
$            "kind": "CLIENT",
$            "name": "post",
$            "duration": 508068,
$            "localEndpoint": {
$                "serviceName": "service-1",
$                "ipv4": "127.0.0.1",
$                "port": 8080
$            },
$            "tags": {
$            }
$        },
$        {
$            "traceId": "test-zipkin-trace-id-1",
$            "parentId": "3e0f5885710776cd",
$            "id": "asdf9asdn123lkasdf",
$            "kind": "CLIENT",
$            "name": "service 2 span",
$            "duration": 2019,
$            "localEndpoint": {
$                "serviceName": "service-2",
$                "ipv4": "127.0.0.1",
$                "port": 8080
$            },
$            "tags": {
$                "error.message": "Invalid credentials"
$            }
$        }
$    ]' 'https://trace-api.newrelic.com/trace/v1'

Dans une minute, la trace devrait être disponible dans notre UI de tracing distribuée. Pour le trouver, exécutez une requête pour le trace.id. Dans cet exemple, c'était test-zipkin-trace-id-1. Notez que vous recherchez par l' attribut transformé de trace.id (et non traceId).

Distributed Tracing Zipkin Integration Searching for sample trace

Pour en savoir plus :

Découvrez où les données de l'API de trace s'affichent dans l'UI.
Envoyer des données à partir d'une instrumentation Zipkin existante.
Apprenez à décorer les travées en ajoutant une balise. Cela vous aide à personnaliser la manière dont les traces sont affichées dans notre UI pour une expérience plus riche et plus utile.
Découvrez les informations générales sur le point de terminaison (limites des données, métadonnées requises et validation des réponses).
Découvrez comment les données Zipkin sont transformées et stockées dans notre format.
Si vous ne voyez pas vos données trace, consultez dépannage.

Envoyer des données à partir de l'instrumentation Zipkin existante

Notes préliminaires :

Si vous souhaitez activer l'Infinite Tracing, vous devez d'abord configurer un observateur de trace.
Il peut être utile d’ envoyer d’abord un exemple de charge utile pour vérifier que tout fonctionne correctement.

Pour signaler des données à partir d'une Zipkin instrumentation existante, vous pointerez le Zipkin traceur vers les points de terminaison d'API appropriés avec certaines métadonnées de requête requises. Vous pouvez envoyer les métadonnées requises sous forme d'en-têtes ou de paramètres de requête (certaines versions du traceur Zipkin ne permettent pas de spécifier des en-têtes HTTP).

Voici un exemple de ce à quoi pourrait ressembler la création d'un Zipkin OkHttpSender en Java configuré pour l'API de trace :

OkHttpSender.create("https://trace-api.newrelic.com/trace/v1?Api-Key=NEW_RELIC_LICENSE_KEY&Data-Format=zipkin&Data-Format-Version=2");

Notez que si vous utilisiez Infinite Tracing ou si vous disposiez d'un compte New Relic dans la région UE, le point de terminaison serait différent.

Pour une explication de Api-Key et des autres métadonnées, voir Demande de métadonnées.

Transformation des données Zipkin

Pour créer une expérience de recherche/requête cohérente, certaines données Zipkin seront transformées pour correspondre à la dénomination des attributs New Relic. Pour en savoir plus sur la manière dont nous stockons et structurons les données trace, consultez Fonctionnement du tracing distribué.

Zipkin tag	Stocké dans New Relic sous le nom...	Détails
`traceId`	`trace.id`	Identifiant unique pour une trace.
`id`	`id`	Identifiant unique pour une durée.
`parentId`	`parent.id`	identifiant du span en amont qui a appelé le service.
`kind`	`kind`	Soit `Client` ou `Server`.
`name`	`name`	Nom de l'envergure.
`duration`	`duration.ms`	Les étendues Zipkin v2 doivent avoir des durées spécifiées en microsecondes et seront converties en millisecondes.
localEndpoint : `serviceName`	`service.name`	Nous utilisons le nom de service Zipkin v2 pour identifier l’entité qui a créé cette plage. Si aucune valeur ou une chaîne vide n'est fournie, l'étendue est attribuée à une entité « INCONNUE » et s'affichera comme telle dans l'UI. Cette valeur doit être fournie pour obtenir une expérience complète dans l'UI.
localEndpoint : `port`	`localEndpoint.port`	Toutes les valeurs de l'objet `localEndpoint` seront aplaties dans un attribut span appelé `localEndpoint.key`
`tags`	signalé comme attribut	les paires valeur clé dans l'objet `tags` dans Zipkin v2 seront écrites comme attribut span.
annotations	non pris en charge	Nous ne prenons actuellement pas en charge les annotations dans l'API de trace. Les étendues ne seront pas rejetées si elles contiennent des annotations, mais les données d'annotations ne seront pas écrites.

Ajouter une autre balise/attribut

Vous pouvez ajouter n'importe quelle balise de votre choix au bloc tags, à l'exception de la balise restreinte. Par exemple, vous souhaiterez peut-être ajouter un attribut tel que customer.id ou user.id pour vous aider à analyser vos données trace . la balise sera convertie en attribut New Relic.

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.