Informations sur les exigences en matière de données de l'API Trace, notamment :
- Spécifications des données et limites maximales
- Métadonnées obligatoires (en-têtes, paramètres de requête)
- Détails de validation de la réponse
Ce document s’applique à l’ensemble de l’API de trace. Pour les règles concernant les formats de données spécifiques, voir :
Point de terminaison
Toutes les données trace sont envoyées via HTTPS POST à un point de terminaison d'API de trace. Nous avons quelques points de terminaison, en fonction de votre configuration :
- Points de trace par défaut de terminaison d'API :
https://trace-api.newrelic.com/trace/v1 - Centre de données de l'UE :
https://trace-api.eu.newrelic.com/trace/v1(voir autre point de terminaison de l'UE). - Infinite Tracing: lorsque vous terminez la configuration de l’observateur de trace, vous obtenez une valeur YOUR_TRACE_OBSERVER_URL personnalisée à utiliser comme point de terminaison. Si vous utilisez une intégration qui utilise l'API de trace (par exemple, le reporter Kamon), vous devez configurer cette intégration avec ce point de terminaison. Vous souhaiterez également ajuster l' échantillonnage de votre service de tracing pour nous envoyer 100 % des portées.
- FedRAMP : Voir point de terminaison FedRAMP.
Formats de données
Actuellement, l'API de trace accepte deux types de formats de données :
zipkin: pour signaler les données de trace Zipkin. Les données Zipkin doivent être Zipkin JSON v2.newrelic: pour signaler toutes les autres données de trace.
Attribut restreint
Les attributs du tableau ci-dessous sont restreints au format JSON newrelic (dans le bloc attributes ) et au format JSON zipkin (dans le bloc tags ). Any values with these keys will be omitted:
Attribut restreint | Description |
|---|---|
chaîne | Identifiant unique de l'entité qui a créé cette travée. Généré à partir de |
chaîne | Utilisé pour la compatibilité descendante avec les données des agents . |
Les attributs du tableau ci-dessous sont utilisés en interne pour identifier l'entité. Toutes les valeurs soumises avec ces clés dans la section d'attribut d'un point de données métrique peuvent provoquer un comportement indéfini tel qu'une entité manquante dans l'UI ou une télémétrie ne s'associant pas à l'entité attendue. Pour plus d'informations, veuillez vous référer à la synthèse d'entité:
Attribut restreint | description |
|---|---|
chaîne | Identifiant unique de l'entité associée à cette travée. |
chaîne | Nom lisible par l'homme d'une entité, souvent utilisé pour identifier une entité dans l'UI. |
chaîne | Utilisé pour différencier les différents types d'entités, comme les hôtes, les applications, etc. |
Requêtes métadonnées (en-têtes et paramètres de requête)
Le tableau suivant présente les métadonnées de demande requises pour tous les formats de données de trace. Cette métadonnées peut être envoyée sous forme d'en-têtes HTTP lors d'une demande d'ingestion ou, dans certains cas, fournie sous forme de paramètres de requête, qui peuvent être nécessaires pour le tracing des frameworks qui n'autorisent pas la modification des en-têtes.
Important
Remarque de sécurité : nous vous suggérons d'utiliser des en-têtes car les paramètres de requête sont présents dans l'URL et peuvent être enregistrés avant d'être chiffrés et reçus par New Relic. Toutes les données envoyées en tant que paramètres de requête doivent être sécurisées en termes d'URL.
En-tête | Paramètre de requête ? | Détails |
|---|---|---|
| Non | Required. Doit être |
| Non | Required. La longueur du corps de la requête en octets (octets de 8 bits), sauf si elle est envoyée avec un codage en morceaux. Cet en-tête est généralement défini par défaut par le client HTTP sous-jacent qui envoie les données et, dans la plupart des cas, ne devrait pas nécessiter d'effort supplémentaire de la part de l'utilisateur final. |
| Oui (sensible à la casse) | Required. L'API de trace nécessite un . Si cela est fourni à la fois comme en-tête et comme paramètre de requête, les valeurs doivent correspondre. |
| Non | Required if compressed payload. La valeur doit être |
| Oui | Required for Si présent, |
| Oui | Required for Si présent, Il n'y a que deux appariements possibles pour ces valeurs :
|
| Non | Optional - Reserved for future use. La valeur doit être un |
Validation des réponses
Une réponse pour l’envoi réussi de données de trace inclura un requestId. Par exemple:
{ "requestId": "c1bb62fc-001a-b000-0000-016bb152e1bb" }Il existe deux manières de signaler les succès/erreurs :
HTTP status code (synchrone). Les erreurs d'authentification et de demande seront signalées via le code d'état HTTP.
NrIntegrationErrorévénement (asynchrone). Les erreurs liées à la charge JSON ou d'autres erreurs sémantiques sont signalées de manière asynchrone via l'événementNrIntegrationErrorqui est stocké dans le compte dont est associé à la requête. Pour toutes les erreurs de ce type, l'attributnewRelicFeatureseraDistributed TracingetrequestIdsera lerequestIdde la réponse du point de terminaison.
Si vous recevez une réponse 202 et ne voyez pas d'événement NrIntegrationError, vos données devraient être visibles dans notre UI de tracing distribué globale dans environ une minute. Vous devriez pouvoir trouver la trace en utilisant une recherche de trace standard comme :
traceId = TRACE_ID_SENTLimites de données
Pour connaître les limites liées trace, consultez Comment fonctionne le tracing distribué.