Anleitung: Konfigurieren Sie OpenTelemetry für Ihre Anwendungen mit NGINX

Wenn Sie nach einem Tool suchen, mit dem Sie Webanwendungen und -infrastruktur effektiver verfolgen können, ist OpenTelemetry möglicherweise genau das Richtige für Sie. Indem Sie Ihren NGINX-Server mit dem vorhandenen OpenTelemetry NGINX-Community-Modul instrumentieren, können Sie Metriken, Traces und Protokolle erfassen und einen besseren Einblick in den Zustand Ihres Servers erhalten. Auf diese Weise können Sie wiederum Probleme beheben und die Leistung Ihrer Webanwendungen optimieren. Dieses vorhandene Community-Modul kann jedoch aufgrund des für die Ablaufverfolgung erforderlichen Leistungsmehraufwands auch die Antwortzeiten Ihres Servers verlangsamen. Dieser Vorgang kann auch zusätzliche Ressourcen verbrauchen und so die CPU- und Speicherauslastung erhöhen. Darüber hinaus kann das Einrichten und Konfigurieren des Moduls mühsam sein.

NGINX hat vor Kurzem ein natives OpenTelemetry-Modul namens ngx_otel_module entwickelt, das die Verfolgung der Anforderungsverarbeitungsleistung revolutioniert. Das Modul nutzt Telemetrieaufrufe, um Anwendungsanforderungen und -antworten zu überwachen und ermöglicht so erweiterte Tracking-Funktionen. Das Modul kann bequem innerhalb der NGINX-Konfigurationsdateien eingerichtet und konfiguriert werden, was es äußerst benutzerfreundlich macht. Dieses neue Modul erfüllt die Anforderungen sowohl von NGINX OSS- als auch von NGINX Plus-Benutzern. Es unterstützt die W3C-Kontextausbreitung und das OTLP/gRPC-Exportprotokoll und stellt somit eine umfassende Lösung zur Leistungsoptimierung dar.

Das NGINX-native OpenTelemetry-Modul ist ein dynamisches Modul, das keine zusätzliche Verpackung mit NGINX Plus erfordert. Es bietet eine Reihe von Funktionen, darunter die API und Key-Value-Store-Module. Zusammen bieten diese Funktionen eine Komplettlösung zur Überwachung und Optimierung der Leistung Ihrer NGINX Plus-Instanz. Durch die Verwendung von ngx_otel_module erhalten Sie wertvolle Einblicke in die Leistung Ihrer Webanwendung und können Schritte zu deren Verbesserung unternehmen. Wir empfehlen Ihnen dringend, ngx_otel_module zu erkunden, um herauszufinden, wie es Ihnen helfen kann, bessere Ergebnisse zu erzielen.

Notiz: Detaillierte Anweisungen zur Installation von nginx_otel_module und zum Einstieg finden Sie auf unserer GitHub-Seite .

Tutorialübersicht

In diesem Blog finden Sie eine Schritt-für-Schritt-Anleitung zum Konfigurieren von OpenTelemetry in NGINX Plus und zur Verwendung des Jaeger-Tools zum Sammeln und Visualisieren von Traces. OpenTelemetry ist ein leistungsstarkes Tool, das eine umfassende Ansicht des Pfads einer Anfrage bietet, einschließlich wertvoller Informationen wie Latenz, Anfragedetails und Antwortdaten. Dies kann bei der Leistungsoptimierung und der Erkennung potenzieller Probleme äußerst nützlich sein. Zur Vereinfachung haben wir das OpenTelemetry-Modul, die Anwendung und Jaeger in einer einzigen Instanz eingerichtet, wie Sie im folgenden Diagramm sehen können.

Befolgen Sie die Schritte in diesen Abschnitten, um das Tutorial abzuschließen:

• Voraussetzungen
• Stellen Sie NGINX Plus bereit und installieren Sie das OpenTelemetry-Modul
• Bereitstellen von Jaeger und der Echo- Anwendung
• Konfigurieren Sie OpenTelemetry in NGINX für die Ablaufverfolgung
• Testen der Konfiguration

Voraussetzungen

• Eine Linux/Unix-Umgebung oder eine beliebige kompatible Umgebung
• Ein NGINX Plus-Abonnement
• Grundlegende Kenntnisse der Linux-Befehlszeile und von JavaScript
• Docker
• Node.js 19.x oder höher
• Locken

Stellen Sie NGINX Plus bereit und installieren Sie das OpenTelemetry-Modul

Die Auswahl einer geeigneten Umgebung ist für die erfolgreiche Bereitstellung einer NGINX-Instanz von entscheidender Bedeutung. Dieses Tutorial führt Sie durch die Bereitstellung von NGINX Plus und die Installation der dynamischen NGINX-Module.

