OpenTelemetry pour les applications Node.js

Modifier en ligne

La principale méthode d'intégration avec OpenTelemetry consiste à configurer l'exportateur OTLP par défaut de toute application surveillée par OpenTelemetry afin qu'il envoie ses données à l'agent Instana. Cela est décrit sur la page « OpenTelemetry ».

L'intégration d' OpenTelemetry s peut être personnalisée davantage à l'aide de composants supplémentaires. Les composants d' OpenTelemetry s disponibles pour Node.js sont décrits comme suit :

Exportateur d' OpenTelemetry s sans serveur

Modifier en ligne

Le paquet @instana/opentelemetry-exporter propose un exportateur OpenTelemetry qui convertit et envoie les spans d' OpenTelemetry s vers le backend Instana.

L'exportateur Instana Node.js OpenTelemetry est principalement conçu pour être utilisé dans des environnements sans serveur, tels qu'AWS Lambda ou AWS Fargate. Instana prend déjà en charge OpenTelemetry pour SaaS ainsi que les solutions auto-hébergées via l'agent hôte. Toutefois, si vos applications « Node.js » s'exécutent dans un environnement sans serveur, où l'agent n'est pas présent, l'exportateur « serverless OpenTelemetry » est la solution à privilégier.

Installation de l'exportateur d' OpenTelemetry

Modifier en ligne

Pour installer l'outil d'exportation d' OpenTelemetry, exécutez la commande suivante :

npm install --save @instana/opentelemetry-exporter@latest

Activation de l'exportateur d' OpenTelemetry

Modifier en ligne

L'exportateur attend deux variables d'environnement de type « Instana » qui doivent être fournies à l'application :

  • INSTANA_AGENT_KEY
  • INSTANA_ENDPOINT_URL

Vous pouvez également fournir ces valeurs en tant qu'arguments au constructeur, mais cette alternative n'est pas recommandée car il s'agit de données sensibles que vous pouvez souhaiter éviter d'exposer.

Par exemple, vous pouvez configurer l'exportateur dans le module de traçage comme suit :

'use strict';

const process = require('process');
require('@opentelemetry/api');
const opentelemetry = require('@opentelemetry/sdk-node');
const { getNodeAutoInstrumentations } = require('@opentelemetry/auto-instrumentations-node');
const { Resource } = require('@opentelemetry/resources');
const { SemanticResourceAttributes } = require('@opentelemetry/semantic-conventions');

// Require the Instana OpenTelemetry Exporter
const { InstanaExporter } = require('@instana/opentelemetry-exporter');

// Instantiate the Instana Exporter.
// Make sure to provide the agent key and the serverless endpoint URL via the following environment variables:
// * INSTANA_AGENT_KEY
// * INSTANA_ENDPOINT_URL
const instanaTraceExporter = new InstanaExporter();

/*
 * 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 nodeAutoInstrumentations = getNodeAutoInstrumentations();

const sdk = new opentelemetry.NodeSDK({
  resource: new Resource({
    [SemanticResourceAttributes.SERVICE_NAME]: 'my-service'
  }),
  // Configure OpenTelemetry to use the Instana Exporter
  traceExporter: instanaTraceExporter,
  instrumentations: [nodeAutoInstrumentations]
});

sdk.start()
...

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

La visualisation des traces d' OpenTelemetry s sera disponible dans l'interface utilisateur d' Instana, au même titre que les segments de traçage classiques d' Instana.

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 page « Propagateurs » sur OpenTelemetry pour obtenir des informations générales sur les propagateurs de contexte d' OpenTelemetry.

Installation du propagateur « OpenTelemetry »

Modifier en ligne

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

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

Activation du propagateur « OpenTelemetry »

Modifier en ligne
const { NodeTracerProvider } = require('@opentelemetry/sdk-trace-node');
const { InstanaPropagator } = require('@opentelemetry/propagator-instana');
// ...

const provider = new NodeTracerProvider();

provider.register({
  propagator: new InstanaPropagator()
});

OpenTelemetry Échantillon

Modifier en ligne

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

Consultez la page « Échantillons d' OpenTelemetry » pour obtenir des informations générales sur les échantillons d' OpenTelemetry.

Installation du sampler d' OpenTelemetry

Modifier en ligne

Pour installer le Sampler d' OpenTelemetry, exécutez la commande suivante :

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

Activation de l'échantillonneur « OpenTelemetry »

Modifier en ligne

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

const api = require('@opentelemetry/api');
const opentelemetry = require('@opentelemetry/sdk-node');
const { getNodeAutoInstrumentations } = require('@opentelemetry/auto-instrumentations-node');
const { SemanticResourceAttributes } = require('@opentelemetry/semantic-conventions');
const { Resource } = require('@opentelemetry/resources');
const { InstanaAlwaysOnSampler } = require('@instana/opentelemetry-sampler');
const { OTLPTraceExporter } = require('@opentelemetry/exporter-trace-otlp-http');
const { InstanaPropagator } = require('@opentelemetry/propagator-instana');

const nodeAutoInstrumentations = getNodeAutoInstrumentations();
api.propagation.setGlobalPropagator(new InstanaPropagator());

const traceOtlpExporter = new OTLPTraceExporter({
  url: process.env.OTEL_EXPORTER_OTLP_ENDPOINT
});

const sdk = new opentelemetry.NodeSDK({
  traceExporter: traceOtlpExporter,
  instrumentations: [nodeAutoInstrumentations],
  resource: new Resource({
    [SemanticResourceAttributes.SERVICE_NAME]: 'my-service'
  }),
  sampler: new InstanaAlwaysOnSampler()
});

sdk
  .start()
  .then(() => console.log('Tracing initialized'))
  .catch(err => console.log('Error initializing tracing', err));

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.

Pour obtenir des informations générales sur les détecteurs de ressources « OpenTelemetry », consultez la page « OpenTelemetry Resource Detectors ».

Installation du détecteur de ressources d' OpenTelemetry

Modifier en ligne

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

npm install --save @instana/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,
});

sdk.start()
...

En outre, les variables d'environnement suivantes peuvent être fournies:

  • INSTANA_AGENT_HOST: Nom d'hôte de l'agent de l' Instana (par défaut : localhost)
  • INSTANA_AGENT_PORT: Port de l'agent de l' Instana (par défaut : 42699)
  • INSTANA_RETRY_TIMEOUT_MS: Le détecteur de ressources effectue trois tentatives pour se connecter à l'agent Instana. Il s'agit du délai d'attente entre les nouvelles tentatives (par défaut: 1000)
  • INSTANA_AGENT_TIMEOUT_MS: Délai d'attente du client lors de la connexion à l'agent Instana (par défaut : 3000)