Options de configuration d'AppSignal pour Browser

Browser monitoring est une fonctionnalité en beta d’AppSignal Labs. Le package @appsignal/browser est publié sous le tag beta sur npm, et sa configuration ainsi que son API peuvent encore changer d’une release beta à l’autre. Partagez vos retours dans notre communauté Discord.

Passez la configuration à init() dans un seul objet. Seul key est obligatoire. Un second appel à init() est ignoré jusqu’à ce que vous appeliez destroy(). La plupart des applications changent les options à leur prochain build.

import { init } from "@appsignal/browser";

init({
  key: "<YOUR_FRONTEND_API_KEY>",
  endpoint: "https://appsignal-endpoint.net",
  active: process.env.NODE_ENV === "production",
  appVersion: "<YOUR_APP_REVISION>",
  tracePropagationTargets: ["api.example.com/**"],
  errors: { sampleRate: 1.0 },
  breadcrumbs: { console: false },
  privacy: {
    queryParamsAllowlist: ["utm_*", "page"],
    networkBlocklist: ["api.stripe.com/**"],
    dom: { blockElement: ["#card-form"] },
  },
});

`key`

Type : string
Obligatoire

La Front-end API key de votre application, destinée à être exposée publiquement. Ce n’est pas l’une des Push keys utilisées par vos intégrations back-end.

`endpoint`

Type : string
Valeur par défaut : l’origine de la page courante

L’endroit où les données sont envoyées. Définissez-le sur https://appsignal-endpoint.net. Si vous relayez le trafic AppSignal via votre domaine, laissez-le vide pour utiliser l’origine courante. Une barre oblique finale est retirée. Les erreurs sont envoyées à POST /ingest/browser/errors, et les web vitals à POST /ingest/browser. La clé voyage en paramètre de requête api_key, ce qui est utile à savoir si vous maintenez une allowlist connect-src.

`active`

Type : boolean
Valeur par défaut : true

L’interrupteur principal pour le premier appel à init(). Quand il vaut false, l’initialisation retourne sans modifier la page, sans démarrer de minuteur ni émettre de requête. Un second appel à init() ne peut pas désactiver un SDK déjà en cours d’exécution. Toutes les autres fonctions ne font rien non plus, vous pouvez donc les appeler partout sans vérification préalable. Définissez-le depuis votre environnement de build pour que les exécutions de développement, de test et de CI n’envoient rien :

init({
  key: "<YOUR_FRONTEND_API_KEY>",
  active: process.env.NODE_ENV === "production", // or import.meta.env.PROD
});

`appVersion`

Type : string

Le tag de release, le SHA de commit ou l’ID de deploy du build en cours d’exécution. Il étiquette les erreurs et les web vitals pour les filtres de version des vues Browser. Il sélectionne aussi les sourcemaps pour les backtraces. Pour en savoir plus, consultez notre guide des deploy markers.

`serviceName`

Type : string
Valeur par défaut : "Browser"

AppSignal utilise cette valeur comme nom de service pour les erreurs du navigateur dans une trace. Par exemple, serviceName: "Checkout UI" affiche Checkout UI au lieu de la valeur par défaut Browser dans la chronologie de trace. Utilisez une valeur différente pour chaque front-end que vous surveillez. Le SDK l’envoie avec chaque rapport d’erreur. Consultez tracing distribué pour Browser.

`tracePropagationTargets`

Type : string[]
Valeur par défaut : []

Utilisez cette liste pour choisir quelles requêtes API portent un en-tête traceparent. Chaque motif doit comporter un hôte et un chemin. Par exemple, ["api.example.com/**"] correspond à tous les chemins de api.example.com. api.example.com seul ne correspond à rien. Si une requête correspondante renvoie une réponse 5xx ou expire, le SDK rapporte une erreur du navigateur. Pour voir les spans back-end dans sa trace, instrumentez le service qui la reçoit pour qu’il lise l’en-tête. La liste vide par défaut n’ajoute aucun en-tête traceparent. Consultez tracing distribué pour Browser pour la configuration et des exemples.

`beforeError`

Type : (event: IncomingError) => IncomingError | null

Appelé pour les erreurs qui passent l’échantillonnage et la limite de débit globale, avant la création d’un breadcrumb ou d’un rapport d’erreur. Retournez null pour écarter l’erreur, ou modifiez ses champs pour les expurger. Pour en savoir plus, consultez filtrer les erreurs. Ce callback doit être synchrone. Une promesse retournée est détectée, journalisée via console.error, et l’erreur est écartée.

`beforeBreadcrumb`

Type : (breadcrumb: Breadcrumb) => Breadcrumb | null

S’exécute une fois pour chaque breadcrumb, au moment de son enregistrement. Retournez null pour le jeter, ou modifiez message et data pour retirer du texte sensible. Cela s’exécute souvent : gardez-le rapide.

`errors.enabled`

Type : boolean
Valeur par défaut : true

Si les erreurs sont rapportées ou non. Quand il vaut false, le SDK continue de les écouter mais n’envoie rien.

`errors.sampleRate`