1. Installieren Sie NGINX Plus auf einem unterstützten Betriebssystem .
2. Installieren Sie ngx_otel_module . Fügen Sie das dynamische Modul zum NGINX-Konfigurationsverzeichnis hinzu, um OpenTelemetry zu aktivieren:

Lademodulmodule/ngx_otel_module.so;

3. Laden Sie NGINX neu, um das Modul zu aktivieren:

nginx -t und nginx -s neu laden

Bereitstellen von Jaeger und der Echo- Anwendung

Zum Anzeigen von Ablaufverfolgungen stehen verschiedene Optionen zur Verfügung. In diesem Tutorial wird Jaeger zum Sammeln und Analysieren von OpenTelemetry-Daten verwendet. Jaeger bietet eine effiziente und benutzerfreundliche Schnittstelle zum Sammeln und Visualisieren von Tracing-Daten. Nach der Datenerfassung stellen Sie mendhak/http-https-echo bereit, eine einfache Docker-Anwendung. Diese Anwendung gibt die Anforderungsattribute für JavaScript im JSON-Format zurück.

1. Verwenden Sie Docker-Compose, um Jaeger und die HTTP-Echo- Anwendung bereitzustellen. Sie können eine Docker-Compose- Datei erstellen, indem Sie die folgende Konfiguration kopieren und in einem Verzeichnis Ihrer Wahl speichern.

    

   Version: '3'
   
   Dienste:
   jaeger:
   Bild: jaegertracing/all-in-one:1.41
   Containername: jaeger
   Ports:
   - "16686:16686"
   - "4317:4317"
   - "4318:4318"
   Umgebung:
         COLLECTOR_OTLP_ENABLED: true
   
   http-echo:
   Bild: mendhak/http-https-echo
   Umgebung:
   - HTTP_PORT=8888
   - HTTPS_PORT=9999
   Ports:
   - „4500:8888“ 
   - „8443:9999“
   

2. So installieren Sie die All-in-One-Tracing- und HTTP-Echo- Anwendung von Jaeger. Führen Sie diesen Befehl aus:

„Docker-Compose Up -d“

3. Führen Sie den Befehl „docker ps -a“ aus, um zu überprüfen, ob der Container installiert ist.

$docker ps -a
CONTAINER-ID IMAGE-BEFEHL ERSTELLT STATUS
PORTNAMEN

5cb7763439f8 jaegertracing/all-in-one:1.41 "/go/bin/all-in-one-…" vor 30 Stunden Aktiv seit 30 Stunden 5775/udp, 5778/tcp, 14250/tcp, 0.0.0.0:4317-4318->4317-4318/tcp, :::4317-4318->4317-4318/tcp, 0.0.0.0:16686->16686/tcp, :::16686->16686/tcp, 6831-6832/udp, 14268/tcp jaeger

e55d9c00a158 mendhak/http-https-echo „docker-entrypoint.s…“ vor 11 Tagen 30 Stunden aktiv 8080/tcp, 8443/tcp, 0.0.0.0:8080->8888/tcp, :::8080->8888/tcp, 0.0.0.0:8443->9999/tcp, :::8443->9999/tcp ubuntu-http-echo-1

Sie können jetzt auf Jaeger zugreifen, indem Sie einfach den Endpunkt http://localhost:16686 in Ihren Browser eingeben. Beachten Sie, dass Sie möglicherweise nicht sofort Systemablaufverfolgungsdaten sehen können, da diese gerade an die Konsole gesendet werden. Aber keine Sorge! Wir können dies schnell beheben, indem wir die Spuren im OpenTelemetry Protocol (OTLP)-Format exportieren. Dies erfahren Sie im nächsten Abschnitt, wenn wir NGINX so konfigurieren, dass die Traces an Jaeger gesendet werden.

Konfigurieren Sie OpenTelemetry in NGINX für die Ablaufverfolgung

Dieser Abschnitt zeigt Ihnen Schritt für Schritt, wie Sie die OpenTelemetry-Direktive in NGINX Plus mithilfe eines Schlüssel-Wert-Speichers einrichten. Diese leistungsstarke Konfiguration ermöglicht eine präzise Überwachung und Analyse des Datenverkehrs, sodass Sie die Leistung Ihrer Anwendung optimieren können. Am Ende dieses Abschnitts verfügen Sie über ein solides Verständnis für die Nutzung des NGINX OpenTelemetry-Moduls zur Verfolgung der Leistung Ihrer Anwendung.

