Migrieren Sie zu Node.js OpenTelemetry

Wenn das X-Ray-SDK für Node.js verwendet wurde, musste das aws-xray-sdk Paket das X-Ray-SDK mit Service-Plug-ins oder lokalen Sampling-Regeln konfigurieren, bevor das SDK zur Instrumentierung Ihres Codes verwendet werden konnte.

var AWSXRay = require('aws-xray-sdk');

AWSXRay.config([AWSXRay.plugins.EC2Plugin,AWSXRay.plugins.ElasticBeanstalkPlugin]);
AWSXRay.middleware.setSamplingRules(<path to file>);
        

Für das folgende Codebeispiel benötigen Sie die folgenden Abhängigkeiten:

npm install --save \
  @opentelemetry/api \
  @opentelemetry/sdk-node \
  @opentelemetry/exporter-trace-otlp-proto \
  @opentelemetry/propagator-aws-xray \
  @opentelemetry/resource-detector-aws
        

Sie müssen das OpenTelemetry SDK einrichten und konfigurieren, bevor Sie Ihren Anwendungscode ausführen können. Dies kann mit dem Flag —-require geschehen. Erstellen Sie eine Datei mit dem Namen instrumentation.js, die Ihre OpenTelemetry Instrumentierungskonfiguration und Ihr Setup enthält.

Es wird empfohlen, die folgenden Komponenten zu konfigurieren:

/*instrumentation.js*/
// Require dependencies
const { NodeSDK } = require('@opentelemetry/sdk-node');
const { OTLPTraceExporter } = require('@opentelemetry/exporter-trace-otlp-proto');
const { AWSXRayPropagator } = require("@opentelemetry/propagator-aws-xray");
const { detectResources } = require('@opentelemetry/resources');
const { awsEc2Detector } = require('@opentelemetry/resource-detector-aws');

const resource = detectResources({
    detectors: [awsEc2Detector],
});
 
const _traceExporter = new OTLPTraceExporter({
    url: 'http://localhost:4318/v1/traces'
});

const sdk = new NodeSDK({
    resource: resource,
    textMapPropagator: new AWSXRayPropagator(),
    traceExporter: _traceExporter
});

sdk.start();
        

Anschließend können Sie Ihre Anwendung mit Ihrem OpenTelemetry Setup wie folgt ausführen:

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

Sie können die Instrumentierung der OpenTelemetry SDK-Bibliothek verwenden, um automatisch Spans für Bibliotheken wie das AWS SDK zu erstellen. Wenn Sie diese aktivieren, werden automatisch Spans für Module wie das AWS SDK für Version 3 erstellt. JavaScript OpenTelemetry bietet die Möglichkeit, alle Bibliotheksinstrumentierungen zu aktivieren oder anzugeben, welche Bibliotheksinstrumentierungen aktiviert werden sollen.

Um alle Instrumentierungen zu aktivieren, installieren Sie das Paket: @opentelemetry/auto-instrumentations-node

npm install @opentelemetry/auto-instrumentations-node
        

Aktualisieren Sie als Nächstes die Konfiguration, um alle Bibliotheksinstrumentierungen zu aktivieren, wie unten gezeigt.

const { getNodeAutoInstrumentations } = require('@opentelemetry/auto-instrumentations-node');

...

const sdk = new NodeSDK({
    resource: resource,
     instrumentations: [getNodeAutoInstrumentations()],
     textMapPropagator: new AWSXRayPropagator(),
    traceExporter: _traceExporter
});

Sie können die automatische ADOT-Instrumentierung für Node.js verwenden, um Ihre Node.js -Anwendungen automatisch zu konfigurieren OpenTelemetry . Durch die Verwendung von ADOT Auto-Instrumentation müssen Sie keine manuellen Codeänderungen vornehmen, um eingehende Anfragen oder Bibliotheken wie AWS SDK- oder HTTP-Clients nachzuverfolgen. Weitere Informationen finden Sie unter Tracing und Metriken mit der AWS Distro for Auto-Instrumentation. OpenTelemetry JavaScript

Die automatische ADOT-Instrumentierung für Node.js unterstützt:

Express.js

Mit dem X-Ray-SDK zur Verfolgung eingehender HTTP-Anfragen, die von den Anwendungen Express.js empfangen AWSXRay.express.closeSegment() wurden, mussten die beiden Middlewares AWSXRay.express.openSegment(<name>) und die beiden Middlewares alle Ihre definierten Routen umschließen, um sie zu verfolgen.

app.use(xrayExpress.openSegment('defaultName'));

