OpenTelemetry Protocol (OTLP) est un protocole de livraison de données télémétriques à usage général conçu pour le projet OpenTelemetry . Chaque OpenTelemetry SDK de langage fournit un exportateur OTLP, et le OpenTelemetry Collector dispose d'un récepteur et d'un exportateur OTLP. De plus, divers outils extérieurs au projet OpenTelemetry ont ajouté la prise en charge de l'exportation OTLP.
New Relic prend en charge l’ingestion OTLP native et la recommande comme méthode préférée pour l’envoi de données OpenTelemetry à la plateforme New Relic. Cette page couvre le support OTLP de New Relic, y compris la configuration, les exigences et les recommandations.
Avant de commencer
Si vous ne l'avez pas déjà fait, créez un compte New Relic gratuit.
Obtenez votre pour le compte New Relic auquel vous souhaitez signaler des données. Cette clé de licence sera utilisée lors de la configuration de l'en-tête
api-key.
Configuration : point de terminaison OTLP, port et protocole
Niveau d'exigence : Obligatoire
Afin de configurer l'envoi de données OTLP à New Relic, vous devez configurer votre exportateur OTLP pour utiliser le point de terminaison et le port appropriés du tableau ci-dessous en fonction de votre environnement.
Le mécanisme de configuration du point de terminaison varie, mais les SDK de langage OpenTelemetry prennent généralement en charge la définition de la variable d'environnement OTEL_EXPORTER_OTLP_ENDPOINT=<INSERT_ENDPOINT> (consultez la documentation OpenTelemetry pour plus d'informations).
De plus, vous devez configurer votre exportateur OTLP pour utiliser la version protobuf binaire OTLP/HTTP du protocole si disponible. Bien que New Relic prenne en charge toutes les versions d'OTLP, le protocole binaire protobuf OTLP/HTTP s'est avéré plus robuste que gRPC sans aucune réduction apparente des performances.
Le mécanisme de configuration du point de terminaison varie, mais les SDK de langage OpenTelemetry prennent généralement en charge la définition de la variable d'environnement OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf (consultez la documentation OpenTelemetry pour plus d'informations).
Si vous utilisez un Collector, nous vous recommandons d'utiliser otlphttpexporter.
Environnement | gRPC | HTTP | Point de terminaison | Ports pris en charge |
|---|---|---|---|---|
OTLP des États-Unis | ✅ | ✅ |
|
|
OTLP de l'UE | ✅ | ✅ |
|
|
JP OTLP | ✅ | ✅ |
|
|
Programme d'action en cas de catastrophe (OTLP) du programme FedRAMP aux États-Unis | ✅ | ✅ |
|
|
Infinite Tracing | ✅ | ✅ |
|
|
Configuration : chiffrement TLS
Niveau d'exigence : Obligatoire
Afin d'envoyer des données OTLP à New Relic, vous devez configurer votre exportateur OTLP pour utiliser TLS 1.2 (voir Chiffrement TLS pour plus d'informations). Généralement, SDK et Collector exportateur répondent à cette exigence par défaut.
Alors que de nombreux exportateurs OTLP déduisent les paramètres TLS du schéma de point de terminaison https, certains exportateurs gRPC peuvent nécessiter que vous activiez explicitement TLS. Le mécanisme de configuration de gRPC TLS varie, mais les SDK de langage OpenTelemetry prennent généralement en charge la définition de la variable d'environnement OTEL_EXPORTER_OTLP_INSECURE=false (voir la documentation OpenTelemetry pour plus d'informations).
Configuration : Définition de la clé API
Niveau d'exigence : Obligatoire
Pour envoyer des données OTLP à New Relic, vous devez configurer votre exportateur OTLP pour inclure un en-tête nommé api-key avec la valeur définie sur votre clé de licence. Le non-respect de cette consigne entraînera des erreurs d’authentification.
Le mécanisme de configuration des en-têtes varie, mais les SDK de langage OpenTelemetry prennent généralement en charge la définition de la variable d'environnement OTEL_EXPORTER_OTLP_HEADERS=api-key=<INSERT_LICENSE_KEY> (consultez la documentation OpenTelemetry pour plus d'informations).
Configuration : limites d'attribut
Niveau requis : Recommandé
New Relic impose diverses limites aux attributs dans les charges OTLP. En général, nous avons une attitude indulgente en matière de validation et nous allons supprimer, tronquer ou modifier autrement les attributs plutôt que de rejeter complètement les données. Chaque fois qu'un attribut est modifié, nous créons une NrIntegrationError pour aider à localiser et à résoudre le problème à la source.
Cas | Description | Configuration pertinente |
Limite de longueur de la valeur de chaîne | Les valeurs d'attribut de type chaîne ont une longueur maximale de 4 095 caractères. Les valeurs dépassant cette limite sont tronquées. | Définissez
. Consultez la pour plus d’informations. |
Limite de longueur de valeur clé | Les clés d'attribut ont une longueur maximale de 255 caractères. Les clés dépassant cette limite sont tronquées. | |
Limite du nombre d’attributs | Chaque source d'attribut est soumise à une limite de nombre. En cas de dépassement, les attributs en excès sont supprimés, en priorisant les attributs définis dans les conventions sémantiques OpenTelemetry. Les limites sont les suivantes :
| Atténuation partielle en définissant
. Consultez la pour plus d’informations. |
Types de valeurs | Les valeurs d'attribut sont limitées aux types : chaîne, entier, double, booléen et éventail d'octets. Les valeurs d'attribut avec des types complexes sont élaguées. Les attributs de log sont exclus de cette limite. [1] | |
Valeurs non définies | Les valeurs d'attribut doivent être définies (c.-à-d.
). Les attributs avec des valeurs non définies sont supprimés. Remarque : les
s ne sont pas créés dans ce cas, car cela se produit assez fréquemment pour que
masque des problèmes de validation plus exploitables. | |
Limite de longueur d'éventail | Les éventails ont une longueur maximale de 64 entrées. Les attributs dépassant cette limite sont supprimés. | |
Homogénéité de l'éventail | Les entrées d'éventails doivent toutes être du même type. Les attributs avec des entrées d'éventail hétérogènes sont supprimés. Les attributs de log sont exclus de cette limite. [1] | |
Entrées d'éventail non définies | Les entrées d'éventail ne doivent pas être non définies (c.-à-d.
). Les entrées d'éventail non définies sont supprimées. | |
Types de valeurs d'entrée d'éventail | Les entrées d'éventail sont limitées aux types : chaîne, entier, double et booléen. Les valeurs d'attribut d'éventail avec des types complexes sont élaguées. Les attributs de log sont exclus de cette limite. [1] | |
Limite de longueur d'éventail d'octets | Les éventails d'octets ont une longueur maximale de 128 000. Les attributs dépassant cette limite sont supprimés. | |
Types de valeurs d’attribut | Les valeurs d'attribut sont limitées aux types : chaîne, entier, double, booléen et éventail d'octets. Les valeurs d'attribut avec des types complexes sont élaguées. Les attributs de log sont exclus de cette limite. [1] |
[1]: voir les types d'attribut OTLP.
Voir limites d'attributs métriques et limites d'attributs d'événement pour d'autres limites.
Configuration : traitement par lots de la charge utile, délai d'expiration, compression et limites de débit
Niveau d'exigence : Obligatoire
Afin d'envoyer des données OTLP à New Relic, votre charge doit être inférieure à la taille de charge maximale de 1 Mo (10^6 octets). Les frais plus élevés seront rejetés avec un code d'état d'erreur. Des frais plus élevés peuvent également ne pas être exportés en raison d'un délai d'attente avant qu'un code d'état d'erreur ne soit renvoyé.
De plus, New Relic impose des limites de débit. Lorsque la limite de débit est dépassée, requests seront rejetées avec un code d'état d'erreur.
Pour éviter les limites de taille de charge utile et de débit, vous devez configurer votre exportateur OTLP pour utiliser une taille de lot appropriée qui entraîne l'exportation des données à un intervalle approprié.
Le mécanisme de configuration du traitement par lots varie. Les SDK OpenTelemetry prennent généralement en charge la définition des variables d'environnement suivantes (consultez la documentation OpenTelemetry pour plus d'informations) :
OTEL_BSP_*pour les travéesOTEL_METRIC_EXPORT_*pour les métriquesOTEL_BLRP_*pour les logs
Si vous utilisez le Collector, le processeur de lots contrôle la taille du lot.
De plus, vous devez prêter attention aux paramètres de délai d’expiration de l’exportateur. En général, requests d'exportation prennent plus de temps lorsque les frais sont plus élevés et lorsque les réseaux sont plus lents (latence plus élevée, bande passante plus faible). Si votre application génère des charges importantes parce que le volume de télémétrie est élevé ou que l'intervalle d'exportation est élevé, vous devrez peut-être augmenter les paramètres de délai d'expiration par défaut pour éviter les erreurs d'exportation.
Le mécanisme de configuration du délai d'expiration varie, mais les SDK de langage OpenTelemetry prennent généralement en charge la définition de la variable d'environnement OTEL_EXPORTER_OTLP_TIMEOUT (consultez la documentation OpenTelemetry pour plus d'informations).
De plus, vous devez activer la compression pour réduire la taille de la charge utile et limiter la probabilité de rencontrer des limites de taille de charge utile. New Relic prend en charge les compressions gzip et zstd . La compression zstd offre des performances supérieures et est recommandée si votre exportateur la prend en charge. Voir la comparaison de compression pour plus de détails sur les informations d'évaluation.
Le mécanisme de configuration du point de terminaison varie, mais les SDK de langage OpenTelemetry prennent généralement en charge la définition de la variable d'environnement OTEL_EXPORTER_OTLP_COMPRESSION=gzip (consultez la documentation OpenTelemetry pour plus d'informations).
Si vous utilisez le Collector, gzip est la compression par défaut, mais vous pouvez éventuellement configurer zstd.
Configuration : Réessayer
Niveau requis : Recommandé
Afin d'envoyer des données OTLP à New Relic, vous devez configurer votre exportateur OTLP pour réessayer lorsque des erreurs transitoires se produisent. Internet n’est pas fiable et l’échec d’une nouvelle tentative augmente le risque de perte de données.
Le mécanisme de configuration de la nouvelle tentative varie. Certains SDK OpenTelemetry peuvent avoir des variables d'environnement spécifiques à la langue (par exemple, Java prend en charge le paramètre OTEL_EXPERIMENTAL_EXPORTER_OTLP_RETRY_ENABLED=true), mais il n'existe pas de mécanisme général. Une configuration programmatique peut être requise.
Si vous utilisez le Collector, otlphttpexporter et otlpexporter réessayent par défaut. Voir exporterhelper pour plus de détails.
Config : temporalité d'agrégation métrique
Niveau requis : Recommandé
Afin d'envoyer des données métriques OTLP à New Relic, vous devez configurer votre exportateur de métriques OTLP pour préférer la temporalité d'agrégation delta. Bien que New Relic prenne en charge la temporalité d'agrégation cumulative, l'architecture des métriques New Relic est généralement un système de métriques delta. L'utilisation du paramètre cumulatif par défaut entraînera généralement une utilisation plus importante de la mémoire des SDK et entraînera une ingestion élevée de données.
Le mécanisme de configuration du point de terminaison varie, mais les SDK de langage OpenTelemetry prennent généralement en charge la définition de la variable d'environnement OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE=delta (consultez la documentation OpenTelemetry pour plus d'informations). Si vous définissez manuellement la temporalité, configurez par type d'instrument comme suit :
- Compteur, Compteur asynchrone, Histogramme : Delta
- Compteur asynchrone, compteur asynchrone, jauge, jauge asynchrone : cumulatif
La temporalité cumulative est utilisée pour les instruments qui correspondent aux types de jauge New Relic et qui sont généralement analysés à l'aide de la valeur cumulative.
Config : agrégation d'histogrammes métriques
Niveau requis : Recommandé
Afin d'envoyer des données de métriques OTLP à New Relic, vous devez configurer votre exportateur de métriques OTLP pour agréger les mesures des instruments d'histogramme en histogrammes exponentiels. Contrairement aux compartiments statiques utilisés avec l'histogramme de compartiment explicite par défaut, l'histogramme exponentiel ajuste automatiquement ses compartiments pour refléter la plage de mesures enregistrées. De plus, ils utilisent une représentation hautement compressée pour envoyer via le réseau. L'histogramme exponentiel fournit des données de distribution plus utiles sur la plateforme New Relic.
Le mécanisme de configuration du point de terminaison varie, mais les SDK de langage OpenTelemetry prennent généralement en charge la définition de la variable d'environnement OTEL_EXPORTER_OTLP_METRICS_DEFAULT_HISTOGRAM_AGGREGATION=base2_exponential_bucket_histogram (consultez la documentation OpenTelemetry pour plus d'informations).
Version du protocole OTLP
New Relic utilise la sortie OTLP v1.4.0. Les versions ultérieures et antérieures sont prises en charge, mais les nouvelles fonctionnalités ne sont pas encore implémentées. Les fonctionnalités expérimentales qui ont été supprimées après la version 0.18.0 ne sont pas prises en charge.
Consultez trace, Métriques et log pour obtenir des détails spécifiques sur la manière dont les données sont mappées et sur les fonctionnalités implémentées.
Types d'attributs OTLP
Les attributs sont un concept récurrent dans OpenTelemetry et OTLP. OpenTelemetry dispose d'une définition d'attribut standard , indiquant que les valeurs d'attribut sont des primitives (chaîne, booléen, double virgule flottante, entier 64 bits) ou un éventail homogène de primitives. Cependant, au niveau du protocole OTLP, les attributs sont représentés à l'aide d'une définition AnyValue plus étendue. De ce fait, il est possible pour les clients OTLP d'envoyer des attributs qui ne sont pas conformes à la définition standard OpenTelemetry .
Le point de terminaison New Relic OTLP prend en charge la définition d’attribut standard. Les types complexes tels que les cartes de cartes, les éventails d'objets et les éventails hétérogènes ne sont pas pris en charge. Les SDK OpenTelemetry ne doivent produire que des données conformes à la définition d'attribut standard.
Important
Bien que la définition d'attribut standard soit généralement utilisée, les attributs d'enregistrement de log sont exceptionnels et prennent en charge des valeurs complexes (par exemple, le type d'attribut d'enregistrement log est map<string, any>). Malgré cela, New Relic ne prend actuellement en charge que les attributs d'enregistrement de log conformes à la définition d'attribut standard.
Frais de réponse OTLP
Veuillez noter les détails suivants concernant les frais de réponse au point de terminaison OTLP de New Relic :
- Les réponses réussies de New Relic n'ont pas de corps de réponse, au lieu d'une réponse codée Protobuf basée sur le type de données.
- New Relic répond après validation de l'authentification, de la taille de la charge utile et de la limitation du débit. La validation du contenu de la charge utile se produit de manière asynchrone. Par conséquent, New Relic peut renvoyer des codes d'état de réussite même si l'ingestion des données échoue finalement et entraîne l'événement
NrIntegrationError. - Les réponses d’échec de New Relic n’incluent pas
Status.messageouStatus.details.