Telemetriesignale in Node.js-Clientbibliotheken aktivieren

Cloud de Confiance by S3NS bietet leistungsstarke Monitoring-, Logging- und Diagnosefunktionen für Node.js-Anwendungen.

Die Node.js-Clientbibliotheken sind so instrumentiert, dass sie Tracing-Daten ausgeben. Die Instrumentierung ist optional. Sie müssen sie explizit aktivieren. In diesem Dokument werden die verfügbaren Signale und die Aktivierung beschrieben.

Verfügbare Signale

Die Node.js-Clientbibliotheken sind so instrumentiert, dass sie die folgenden Signale generieren:

  1. INFO-Spans für jede logische Clientanfrage. In der Regel wird ein solcher Span durch einen einzelnen Methodenaufruf in der Clientstruktur ausgelöst, z. B. durch den Aufruf von accessSecretVersion für einen SecretManagerServiceClient.
  2. INFO-Spans für jeden RPC-Versuch auf niedriger Ebene. In der Regel wird ein solcher Span durch eine einzelne Methode in der Clientstruktur ausgelöst. Es können aber auch mehrere Spans entstehen, wenn die Bibliothek den RPC-Aufruf wiederholen muss.

Diese Spans und Logs folgen den semantischen OpenTelemetry- Konventionen und enthalten zusätzliche Cloud de Confiance by S3NS Attribute. Sowohl die Spans als auch die Logs eignen sich für das Produktionsmonitoring. Die Signale enthalten standardmäßige OpenTelemetry-Attribute wie http.response.status_code und rpc.system.name.

Eine vollständige Liste der Standardattribute finden Sie in den semantischen OpenTelemetry-Konventionen für HTTP und gRPC.

Telemetriesignale aktivieren

Zum Schutz sensibler Daten sind Telemetriesignale standardmäßig deaktiviert.

In Node.js müssen Sie den Client so konfigurieren, dass er Traces ausgibt. Außerdem müssen Sie Abonnenten und Exporter konfigurieren, um diese Signale an einen externen Dienst zu senden.

Zum Konfigurieren des Clients können Sie die folgende Umgebungsvariable festlegen:

export GOOGLE_SDK_NODE_ENABLE_TRACING=true

Wenn das Tracing aktiviert ist und Ihre Anwendung einen aktiven OpenTelemetry-Span im aktuellen Kontext hat, wenn Sie eine Clientbibliotheksmethode aufrufen, verknüpft die Clientbibliothek ihre Spans automatisch als untergeordnete Spans Ihres aktiven Spans.

Traces exportieren

Nachdem die Telemetrie in den Clientbibliotheken aktiviert wurde, muss Ihre Anwendung so konfiguriert werden, dass diese Daten erfasst und an Ihren Observability-Dienst exportiert werden.

Eine detaillierte Anleitung zum Konfigurieren der OpenTelemetry-Trace-Korrelation daten finden Sie im Observability-Beispiel im Node.js-Repository.

Wenn Sie die von den Cloud de Confiance by S3NS Clientbibliotheken generierten tracing Spans nach OpenTelemetry exportieren möchten, müssen Sie einen Tracer-Provider und einen Exporter einrichten:

const cloudTraceExporter = new TraceExporter();
const spanProcessor = new BatchSpanProcessor(cloudTraceExporter);

const provider = new NodeTracerProvider({
  spanProcessors: [spanProcessor],
});
provider.register();