Point de terminaison New Relic OTLP

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 clé de licencepour 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.

OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://otlp.nr-data.net:4318/v1/traces

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 d'exigence : Obligatoire

Afin d'envoyer des données OTLP à New Relic, vous devez configurer votre source de télémétrie pour qu'elle soit conforme aux limites d'attributs de New Relic. Le non-respect de cette consigne peut entraîner un événement NrIntegrationError lors de la validation asynchrone des données.

Les limites d'attribut sont les suivantes :

• Longueur maximale du nom de l'attribut : 255 caractères
• Longueur maximale de la valeur de l'attribut : 4 095 caractères
• Taille maximale de la valeur de l'attribut éventail : 64 entrées

Voir limites d'attributs métriques et limites d'attributs d'événement pour d'autres limites.

Le mécanisme de configuration des limites d'attribut varie, mais les SDK de langage OpenTelemetry prennent généralement en charge la définition des variables d'environnement OTEL_ATTRIBUTE_VALUE_LENGTH_LIMIT=4095 et OTEL_ATTRIBUTE_COUNT_LIMIT=64 (consultez la documentation OpenTelemetry pour plus d'informations).

Lorsque vous utilisez le collecteur, vous pouvez configurer le processeur de transformation pour tronquer l'attribut aux limites de New Relic.

Remarques :

• Les attributs de ressources sont soumis à des limites d'attributs, mais il n'existe pas de variables d'environnement standard pour les limiter. Si un attribut de ressource dépasse la limite autorisée, envisagez de le tronquer à l'aide du processeur Collector de transformation ou d'écraser l'attribut de ressource avec une autre valeur.
• Il n’existe pas de mécanisme standard pour limiter les noms d’attributs. Cependant, l'instrumentation ne produit généralement pas de noms d'attributs qui dépassent les limites de New Relic. Si vous rencontrez des limites de longueur de nom, supprimez l'attribut à l'aide du Collector.

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ées
• OTEL_METRIC_EXPORT_* pour les métriques
• OTEL_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 asynchrone Compteur 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.

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.message ou Status.details.