...

app.use(xrayExpress.closeSegment());
          

Erneut stifizieren

Um eingehende HTTP-Anfragen zu verfolgen, die von Restify Anwendungen empfangen wurden, wurde die Middleware aus dem X-Ray SDK verwendet, indem enable über das aws-xray-sdk-restify Modul auf dem Restify-Server ausgeführt wurde:

var AWSXRay = require('aws-xray-sdk');
var AWSXRayRestify = require('aws-xray-sdk-restify');

var restify = require('restify');
var server = restify.createServer();
AWSXRayRestify.enable(server, 'MyApp'));
          

Express.js

Die Ablaufverfolgungsunterstützung für eingehende Anfragen für Express.js wird durch die OpenTelemetry HTTP-Instrumentierung und die OpenTelemetry Express-Instrumentierung bereitgestellt. Installieren Sie die folgenden Abhängigkeiten mitnpm:

npm install --save @opentelemetry/instrumentation-http @opentelemetry/instrumentation-express
          

Aktualisieren Sie die OpenTelemetry SDK-Konfiguration, um die Instrumentierung für das Express-Modul zu aktivieren:

const { HttpInstrumentation } = require('@opentelemetry/instrumentation-http');
const { ExpressInstrumentation } = require('@opentelemetry/instrumentation-express');
...

const sdk = new NodeSDK({
  ...
  
  instrumentations: [
    ...
    // Express instrumentation requires HTTP instrumentation
    new HttpInstrumentation(),
    new ExpressInstrumentation(),
  ],
});
          

Erneut stifizieren

Für Restify-Anwendungen benötigen Sie die Restify-Instrumentierung. OpenTelemetry Installieren Sie die folgende Abhängigkeit:

npm install --save @opentelemetry/instrumentation-restify
          

Aktualisieren Sie die OpenTelemetry SDK-Konfiguration, um die Instrumentierung für das Restify-Modul zu aktivieren:

const { RestifyInstrumentation } = require('@opentelemetry/instrumentation-restify');
...

const sdk = new NodeSDK({
  ...
  
  instrumentations: [
    ...
    new RestifyInstrumentation(),
  ],
});
          

Um ausgehende AWS Anfragen vom AWS SDK zu instrumentieren, haben Sie Clients wie im folgenden Beispiel instrumentiert:

import { S3, PutObjectCommand } from '@aws-sdk/client-s3';

const s3 = AWSXRay.captureAWSv3Client(new S3({}));

await s3.send(new PutObjectCommand({
  Bucket: bucketName,
  Key: keyName,
  Body: 'Hello!',
}));
      

Die Unterstützung der Ablaufverfolgung für AWS Downstream-SDK-Aufrufe an DynamoDB, Amazon S3 und andere wird durch die OpenTelemetry AWS SDK-Instrumentierung bereitgestellt. Installieren Sie die folgende Abhängigkeit mit: npm

npm install --save @opentelemetry/instrumentation-aws-sdk
      

Aktualisieren Sie die OpenTelemetry SDK-Konfiguration mit der AWS SDK-Instrumentierung.

import { AwsInstrumentation } from '@opentelemetry/instrumentation-aws-sdk';
...

const sdk = new NodeSDK({
  ...

  instrumentations: [
    ...
    new AwsInstrumentation()
  ],
});
      

Um ausgehende HTTP-Anfragen mit X-Ray zu instrumentieren, war es erforderlich, Clients zu instrumentieren. Siehe zum Beispiel unten.

Einzelne HTTP-Clients

var AWSXRay = require('aws-xray-sdk');
var http = AWSXRay.captureHTTPs(require('http'));
      

Alle HTTP-Clients (global)

var AWSXRay = require('aws-xray-sdk');
AWSXRay.captureHTTPsGlobal(require('http'));
var http = require('http');

Die Ablaufverfolgungsunterstützung für die HTTP-Clients von Node.js wird von der OpenTelemetry HTTP Instrumentation bereitgestellt. Installieren Sie die folgende Abhängigkeit mitnpm:

npm install --save @opentelemetry/instrumentation-http
      

Aktualisieren Sie die OpenTelemetry SDK-Konfiguration wie folgt:

const { HttpInstrumentation } = require('@opentelemetry/instrumentation-http');
...

const sdk = new NodeSDK({
  ...
  
  instrumentations: [
    ...
    new HttpInstrumentation(),
  ],
});
      

Bei Verwendung von X-Ray war der aws-xray-sdk Paketcode erforderlich, um Segmente und ihre untergeordneten Untersegmente manuell zu erstellen, um Ihre Anwendung zu verfolgen.

