• /
  • EnglishEspañolFrançais日本語한국어Português
  • Se connecterDémarrer

Cette traduction automatique est fournie pour votre commodité.

En cas d'incohérence entre la version anglaise et la version traduite, la version anglaise prévaudra. Veuillez visiter cette page pour plus d'informations.

Créer un problème

Guide d'utilisation de l'API de l'agent Java

L'API de l'agent Java New Relic vous permet de contrôler, de personnaliser et d'étendre les fonctionnalités de l'agent Java . Cette API se compose de :

  • Méthodes statiques sur la classe com.newrelic.api.agent.NewRelic
  • Une annotation@Trace pour implémenter une instrumentation personnalisée
  • Une hiérarchie d'objets API offrant des fonctionnalités supplémentaires

Utilisez cette API pour configurer une instrumentation personnalisée de votre application Java et collecter des données plus approfondies. Pour des informations détaillées sur cette API, consultez la Javadoc complète sur GitHub.

Une autre façon de configurer une instrumentation personnalisée est d’utiliser l’instrumentation XML. L'option XML est plus simple et ne nécessite pas de modification du code de votre application, mais elle ne dispose pas de toutes les fonctionnalités de l'API de l'agent Java.

Important

Pour de meilleurs résultats lors de l'utilisation de l'API, assurez-vous que vous disposez de la dernière version agent Java . Plusieurs API utilisées dans les exemples nécessitent l’agent Java 6.4.0 ou supérieur.

Pour toutes les API New Relic disponibles, voir Introduction aux API.

Utiliser l'API

Pour accéder à l'API, téléchargez-la depuis Maven Central via un outil de build.

Voici un exemple pour Gradle où vous pouvez remplacer ${agent.version} par la version de votre agent :

implementation 'com.newrelic.agent.java:newrelic-api:${agent.version}'

Vous pouvez appeler l'API même sans que l'agent ne soit en cours d'exécution, mais les méthodes seront inopérantes jusqu'à ce que l'agent charge votre application.

Transactions

Pour instrumenter les transactions dans votre application, utilisez l'API suivante.

Si vous voulez...

Utilisez ceci

Créer un Transaction lorsque New Relic n'en crée pas un automatiquement

@Trace(dispatcher = true) sur la méthode qui englobe le travail à signaler. Lorsque cette annotation est utilisée sur une méthode dans le contexte d'une transaction existante, cela ne démarrera pas une nouvelle transaction, mais inclura plutôt la méthode dans la transaction existante.

Capturez la durée d'une méthode que New Relic ne trace pas automatiquement

@Trace() sur la méthode que vous souhaitez chronométrer.

Définir le nom du courant Transaction

NewRelic.setTransactionName(...)

Démarrer le minuteur pour le temps de réponse du Transaction actuel et pour faire en sorte qu'un Transaction que vous créez soit signalé comme une transaction Web, plutôt que comme une transaction Other

NewRelic.setRequestAndReponse(...)

Ajoutez l'attribut personnalisé à Transactions et TransactionEvents

NewRelic.addCustomParameter(...)

Ajoute le suivi des utilisateurs à Transactions en définissant l'attribut agent enduser.id.

NewRelic.setUserId()

Empêcher qu'un Transaction soit signalé à New Relic

NewRelic.ignoreTransaction()

Exclure un Transaction lors du calcul du score Apdex de votre application

NewRelic.ignoreApdex()

Voir le log associé

Pour voir le log directement dans le contexte des erreurs et des traces de votre application, utilisez ces appels d'API pour annoter votre log :

Pour plus d'informations sur la corrélation des données log avec d'autres données télémétriques, consultez notre documentation sur les logs en contexte .

Travail asynchrone de l'instrument

Pour des informations détaillées, consultez agent Java API pour l'application asynchrone.

Si vous voulez...

Utilisez ceci

tracer une méthode asynchrone si elle est liée à une Transaction existante ...

@Trace(async = true)

Liez le Transaction associé au Token sur le thread actuel...

Token.link() ou Token.linkAndExpire()

Expirer un Token associé au Transaction actuel ...

Token.expire()

Arrêtez de chronométrer un Segment et faites-le signaler comme faisant partie de son parent Transaction

Segment.end()

Arrêtez de chronométrer un Segment et ne le faites pas signaler comme faisant partie de son parent Transaction

Segment.ignore()

Traçage distribué de l'utilisation API

Ces API nécessitent que le traçage distribué soit activé. agent Java configuration Consultez pour toutes les options de configuration de traçage distribué.

Le traçage distribué vous permet de voir le chemin emprunté par une requête lorsqu'elle traverse un système distribué. Pour obtenir des instructions générales sur la façon d'utiliser les appels ci-dessous pour implémenter le traçage distribué, consultez Utiliser API de traçage distribué. Pour voir ces API en action, consultez Utilisation de agent Java de traçage de distribution API avec Kafka.

