Die vorliegende Übersetzung wurde maschinell erstellt. Im Falle eines Konflikts oder eines Widerspruchs zwischen dieser übersetzten Fassung und der englischen Fassung (einschließlich infolge von Verzögerungen bei der Übersetzung) ist die englische Fassung maßgeblich.
# Migrieren Sie zu Node.js OpenTelemetry
In diesem Abschnitt wird erklärt, wie Sie Ihre Node.js -Anwendungen vom X-Ray SDK auf migrieren OpenTelemetry. Er behandelt sowohl automatische als auch manuelle Instrumentierungsansätze und bietet konkrete Beispiele für gängige Anwendungsfälle.
Das X-Ray Node.js SDK hilft Ihnen, Ihre Node.js -Anwendungen manuell für die Ablaufverfolgung zu instrumentieren. Dieser Abschnitt enthält Codebeispiele für die Migration von X-Ray zu OpenTelemetry Instrumentation.
**Topics**
+ [Automatische Instrumentierungslösungen ohne Code](#zero-code-instrumentation)
+ [Lösungen für die manuelle Instrumentierung](#manual-instrumentation)
+ [Nachverfolgung eingehender Anfragen](#tracing-incoming-requests)
+ [AWS SDK V3-Instrumentierung JavaScript](#aws-sdk-instrumentation)
+ [Instrumentieren von ausgehenden HTTP-Aufrufen](#http-instrumentation)
+ [Instrumentierungsunterstützung für andere Bibliotheken](#other-libraries)
+ [Manuelles Erstellen von Trace-Daten](#manual-trace-creation)
+ [Lambda-Instrumentierung](#lambda-instrumentation)
## Automatische Instrumentierungslösungen ohne Code
Um Anfragen mit dem X-Ray SDK für Node.js nachzuverfolgen, müssen Sie Ihren Anwendungscode ändern. Mit OpenTelemetry können Sie Zero-Code-Lösungen zur automatischen Instrumentierung verwenden, um Anfragen zu verfolgen.
**Automatische Null-Code-Instrumentierung mit OpenTelemetry basierten automatischen Instrumentierungen.**
1. Verwenden der automatischen Instrumentierung von AWS Distro for OpenTelemetry (ADOT) für Node.js — Informationen zur automatischen Instrumentierung für die Anwendung Node.js finden Sie unter [Tracing and Metrics with the AWS](https://aws-otel.github.io/docs/getting-started/js-sdk/trace-metric-auto-instr) Distro for Auto-Instrumentation. OpenTelemetry JavaScript
(Optional) Sie können CloudWatch Application Signals auch bei der automatischen Instrumentierung Ihrer Anwendungen AWS mit der JavaScript automatischen ADOT-Instrumentierung aktivieren, um den aktuellen Anwendungsstatus zu überwachen und die langfristige Anwendungsleistung anhand Ihrer Geschäftsziele zu verfolgen. Application Signals bietet Ihnen einen einheitlichen, anwendungsorientierten Überblick über Ihre Anwendungen, Services und Abhängigkeiten und unterstützt Sie bei der Überwachung und Diagnose des Zustands Ihrer Anwendungen. Weitere Informationen finden Sie unter [Application Signals](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Application-Monitoring-Sections.html).
1. [Verwendung der automatischen OpenTelemetry JavaScript Null-Code-Instrumentierung — Informationen zur automatischen Instrumentierung mit der finden Sie unter Zero-Code-Instrumentierung. OpenTelemetry JavaScript JavaScript ](https://opentelemetry.io/docs/zero-code/js/)
## Lösungen für die manuelle Instrumentierung
------
#### [ Tracing setup with X-Ray SDK ]
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();
```
------
#### [ Tracing setup with OpenTelemetry SDK ]
**Anmerkung**
AWS X-Ray Remote Sampling kann derzeit nicht für OpenTelemetry JS konfiguriert werden. Unterstützung für X-Ray Remote Sampling ist derzeit jedoch über die ADOT Auto-Instrumentation for Node.js verfügbar.
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](https://nodejs.org/api/cli.html#-r---require-module) 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:
+ OTLPTraceExporter — Erforderlich für den Export von Traces zum CloudWatch OpenTelemetry Agent/Collector
+ AWSXRayPropagator — Erforderlich für die Weitergabe des Trace-Kontextes an AWS Dienste, die in X-Ray integriert sind
+ Ressourcendetektoren (z. B. Amazon EC2 Resource Detector) — Um Metadaten des Hosts zu erkennen, auf dem Ihre Anwendung ausgeführt wird
```
/*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
});
```
------
#### [ Tracing setup with ADOT auto-instrumentation for Node.js ]
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](https://aws-otel.github.io/docs/getting-started/js-sdk/trace-metric-auto-instr) for Auto-Instrumentation. OpenTelemetry JavaScript
Die automatische ADOT-Instrumentierung für Node.js unterstützt:
+ Röntgenfernprobenentnahme durch Umgebungsvariable — `export OTEL_TRACES_SAMPLER=xray`
+ Übertragung des X-Ray-Trace-Kontextes (standardmäßig aktiviert)
+ Ressourcenerkennung (Ressourcenerkennung für Amazon EC2-, Amazon ECS- und Amazon EKS-Umgebungen ist standardmäßig aktiviert)
+ Automatische Bibliotheksinstrumentierung für alle unterstützten OpenTelemetry Instrumentierungen, die disabled/enabled selektiv durch Umgebungsvariablen und Umgebungsvariablen gesteuert werden können `OTEL_NODE_ENABLED_INSTRUMENTATIONS` `OTEL_NODE_DISABLED_INSTRUMENTATIONS`
+ Manuelles Erstellen von Spans
------
## Nachverfolgung eingehender Anfragen
------
#### [ With X-Ray SDK ]
**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()` 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'));
```
------
#### [ With OpenTelemetry SDK ]
**Express.js**
Die Ablaufverfolgungsunterstützung für eingehende Anfragen für `Express.js` wird durch die [OpenTelemetry HTTP-Instrumentierung und die [OpenTelemetry Express-Instrumentierung](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-express)](https://github.com/open-telemetry/opentelemetry-js/tree/main/experimental/packages/opentelemetry-instrumentation-http) bereitgestellt. Installieren Sie die folgenden Abhängigkeiten mit`npm`:
```
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 ](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-restify) 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(),
],
});
```
------
## AWS SDK V3-Instrumentierung JavaScript
------
#### [ With X-Ray SDK ]
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!',
}));
```
------
#### [ With OpenTelemetry SDK ]
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()
],
});
```
------
## Instrumentieren von ausgehenden HTTP-Aufrufen
------
#### [ With X-Ray SDK ]
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');
```
------
#### [ With OpenTelemetry SDK ]
Die Ablaufverfolgungsunterstützung für die HTTP-Clients von Node.js wird von der OpenTelemetry HTTP Instrumentation bereitgestellt. Installieren Sie die folgende Abhängigkeit mit`npm`:
```
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(),
],
});
```
------
## Instrumentierungsunterstützung für andere Bibliotheken
Die vollständige Liste der unterstützten Bibliotheksinstrumentationen finden Sie OpenTelemetry JavaScript unter [Unterstützte Instrumentationen](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/metapackages/auto-instrumentations-node#supported-instrumentations).
[Alternativ können Sie in der OpenTelemetry Registry unter Registrierung herausfinden, ob Instrumentierung für Ihre Bibliothek OpenTelemetry unterstützt wird.](https://opentelemetry.io/ecosystem/registry/)
## Manuelles Erstellen von Trace-Daten
------
#### [ With X-Ray SDK ]
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();
```
------
#### [ With OpenTelemetry SDK ]
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](https://docs.aws.amazon.com/xray/latest/devguide/xray-concepts.html#xray-concepts-segments).
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.](https://aws-otel.github.io/docs/getting-started/x-ray#enable-the-customized-x-ray-annotations)
```
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();
});
```
------
## Lambda-Instrumentierung
------
#### [ With X-Ray SDK ]
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.
------
#### [ With OpenTelemetry SDK ]
Sie können Ihr Lambda automatisch mit verkauften AWS Lambda-Layern instrumentieren. Es gibt zwei Lösungen:
+ (Empfohlen) AWS Lambda Layer für OpenTelemetry
**Anmerkung**
Auf dieser Lambda-Schicht sind CloudWatch Application Signals standardmäßig aktiviert, wodurch die Leistungs- und Zustandsüberwachung für Ihre Lambda-Anwendung ermöglicht wird, indem sowohl Metriken als auch Traces erfasst werden. Wenn Sie nur die Ablaufverfolgung wünschen, sollten Sie die Umgebungsvariable Lambda festlegen. `OTEL_AWS_APPLICATION_SIGNALS_ENABLED=false` Weitere Informationen finden Sie unter [Aktivieren Ihrer Anwendungen auf Lambda](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Application-Signals-Enable-LambdaMain.html).
+ AWS verwaltete Lambda-Schicht für ADOT JS. Weitere Informationen finden Sie unter [AWS Distro for OpenTelemetry Lambda Support For](https://aws-otel.github.io/docs/getting-started/lambda/lambda-js). JavaScript
**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
```
------