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.

Par défaut, le collecteur Instana Node.js traite et transmet les en-têtes tracestate W3C traceparent et à des fins de corrélation des traces distribuées. Vous pouvez désactiver la corrélation, la propagation ou les deux à la fois dans « W3C », de manière indépendante, en fonction de vos besoins en matière de traçabilité.

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

Lorsqu'une bibliothèque de journalisation prise en charge est instrumentée, le collecteur d' Node.js s capture les appels de journalisation sous forme de segments et les transmet à Instana. Par défaut, seuls les appels dont le niveau de gravité est égal ou warn supérieur à sont enregistrés.

Pour configurer le niveau de gravité minimal, utilisez l'une des méthodes suivantes :

• Variable d'environnement : Définissez la variable d'environnement INSTANA_TRACING_CAPTURE_LOG_LEVEL :

  INSTANA_TRACING_CAPTURE_LOG_LEVEL=error

• Configuration dans le code : passez l'option suivante lors de l'initialisation du collecteur :

  require('@instana/collector')({
    tracing: {
      captureLogLevel: 'error'
    }
  });

Le tableau suivant présente les valeurs prises en charge :

Les valeurs ne sont pas sensibles à la casse. Si une valeur non prise en charge est configurée, le collecteur enregistre un avertissement et utilise la valeur par défaut (warn).

Pour configurer la sortie du journal de traçage interne, reportez-vous à la section « Configuration du niveau du journal de traçage ».

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 portées et les traces sont étroitement lié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: .... }}}.

Par défaut, Instana ne considère pas les réponses de type « HTTP » 4xx comme des erreurs lors des appels à HTTP. Vous pouvez activer ce comportement lorsque vous avez besoin d'une visibilité sur les réponses d'erreur client, par exemple pour inclure 401 Unauthorized ou 403 Forbidden les réponses provenant d'un service en aval.

Les options de configuration suivantes sont disponibles :

• classifyAll4xxAsErrors: Considère chaque réponse « 4xx » provenant d'un service en aval comme une erreur.
• classifyAsErrors: Ne considère comme des erreurs que certains codes d'état spécifiques provenant d'un service en aval.

Lorsque ces deux options sont activées, classifyAsErrors a la priorité, et seuls les codes répertoriés sont considérés comme des erreurs. Les codes d'état pour classifyAsErrors doivent se situer dans l'intervalle 400–499. Tout code ne se situant pas dans cette plage est ignoré.

Par défaut, le niveau de journalisation du collecteur est info. Pour modifier le niveau de journalisation, utilisez l'une des méthodes suivantes :

• Configurer le collecteur lors de l'initialisation :

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

• Définissez la variable d'environnement INSTANA_LOG_LEVEL sur debug, info, warn, ou error.

• Définissez la variable d'environnement INSTANA_DEBUG sur une valeur non vide pour activer la journalisation debug .

Si vous constatez l'apparition de messages de journalisation de débogage inattendus liés à Instana (entrées de journal contenant "name":"@instana/collector" et "level":20), vérifiez si le niveau de journalisation est défini sur debug ou si INSTANA_LOG_LEVEL=debug ou INSTANA_DEBUG est activé.

Si vous utilisez votre propre module de journalisation (voir la section suivante), il vous appartient de configurer son niveau de journalisation.

Voir la configuration de l'enregistreur.