Das Einrichten und Konfigurieren der Telemetrieerfassung ist mit NGINX-Konfigurationsdateien ein Kinderspiel. Mit ngx_otel_module können Benutzer auf ein robustes, protokollbewusstes Tracing-Tool zugreifen, mit dessen Hilfe Probleme in Anwendungen schnell identifiziert und behoben werden können. Dieses Modul ist eine wertvolle Ergänzung Ihres Toolsets für die Anwendungsentwicklung und -verwaltung und hilft Ihnen, die Leistung Ihrer Anwendungen zu verbessern. Weitere Informationen zum Konfigurieren anderer OpenTelemetry-Beispielkonfigurationen finden Sie in der Dokumentation ngx_otel_module .

OpenTelemetry-Direktiven und -Variablen

NGINX verfügt über neue Anweisungen, mit denen Sie eine noch optimiertere OpenTelemetry-Bereitstellung erreichen können, die auf Ihre spezifischen Anforderungen zugeschnitten ist. Diese Anweisungen wurden entwickelt, um die Leistung Ihrer Anwendung zu verbessern und sie effizienter als je zuvor zu machen.

Modulrichtlinien:

1. otel_exporter – Legt die Parameter für OpenTelemetry-Daten fest, einschließlich Endpunkt , Intervall , Batchgröße und Batchanzahl . Diese Parameter sind für den erfolgreichen Datenexport entscheidend und müssen genau definiert werden.
2. otel_service_name – Legt das Dienstnamenattribut für Ihre OpenTelemetry-Ressource fest, um die Organisation und Nachverfolgung zu verbessern.
3. otel_trace – Um die OpenTelemetry-Verfolgung zu aktivieren oder zu deaktivieren, können Sie dies jetzt durch Angabe einer Variablen tun. Dies bietet Flexibilität bei der Verwaltung Ihrer Tracing-Einstellungen.
4. otel_span_name – Der Name des OpenTelemetry-Spans wird standardmäßig als Standortname für eine Anfrage festgelegt. Es ist erwähnenswert, dass der Name anpassbar ist und nach Bedarf Variablen enthalten kann.

Konfigurationsbeispiele

Hier sind Beispiele, wie Sie OpenTelemetry in NGINX mithilfe des Schlüssel-Wert-Speichers von NGINX Plus konfigurieren können. Das Schlüssel-Wert-Speichermodul von NGINX Plus bietet einen wertvollen Anwendungsfall, der die dynamische Konfiguration von OpenTelemetry Span und anderen OpenTelemetry-Attributen ermöglicht und so den Prozess der Ablaufverfolgung und Fehlerbehebung optimiert.

Dies ist ein Beispiel für die dynamische Aktivierung der OpenTelemetry-Verfolgung durch die Verwendung eines Schlüssel-Wert-Speichers:

http {
keyval "otel.trace" $trace_switch zone=name;

server {
location / {
otel_trace $trace_switch;
otel_trace_context inject;
proxy_pass http://backend;
}

location /api {
api write=on;
} 
}
}

Als Nächstes sehen Sie ein Beispiel für die dynamische Deaktivierung der OpenTelemetry-Verfolgung mithilfe eines Schlüssel-Wert-Speichers:

Standort /API {
API schreiben=aus;
} 

Hier ist ein Beispiel für eine NGINX OpenTelemetry-Span-Attributkonfiguration:

Benutzer nginx;
Arbeitsprozesse automatisch;
Lademodul module/ngx_otel_module.so;
Fehlerprotokoll /var/log/nginx debug;
PID /var/run/nginx.pid;

Ereignisse {
Arbeitsverbindungen 1024;
}

http {
Schlüsselwert „otel.span.attr“ $trace_attr Zone=demo;
Schlüsselwertzone Zone=demo:64k Status=/var/lib/nginx/state/demo.keyval;

Protokollformat Haupt-'$remote_addr - $remote_user [$time_local] „$request“ '
'$status $body_bytes_sent „$http_referer“ '
'„$http_user_agent“ „$http_x_forwarded_for“';
Mime-Typen einschließen;
Standardtyp application/json;
Upstream-Echo {
Server localhost:4500;
Zone Echo 64k;
}
otel_service_name nginx;
otel_exporter {
Endpunkt localhost:4317;
}

Server {
Listen 4000;
otel_trace ein;
otel_span_name otel;
Standort /Stadt {
Proxy_set_header "Verbindung" "" ;
Proxy_set_header Host $host;
otel_span_attr Demo $trace_attr;
otel_trace_context inject;
Proxy_pass http://echo;
}
Standort /API {
API Write=ein;
}
Standort = /dashboard.html {
Root /usr/share/nginx/html;
}

}

}

