> ## Documentation Index
> Fetch the complete documentation index at: https://docs.appsignal.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Instrumentation personnalisée pour Node.js
đ N'hĂ©sitez pas Ă [nous contacter](mailto:support@appsignal.com) si vous rencontrez
des problĂšmes lors de la mise en Ćuvre d'instrumentations personnalisĂ©es. Nous sommes lĂ pour vous aider !
L'inclusion d'une instrumentation personnalisĂ©e dans votre application peut ĂȘtre utile pour identifier les lignes de code spĂ©cifiques qui causent des problĂšmes de performance. AppSignal fournit des [helpers](#helpers), qui vous permettent d'afficher des donnĂ©es pertinentes sur l'Ă©tat de votre application aux cĂŽtĂ©s des mĂ©triques de performance, afin de vous aider Ă identifier les causes profondes de tout problĂšme de performance que votre application pourrait rencontrer.
## Configuration
Pour utiliser les fonctions helper d'AppSignal dans votre instrumentation, vous devez d'abord [importer `opentelemetry` et dĂ©finir un objet tracer](#import-opentelemetry-and-define-tracer). Selon votre instrumentation, vous devrez peut-ĂȘtre Ă©galement [crĂ©er des spans supplĂ©mentaires](#spans).
Nos [exemples de cas d'usage](#example-use-cases) montrent comment vous pouvez utiliser les tracers, les spans et les helpers pour créer votre instrumentation personnalisée.
### Importer OpenTelemetry et définir un Tracer
L'intégration AppSignal pour Node.js utilise les objets tracer d'OpenTelemetry. Ces tracers contiennent diverses fonctions pour créer des instrumentations personnalisées.
Le Tracer expose des fonctions pour créer de nouveaux spans. Cette documentation décrit comment vous pouvez utiliser les tracers et les spans pour implémenter votre intégration personnalisée.
Vous devez d'abord importer l'objet trace depuis `@opentelemetry/api` avant de travailler avec les tracers et les spans. En invoquant la fonction `getTracer` sur l'objet trace, un nouvel objet tracer peut ĂȘtre crĂ©Ă©. Vous devez donner un nom Ă votre objet tracer dans cette fonction, comme dans l'exemple ci-dessous, oĂč la fonction `getTracer` est utilisĂ©e pour dĂ©finir un tracer avec le nom `"my interesting app"`.
```javascript Node.js theme={null}
import { trace } from "@opentelemetry/api";
const tracer = trace.getTracer("my-interesting-app");
```
### Spans
Un span est le nom de l'objet que nous utilisons pour capturer des données sur les performances de votre application, les éventuelles erreurs et le contexte qui les entoure. Un span fait partie d'une trace plus large, une représentation hiérarchique du flux de données à travers votre application. Les spans gardent la trace de l'heure de début et de fin d'un événement, ainsi que d'autres informations, telles que le nom ou d'autres données qui s'y rapportent.
Vous pouvez en savoir plus sur les spans dans la [documentation de traçage OpenTelemetry](https://opentelemetry.io/docs/instrumentation/js/api/tracing/).
### Créer un span actif
De nouveaux spans peuvent ĂȘtre invoquĂ©s via l'[objet trace](#import-opentelemetry-and-define-tracer). Le code instrumentĂ© Ă l'intĂ©rieur d'un handler Express ou Koa sera dĂ©jĂ Ă l'intĂ©rieur d'un span. Vous pouvez crĂ©er de nouveaux spans en invoquant la fonction `startActiveSpan()` sur l'objet tracer. Les spans nouvellement crĂ©Ă©s seront l'enfant du span dans lequel ils ont Ă©tĂ© crĂ©Ă©s, s'il en existe un. Vous pouvez utiliser des spans enfants pour mesurer les performances des tĂąches exĂ©cutĂ©es depuis un span parent.
Vous devez donner à votre span un nom qui rend son objectif clair. Exécutez toutes les tùches que vous souhaitez surveiller dans la fonction `startActiveSpan()`, comme dans l'exemple ci-dessous.
```javascript Node.js theme={null}
tracer.startActiveSpan("printing coffee beans", async (span) => {
const coffeeBeans = await fetchAllCoffeeBeans();
console.log(coffeeBeans);
span.end();
});
```
Une fois la tùche terminée, vous devez fermer le span : `span.end()`
### Exemples de cas d'usage
Lors de la mise en Ćuvre d'une instrumentation personnalisĂ©e, vous pouvez ĂȘtre curieux de comprendre le comportement de fonctions particuliĂšres, par exemple combien de temps elles mettent Ă s'exĂ©cuter.
#### Utilisation des helpers
Dans l'exemple ci-dessous, nous nous intĂ©ressons aux performances de notre endpoint GET « order-coffee » pour diffĂ©rentes torrĂ©factions de cafĂ©. Pour Ă©tudier cela, nous utilisons la fonction `setAttribute` pour crĂ©er un [tag](#tag) appelĂ© flavor, dont la valeur est rĂ©cupĂ©rĂ©e depuis les paramĂštres de la requĂȘte.
**Note :** Ă©tant donnĂ© qu'il s'agit d'un handler de requĂȘte Express, un span racine a dĂ©jĂ Ă©tĂ© crĂ©Ă©.
```javascript Node.js theme={null}
app.get('/order-coffee', (req, res) => {
const roast = req.params.roast
setTag("roast", roast)
const coffeeBeans = pickCoffeeBeans(roast)
prepareCoffeeBag(coffeeBeans)
})
}
```
Pour obtenir des informations plus approfondies sur les performances de notre code, nous pouvons utiliser des spans enfants pour inspecter les fonctions appelées dans notre handler Express.
Le code ci-dessous crée un span enfant du span `"picking coffee beans"` défini dans la fonction `pickCoffeeBeans`.
Une fois l'attribut assigné et toutes les fonctions exécutées, nous appelons `.end()` sur le span pour nous assurer qu'AppSignal reçoit l'heure de début et de fin ainsi que les attributs que nous avons assignés :
```javascript Node.js theme={null}
function pickCoffeeBeans(roast) {
tracer.startActiveSpan("picking coffee beans", async (span) => {
const roastBrands = {
light: "Caffinated Cloud",
medium: "Feeling The Buzz",
dark: "The Jitters",
};
const roastBrand = roastBrands[roast];
setTag("brand", roastBrand);
await retrieveDrinkTypes(roastBrand);
span.end();
});
}
```
Dans AppSignal, nous pouvons voir les données de performance pour cette fonction. Nous pouvons utiliser les tags roast et batch pour filtrer les données et obtenir des informations plus approfondies sur les paramÚtres qui pourraient influencer le comportement du code de notre application.
#### Spans actifs
Bien que les tags soient utiles pour analyser les diffĂ©rences de performance sur une mĂȘme fonction, ils ne nous donnent pas d'aperçu des performances des fonctions appelĂ©es depuis notre fonction.
Pour obtenir plus d'informations sur ce qui se passe à l'intérieur de `pickCoffeeBeans()`, nous créons un nouveau `activeSpan` et le nommons « picking coffee beans ». Toute la logique que nous souhaitons suivre est exécutée à l'intérieur d'une fonction async.
Nous attendons (`await`) la promesse retournée par `retrieveDrinkTypes()`, afin de pouvoir suivre ses performances en tant que span enfant du span `"picking coffee beans"` que nous avons créé dans `pickCoffeeBeans()`.
```javascript Node.js theme={null}
function pickCoffeeBeans(roast) {
tracer.startActiveSpan("picking coffee beans", async (span) => {
const roastBrands = {
light: "Caffinated Cloud",
medium: "Feeling The Buzz",
dark: "The Jitters",
};
const roastBrand = roastBrands[roast];
await retrieveDrinkTypes(roastBrand);
span.end();
});
}
function retrieveDrinkTypes(roastBrand) {
return new Promise((resolve) => {
const span = tracer.startActiveSpan("Fetching coffee types");
const brandDrinks = {
"Caffinated Cloud": ["americano", "capuccino"],
"Feeling The Buzz": ["capuccino", "latte"],
"The Jitters": ["espresso"],
};
const drinkTypes = brandDrinks[roastBrand];
// we want to give our Barista's some time prepare the machine
setTimeout(() => {
resolve(drinkTypes);
span.end();
}, 60000);
});
}
```
Avec cette instrumentation, AppSignal fournira des informations sur les performances de `pickCoffeeBeans()`, ce qui inclura les données de performance de la fonction `retrieveDrinkTypes()`, offrant ainsi une meilleure compréhension des facteurs qui impactent les performances globales d'une fonction.
## Helpers
Les données envoyées à AppSignal ne doivent contenir aucune donnée personnelle, telle que
des noms, des adresses e-mail, etc. Il est de votre responsabilité de vous assurer que les
donnĂ©es de votre application sont assainies avant d'ĂȘtre transmises Ă AppSignal. Lorsqu'il est
nécessaire d'identifier une personne, votre application doit utiliser d'autres formes
d'identification telles qu'un identifiant utilisateur, un hash ou un pseudonyme.
Pour utiliser les fonctions helper, vous devez d'abord les importer depuis `@appsignal/nodejs`. Dans l'exemple ci-dessous, le namespace dans lequel le code est exécuté est signalé à AppSignal. Toutes les fonctions helper disponibles sont décrites dans la [documentation ci-dessous](/#helper-functions).
```javascript Node.js theme={null}
import { setNamespace } from "@appsignal/nodejs";
setNamespace("web");
```
Toutes les fonctions helper disponibles pour les attributs d'instrumentation personnalisée sont décrites dans la [liste ci-dessous](#helper-functions).
### Fonctions helper
Les extraits de code pour les helpers ci-dessous supposent que votre code est dĂ©jĂ
instrumentĂ© (par exemple, Ă l'intĂ©rieur d'un handler de requĂȘte Express ou Koa). Si votre
code n'est pas déjà instrumenté, vous devez [créer un span](#spans) et utiliser les
helpers à l'intérieur de celui-ci.
* [Namespace](#namespace)
* [Tag](#tag)
* [ParamĂštres de requĂȘte](#request-parameters)
* [Définir les données de session](#set-session-data)
* [En-tĂȘtes de requĂȘte](#request-headers)
* [Nom racine](#root-name)
* [Données personnalisées](#custom-data)
* **[Helpers de span enfant :](#child-span-helpers)**
* [Catégorie](#category)
* [Nom](#name)
* [Corps](#body)
### Namespace
DĂ©finit la valeur de chaĂźne du namespace du span racine.
```javascript JavaScript theme={null}
import { setNamespace } from "@appsignal/nodejs";
setNamespace("app");
```
### Tag
DĂ©finit un tag, par exemple Ă partir d'un paramĂštre de requĂȘte, qui peut ĂȘtre utilisĂ© comme filtre dans l'application AppSignal. Dans l'exemple ci-dessous, nous crĂ©ons un tag appelĂ© color avec la valeur blue. Vous pouvez configurer les tags avec des noms pertinents pour le contexte de votre application.
```javascript Node.js theme={null}
import { setTag } from "@appsignal/nodejs";
setTag("color", "blue");
```
### ParamĂštres de requĂȘte
Un objet sĂ©rialisable en JSON. Les paramĂštres de requĂȘte entrants, le corps de la requĂȘte et les paramĂštres de requĂȘte.
```javascript Node.js theme={null}
import { setParams } from "@appsignal/nodejs";
const exampleParams = { action: "delete" };
setParams(exampleParams);
```
### Définir les données de session
Un objet sérialisable en JSON.
```javascript Node.js theme={null}
import { setSessionData } from "@appsignal/nodejs";
const exampleSessionData = { locale: "en-GB" };
setSessionData(exampleSessionData);
```
### En-tĂȘtes de requĂȘte
Une chaĂźne contenant la valeur de l'en-tĂȘte.
```javascript Node.js theme={null}
import { setHeader } from "@appsignal/nodejs";
setHeader("Content-type", "application/json");
```
### Nom racine
Vous permet de définir le nom de la trace. Les échantillons sont regroupés en actions en fonction de leur nom de trace.
```javascript Node.js theme={null}
import { setRootName } from "@appsignal/nodejs";
// somewhere in your code where there's an active span...
setRootName("The action name");
```
#### Exemple de cas d'usage
Votre application a un endpoint appelé `GET /coffee`.
```javascript Node.js theme={null}
app.get("/coffee", (req, res) => {
// ...
});
```
Toutes les requĂȘtes vers cet endpoint gĂ©nĂ©reront des Ă©chantillons appelĂ©s `GET /coffee`, mais votre endpoint gĂšre plusieurs actions : `coffee?action=buy` et `coffee?action=sell`.
Bien qu'elles utilisent toutes l'endpoint `GET /coffee`, elles sont conceptuellement trĂšs diffĂ©rentes et il serait donc logique qu'elles soient regroupĂ©es sĂ©parĂ©ment dans AppSignal plutĂŽt que dans le mĂȘme Ă©chantillon `GET /coffee`. Pour ce faire, vous pouvez utiliser le helper `setRootName()` :
```javascript Node.js theme={null}
import { setRootName } from "@appsignal/nodejs";
app.get("/coffee", (req, res) => {
if (req.query.action === "buy") {
setRootName("Buy coffee");
// ... buy coffee
} else if (req.query.action === "sell") {
setRootName("Sell coffee");
// ... sell coffee
}
});
```
L'utilisation de `setRootName` modifiera le nom du span racine, regroupant les Ă©chantillons des requĂȘtes `coffee?action=buy` et `coffee?action=sell` dans des actions distinctes :
### Données personnalisées
Un objet sérialisable en JSON.
```javascript Node.js theme={null}
import { setCustomData } from "@appsignal/nodejs";
const exampleCustomData = { stroopwaffle: "true", coffee: "false" };
setCustomData(exampleCustomData);
```
### Helpers de span enfant
Les helpers suivants ne s'appliquent qu'aux spans enfants. Pour créer un span enfant, vous devez créer un nouveau [span actif](#creating-an-active-span).
Les nouveaux spans sont automatiquement enfants de leur span parent.
#### Catégorie
Une chaßne contenant la catégorie du span enfant. Le nom doit utiliser `.` pour exprimer l'héritage hiérarchique de la catégorie. Par exemple : `cafe.coffee.cupsize`
```javascript Node.js theme={null}
import { setCategory } from "@appsignal/nodejs";
setCategory("category.name");
```
#### Nom
Une chaßne contenant le titre de la chronologie d'événements du span enfant.
```javascript Node.js theme={null}
import { setName } from "@appsignal/nodejs";
setName("Users query");
```
#### Corps
đ N'envoyez pas d'informations personnelles identifiables (PII) Ă AppSignal. Filtrez les PII (par exemple, noms, e-mails) et utilisez un identifiant, un hash ou un identifiant pseudonymisĂ© Ă la place.
Pour les entités couvertes par la HIPAA, plus d'informations sur la signature d'un Business Associate Agreement (BAA) sont disponibles dans notre documentation Business Add-Ons.
Le corps du span peut inclure des informations supplĂ©mentaires sur l'Ă©vĂ©nement, comme la requĂȘte HTTP, l'hĂŽte connectĂ©, etc. Veillez Ă assainir les informations avant de les ajouter au span afin qu'aucune information personnelle identifiable ne soit envoyĂ©e Ă AppSignal. Ces informations seront visibles pour le span lors du survol de la chronologie d'Ă©vĂ©nements.
Pour stocker des requĂȘtes SQL dans le corps du span, veuillez utiliser le [helper `setSqlBody`](#sql-body) Ă la place.
```javascript Node.js theme={null}
import { setBody } from "@appsignal/nodejs";
setBody("Span body");
```
#### Corps SQL
Disponible depuis le package Node.js 3.0.25.
DĂ©finir une requĂȘte SQL comme corps du span tel qu'elle apparaĂźt dans la chronologie des Ă©vĂ©nements de performance dans la vue dĂ©taillĂ©e d'un Ă©chantillon d'incident. Ceci est similaire au [helper `setBody`](#body), mais spĂ©cialisĂ© pour les requĂȘtes SQL. Toute requĂȘte SQL dĂ©finie comme corps avec cet attribut sera assainie pour Ă©viter d'envoyer des donnĂ©es PII (Personal Identifiable Information) Ă nos serveurs.
Consultez le [helper `setBody`](#body) pour plus de détails sur le fonctionnement de l'attribut body.
Lorsque les helpers `setBody` et `setSqlBody` sont appelĂ©s sur le mĂȘme span, la valeur du helper `setSqlBody` prĂ©vaut et la valeur du helper `setBody` sera ignorĂ©e.
```javascript Node.js theme={null}
import { setSqlBody } from "@appsignal/nodejs";
setSqlBody("SELECT * FROM users");
```