OpenTelemetry surveillance des applications Instana et Node.js

Restrictions

Remarque : évitez d'utiliser à la fois le SDK OpenTelemetry et le traceur Instana Node.js dans la même application Node.js. L'utilisation des deux pourrait entraîner les problèmes suivants :

Appels manqués dans l' Instana
Données de télémétrie en double
Pannes d'instruments

Node.js Options de surveillance avec le SDK d' OpenTelemetry

Modifier en ligne

Lorsque vous utilisez le SDK « OpenTelemetry », vous pouvez choisir parmi les options de traçage suivantes :

Suivi basé sur des agents : les traces et les métriques sont envoyées aux points de terminaison de l'agent « Instana » à l'aide du SDK « OpenTelemetry »
Traçage sans serveur :
- Tracé sans serveur avec le SDK « OpenTelemetry » au format « OTLP » : les tracés et les métriques sont envoyés aux points de terminaison Instana et OTLP à l'aide du SDK « OpenTelemetry » ( méthode recommandée )
- Traçage sans serveur avec le SDK OpenTelemetry au format Instana : les traces et les métriques sont envoyées à Instana au format Instana à l'aide du SDK OpenTelemetry

Remarque : vous devez envoyer au moins une métrique pour établir la corrélation au niveau de l'infrastructure entre les hôtes, les processus et les services.

Suivi basé sur des agents avec le SDK « OpenTelemetry »

Modifier en ligne

Vous pouvez activer le traçage par agent pour les applications « Node.js » à l'aide du SDK « OpenTelemetry ».

Configuration requise

Modifier en ligne

Installation des paquets

Modifier en ligne

Pour installer les paquets, exécutez la commande suivante :

npm i @opentelemetry/exporter-metrics-otlp-http @opentelemetry/exporter-trace-otlp-http @opentelemetry/propagator-instana @opentelemetry/resource-detector-instana @opentelemetry/resources @opentelemetry/sdk-metrics --save

Activation des paquets

Modifier en ligne

Pour un exemple complet et fonctionnel, consultez l'exemple « HTTP » basé sur des agents.

...
          const { OTLPTraceExporter } = require('@opentelemetry/exporter-trace-otlp-http');
          const { OTLPMetricExporter } = require('@opentelemetry/exporter-metrics-otlp-http');
          const { PeriodicExportingMetricReader } = require('@opentelemetry/sdk-metrics');
          const { instanaAgentDetector } = require('@opentelemetry/resource-detector-instana');
          const { processDetector, envDetector } = require('@opentelemetry/resources');
          const { InstanaPropagator } = require('@opentelemetry/propagator-instana');

          const instanaAgentHost = 'http://127.0.0.1:4318';

          const instanaReader = new PeriodicExportingMetricReader({
            exportIntervalMillis: 1000 * 10,
            exporter: new OTLPMetricExporter({
              url: `${otlpEndpoint}/v1/metrics`
            })
          });

          const sdk = new opentelemetry.NodeSDK({
            resourceDetectors: [envDetector, processDetector, instanaAgentDetector],
            traceExporter: new OTLPTraceExporter({
              url: `${otlpEndpoint}/v1/traces`
            }),
            propagator: new InstanaPropagator(),
            metricReader: instanaReader,
            instrumentations: ...
          });

Tracé sans serveur avec le SDK « OpenTelemetry » au format « OTLP »

Modifier en ligne

Vous pouvez configurer le traçage sans serveur pour les applications Node.js à l'aide du SDK OpenTelemetry au format OTLP afin d'envoyer des traces et des métriques vers Instana.

Configuration requise

Modifier en ligne

Configurer l' OpenTelemetry SDK for Node.js
Choisissez un point de terminaison « sans serveur » (serverless) de type « acceptor » dans l' OTLP, puis définissez-le INSTANA_ENDPOINT_URL sur le point de terminaison URL.
Récupérez la clé de l'agent et définissez-la INSTANA_AGENT_KEY sur cette clé.

Installation des paquets

Modifier en ligne

Pour installer les paquets suivants, exécutez cette commande :

npm i @opentelemetry/exporter-metrics-otlp-grpc @opentelemetry/exporter-trace-otlp-grpc @opentelemetry/propagator-instana @opentelemetry/sdk-metrics --save

Activation des paquets

Modifier en ligne

Pour un exemple complet et fonctionnel, consultez l'exemple de format « Serverless OpenTelemetry OTLP ».

...
          const { OTLPTraceExporter } = require('@opentelemetry/exporter-trace-otlp-grpc');
          const { OTLPMetricExporter } = require('@opentelemetry/exporter-metrics-otlp-grpc');
          const { PeriodicExportingMetricReader } = require('@opentelemetry/sdk-metrics');
          const { InstanaPropagator } = require('@opentelemetry/propagator-instana');

          const otlpEndpoint = process.env.INSTANA_ENDPOINT_URL;
          const metadata = new grpc.Metadata();
          metadata.set('x-instana-key', process.env.INSTANA_AGENT_KEY);

          const instanaReader = new PeriodicExportingMetricReader({
            exportIntervalMillis: 1000 * 10,
            exporter: new OTLPMetricExporter({
              url: otlpEndpoint,
              metadata
            })
          });

          const sdk = new opentelemetry.NodeSDK({
            traceExporter: new OTLPTraceExporter({
              url: otlpEndpoint,
              metadata
            }),
            propagator: new InstanaPropagator(),
            metricReader: instanaReader,
            instrumentations: [...]
          });

          ...

Tracé sans serveur avec le SDK « OpenTelemetry » au format « Instana »

Modifier en ligne