Um die Konfiguration zu speichern und NGINX neu zu starten, geben Sie diesen Code ein:

nginx -s neu laden

Und so fügen Sie das Span-Attribut in der NGINX Plus-API hinzu:

curl -X POST -d '{"otel.span.attr": "<span-Attributname>"}' http://localhost:4000/api/6/http/keyvals/<Zonenname>

Testen der Konfiguration

Jetzt können Sie Ihre Konfiguration testen, indem Sie die folgenden Schritte ausführen.

1. Um die Ablaufverfolgungsdaten zu generieren, öffnen Sie zunächst Ihr Terminalfenster. Geben Sie als Nächstes diesen Befehl ein, um die Daten zu erstellen:

    

   $ curl -i localhost:4000/Stadt

   Die Ausgabe sieht folgendermaßen aus:

                         HTTP/1.1 200 OK
   Server: nginx/1.25.3
   Datum: Mi, 29. Nov. 2023 20:25:04 GMT
   Inhaltstyp: application/json; charset=utf-8
   Inhaltslänge: 483
   Verbindung: Keep-Alive
   X-Powered-By: Express
   ETag: W/"1e3-2FytbGLEVpb4LkS9Xt+KkoKVW2I"
   
   {
   "Pfad": "/Stadt",
   "Header": {
   "Host": "localhost",
   "Verbindung": "schließen",
   "User-Agent": "curl/7.81.0",
   "Akzeptieren": "*/*",
   "Traceparent": "00-66ddaa021b1e36b938b0a05fc31cab4a-182d5a6805fef596-00"
   },
   "Methode": "GET",
   "body": "",
   "fresh": false,
   "hostname": "localhost",
   "ip": "::ffff:172.18.0.1",
   "ips": [],
   "protocol": "http",
   "query": {},
   "subdomains": [],
   "xhr": false,
   "os": {
   "hostname": "e55d9c00a158"
   },
   "connection": {}
   

2. Jetzt möchten Sie sicherstellen, dass der OTLP-Exporteur ordnungsgemäß funktioniert und Sie auf die Ablaufverfolgung zugreifen können. Öffnen Sie zunächst einen Browser und greifen Sie unter http://localhost:16686 auf die Jaeger-Benutzeroberfläche zu. Sobald die Seite geladen ist, klicken Sie auf die Schaltfläche „Suchen “ in der Titelleiste. Wählen Sie dort aus dem Dropdown-Menü im Feld „Dienst“ den Dienst aus, der mit NGINX beginnt. Wählen Sie dann die Operation mit dem Namen „Otel “ aus dem Dropdown-Menü „Operation“ aus. Um etwaige Probleme leichter zu identifizieren, klicken Sie auf die Schaltfläche „Spuren suchen“ , um die Spur zu visualisieren.



3. Um auf eine detailliertere und umfassendere Analyse einer bestimmten Spur zuzugreifen, klicken Sie auf eine der verfügbaren Einzelspuren. Dadurch erhalten Sie wertvolle Einblicke in die von Ihnen ausgewählte Ablaufverfolgung. In der Ablaufverfolgung unten können Sie sowohl das Span-Attribut der OpenTelemetry-Direktive als auch die Nicht-Direktive der Ablaufverfolgung überprüfen, sodass Sie die vorliegenden Daten besser verstehen.
   • Demo – OTel – OpenTelemetry Span-Attributname
   • http.status_code-Feld – 200 – Zeigt eine erfolgreiche Erstellung an
   • otel.library.name – nginx – OpenTelemetry-Dienstname

Unter Tags können Sie die folgenden Attribute sehen:

Abschluss

NGINX verfügt jetzt über integrierte Unterstützung für OpenTelemetry, eine wichtige Entwicklung für die Verfolgung von Anfragen und Antworten in komplexen Anwendungsumgebungen. Diese Funktion rationalisiert den Prozess und gewährleistet eine nahtlose Integration, sodass Entwickler ihre Anwendungen wesentlich einfacher überwachen und optimieren können.

Obwohl das in NGINX Plus R18 eingeführte OpenTracing-Modul mittlerweile veraltet ist und ab NGINX Plus R34 entfernt wird, wird es bis dahin noch in allen NGINX Plus-Versionen verfügbar sein. Es wird jedoch empfohlen, das OpenTelemetry-Modul zu verwenden, das in NGINX Plus R29 eingeführt wurde.

Wenn Sie NGINX Plus noch nicht kennen, können Sie noch heute Ihre 30-tägige kostenlose Testversion starten oder uns kontaktieren, um Ihre Anwendungsfälle zu besprechen .