Type : number entre 0 et 1
Valeur par défaut : 1.0

La proportion d’erreurs à rapporter. Le choix est fait au hasard pour chaque erreur, donc 0.25 rapporte environ un quart d’entre elles. Cela se produit avant les limites de débit et avant l’exécution de beforeError.

`breadcrumbs.network`

Type : boolean
Valeur par défaut : true

Enregistre des breadcrumbs pour les appels fetch et XMLHttpRequest, à l’exception des requêtes annulées. Cette option ne contrôle pas le breadcrumb du chargement initial du document. Le SDK ne lit pas les corps de requête ni de réponse.

`breadcrumbs.console`

Type : boolean
Valeur par défaut : true

Enregistre un breadcrumb pour console.warn et console.error. console.log n’est pas modifié.

`breadcrumbs.clicks`

Type : boolean
Valeur par défaut : true

Enregistre un breadcrumb quand un utilisateur sélectionne un élément.

`breadcrumbs.longTasks`

Type : boolean
Valeur par défaut : true

Enregistre un breadcrumb quand le thread principal est bloqué plus de 50 ms.

`privacy.queryParamsAllowlist`

Type : string[]
Valeur par défaut : []

Les paramètres de requête à conserver dans les URL enregistrées. Utilisez * pour faire correspondre plusieurs noms à la fois : "utm_*" conserve donc tous les paramètres UTM. La liste par défaut est vide, ce qui les supprime tous. Pour en savoir plus, consultez confidentialité et filtrage.

`privacy.networkBlocklist`

Type : string[]
Valeur par défaut : []

Des motifs d’URL en glob pour les appels fetch et XMLHttpRequest qui ne sont enregistrés ni comme breadcrumbs ni comme erreurs de requête échouée. Comparés à l’hôte et au chemin. Les appels ont toujours lieu. Cette option ne filtre pas le breadcrumb du chargement initial du document.

`privacy.dom.maskText`

Type : string[]
Valeur par défaut : []

Des sélecteurs CSS dont le contenu textuel est remplacé par [masked] dans les breadcrumbs click. Le breadcrumb est tout de même enregistré, vous conservez donc le fait qu’une interaction a eu lieu.

`privacy.dom.blockElement`

Type : string[]
Valeur par défaut : []

Des sélecteurs CSS dont les interactions ne sont pas enregistrées du tout. Utilisez-les pour les formulaires de carte bancaire et les autres champs qui ne doivent jamais apparaître.

Référence de l’API

À l’exception d’init(), ces fonctions ne font rien tant que le SDK n’a pas été initialisé avec active: true.

Fonction	Description
`init(config)`	Démarre la collecte. À appeler une fois, le plus tôt possible. Les appels suivants sont ignorés.
`captureError(error)`	Rapporte une erreur interceptée. L’argument de contexte optionnel n’est pas inclus dans les rapports d’erreur ordinaires pendant cette bêta. Pour en savoir plus, consultez error tracking.
`addBreadcrumb({ category, message, data? })`	Ajoute votre propre breadcrumb à la chronologie.
`setRouteTemplate(template)`	Déclare la route sur laquelle se trouve l’utilisateur, par exemple `/users/:id`. Passez `null` pour l’effacer.
`setTags(tags)`	Attache des tags à chaque erreur rapportée à partir de maintenant. Fusionne avec les tags existants.
`clearTags()`	Supprime tous les tags. Les tags survivent à un rechargement : appelez donc ceci à la déconnexion.
`flush()`	Envoie immédiatement les web vitals mises en tampon.
`destroy()`	Envoie les données en attente et arrête la collecte. Un nouvel appel à `init()` peut la redémarrer, y compris sur la même page.

SDK & télémétrie

SDK de langage

Outils de télémétrie

Options de configuration d'AppSignal pour Browser

`key`

`endpoint`

`active`

`appVersion`

`serviceName`

`tracePropagationTargets`

`beforeError`

`beforeBreadcrumb`

`errors.enabled`

`errors.sampleRate`

`privacy.queryParamsAllowlist`

`privacy.networkBlocklist`

`privacy.dom.maskText`

`privacy.dom.blockElement`

Référence de l’API

​key

​endpoint

​active

​appVersion

​serviceName

​tracePropagationTargets

​beforeError

​beforeBreadcrumb

​errors.enabled

​errors.sampleRate

​breadcrumbs.network

​breadcrumbs.console

​breadcrumbs.clicks

​breadcrumbs.longTasks

​privacy.queryParamsAllowlist

​privacy.networkBlocklist

​privacy.dom.maskText

​privacy.dom.blockElement

​Référence de l’API

`key`

`endpoint`

`active`

`appVersion`

`serviceName`

`tracePropagationTargets`

`beforeError`

`beforeBreadcrumb`

`errors.enabled`

`errors.sampleRate`

`breadcrumbs.network`

`breadcrumbs.console`

`breadcrumbs.clicks`

`breadcrumbs.longTasks`

`privacy.queryParamsAllowlist`

`privacy.networkBlocklist`

`privacy.dom.maskText`

`privacy.dom.blockElement`

Référence de l’API