var AWSXRay = require('aws-xray-sdk');

AWSXRay.enableManualMode();

var segment = new AWSXRay.Segment('myApplication');

captureFunc('1', function(subsegment1) {
  captureFunc('2', function(subsegment2) {

  }, subsegment1);
}, segment);

segment.close();
segment.flush();
      

Sie können benutzerdefinierte Zeitspannen erstellen und verwenden, um die Leistung interner Aktivitäten zu überwachen, die nicht von Instrumentierungsbibliotheken erfasst werden. Beachten Sie, dass nur Bereiche der Art Server in X-Ray-Segmente umgewandelt werden, alle anderen Bereiche werden in X-Ray-Untersegmente umgewandelt. Weitere Informationen hierzu finden Sie unter Segmente.

Nachdem Sie das OpenTelemetry SDK im Tracing-Setup konfiguriert haben, benötigen Sie eine Tracer-Instanz, um Spans zu erstellen. Sie können so viele Tracer-Instanzen wie nötig erstellen, es ist jedoch üblich, einen Tracer für eine gesamte Anwendung zu verwenden.

const { trace, SpanKind } = require('@opentelemetry/api');

// Get a tracer instance
const tracer = trace.getTracer('your-tracer-name');

...

  // This span will appear as a segment in X-Ray
  tracer.startActiveSpan('server', { kind: SpanKind.SERVER }, span => {
    // Do work here

    // This span will appear as a subsegment in X-Ray
    tracer.startActiveSpan('operation2', { kind: SpanKind.INTERNAL }, innerSpan => {
      // Do more work here

      innerSpan.end();
    });
    span.end();
  });
      

Hinzufügen von Anmerkungen und Metadaten zu Traces mit dem SDK OpenTelemetry

Sie können Ihren Spans auch benutzerdefinierte Schlüssel-Wert-Paare als Attribute hinzufügen. Beachten Sie, dass alle diese Span-Attribute standardmäßig in Metadaten in X-Rohdaten umgewandelt werden. Um sicherzustellen, dass ein Attribut in eine Anmerkung und nicht in Metadaten umgewandelt wird, fügen Sie den Schlüssel des Attributs zur Liste des aws.xray.annotations Attributs hinzu. Weitere Informationen finden Sie unter Aktivieren der benutzerdefinierten X-Ray-Anmerkungen.

  tracer.startActiveSpan('server', { kind: SpanKind.SERVER }, span => {
    span.setAttribute('metadataKey', 'metadataValue');
    span.setAttribute('annotationKey', 'annotationValue');

    // The following ensures that "annotationKey: annotationValue" is an annotation in X-Ray raw data.
    span.setAttribute('aws.xray.annotations', ['annotationKey']);

    // Do work here

    span.end();
  });
      

Nachdem Sie Active Tracing für Ihre Lambda-Funktion aktiviert hatten, war das X-Ray SDK ohne zusätzliche Konfiguration erforderlich. Lambda erstellt ein Segment, das den Lambda-Handler-Aufruf darstellt, und Sie haben Untersegmente oder Instrumentenbibliotheken mit dem X-Ray SDK ohne zusätzliche Konfiguration erstellt.

Sie können Ihr Lambda automatisch mit verkauften AWS Lambda-Layern instrumentieren. Es gibt zwei Lösungen:

Manuelles Erstellen von Spans mit Lambda-Instrumentierung

Der ADOT JavaScript Lambda Layer bietet zwar automatische Instrumentierung für Ihre Lambda-Funktion, Sie müssen jedoch möglicherweise eine manuelle Instrumentierung in Ihrem Lambda durchführen, um beispielsweise benutzerdefinierte Daten bereitzustellen oder Code innerhalb der Lambda-Funktion selbst zu instrumentieren, der nicht durch Bibliotheksinstrumentierungen abgedeckt wird.

Um neben der automatischen Instrumentierung auch eine manuelle Instrumentierung durchzuführen, müssen Sie eine Abhängigkeit hinzufügen. @opentelemetry/api Es wird empfohlen, dass es sich bei der Version dieser Abhängigkeit um dieselbe Version derselben Abhängigkeit handelt, die vom ADOT JavaScript SDK verwendet wird. Sie können die OpenTelemetry API verwenden, um manuell Spans in Ihrer Lambda-Funktion zu erstellen.

Um die @opentelemetry/api Abhängigkeit mit NPM hinzuzufügen:

npm install @opentelemetry/api