Remarques pour les développeurs OpenTelemetry Node.js

L'instrumentation automatique est un mécanisme permettant de collecter des données de télémétrie sans modifier le code source de l'application. L'instrumentation automatique est une fonction fournie par OpenTelemetry qui vous permet d'instrumenter automatiquement votre application sans écrire de code personnalisé.

Utilisez des « détecteurs de ressources » adaptés pour améliorer la corrélation des entités d'infrastructure utilisée dans l' Instana. L'auto-instrumentation de l' OpenTelemetry JavaScript doit déclarer des détecteurs de ressources afin de disposer d'un nombre suffisant d'attributs de ressources. Vous devez disposer d'un service d' Instrumentation.js s externe doté de détecteurs de ressources capables de prendre en charge un nombre suffisant d'attributs de ressources. Par exemple, @opentelemetry/resource-detector-container la version 0.3.4 ou une version ultérieure est requise pour la liaison dans un environnement conteneurisé, tel qu'un cluster Kubernetes ou Red Hat OpenShift. L'exemple suivant est un Instrumentation.js élément utilisé dans la démo officielle d' OpenTelemetry :

// Copyright The OpenTelemetry Authors
// SPDX-License-Identifier: Apache-2.0

const opentelemetry = require('@opentelemetry/sdk-node');
const { getNodeAutoInstrumentations } = require('@opentelemetry/auto-instrumentations-node');
const { OTLPTraceExporter } = require('@opentelemetry/exporter-trace-otlp-grpc');
const { OTLPMetricExporter } = require('@opentelemetry/exporter-metrics-otlp-grpc');
const { PeriodicExportingMetricReader } = require('@opentelemetry/sdk-metrics');
const { alibabaCloudEcsDetector } = require('@opentelemetry/resource-detector-alibaba-cloud');
const { awsEc2Detector, awsEksDetector } = require('@opentelemetry/resource-detector-aws');
const { containerDetector } = require('@opentelemetry/resource-detector-container');
const { gcpDetector } = require('@opentelemetry/resource-detector-gcp');
const { envDetector, hostDetector, osDetector, processDetector } = require('@opentelemetry/resources');

const sdk = new opentelemetry.NodeSDK({
    traceExporter: new OTLPTraceExporter(),
    instrumentations: [getNodeAutoInstrumentations()],
    metricReader: new PeriodicExportingMetricReader({
        exporter: new OTLPMetricExporter(),
    }),
    resourceDetectors: [
        containerDetector,
        envDetector,
        hostDetector,
        osDetector,
        processDetector,
        alibabaCloudEcsDetector,
        awsEksDetector,
        awsEc2Detector,
        gcpDetector,
    ],
});

sdk.start();

L'instrumentation manuelle implique l'écriture d'un code personnalisé pour instrumenter des parties spécifiques de votre application. Cela nécessite de configurer manuellement le code source de l'application pour configurer OpenTelemetry SDK pour recevoir, traiter et exporter les données de télémétrie. Pour des instructions plus détaillées, consultez le manuel d'instrumentation.

L'agent « Instana » peut recevoir directement les traces, les métriques et les journaux d' OpenTelemetry au format « OTLP ». Ensuite, l'agent « Instana » transmet les données au backend « Instana ». Pour plus d'informations, consultez la section « Envoyer des données à l'agent d' Instana ».

Vous devez indiquer le point de terminaison de l'agent d' Instana dans la configuration d' OTLPMetricExporter. Définissez le point de terminaison ainsi que la clé « Instana » au format « JSON », puis transmettez-le en tant qu'argument à « OTLPMetricExporter », comme indiqué dans l'exemple suivant. Pour plus d'informations, consultez la section « Utilisation avec Node.js ».

metricReader: new PeriodicExportingMetricReader({
  exporter: new OTLPMetricExporter({
    url: '<agent-otlp-endpoint>/v1/metrics', // url is optional and can be omitted - default is https://otlp-orange-saas.instana.io:4318/v1/metrics
    headers: { // an optional object containing custom headers to be sent with each request
      'x-instana-key': '<Instana key>'
    }
  }),
}),

Les données de télémétrie peuvent être envoyées au format « OTLP » directement depuis des applications ou des systèmes vers le serveur central d' Instana, ce que l'on appelle également la «communication sans agent». Pour plus d'informations, consultez la section « Envoi de données vers le backend d' Instana ».

Vous devez indiquer le point de terminaison du backend Instana dans la configuration de OTLPMetricExporter. Définissez le point de terminaison ainsi que la clé Instana et les informations d'hôte Instana au format JSON, puis transmettez-les en tant qu'argument à OTLPMetricExporter, comme indiqué dans l'exemple suivant. Pour plus d'informations, consultez la section « Utilisation avec Node.js ».

metricReader: new PeriodicExportingMetricReader({
  exporter: new OTLPMetricExporter({
    url: '<backend-otlp-endpoint>/v1/metrics', // url is optional and can be omitted - default is https://otlp-orange-saas.instana.io:4318/v1/metrics
    headers: { // an optional object containing custom headers to be sent with each request
      'x-instana-key': '<Instana key>',
      'x-instana-host': '<hostname>'
    }
  }),
}),

Pour activer l'instrumentation automatique, exécutez la commande suivante pour pointer vers le fichier instrumentation.js lorsque vous exécutez l'application :

node --require ./instrumentation.js app.js

Pour plus d'informations sur le détecteur de ressources Node.JS, consultez opentelemetry-js-contrib.

1. Consultez les journaux de l'agent hôte d' Instana pour vérifier si des messages sont liés à ce processus OpenTelemetry.
2. Vérifiez si NodeJS a été correctement instrumenté, soit automatiquement, soit manuellement.
3. Vérifiez si les paramètres de configuration, tels que le point de terminaison et la clé d' Instana, sont correctement définis dans le code instrumenté.