Configuration du collecteur « Node.js »

Le collecteur tente de communiquer avec l'agent Instana via l'adresse IP 127.0.0.1 et via la passerelle par défaut de l'hôte en tant qu'option de secours. Si l'agent n'est pas disponible via l'une de ces adresses IP, indiquez l'option agentHost pour utiliser une adresse IP personnalisée.

require('@instana/collector')({
  agentHost: '::1' // use IPv6 to contact via localhost
});
 

Ou tirez parti d'une variable d'environnement.

require('@instana/collector')({
  agentHost: process.env.HOST_IP
});
 

S'il n'est pas configuré, le collecteur Instana recherche une variable d'environnement appelée INSTANA_AGENT_HOST et utilise ce qui est défini dans cette variable d'environnement pour communiquer avec l'agent. S'il n'existe pas de variable d'environnement de ce type, il va d'abord essayer de contacter l'agent sur localhost, puis sur la passerelle par défaut.

Le collecteur tente de communiquer avec l'agent Instana via le port 42699. Si le port a été modifié, vous pouvez utiliser l'option agentPort pour modifier le port.

require('@instana/collector')({
  agentPort: 42699
});
 

S'il n'est pas configuré, le collecteur Instana recherche une variable d'environnement appelée INSTANA_AGENT_PORT et utilise ce qui est défini dans cette variable d'environnement pour communiquer avec l'agent. S'il n'existe pas de variable d'environnement de ce type, il bascule sur le port par défaut 42699.

Si votre application Node.js et l'agent Instana s'exécutent dans un cluster Kubernetes, consultez la documentation relative à l'accès réseau à l'adresse Kubernetes pour obtenir des informations sur la configuration requise dans ce contexte.

Dans les environnements non « serverless » équipés d'un agent Instana, le Tracer d' Node.js déclenche des événements d'incident lorsqu'il détecte que la version d' Node.js en cours d'exécution a atteint sa fin de vie (EOL).

Pour désactiver ces événements EOL, vous pouvez les désactiver à l'aide de la variable d'environnement suivante :

INSTANA_TRACING_DISABLE_EOL_EVENTS=true
 

Pour obtenir la liste complète des versions d' Node.js en fin de vie, consultez la page officielle des versions d' Node.js.

Par défaut, l'outil Tracer de Instana Node.js ne capture que les segments de sortie pour lesquels il existe un segment d'entrée actif. Vous pouvez activer cette fonction pour permettre au traceur de tracer des travées de sortie autonomes.

Pour activer cette fonction, utilisez l'une des options suivantes :

• Définissez la variable INSTANA_ALLOW_ROOT_EXIT_SPAN d'environnement.

• Configurer la fonction par le biais de la fonction d'initialisation du traceur :

  require('@instana/collector')({
  tracing: {
    allowRootExitSpan: true
  }
  });
   

Si INSTANA_ALLOW_ROOT_EXIT_SPAN est configuré sur 1 ou true, ou si allowRootExitSpan est défini sur true, le traceur capture les segments de sortie même en l'absence de segment d'entrée actif.

Cette fonctionnalité est utile dans les cas suivants, où les tâches sont déclenchées par un mécanisme qui n'est pas pris en charge par l'instrumentation automatique d' Instana :

• Messages entrants provenant de bibliothèques de messagerie non prises en charge
• Les requêtes effectuées via des protocoles non pris en charge, tels que le protocole « raw » Transmission Control Protocol ( TCP ) ou WebSocket
• Les tâches planifiées qui sont lancées en interne par l'application en utilisant des mécanismes tels que " setTimeout, " setInterval ou des bibliothèques de planification Node.js non prises en charge

À partir de l'outil de traçage d' Node.js ( Tracer 4.9.0 ), vous pouvez réduire l'ingestion de données superflues en excluant certaines traces ou certains appels. Ce mécanisme de filtrage affine la collecte de vos traces. Pour désactiver les traces, définissez ces paramètres dans les paramètres de configuration de Tracer de l' Node.js :

• Technologie : Indiquez la technologie concernée, par exemple, Kafka, Redis DynamoDB, ou HTTP.
• Méthode : Identifiez la méthode à exclure. Par exemple, excluez ces méthodes pour les technologies suivantes :
  • Kafka: send, consume
  • Redis: get, type
  • DynamoDB: query, scan
  • HTTP: get, post
• Terminal (le cas échéant) : affinez davantage le filtrage en fonction de terminaux spécifiques. Par exemple, les points de terminaison pour les technologies suivantes sont définis comme suit :
  • Kafka: Le point de terminaison correspond au nom du sujet.
  • HTTP: Le point de terminaison correspond au chemin d'accès URL.
• Connexion (facultatif) : exclure les traces d'une connexion spécifique. Par exemple, la connexion pour les technologies suivantes est définie comme suit :
  • Redis: La connexion correspond à la chaîne de connexion.
  • HTTP: La connexion comprend l'hôte et le port.

Pour désactiver le traçage, vous pouvez soit le désactiver complètement, soit exclure de manière sélective certaines instrumentations ou des groupes entiers, tels que les bases de données, la messagerie ou la journalisation. Cette flexibilité vous permet d'ajuster le traçage en fonction des besoins de votre application.

Pour appliquer la configuration permettant de désactiver le traçage, utilisez l'une des méthodes suivantes :