Lorsque l'application surveillée par OpenTelemetry s'exécute, l'exportateur Instana convertit les spans OpenTelemetry en spans Instana et les envoie au point de terminaison backend.

Les traces « OpenTelemetry » apparaissent dans l'interface utilisateur d' Instana, au même titre que les segments de traçage « Instana » classiques.

Configuration requise

Modifier en ligne

Installez l' OpenTelemetry SDK for Node.js
Choisissez un point de terminaison accepteur OTLP et configurez-le. INSTANA_ENDPOINT_URL vers l' URL du point de terminaison.
Récupérez la clé de l'agent et définissez-la INSTANA_AGENT_KEY sur cette clé.

Installation

Modifier en ligne

Installez les paquets suivants en exécutant cette commande :

npm i @instana/opentelemetry-exporter@ @opentelemetry/propagator-instana --save

Activation en cours

Modifier en ligne

Pour un exemple complet et fonctionnel, consultez l'exemple de format « Serverless OpenTelemetry Instana ».

...
          const { InstanaExporter } = require('@instana/opentelemetry-exporter');
          const { InstanaPropagator } = require('@opentelemetry/propagator-instana');

          /*
           * If you have not provided the agent key and the serverless endpoint URL via environment variables:
           * const instanaTraceExporter = new InstanaExporter({ agentKey: 'agent_key', endpointUrl: 'endpoint_url' });
           */
          const instanaTraceExporter = new InstanaExporter();

          const sdk = new opentelemetry.NodeSDK({
            ...
            traceExporter: instanaTraceExporter,
            propagator: new InstanaPropagator(),
            instrumentations: [...]
          });

OpenTelemetry Présentation des plugins

Modifier en ligne

Utilisez les plugins « Instana » et « OpenTelemetry » pour Node.js afin de gérer la propagation des traces, l'échantillonnage et la détection des ressources, et ainsi améliorer la corrélation et le contexte de vos données de télémétrie.

OpenTelemetry propagateur

Modifier en ligne

Le package de propagation de contexte @opentelemetry/propagator-instana d’ OpenTelemetry convertit les en-têtes de corrélation de traces propriétaires d’ Instana en un contexte de trace d’ OpenTelemetry, et inversement.

Consultez la section « Propagateurs OpenTelemetry pour obtenir des informations générales sur les propagateurs de contexte OpenTelemetry.

Installation du propagateur « OpenTelemetry »

Modifier en ligne

Pour installer le propagateur « OpenTelemetry », exécutez la commande suivante :

npm install --save @opentelemetry/propagator-instana@

Activation du propagateur « OpenTelemetry »

Modifier en ligne

Pour activer le propagateur « OpenTelemetry », exécutez la commande suivante :

...
          const { InstanaPropagator } = require('@opentelemetry/propagator-instana');
          // ...

          new opentelemetry.NodeSDK({
            ...
            propagator: new InstanaPropagator(),
            ...
          });

Echantillonneur OpenTelemetry

Modifier en ligne

Le package d'échantillonnage « OpenTelemetry » @instana/opentelemetry-sampler remplace le comportement d'échantillonnage par défaut d' OpenTelemetry, de sorte que toute requête soit échantillonnée, sauf si la valeur du sampled drapeau dans le contexte de trace est false.

Installation du sampler « OpenTelemetry »

Modifier en ligne

Pour installer l'échantillonneur « OpenTelemetry », exécutez la commande suivante :

npm install --save @instana/opentelemetry-sampler@

Activation de l'échantillonneur « OpenTelemetry »

Modifier en ligne

L'échantillonneur doit être utilisé avec le paquet @opentelemetry/propagator-instana.

const { InstanaPropagator } = require('@opentelemetry/propagator-instana');
          const { InstanaAlwaysOnSampler } = require('@instana/opentelemetry-sampler');

          const sdk = new opentelemetry.NodeSDK({
            ...
            propagator: new InstanaPropagator(),
            sampler: new InstanaAlwaysOnSampler()
            ...
          });

          ...

OpenTelemetry détecteur de ressources

Modifier en ligne

Remarque : un détecteur de ressources « Instana » OpenTelemetry nécessite toujours qu’un agent « Instana » soit déployé et en cours d’exécution sur le même hôte.

Le package de détection des ressources d' OpenTelemetry, @opentelemetry/resource-detector-instana, enrichit les informations de traçage d' OpenTelemetry avec des attributs de ressources supplémentaires.

Installation du détecteur de ressources « OpenTelemetry »

Modifier en ligne

Pour installer le détecteur de ressources « OpenTelemetry », exécutez la commande suivante :

npm install --save @opentelemetry/resource-detector-instana

Activation du détecteur de ressources « OpenTelemetry »

Modifier en ligne

import {
            Resource,
            processDetector,
            envDetector,
          } from "@opentelemetry/resources";
          import { SemanticResourceAttributes } from "@opentelemetry/semantic-conventions";
          import { NodeSDK } from "@opentelemetry/sdk-node";
          import { instanaAgentDetector } from "@opentelemetry/resource-detector-instana";

          const globalResource = new Resource({
             [SemanticResourceAttributes.SERVICE_NAME]: "TestService",
          });

          const sdk = new NodeSDK({
             resourceDetectors: [envDetector, processDetector, instanaAgentDetector]
             resource: globalResource,
          });

          ...

De plus, vous pouvez définir les variables d'environnement suivantes :

INSTANA_RETRY_TIMEOUT_MS: Le détecteur de ressources effectue trois tentatives pour se connecter à l'agent Instana. Cette valeur correspond au délai d'attente entre les tentatives. (par défaut : 1000)
INSTANA_AGENT_TIMEOUT_MS: Délai d'expiration du client lors de la connexion à l'agent Instana. (par défaut : 3000)