Important

Avec la version 6.4.0agent , les API de traçage distribué suivantes ont été introduites, à l'exception de addCustomAttribute(), qui a été introduite dans la version 6.1.0. Nous vous recommandons fortement d'utiliser ces API plutôt que celles obsolètes.

Si vous voulez...

Utilisez ceci

Découvrez les en-têtes spécifiques au type d’un message entrant ou sortant.

Headers

Pour une implémentation fournie de Headers utilisez ConcurrentHashMapHeaders.

Voir un exemple d'implémentation des en-têtes de contexte de trace W3C dans l'utilisation API DT avec Kafka.

Créez et insérez des en-têtes de traçage distribués dans une structure de données Headers . Cette API insérera les en-têtes newrelic et W3C Trace Context (traceparent et tracestate), sauf si l'agent est explicitement configuré pour exclure les en-têtes newrelic .

Pour plus d'informations sur l'obtention de références à la transaction en cours et à d'autres classes API, consultez Obtenir des références.

Acceptez les en-têtes de traçage distribués envoyés par le service appelant et liez ces services ensemble dans une trace distribuée.

Pour plus d'informations sur l'obtention de références à la transaction en cours et à d'autres classes API, consultez Obtenir des références.

Comprendre une classe utilitaire qui fournit des constantes d’énumération pour définir le type de transport lors de l’acceptation du traçage des en-têtes distribués.

Ajouter l'attribut personnalisé à SpanEvents dans les traces distribuées

NewRelic.getAgent().getTracedMethod().addCustomAttribute(...)

Prudence

Avec la version 6.4.0agent , l'API de traçage distribué suivante a été déconseillée et remplacée par l'API du tableau ci-dessus. Il est fortement recommandé de mettre à niveau l'agent et d'utiliser les nouvelles API au lieu de celles obsolètes.

Si vous voulez...

Utilisez ceci

Créez une charge utile à envoyer à un service appelé.

Pour plus d'informations sur l'obtention de références à la transaction en cours et à d'autres classes API, consultez Obtenir des références.

Prudence

API obsolète à partir de l'agent 6.4.0

Acceptez une charge utile envoyée par le premier service ; cela liera ces services ensemble dans une trace.

Pour plus d'informations sur l'obtention de références à la transaction en cours et à d'autres classes API, consultez Obtenir des références.

Prudence

API obsolète à partir de l'agent 6.4.0

frais utilisés pour connecter les services. L'appel text() renvoie une représentation sous forme de chaîne JSON de la charge utile.

DistributedTracePayload.text()

Prudence

API obsolète à partir de l'agent 6.4.0

frais utilisés pour connecter les services. L'appel httpSafe() renvoie une représentation de chaîne JSON codée en base64 de la charge utile.

DistributedTracePayload.httpSafe()

Prudence

API obsolète à partir de l'agent 6.4.0

Utilisation de l'API de traçage inter-applications (CAT)

Important

Le traçage inter-applications est obsolète à partir de la version 7.4.0 de l'agent et sera supprimé dans une future version de l'agent.

Au lieu d'utiliser le traçage inter-application, nous recommandons notre fonctionnalité de traçage distribué . tracing distribué est une amélioration de la fonctionnalité de tracing inter-applicationet est recommandé pour les grands systèmes distribués.

Pour suivre les appels externes et ajouter un traçage inter-applications, utilisez les API suivantes :

Si vous voulez...

Utilisez ceci

tracer via un canal de transport personnalisé que New Relic ne prend pas en charge par défaut, tel qu'un transport RPC propriétaire

Consultez également les informations de ce document sur l’utilisation de Transaction pour obtenir des références aux classes d’API New Relic.

Afficher ou modifier le nom de la métrique ou le nom d'une métrique rollup d'un TracedMethod