• Variables d'environnement
• Configuration en code
• Configuration de l'agent ( YAML )

Le traçage automatique est également activé par défaut. Pour désactiver uniquement le traçage automatique (en laissant le traçage manuel activé avec le kit SDK ou openTraing), indiquez l'option suivante dans la fonction d'initialisation :

require('@instana/collector')({
  tracing: {
    automaticTracingEnabled: false
  }
});
 

Enfin, vous pouvez désactiver le traçage automatique en définissant la variable d'environnement INSTANA_DISABLE_AUTO_INSTR=true.

Lorsque le traçage automatique est désactivé, vous pouvez toujours utiliser le kit SDK ou l'API OpenTracing pour créer des étendues manuellement.

L'intégration d'Opentelemetry est activée par défaut. Pour désactiver l'intégration, transmettez l'option suivante à la fonction d'initialisation:

require('@instana/collector')({
  tracing: {
    useOpentelemetry: false
  }
});
 

De plus, vous pouvez désactiver l'intégration d' OpenTelemetry en définissant la variable INSTANA_DISABLE_USE_OPENTELEMETRY sur true. Pour plus d'informations, consultez la section « Variables d'environnement » sur Instana.

Pour empêcher le collecteur Instana Node.js de tracer les threads de travail, définissez la variable d'environnement suivante :

INSTANA_DISABLE_WORKER_THREADS=true

Cette configuration désactive le traçage pour tous les threads de travail, mais le processus principal continue d'être tracé automatiquement. Utilisez cette configuration lorsque les threads de travail exécutent des tâches internes ou en arrière-plan que vous souhaitez exclure du traçage.

Par défaut, le collecteur enregistre les 10 derniers points d'appel pour chaque intervalle de sortie capturé. Cette valeur peut être augmentée ou diminuée selon vos besoins.

Vous pouvez configurer deux aspects de la capture de la trace de pile :

• Longueur de la trace de pile : nombre de points d'appel à capturer.
  • Valeurs acceptées : 0 à 500
  • Valeur par défaut : 10
• Mode de trace de pile : comment les traces de pile sont-elles capturées?
  • Valeurs prises en charge :
    • all: Récupère la trace de pile pour tous les segments de sortie (par défaut).

      # Captures stack trace for all spans.
      INSTANA_STACK_TRACE=all

    • error: Ne recueille la trace de la pile que pour les segments présentant des erreurs.

      # Captures stack trace only for erroneous spans.
      INSTANA_STACK_TRACE=error

    • none: Ne recueille pas la trace de la pile.

      # Disable collection of stack trace.
      INSTANA_STACK_TRACE=none

Vous pouvez configurer la capture de la trace de pile en utilisant l'une des options suivantes :

• Variables d'environnement
• Configuration en code
• Configuration de l'agent

Le collecteur « Instana » tente de localiser le fichier package.json principal de votre projet afin d'en extraire des informations importantes, telles que le nom de votre application. Si vous devez définir un chemin personnalisé pour votre fichier package.json ou si le collecteur ne parvient pas à localiser le fichier, vous pouvez utiliser l'option de configuration nommée packageJsonPath.

require('@instana/collector')({
  packageJsonPath: 'absolute/path/to/package.json'
});
 

Vous pouvez également configurer le chemin du fichier package.json en définissant la variable d'environnement INSTANA_PACKAGE_JSON_PATH .

Les services sont un concept central dans Instana. Les appels, les étendues et les traces sont étroitement associés aux services. Par défaut, le collecteur Node.js utilise les attributs name et version à partir du fichier principal package.json. Pour personnaliser le nom du service, vous pouvez configurer la propriété serviceName.

require('@instana/collector')({
  serviceName: 'shop'
});
 

Vous pouvez également configurer un nom de service personnalisé en définissant la variable d'environnement INSTANA_SERVICE_NAME. Pour plus d'informations sur la configuration d'un service personnalisé, consultez la section « Définition du nom du service au niveau global ».

À partir de la version 4.x du collecteur, les en-têtes de corrélation de la trace Kafka sont toujours envoyés dans le format " string, ce qui élimine le support du format " binary. Pour plus d'informations, voir Migration des en-têtesKafka.

Supprimer toutes les configurations qui font référence à la variable d'environnement " INSTANA_KAFKA_HEADER_FORMAT et à l'option de configuration " tracing: { kafka: { headerFormat: .... }}}.

Si vous souhaitez modifier le niveau de journalisation par défaut, vous pouvez le configurer via :

require('@instana/collector')({
  level: 'debug'
});
 

Vous pouvez également configurer le niveau de consignation en affectant à la variable d'environnement INSTANA_LOG_LEVEL la valeur debug, info, warn ou error. Enfin, la définition de INSTANA_DEBUG avec une chaîne non vide va définir le niveau de journalisation sur debug.

Notez que le niveau de journalisation par défaut est info. Si vous constatez la présence de journaux de débogage inattendus liés à Instana (lignes de journal contenant "name":"@instana/collector" et "level":20), vérifiez si vous avez défini le niveau de journalisation sur « debug » dans votre configuration ou si INSTANA_LOG_LEVEL=debug ou INSTANA_DEBUG est activé. Si vous fournissez votre propre consignateur (voir ci-dessous), vous êtes responsable de la définition du niveau de journalisation sur ce consignateur comme vous le souhaitez.

Voir la configuration de l'enregistreur.