L'agent .NET de New Relic inclut une API qui vous permet d'étendre les fonctionnalités standard de l'agent. Par exemple, vous pouvez utiliser l'API .NET d'agent pour :
- Personnalisez le nom de votre application
- Créer un paramètre de transaction personnalisé
- Signaler les erreurs et les mesures personnalisées
Vous pouvez également personnaliser certains comportements par défaut de l'agent .NET en ajustant les paramètres de configuration ou en utilisant une instrumentation personnalisée.
Exigences
Pour utiliser l'API .NET deagent, assurez-vous que vous disposez de la dernière version de l'agent .NET. Ensuite, ajoutez une référence à l’agent dans votre projet en utilisant l’une des deux options ci-dessous :
Ajoutez une référence à
NewRelic.Api.Agent.dllà votre projet.OU
Affichez et téléchargez le API package à partir de la bibliothèque de packages NuGet.
Notes sur l'injection de dépendances
Si vous consommez l'API d’agent via Microsoft.Extensions.DependencyInjection (ou un conteneur similaire), il existe deux pièges qui désactiveront silencieusement votre instrumentation personnalisée sans produire d'erreur. Les deux découlent du fait que IAgent est un handle à longue durée de vie, mais que CurrentTransaction et CurrentSpan sont des vues à l'échelle de la requête qui doivent être relues à chaque appel.
Enregistrer IAgent de manière différée, et non de manière anticipée
GetAgent() doit être appelé après que le profileur a fini de s'attacher. Si vous le résolvez de manière anticipée pendant la construction du conteneur DI, vous risquez de mettre en cache l’espace réservé no-op que l’API renvoie avant que l’agent ne soit actif, laissant l’application avec une API silencieusement désactivée pour la durée de vie du processus. Utilisez une lambda de fabrique pour que l'appel soit différé à la première résolution :
// ❌ Eager — may capture the no-op placeholderbuilder.Services.AddSingleton<IAgent>(NewRelic.Api.Agent.NewRelic.GetAgent());
// ✅ Lazy — GetAgent() runs on first resolution, after the profiler is readybuilder.Services.AddSingleton<IAgent>(_ => NewRelic.Api.Agent.NewRelic.GetAgent());Ne mettez pas en cache ITransaction ou ISpan dans les champs
IAgent lui-même peut être stocké en toute sécurité, mais CurrentTransaction et CurrentSpan doivent être lus à nouveau à chaque fois que vous les utilisez. Les capturer dans un constructeur ou un champ lie votre service à la requête qui se trouvait être en cours lorsque le champ a été assigné pour la première fois. Chaque appel ultérieur écrit alors des attributs, des erreurs, et des événements dans une transaction qui est déjà terminée, et les données n'apparaissent jamais sur les transactions que vous consultez réellement.
// ❌ Captures one request's transaction foreverpublic class BuggyService{ private readonly ITransaction _transaction; public BuggyService(IAgent agent) => _transaction = agent.CurrentTransaction;}
// ✅ Fetch per-callpublic class WorkService{ private readonly IAgent _agent; public WorkService(IAgent agent) => _agent = agent;
public void DoWork() { var transaction = _agent.CurrentTransaction; transaction.AddCustomAttribute("key", "value"); }}Pour un guide complet et exécutable, y compris des exemples d'anti-modèles vérifiés à la compilation, consultez l'exemple d'injection de dépendance (api-dependency-injection) dans le référentiel newrelic-dotnet-examples.
Liste des appels d'API
La liste suivante contient les différents appels que vous pouvez effectuer avec l'API, y compris la syntaxe, les exigences, les fonctionnalités et les exemples :
Syntaxe
NewRelic.Api.Agent.NewRelic.DisableBrowserMonitoring([boolean $override])Désactiver automatique injection d'monitoring de des navigateurs snippet sur des pages spécifiques.
Exigences
- Compatible avec toutes les versions d'agent.
- Doit être appelé à l'intérieur d'une transaction.
Description
Ajoutez cet appel pour désactiver l'injection automatique du script sur des pages spécifiques. Vous pouvez également ajouter une substitution facultative pour désactiver l' injection manuelle et automatique. Dans les deux cas, placez cet appel d'API aussi près que possible du haut de la vue dans laquelle vous souhaitez désactiver le navigateur.
Conseil
Comparez GetBrowserTimingHeader(), qui ajoute le script du navigateur à la page.
Paramètres
paramètres | Description |
|---|---|
booléen | Facultatif. Lorsque |
Exemples
Désactiver l'injection automatique
Cet exemple désactive uniquement l'injection automatique du snippet:
NewRelic.Api.Agent.NewRelic.DisableBrowserMonitoring();Désactiver l'injection automatique et manuelle
Cet exemple désactive l'injection automatique et manuelle du snippet:
NewRelic.Api.Agent.NewRelic.DisableBrowserMonitoring(true);Syntaxe
NewRelic.Api.Agent.NewRelic.GetAgent()Accédez à l'agent via l'interface IAgent .
Exigences
- Version de l'agent 8.9 ou supérieure.
- Compatible avec tous les types d'applications.
Description
Accédez à API des méthodes deagent via l'interface IAgent.
Valeurs de retour
Une implémentation d'IAgent fournissant l'accès à l'API IAgent.
Exemples
IAgent agent = NewRelic.Api.Agent.NewRelic.GetAgent();Syntaxe
NewRelic.Api.Agent.NewRelic.GetBrowserTimingHeader();NewRelic.Api.Agent.NewRelic.GetBrowserTimingHeader(string nonce);Générer monitoring un HTML des navigateurs snippet pour instrumenter utilisateur final du navigateur.
Exigences
- Compatible avec toutes les versions d'agent.
- Doit être appelé à l'intérieur d'une transaction.
Description
Renvoie un snippet HTML utilisé pour activer . Le snippet demande au navigateur de récupérer un petit fichier JavaScript et de démarrer le minuteur de page. Vous pouvez ensuite insérer le snippet renvoyé dans l'en-tête de vos pages Web HTML. Pour plus d'informations, voir Ajout d'applications au monitoring des navigateurs.
Conseil
Comparez DisableBrowserMonitoring(), qui désactive le script du navigateur sur une page.
Paramètres
paramètres | Description |
|---|---|
chaîne | Le nonce cryptographique par demande utilisé par les politiques de sécurité du contenu. |
Conseil
Cet appel d'API nécessite des mises à jour de la liste de sécurité des domaines autorisés. Pour plus d'informations sur les considérations relatives à la politique de sécurité du contenu (CSP), visitez la page monitoring de la compatibilité et des exigences des navigateurs.
Valeurs de retour
Une chaîne HTML à intégrer dans un en-tête de page.
Exemples
<html><head> <%= NewRelic.Api.Agent.NewRelic.GetBrowserTimingHeader()%> ...</head><body>...<html><head> <%= NewRelic.Api.Agent.NewRelic.GetBrowserTimingHeader("YOUR_NONCE_VALUE")%> ...</head><body>...<!DOCTYPE html><html lang="en"><head> @Html.Raw(NewRelic.Api.Agent.NewRelic.GetBrowserTimingHeader()) ...</head><body>...<!DOCTYPE html><html lang="en"><head> @Html.Raw(NewRelic.Api.Agent.NewRelic.GetBrowserTimingHeader("YOUR_NONCE_VALUE")) ...</head><body>...Important
Cette API n'est pas prise en charge pour Blazor Webassembly, car l'agent ne peut pas instrumenter le code Webassembly. Les exemples suivants concernent uniquement l'application Blazor Server. Utilisez la méthode copier-coller pour ajouter l'agent de navigateur aux pages Blazor Webassembly.
Important
Cette API ne peut pas être placée dans un élément <HeadContent> d'une page .razor . Au lieu de cela, il doit être appelé à partir de _Layout.cshtml ou d'un fichier de mise en page équivalent.
<!DOCTYPE html><html lang="en"><head> @Html.Raw(NewRelic.Api.Agent.NewRelic.GetBrowserTimingHeader()) ...</head><body>...<!DOCTYPE html><html lang="en"><head> @Html.Raw(NewRelic.Api.Agent.NewRelic.GetBrowserTimingHeader("YOUR_NONCE_VALUE")) ...</head><body>...Syntaxe
NewRelic.Api.Agent.NewRelic.GetLinkingMetadata();Renvoie des paires valeur-clé qui peuvent être utilisées pour lier une trace ou une entité.
Exigences
- Version de l'agent 8.19 ou supérieure.
- Compatible avec tous les types d'applications.
Description
Le dictionnaire des paires valeur-clé renvoyées comprend des éléments utilisés pour lier la trace et l'entité dans le produit APM . Il ne contiendra que des éléments avec des valeurs significatives. Par instance, si le tracing distribué est désactivé, trace.id ne sera pas inclus.
Valeurs de retour
Dictionary <string, string>() renvoyé inclut les éléments utilisés pour lier la trace et l'entité dans le produit APM .
Exemples
NewRelic.Api.Agent.IAgent Agent = NewRelic.Api.Agent.NewRelic.GetAgent();var linkingMetadata = Agent.GetLinkingMetadata();foreach (KeyValuePair<string, string> kvp in linkingMetadata){ Console.WriteLine("Key = {0}, Value = {1}", kvp.Key, kvp.Value);}Syntaxe
public interface IAgentFournit un accès aux artefacts et méthodes de l'agent, tels que la transaction en cours d'exécution.
Exigences
- Version de l'agent 8.9 ou supérieure.
- Compatible avec tous les types d'applications.
Description
Fournit un accès aux artefacts et méthodes de l'agent, tels que la transaction en cours d'exécution. Pour obtenir une référence à IAgent, utilisez GetAgent.
Propriétés
Nom | Description |
|---|---|
Transaction en cours | Propriété permettant d'accéder à la transaction en cours d'exécution via l'interface ITransaction. Doit être appelé à l'intérieur d'une transaction. |
CurrentSpan | Propriété donnant accès à la span en cours d'exécution via l'interface ISpan. |
Exemples
IAgent agent = NewRelic.Api.Agent.NewRelic.GetAgent();ITransaction transaction = agent.CurrentTransaction;Syntaxe
public interface ITransactionFournit l'accès aux méthodes spécifiques aux transactions dans l'API New Relic.
Description
Fournit l'accès aux méthodes spécifiques aux transactions dans l'API de l'agent .NET de New Relic. Pour obtenir une référence à ITransaction, utilisez la méthode de transaction actuelle disponible sur IAgent.
Les méthodes suivantes sont disponibles sur ITransaction:
Nom | Description |
|---|---|
| Ajoute les données du tracing distribué à une demande sortante (voir ci-dessous pour plus de détails). |
| Accepte les données entrantes de tracing distribué provenant d'un autre service (voir ci-dessous pour plus de détails). |
| Ajoutez des informations contextuelles de votre application à la transaction en cours sous forme d'attribut (voir ci-dessous pour plus de détails). |
| Fournit l'accès à l'exécution en cours, qui donne accès aux méthodes spécifiques à l'exécution dans l'API New Relic (voir ci-dessous pour plus de détails). |
| Associe un identifiant utilisateur à la transaction en cours (voir ci-dessous pour plus de détails). |
| Permet d'instrumenter un datastore non pris en charge (voir ci-dessous pour plus de détails). |
Syntaxe
void InsertDistributedTraceHeaders(carrier, setter)Ajoute des données du tracing distribué à un message sortant vers un autre service instrumenté.
Description
ITransaction.InsertDistributedTraceHeaders modifie l'objet porteur qui est transmis en ajoutant des en-têtes W3C Trace Context et des en-têtes de traces distribuées New Relic . Les en-têtes New Relic peuvent être désactivés avec <distributedTracing excludeNewrelicHeader="true" /> dans la configuration.
Paramètres
Nom | Description |
|---|---|
<T> | Requis. Un magasin de paires de valeurs clés où sont insérées les données de tracing distribué. Cela doit exister dans tout objet de message transmis du service appelant au service appelé, via le transport utilisé. Par exemple, pour les messages Azure Service Bus, le type |
Action<T, string, string> | Requis. Une action définie par l'utilisateur pour insérer des données de tracing dans le support. Voir l'exemple ci-dessous. |
Considérations d'utilisation
- Le tracing distribué doit être activé.
- Cette API ne peut être utilisée que dans le contexte d'une transaction existante.
Exemple
Vous pouvez trouver un exemple complet que vous pouvez créer et exécuter pour démontrer l'utilisation de cette API ici.
// Get a reference to the agent, which lets you get a reference to the current transactionIAgent agent = NewRelic.Api.Agent.NewRelic.GetAgent();ITransaction currentTransaction = agent.CurrentTransaction;
// In this example, we are using Azure Service Bus. The `ServiceBusMessage` type has an `ApplicationProperties` property for custom key/value pairs.
// Create the outbound messageServiceBusMessage message = new ("Hello, world!");
// Define the setter Action. The `ApplicationProperties` dictionary is the trace data carrier.var setter = new Action<ServiceBusMessage, string, string>((carrier, key, value) => { carrier.ApplicationProperties?.Set(key, value); });
// Call the API to add the distributed tracing data to the messagecurrentTransaction.InsertDistributedTraceHeaders(message, setter);
// Send the messageSyntaxe
void AcceptDistributedTraceHeaders(carrier, getter, transportType)Accepte les données detracing distribué à partir d'un message entrant provenant d'un autre service instrumenté.
Description
ITransaction.AcceptDistributedTraceHeaders est utilisé pour lier les spans d'une trace en acceptant une charge générée par InsertDistributedTraceHeaders ou générée par un autre traceur compatible W3C Trace Context . Cette méthode accepte la valeur clé stockée à partir d'une requête entrante, recherche les W3C Trace Context données et, si elle ne les trouve pas, revient aux New Relic tracedonnées distribuées .
Paramètres
Nom | Description |
|---|---|
<T> | Requis. Un magasin de paires valeur-clé dans lequel lesdonnées de tracing distribué a été inséré par le service appelant. Cela doit exister dans tout objet de message transmis du service appelant au service appelé, via le transport utilisé. Par exemple, pour les messages Azure Service Bus, le type |
Func<T, string, IEnumerable<string>> | Requis. Une fonction définie par l'utilisateur pour extraire les données de tracing du transporteur. Voir l'exemple ci-dessous. |
Énumération TransportType | Requis. Décrit le transport de la charge utile entrante (par exemple |
Considérations d'utilisation
- Le tracing distribué doit être activé.
- Cette API ne peut être utilisée que dans le contexte d'une transaction existante.
AcceptDistributedTraceHeaderssera ignoré siInsertDistributedTraceHeadersouAcceptDistributedTraceHeadersa déjà été appelé pour cette transaction.
Exemple
Vous pouvez trouver un exemple complet que vous pouvez créer et exécuter pour démontrer l'utilisation de cette API ici
// Get a reference to the agent, which lets you get a reference to the current transactionIAgent agent = NewRelic.Api.Agent.NewRelic.GetAgent();ITransaction currentTransaction = agent.CurrentTransaction;
// In this example, we are using Azure Service Bus. The `ServiceBusMessage` type has an `ApplicationProperties` property for custom key/value pairs.
// Recieve an incoming message. Assume that `receiver` is a previously-configured `ServiceBusReceiver`ServiceBusReceivedMessage message = await receiver.ReceiveMessageAsync();
// Define the getter Func. The `ApplicationProperties` dictionary is the trace data carrier.IEnumerable<string> Getter(IDictionary<string, object> carrier, string key){ var data = new List<string>(); if (carrier == null) { return data; } object value; if (applicationProperties.TryGetValue(key, out value)) { if (value != null) { data.Add(value.ToString()); } } return data;}
// Call the API to accept the distributed tracing data from the messagecurrentTransaction.AcceptDistributedTraceHeaders(message.ApplicationProperties, Getter, TransportType.Queue);Syntaxe
ITransaction AddCustomAttribute(string key, object value)Ajoute des informations contextuelles sur votre application à la transaction en cours sous la forme d'attribut.
Cette méthode nécessite la agent version .NET et la version de .NET API agent 8.24.244.0 ou supérieure. Il a remplacé le AddCustomParameter obsolète.
Paramètres
paramètres | Description |
|---|---|
chaîne | Identifie les informations rapportées. Également connu sous le nom.
|
objet | La valeur signalée. Remarque: les valeurs |
Type .NET | Comment la valeur sera représentée |
|---|---|
| En tant que valeur intégrale. |
| Un nombre décimal. |
| Une chaîne tronquée après 255 octets. Les chaînes vides sont prises en charge. |
| Vrai ou faux. |
| Une représentation de chaîne suivant le format ISO-8601, incluant des informations sur le fuseau horaire : Exemple: |
| Un nombre décimal représentant le nombre de secondes. |
| Sérialisé sous forme de tableau JSON. Les éléments individuels suivent les mêmes règles de conversion de type ci-dessus. Les éléments nuls sont filtrés. Les tableaux vides et les tableaux ne contenant que des valeurs nulles ne sont pas enregistrés. Nécessite la version 10.50.0 ou ultérieure de l'agent .NET. |
tout le reste | La méthode |
Retours
Une référence à la transaction en cours.
Considérations d'utilisation
Pour plus de détails sur les types de données pris en charge, voir attribut personnalisé.
Exemple
IAgent agent = NewRelic.Api.Agent.NewRelic.GetAgent();ITransaction transaction = agent.CurrentTransaction;transaction.AddCustomAttribute("customerName","Bob Smith") .AddCustomAttribute("currentAge",31) .AddCustomAttribute("birthday", new DateTime(2000, 02, 14)) .AddCustomAttribute("waitTime", TimeSpan.FromMilliseconds(93842)) .AddCustomAttribute("colors", new[] { "red", "green", "blue" }) .AddCustomAttribute("ids", new List<int> { 1, 2, 3 });Fournit l'accès à l' exécution en cours, rendant les méthodes spécifiques à l'exécution disponibles dans l'API New Relic.
Exemple
IAgent agent = NewRelic.Api.Agent.NewRelic.GetAgent(); ITransaction transaction = agent.CurrentTransaction; ISpan currentSpan = transaction.CurrentSpan;Syntaxe
ITransaction SetUserId(string userId)Associe un identifiant utilisateur à la transaction en cours.
Cette méthode nécessite agent .NET et API d'agent .NET version 10.9.0 ou supérieure.
Paramètres
paramètres | Description |
|---|---|
chaîne | L'identifiant utilisateur à associer à cette transaction.
|
Exemple
IAgent agent = NewRelic.Api.Agent.NewRelic.GetAgent(); ITransaction transaction = agent.CurrentTransaction; transaction.SetUserId("BobSmith123");Syntaxe
SegmentWrapper? RecordDatastoreSegment(string vendor, string model, string operation, string? commandText = null, string? host = null, string? portPathOrID = null, string? databaseName = null)Permet à un datastore non pris en charge d'être instrumenté de la même manière que l'agent .NET instrumente automatiquement ses magasins de données pris en charge.
Cette méthode nécessite agent .NET et API d'agent .NET version 10.22.0 ou supérieure.
Paramètres
paramètres | Description |
|---|---|
chaîne | Nom du fournisseur du datastore, tel que MySQL, MSSQL ou MongoDB. |
chaîne | Nom de table ou identifiant similaire dans une datastore non relationnelle. |
chaîne | Opération en cours d'exécution, telle que « SELECT » ou « UPDATE » pour la base de données SQL. |
chaîne? | Facultatif. requête, ou descripteur similaire dans une datastore non relationnelle. |
chaîne? | Facultatif. Serveur hébergeant le datastore. |
chaîne? | Facultatif. Port, chemin ou autre identifiant, associé à l'hôte pour faciliter l'identification du datastore. |
chaîne? | Facultatif. nom de la banque de données ou identifiant similaire. |
Retours
Wrapper de segment IDisposable qui crée et termine le segment automatiquement.
Exemple
var transaction = NewRelic.Api.Agent.NewRelic.GetAgent().CurrentTransaction;using (transaction.RecordDatastoreSegment(vendor, model, operation, commandText, host, portPathOrID, databaseName)){ DatastoreWorker();}Syntaxe
Public interface ISpanFournit l'accès aux méthodes spécifiques à la span dans l'API New Relic.
Description
Fournit l'accès aux méthodes spécifiques à span dans New Relic API agentl'.NET de . Pour obtenir une référence à ISpan, utilisez :
- La propriété
CurrentSpansurIAgent(recommandé). - La propriété
CurrentSpansurITransaction.
Cette section contient des descriptions et des paramètres des méthodes ISpan :
Nom | Description |
|---|---|
| Ajoutez des informations contextuelles de votre application à la plage actuelle sous forme d'attribut (voir ci-dessous pour plus de détails). |
| Modifie le nom de la plage/du segment/des métriques actuels qui seront signalés à New Relic (voir ci-dessous pour plus de détails). |
Ajoute des informations contextuelles sur votre application à la plage actuelle sous la forme d'attribut.
Cette méthode nécessite la agent version .NET et la API agent version de .NET 8.25 ou supérieure.
Syntaxe
ISpan AddCustomAttribute(string key, object value)Paramètres
paramètres | Description | ||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
chaîne | Identifie les informations rapportées. Également connu sous le nom.
| ||||||||||||||||||
objet | La valeur signalée. Remarque: les valeurs
|
Retours
Une référence à la durée actuelle.
Considérations d'utilisation
Pour plus de détails sur les types de données pris en charge, consultez le guide des attributs personnalisés.
Exemples
IAgent agent = NewRelic.Api.Agent.NewRelic.GetAgent();ISpan currentSpan = agent.CurrentSpan;
currentSpan .AddCustomAttribute("customerName","Bob Smith") .AddCustomAttribute("currentAge",31) .AddCustomAttribute("birthday", new DateTime(2000, 02, 14)) .AddCustomAttribute("waitTime", TimeSpan.FromMilliseconds(93842)) .AddCustomAttribute("colors", new[] { "red", "green", "blue" }) .AddCustomAttribute("ids", new List<int> { 1, 2, 3 });Modifie le nom du segment/de la plage actuelle qui sera signalé à New Relic. Pour les segments/spans résultant d'une instrumentation personnalisée, le nom de la métrique signalé à New Relic sera également modifié.
Cette méthode nécessite la agent version .NET et la API agent version de l'.NET 10.1.0 ou supérieur.
Syntaxe
ISpan SetName(string name)Paramètres
paramètres | Description |
|---|---|
chaîne | Le nouveau nom du span/segment. |
Retours
Une référence à la durée actuelle.
Exemples
[Trace]public void MyTracedMethod(){ IAgent agent = NewRelic.Api.Agent.NewRelic.GetAgent(); ISpan currentSpan = agent.CurrentSpan;
currentSpan.SetName("MyCustomName");}Syntaxe
NewRelic.Api.Agent.NewRelic.IgnoreApdex()Ignorer la transaction en cours lors du calcul de l'Apdex.
Exigences
Compatible avec toutes les versions d'agent.
Description
Ignore la transaction en cours lors du calcul de votre score Apdex. Cela est utile lorsque vous avez des transactions très courtes ou très longues (telles que des téléchargements de fichiers) qui peuvent fausser votre score Apdex.
Exemples
NewRelic.Api.Agent.NewRelic.IgnoreApdex();Syntaxe
NewRelic.Api.Agent.NewRelic.IgnoreTransaction()N'instrumentez pas la transaction en cours.
Exigences
- Compatible avec toutes les versions d'agent.
- Doit être appelé à l'intérieur d'une transaction.
Description
Ignore la transaction en cours.
Conseil
Vous pouvez également ignorer les transactions via un fichier XML instrumentation personnalisée.
Exemples
NewRelic.Api.Agent.NewRelic.IgnoreTransaction();Syntaxe
NewRelic.Api.Agent.NewRelic.IncrementCounter(string $metric_name)Incrémentez le compteur d'une métrique personnalisée de 1.
Exigences
- Compatible avec toutes les versions d'agent.
- Compatible avec tous les types d'applications.
Description
Incrémentez le compteur d'une métrique personnalisée de 1. Pour afficher ces métriques personnalisées, utilisez le générateur de requêtes pour rechercher des métriques et créer des graphiques personnalisables. Voir aussi RecordMetric() et RecordResponseTimeMetric().
Important
Lors de la création d'une métrique personnalisée, commencez le nom par Custom/ (par exemple, Custom/MyMetric). Pour en savoir plus sur la dénomination, voir Collecter des métriques personnalisées.
Paramètres
paramètres | Description |
|---|---|
chaîne | Requis. Le nom de la métrique à incrémenter. |
Exemples
NewRelic.Api.Agent.NewRelic.IncrementCounter("Custom/ExampleMetric");Surcharges
Notez une erreur et signalez-la à New Relic, avec l'attribut personnalisé facultatif.
NewRelic.Api.Agent.NewRelic.NoticeError(Exception $exception);NewRelic.Api.Agent.NewRelic.NoticeError(Exception $exception, IDictionary<TKey, TValue> $attributes);NewRelic.Api.Agent.NewRelic.NoticeError(string $error_message, IDictionary<TKey, TValue> $attributes);NewRelic.Api.Agent.NewRelic.NoticeError(string $error_message, IDictionary<TKey, TValue> $attributes, bool $is_expected);Exigences
Cet appel d'API est compatible avec :
- Toutes les versions agent
- Tous les types d'applications
Description
Notez une erreur et signalez-la à New Relic avec l'attribut personnalisé facultatif. Pour chaque transaction, l'agent conserve uniquement l'exception et l'attribut du premier appel à NoticeError(). Vous pouvez transmettre une exception réelle ou transmettre une chaîne pour capturer un message d'erreur arbitraire.
Si cette méthode est invoquée dans une transaction, l'agent signale l'exception dans la transaction parent. S'il est invoqué en dehors d'une transaction, l'agent crée une d'erreur trace et catégorise l'erreur dans l'UI de New Relic comme un appel d'API NewRelic.Api.Agent.NoticeError. Si invoqué en dehors d'une transaction, l'appel NoticeError() ne contribuera pas au taux d'erreur d'une application.
L'agent ajoute l'attribut uniquement à l'erreur de trace ; il ne l'envoie pas à New Relic. Pour plus d'informations, voir AddCustomAttribute().
Lors du passage d'une exception à NoticeError(), déterminez l'exception la plus interne à l'aide de l'API Exception.GetBaseException() de Microsoft. Cette exception la plus interne représente la cause première de l’erreur et est ce qui est affiché dans APM. L'intégralité de trace des appels de l'exception de niveau supérieur est signalée, car elle fournit un contexte pertinent et des détails d'exécution. Cette approche offre les informations d’erreur les plus spécifiques de l’exception de base tout en préservant le contexte complet de la manière dont l’erreur s’est propagée dans l’application.
Les erreurs signalées avec cette API sont toujours envoyées à New Relic lorsqu'elles sont signalées dans une transaction qui génère un code d'état HTTP, tel que 404, qui est configuré pour être ignoré par la configuration de l'agent. Pour plus d'informations, consultez notre documentation sur la gestion des erreurs dans APM.
Consultez les sections ci-dessous pour voir des exemples d’utilisation de cet appel.
NewRelic.Api.Agent.NewRelic.NoticeError(Exception $exception)paramètres | Description |
|---|---|
Exception | Requis. Le |
NewRelic.Api.Agent.NewRelic.NoticeError(Exception $exception, IDictionary<TKey, TValue> $attributes)paramètres | Description |
|---|---|
Exception | Requis. Le |
IDictionary<TKey, TValue> | Spécifiez les paires valeur clé d'attribut pour annoter le message d'erreur. Le |
NewRelic.Api.Agent.NewRelic.NoticeError(string $error_message, IDictionary<TKey, TValue> $attributes)paramètres | Description |
|---|---|
chaîne | Requis. Spécifiez une chaîne à signaler à New Relic comme s'il s'agissait d'une exception. Cette méthode crée à la fois un événement d'erreur et une trace d'erreur. Seuls les 1023 premiers caractères sont conservés dans l'événement d'erreur, tandis que la trace d'erreur conserve le message complet. |
IDictionary<TKey, TValue> | Obligatoire (peut être nul). Spécifiez les paires valeur clé d'attribut pour annoter le message d'erreur. Le |
NewRelic.Api.Agent.NewRelic.NoticeError(string $error_message, IDictionary<TKey, TValue> $attributes, bool $is_expected)paramètres | Description |
|---|---|
chaîne | Requis. Spécifiez une chaîne à signaler à New Relic comme s'il s'agissait d'une exception. Cette méthode crée à la fois un événement d'erreur et une trace d'erreur. Seuls les 1023 premiers caractères sont conservés dans l'événement d'erreur, tandis que la trace d'erreur conserve le message complet. |
IDictionary<TKey, TValue> | Obligatoire (peut être nul). Spécifiez les paires valeur clé d'attribut pour annoter le message d'erreur. Le |
booléen | Marquez l'erreur comme prévue afin qu'elle n'affecte pas le score Apdex et le taux d'erreur. |
Exemples
Passer une exception sans attribut personnalisé
try{ string ImNotABool = "43"; bool.Parse(ImNotABool);}catch (Exception ex){ NewRelic.Api.Agent.NewRelic.NoticeError(ex);}Passer une exception avec l'attribut personnalisé
try{ string ImNotABool = "43"; bool.Parse(ImNotABool);}catch (Exception ex){ var errorAttributes = new Dictionary<string, string>() {{"foo", "bar"},{"baz", "luhr"}}; NewRelic.Api.Agent.NewRelic.NoticeError(ex, errorAttributes);}Passer une chaîne de message d'erreur avec l'attribut personnalisé
try{ string ImNotABool = "43"; bool.Parse(ImNotABool);}catch (Exception ex){ var errorAttributes = new Dictionary<string, string>{{"foo", "bar"},{"baz", "luhr"}}; NewRelic.Api.Agent.NewRelic.NoticeError("String error message", errorAttributes);}Passer une chaîne de message d'erreur sans attribut personnalisé
try{ string ImNotABool = "43"; bool.Parse(ImNotABool);}catch (Exception ex){ NewRelic.Api.Agent.NewRelic.NoticeError("String error message", null);}Transmettez une chaîne de message d’erreur et marquez-la comme prévu
try{ string ImNotABool = "43"; bool.Parse(ImNotABool);}catch (Exception ex){ NewRelic.Api.Agent.NewRelic.NoticeError("String error message", null, true);}Syntaxe
NewRelic.Api.Agent.NewRelic.RecordCustomEvent(string eventType, IEnumerable<string, object> attributeValues)Enregistre un événement personnalisé avec le prénom et l'attribut.
Exigences
- Compatible avec toutes les versions d'agent.
- Compatible avec tous les types d'applications.
Description
Enregistre un événement personnalisé avec le prénom et l'attribut, que vous pouvez requêter dans le générateur de requêtes. Pour vérifier si un événement est enregistré correctement, recherchez les données dans le dashboard.
Important
- L'envoi d'un grand nombre d'événements peut augmenter la charge mémoire de l'agent.
- De plus, les messages d'une taille supérieure à 1 Mo (10^6 octets) ne seront pas enregistrés, quel que soit le nombre maximum d'événements.
- événement personnalisé est limité à 64 attributs.
- Pour plus d'informations sur la façon dont les valeurs d'attribut personnalisé sont traitées, consultez le guide d'attribut personnalisé.
Paramètres
paramètres | Description |
|---|---|
chaîne | Requis. Le nom du type d'événement à enregistrer. Les chaînes de plus de 255 caractères entraîneront que l'appel d'API ne sera pas envoyé à New Relic. Le nom ne peut contenir que des caractères alphanumériques, des traits de soulignement |
IEnumerable<string, object> | Requis. Spécifiez les paires valeur clé d'attribut pour annoter l'événement. |
Exemples
Valeurs d'enregistrement [#record-strings]
var eventAttributes = new Dictionary<string, object>() { {"foo", "bar"}, {"alice", "bob"}, {"age", 32}, {"height", 21.3f}};
NewRelic.Api.Agent.NewRelic.RecordCustomEvent("MyCustomEvent", eventAttributes);Syntaxe
NewRelic.Api.Agent.NewRelic.RecordMetric(string $metric_name, single $metric_value)Enregistre une métrique personnalisée avec le prénom.
Exigences
- Compatible avec toutes les versions d'agent.
- Compatible avec tous les types d'applications.
Description
Enregistre une métrique personnalisée avec le prénom. Pour afficher ces métriques personnalisées, utilisez le générateur de requêtes pour rechercher des métriques et créer des graphiques personnalisables. Voir aussi IncrementCounter() et RecordResponseTimeMetric().
Important
Lors de la création d'une métrique personnalisée, commencez le nom par Custom/ (par exemple, Custom/MyMetric).
Paramètres
paramètres | Description |
|---|---|
chaîne | Requis. Le nom de la métrique à enregistrer. Seuls les 255 premiers caractères sont conservés. |
célibataire | Requis. La quantité à enregistrer pour la métrique. |
Exemples
Enregistrer le temps de réponse d'un processus en veille [#record-stopwatch]
Stopwatch stopWatch = Stopwatch.StartNew();System.Threading.Thread.Sleep(5000);stopWatch.Stop();NewRelic.Api.Agent.NewRelic.RecordMetric("Custom/DEMO_Record_Metric", stopWatch.ElapsedMilliseconds);Syntaxe
NewRelic.Api.Agent.NewRelic.RecordResponseTimeMetric(string $metric_name, Int64 $metric_value)Enregistre une métrique personnalisée avec le prénom et le temps de réponse en millisecondes.
Exigences
- Compatible avec toutes les versions d'agent.
- Compatible avec tous les types d'applications.
Description
Enregistre le temps de réponse en millisecondes pour une métrique personnalisée. Pour afficher ces métriques personnalisées, utilisez le générateur de requêtes pour rechercher des métriques et créer des graphiques personnalisables. Voir aussi IncrementCounter() et RecordMetric().
Important
Lors de la création d'une métrique personnalisée, commencez le nom par Custom/ (par exemple, Custom/MyMetric).
Paramètres
paramètres | Description |
|---|---|
chaîne | Requis. Le nom du temps de réponse métrique à enregistrer. Seuls les 255 premiers caractères sont conservés. |
Int64 | Requis. Le temps de réponse à l'enregistrement en millisecondes. |
Exemples
Enregistrer le temps de réponse d'un processus en veille [#record-stopwatch]
Stopwatch stopWatch = Stopwatch.StartNew();System.Threading.Thread.Sleep(5000);stopWatch.Stop();NewRelic.Api.Agent.NewRelic.RecordResponseTimeMetric("Custom/DEMO_Record_Response_Time_Metric", stopWatch.ElapsedMilliseconds);Syntaxe
NewRelic.Api.Agent.NewRelic.SetApplicationName(string $name[, string $name_2, string $name_3])Définissez le nom de l'application pour rollup des données.
Exigences
- Compatible avec toutes les versions d'agent.
- Compatible avec tous les types d'applications.
Description
Définissez le(s) nom(s) d'application signalé(s) à New Relic. Pour plus d’informations sur la dénomination des applications, voir Nommez votre application .NET. Cette méthode est destinée à être appelée une fois, lors du démarrage d'une application.
Important
La mise à jour du nom de l'application force l'agent à redémarrer. L'agent supprime toutes les données non signalées associées aux noms d'application précédents. Il n'est pas recommandé de modifier le nom de l'application plusieurs fois au cours du cycle de vie d'une application en raison de la perte de données associée.
Paramètres
paramètres | Description |
|---|---|
chaîne | Requis. Le nom de l'application principale. |
chaîne | Facultatif. Deuxième et troisième noms pour rollup d'applications. Pour plus d'informations, voir Utiliser plusieurs noms pour une application. |
Exemples
NewRelic.Api.Agent.NewRelic.SetApplicationName("AppName1", "AppName2");Syntaxe
NewRelic.Api.Agent.NewRelic.SetErrorGroupCallback(Func<IReadOnlyDictionary<string,object>, string> errorGroupCallback);Fournissez une méthode de rappel qui prend un IReadOnlyDictionary<string,object> de données d’attribut et renvoie un nom de groupe d’erreurs.
Exigences
Cet appel d'API est compatible avec :
- Version de l'agent 10.9.0 ou supérieure.
- Tous les types d'applications
Description
Définissez une méthode de rappel que l'agent utilisera pour déterminer le nom du groupe d'erreurs pour l'événement d'erreur et la trace. Ce nom est utilisé dans la Errors Inbox pour regrouper les erreurs en groupes logiques.
La méthode de rappel doit accepter un seul argument de type IReadOnlyDictionary<string,object> et renvoyer une chaîne (le nom du groupe d'erreurs). Le IReadOnlyDictionary est une collection de données d'attribut associées à chaque événement d'erreur, y compris les attributs personnalisés.
La liste exacte des attributs disponibles pour chaque erreur varie en fonction de :
- Quel code d'application a généré l'erreur
- Paramètres de configuration de l'agent
- Si des attributs personnalisés ont été ajoutés
Cependant, l'attribut suivant doit toujours exister :
error.classerror.messagestack_tracetransactionNamerequest.urierror.expected
Une chaîne vide peut être renvoyée pour le nom du groupe d'erreurs lorsque l'erreur ne peut pas être attribuée à un groupe d'erreurs logique.
Paramètres
paramètres | Description |
|---|---|
{'Func<IReadOnlyDictionary<string,object>,string>'} | Le rappel pour déterminer le nom du groupe d'erreurs en fonction des données d'attribut. |
Exemples
Regrouper les erreurs par nom de classe d'erreur :
Func<IReadOnlyDictionary<string, object>, string> errorGroupCallback = (attributes) => { string errorGroupName = string.Empty; if (attributes.TryGetValue("error.class", out var errorClass)) { if (errorClass.ToString() == "System.ArgumentOutOfRangeException" || errorClass.ToString() == "System.ArgumentNullException") { errorGroupName = "ArgumentErrors"; } else { errorGroupName = "OtherErrors"; } } return errorGroupName;};
NewRelic.Api.Agent.NewRelic.SetErrorGroupCallback(errorGroupCallback);Regrouper les erreurs par nom de transaction :
Func<IReadOnlyDictionary<string, object>, string> errorGroupCallback = (attributes) => { string errorGroupName = string.Empty; if (attributes.TryGetValue("transactionName", out var transactionName)) { if (transactionName.ToString().IndexOf("WebTransaction/MVC/Home") != -1) { errorGroupName = "HomeControllerErrors"; } else { errorGroupName = "OtherControllerErrors"; } } return errorGroupName;};
NewRelic.Api.Agent.NewRelic.SetErrorGroupCallback(errorGroupCallback);Syntaxe
NewRelic.Api.Agent.NewRelic.SetTransactionName(string $category, string $name)Définit le nom de la transaction en cours.
Exigences
- Compatible avec toutes les versions d'agent.
- Doit être appelé à l'intérieur d'une transaction.
Description
Définissez un nom de transaction personnalisé, à ajouter après un préfixe initial (WebTransaction ou OtherTransaction) en fonction du type de transaction en cours. Avant d’utiliser cet appel, assurez-vous de bien comprendre les implications des problèmes de regroupement métrique.
Si vous utilisez cet appel plusieurs fois au sein de la même transaction, chaque appel écrase l'appel précédent et le dernier appel définit le nom.
Important
N'utilisez pas de crochets [suffix] à la fin du nom de votre transaction. New Relic supprime automatiquement les crochets du nom. Utilisez plutôt des parenthèses (suffix) ou d’autres symboles si nécessaire.
Les valeurs uniques telles que les URL, les titres de page, les valeurs hexadécimales, les identifiants de session et les valeurs identifiables de manière unique ne doivent pas être utilisées pour nommer vos transactions. Ajoutez plutôt ces données à la transaction en tant que paramètre personnalisé avec l’appel AddCustomAttribute().
Important
Ne créez pas plus de 1 000 noms de transaction uniques (par exemple, évitez de nommer par URL si possible). Cela rendra vos graphiques moins utiles et vous risquez de rencontrer les limites fixées par New Relic sur le nombre de noms de transaction uniques par compte. Cela peut également ralentir les performances de votre application.
Paramètres
paramètres | Description |
|---|---|
chaîne | Requis. La catégorie de cette transaction, que vous pouvez utiliser pour distinguer différents types de transactions. La valeur par défaut est |
chaîne | Requis. Le nom de la transaction. Seuls les 255 premiers caractères sont conservés. |
Exemples
Cet exemple montre l’utilisation de cette API dans un contrôleur ASP.NET Core MVC. Une transaction est créée automatiquement par l'agent de instrumentation pour ASP.NET Core. La première partie du nom de la transaction continuera d’être WebTransaction.
public class HomeController : Controller{
public IActionResult Order(string product) {
// The commented-out API call below is probably a bad idea and will lead to a metric grouping issue (MGI) // because too many transaction names will be created. Don't do this. //NewRelic.Api.Agent.NewRelic.SetTransactionName("Other", $"ProductOrder-{product}");
// Do this instead if you want to record request-specific data about this MVC endpoint var tx = NewRelic.Api.Agent.NewRelic.GetAgent().CurrentTransaction; tx.AddCustomAttribute("productName", product);
// The default transaction name at this point will be: WebTransaction/MVC/Home/Order
// Set custom transaction name NewRelic.Api.Agent.NewRelic.SetTransactionName("Other", "OrderProduct");
// Transaction name is now: WebTransaction/Other/OrderProduct
return View(); }}Cet exemple montre l'utilisation de cette API dans une application console. Notez l'attribut instrumentation personnalisée [Transaction], qui est nécessaire pour créer une transaction pour la méthode d'exemple. La première partie du nom de la transaction continuera d’être OtherTransaction.
using NewRelic.Api.Agent;
namespace SetApplicationNameConsoleExample{ internal class Program { static void Main(string[] args) { Console.WriteLine("Hello, World!");
var start = DateTime.Now; while (DateTime.Now - start < TimeSpan.FromMinutes(2)) { DoSomething(); Thread.Sleep(TimeSpan.FromSeconds(5)); } }
[Transaction] // Attribute-based custom instrumentation to create a transaction for this method static void DoSomething() { Console.WriteLine("Doing something: " + Guid.NewGuid().ToString());
// Transaction name from default naming at this point is: OtherTransaction/Custom/SetApplicationNameConsoleExample.Program/DoSomething
NewRelic.Api.Agent.NewRelic.SetTransactionName("Console", "MyCustomTransactionName");
// Transaction name at this point is: OtherTransaction/Console/MyCustomTransactionName
// Note, however, that this transaction will still have a child segment (span) named "SetApplicationNameConsoleExample.Program.DoSomething" } }}Syntaxe
NewRelic.Api.Agent.NewRelic.SetTransactionUri(Uri $uri)Définit l'URI de la transaction en cours.
Exigences
- Doit être appelé à l'intérieur d'une transaction.
- Version de l'agent 6.16 ou supérieure.
Important
Cette méthode ne fonctionne que lorsqu'elle est utilisée dans une transaction créée à l'aide de l'attribut Transaction avec la propriété Web définie sur true. (Voir instrumentation personnalisée via attribut.) Il fournit un support pour un framework Web personnalisé que l'agent ne prend pas automatiquement en charge.
Description
Définissez l'URI de la transaction en cours. L'URI apparaît dans l'attribut request.uri de la trace de transaction et de l'événement de transaction, et il peut également affecter la dénomination de la transaction.
Si vous utilisez cet appel plusieurs fois au sein de la même transaction, chaque appel écrase l'appel précédent. Le dernier appel définit l'URI.
Remarque: à partir de la version 8.18 de l'agent, la valeur de l'attribut request.uri est définie sur la valeur de la propriété Uri.AbsolutePath de l'objet System.Uri transmis à l'API.
Paramètres
paramètres | Description |
|---|---|
Uri | L'URI de cette transaction. |
Exemples
var uri = new System.Uri("https://www.mydomain.com/path");NewRelic.Api.Agent.NewRelic.SetTransactionUri(uri);Syntaxe
NewRelic.Api.Agent.NewRelic.SetUserParameters(string $user_value, string $account_value, string $product_value)Créez un attribut personnalisé lié à l'utilisateur. AddCustomAttribute est plus flexible.
Exigences
- Compatible avec toutes les versions d'agent.
- Doit être appelé à l'intérieur d'une transaction.
Description
Conseil
Cet appel vous permet uniquement d'attribuer des valeurs à des clés préexistantes. Pour une méthode plus flexible pour créer des paires valeur-clé, utilisez AddCustomAttribute().
Définissez l'attribut personnalisélié à l'utilisateur à associer à une vue de page du navigateur (nom d'utilisateur, nom de compte et nom de produit). Les valeurs sont automatiquement associées aux clés préexistantes (user, account et product), puis attachées à la transaction APM parent. Vous pouvez également joindre (ou « transférer ») ces attributs à l'événement PageView du navigateur.
Paramètres
paramètres | Description |
|---|---|
chaîne | Obligatoire (peut être nul). Spécifiez un nom ou un nom d'utilisateur à associer à cette vue de page. Cette valeur est attribuée à la touche |
chaîne | Obligatoire (peut être nul). Spécifiez le nom d’un compte utilisateur à associer à cette vue de page. Cette valeur est attribuée à la touche |
chaîne | Obligatoire (peut être nul). Spécifiez le nom d'un produit à associer à cette vue de page. Cette valeur est attribuée à la touche |
Exemples
Enregistrer trois attribut utilisateur
NewRelic.Api.Agent.NewRelic.SetUserParameters("MyUserName", "MyAccountName", "MyProductName");Enregistrer deux attribut utilisateur et un attribut vide
NewRelic.Api.Agent.NewRelic.SetUserParameters("MyUserName", "", "MyProductName");Syntaxe
NewRelic.Api.Agent.NewRelic.StartAgent()Démarrez l'agent s'il n'a pas déjà démarré. Généralement inutile.
Exigences
- Compatible avec toutes les versions d'agent.
- Compatible avec tous les types d'applications.
Description
Démarre l'agent s'il n'a pas déjà été démarré. Cet appel est généralement inutile, car l'agent démarre automatiquement lorsqu'il rencontre une méthode instrumentée, sauf si vous désactivez autoStart. Si vous utilisez SetApplicationName(), assurez-vous de définir le nom de l'application avant de démarrer l'agent.
Conseil
Cette méthode démarre l'agent de manière asynchrone (ce qui signifie qu'elle ne bloquera pas le démarrage de l'application) sauf si vous activez syncStartup ou sendDataOnExit.
Exemples
NewRelic.Api.Agent.NewRelic.StartAgent();Syntaxe
NewRelic.Api.Agent.TraceMetadata;Renvoie les propriétés de l'environnement d'exécution actuel utilisées pour prendre en charge le tracing.
Exigences
- Version de l'agent 8.19 ou supérieure.
- Compatible avec tous les types d'applications.
- le tracing distribué doit être activé pour obtenir des valeurs significatives.
Description
Donne accès aux propriétés suivantes :
Propriétés
Nom | Description |
|---|---|
| Renvoie une chaîne représentant la trace en cours d'exécution. Si l'ID trace n'est pas disponible ou si le tracing distribué est désactivé, la valeur sera |
| Renvoie une chaîne représentant la plage en cours d'exécution. Si l'ID de portée n'est pas disponible ou si le tracing distribué est désactivé, la valeur sera |
| Renvoie |
Exemples
IAgent agent = NewRelic.Api.Agent.NewRelic.GetAgent();ITraceMetadata traceMetadata = agent.TraceMetadata;string traceId = traceMetadata.TraceId;string spanId = traceMetadata.SpanId;bool isSampled = traceMetadata.IsSampled;