(Un nom de métrique rollup, tel que OtherTransaction/all, n'est pas limité à une transaction spécifique. Il représente toutes les transactions en arrière-plan.)

Consultez également les informations de ce document sur l’utilisation de TracedMethod pour obtenir des références aux classes d’API New Relic.

Signaler un appel à un service HTTP externe, un serveur de base de données, un fichier d'attente de messages ou une autre ressource externe qui est tracée à l'aide de agent Java API @Trace l'annotation del'de

TracedMethod.reportAsExternal(...) en passant des arguments construits à l'aide du générateur ExternalParameters .

Consultez également les informations de ce document sur l’utilisation de TracedMethod pour obtenir des références aux classes d’API New Relic.

Activer et ajouter le traçage inter-applications lors de la communication avec un service HTTP ou JMS externe instrumenté par New Relic

TracedMethod.addOutboundRequestHeaders(...) avec TracedMethod.reportAsExternal(...)

Consultez également les informations de ce document sur l’utilisation de TracedMethod pour obtenir des références aux classes d’API New Relic.

Ajouter une temporisation pour un serveur d'application ou un répartiteur qui n'est pas pris en charge automatiquement

Transaction.setRequest(...), Transaction.setResponse(...), ou NewRelic.setRequestAndResponse(...), et Transaction.markResponseSent()

Consultez également les informations de ce document sur l’utilisation de Transaction pour obtenir des références aux classes d’API New Relic.

Obtenir des références aux classes de l'API New Relic

D'autres tâches nécessitent l'objet New Relic Agent . L'objet Agent expose plusieurs objets qui vous offrent les fonctionnalités suivantes :

Si vous voulez...

Utilisez ceci

Obtenez une référence à l'actuel Transaction

NewRelic.getAgent().getTransaction()

Obtenez un Token pour lier un travail asynchrone

Commencez et obtenez une référence à un Segment

Obtenir une référence à la méthode en cours de traçage

NewRelic.getAgent().getTracedMethod()

Obtenir une référence à l'enregistreur Agent

NewRelic.getAgent().getLogger()

Obtenir une référence à la configuration Agent

NewRelic.getAgent().getConfig()

Obtenir une référence à un agrégateur pour les métriques personnalisées

NewRelic.getAgent().getAggregator()

Obtenez une référence à Insights (notre nom d'origine pour la fonctionnalité qui régit l'événement personnalisé) afin d'enregistrer l'événement personnalisé

NewRelic.getAgent().getInsights()

Fonctionnalités API supplémentaires

L'API suivante fournit des fonctionnalités supplémentaires, telles que la définition des informations sur le serveur d'applications, le signalement des erreurs, l'ajout d'informations sur la durée de chargement des pages, l'enregistrement des métriques personnalisées et l'envoi d'événements personnalisés.

Si vous voulez...

Utilisez ceci

Définissez explicitement les informations de port, de nom et de version pour un serveur application ou un répartiteur et le nom instance pour une JVM

Signaler une erreur que New Relic ne signale pas automatiquement

NewRelic.noticeError(...)

Lors d'une transaction, le dernier appel à noticeError l'emporte. Une seule erreur sera signalée par transaction.

Regroupez les erreurs avec votre propre empreinte digitale personnalisée définie, implémentez l'interface ErrorGroupCallback utilisée pour générer des clés de regroupement pour les erreurs qui seront envoyées à New Relic. L'empreinte sera utilisée pour regrouper les messages d'erreur dans l'UI d'Errors Inbox.

Définissez votre propre empreinte d’erreur via une fonction de rappel. Pour enregistrer un ErrorGroupCallback utilisé pour générer une clé de regroupement pour l'erreur fournie.

NewRelic.setErrorGroupCallback(errorGroupCallback)

Ajoutez le temps de chargement de la page du navigateur pour Transactions que New Relic n'ajoute pas automatiquement à l'en-tête

Créer et accumuler des métriques personnalisées

NewRelic.recordMetric(...), .recordResponseTimeMetric(...), ou .incrementCounter(...)

Enregistrer un événement personnalisé

Insights.recordCustomEvent(...)

Ou utilisez NewRelic.addCustomParameter(...) pour ajouter un attribut personnalisé au type TransactionEvent défini par New Relic .

Consultez également les informations de ce document sur l’utilisation de Insights pour obtenir des références aux classes d’API New Relic.

Fournir des informations générales sur le compte du fournisseur de cloud à l'agent

NewRelic.getAgent().getCloud().setAccountInfo(CloudAccountInfo.AWS_ACCOUNT_ID, "...");

Avec cette méthode, vous pouvez fournir le type d’informations de compte et sa valeur. L'agent utilise ces informations pour renseigner l'attribut cloud.resource_id dans les étendues de services cloud sélectionnées.

AWS DynamoDB et Kinesis sont des services qui nécessitent cette valeur pour renseigner l'attribut cloud.resource_id . De même, AWS Lambda requiert cette valeur lorsque l’ID de compte ne fait pas partie du nom de la fonction.

L'appel de cette méthode remplace la configuration cloud correspondante. L'appel affiché ci-dessus remplace cloud.aws.account_id.

Fournir à l'agent des informations sur le compte du fournisseur de cloud spécifique au client SDK

NewRelic.getAgent().getCloud().setAccountInfo(sdkClient, CloudAccountInfo.AWS_ACCOUNT_ID, "...");

Cet appel fournit les mêmes informations que la méthode précédente, mais il est spécifique au client SDK fourni. Lorsque le client SDK spécifié est utilisé, ces données seront utilisées à la place des données générales.

Exemples d'utilisation d'API supplémentaires

Pour des exemples de code détaillés sur l'utilisation des API, consultez la documentation de New Relic sur l'instrumentation personnalisée pour :

Droits d'auteur © 2025 New Relic Inc.

This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.