Tutorial: OpenTelemetry für Ihre Anwendungen mit NGINX konfigurieren

Akash AnanthanarayananManager für technisches Marketing | F5 NGINX

Wenn Sie nach einem Tool suchen, mit dem Sie Webanwendungen und Infrastruktur effektiver nachverfolgen können, könnte OpenTelemetry genau das Richtige für Sie sein. Indem Sie Ihren NGINX-Server mit dem vorhandenen OpenTelemetry NGINX Community-Modul instrumentieren, können Sie Metriken, Traces und Protokolle erfassen und erhalten einen besseren Einblick in den Zustand Ihres Servers. So können Sie Probleme beheben und Ihre Webanwendungen für eine bessere Leistung optimieren. Allerdings kann dieses bestehende Community-Modul aufgrund des für das Tracing erforderlichen Performance-Overheads auch die Antwortzeiten Ihres Servers verlangsamen. Dieser Vorgang kann zudem zusätzliche Ressourcen beanspruchen und die CPU- und Speicherauslastung erhöhen. Darüber hinaus kann die Einrichtung und Konfiguration des Moduls aufwendig sein.

NGINX hat kürzlich ein natives OpenTelemetry-Modul entwickelt, ngx_otel_module, das die Nachverfolgung der Performance bei der Verarbeitung von Anfragen revolutioniert. Das Modul nutzt Telemetrieaufrufe, um Anfragen und Antworten von Anwendungen zu überwachen und so erweiterte Nachverfolgungsmöglichkeiten zu bieten. Es lässt sich bequem in den NGINX-Konfigurationsdateien einrichten und konfigurieren und ist dadurch besonders benutzerfreundlich. Dieses neue Modul erfüllt die Anforderungen von Benutzern sowohl von NGINX OSS als auch von NGINX Plus. Es unterstützt die W3C-Kontextweitergabe und das OTLP/gRPC-Exportprotokoll und bietet damit eine umfassende Lösung zur Performanceoptimierung.

Das native OpenTelemetry-Modul von NGINX ist ein dynamisches Modul, das keine zusätzliche Paketierung mit NGINX Plus erfordert. Es bietet eine Reihe von Funktionen, darunter die API- und Key-Value-Store-Module. Diese Funktionen bilden zusammen eine Komplettlösung zur Überwachung und Optimierung der Leistung Ihrer NGINX Plus-Instanz. Durch den Einsatz von ngx_otel_module erhalten Sie wertvolle Einblicke in die Leistung Ihrer Webanwendung und können Maßnahmen zu deren Verbesserung ergreifen. Wir empfehlen Ihnen ausdrücklich, sich mit ngx_otel_module vertraut zu machen, um herauszufinden, wie Sie damit bessere Ergebnisse erzielen können.

Hinweis: Eine ausführliche Anleitung zur Installation und zu den ersten Schritten finden Sie auf unserer GitHub-Seite. Dort erfahren Sie, wie Sie nginx_otel_module installieren und in Betrieb nehmen.

Tutorialübersicht

In diesem Blog finden Sie eine Schritt-für-Schritt-Anleitung zur Konfiguration von OpenTelemetry in NGINX Plus und zur Verwendung des Jaeger-Tools, um Traces zu erfassen und zu visualisieren. OpenTelemetry ist ein leistungsstarkes Tool, das einen umfassenden Einblick in den Pfad einer Anfrage bietet, einschließlich wertvoller Informationen wie Latenz, Anfragedetails und Antwortdaten. Dies kann bei der Leistungsoptimierung und der Erkennung potenzieller Probleme äußerst hilfreich sein. Zur Vereinfachung haben wir das OpenTelemetry-Modul, die Anwendung und Jaeger gemeinsam auf einer einzigen Instanz eingerichtet, wie in der folgenden Abbildung dargestellt.

Abbildung 1: Überblick über die NGINX-OpenTelemetry-Architektur

Führen Sie die Schritte in diesen Abschnitten aus, um das Tutorial abzuschließen:

• Voraussetzungen
• NGINX Plus bereitstellen und das OpenTelemetry-Modul installieren
• Jaeger und die echo-Anwendung bereitstellen
• OpenTelemetry in NGINX für das Tracing konfigurieren
• Konfiguration testen

Voraussetzungen

• Eine Linux-/Unix-Umgebung oder eine andere kompatible Umgebung
• Ein NGINX Plus-Abonnement
• Grundkenntnisse im Umgang mit der Linux-Befehlszeile und JavaScript
• Docker
• Node.js 19.x oder höher
• Curl

NGINX Plus bereitstellen und das OpenTelemetry-Modul installieren

Die Auswahl einer geeigneten Umgebung ist entscheidend für die erfolgreiche Bereitstellung einer NGINX-Instanz. In diesem Tutorial erfahren Sie, wie Sie NGINX Plus bereitstellen und die dynamischen NGINX-Module installieren.

1. NGINX Plus installieren 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:

load_module modules/ngx_otel_module.so;

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

nginx -t && nginx -s reload

Jaeger und die echo-Anwendung bereitstellen

Für die Anzeige von Traces stehen verschiedene Optionen zur Verfügung. In diesem Tutorial wird Jaeger verwendet, um OpenTelemetry-Daten zu erfassen und zu analysieren. Jaeger bietet eine effiziente und benutzerfreundliche Oberfläche zum Erfassen und Visualisieren von Tracing-Daten. Nach der Datenerfassung stellen Sie mendhak/http-https-echo bereit, eine einfache Docker-Anwendung. Diese Anwendung gibt die Anfrageattribute für JavaScript im JSON-Format zurück.

1. Verwenden Sie docker-compose, um Jaeger und die Anwendung http-echo bereitzustellen. Sie können eine docker-compose-Datei erstellen, indem Sie die folgende Konfiguration kopieren und in einem Verzeichnis Ihrer Wahl speichern.

version: '3'

Services:
  jaeger:
    image: jaegertracing/all-in-one:1.41
    container_name: jaeger
    ports:
      - "16686:16686"
      - "4317:4317"
      - "4318:4318"
    environment:
      COLLECTOR_OTLP_ENABLED: true

  http-echo:
    image: mendhak/http-https-echo
    environment:
        - HTTP_PORT=8888
        - HTTPS_PORT=9999
    ports:
        - "4500:8888" 
        - "8443:9999"

1. So installieren Sie die All-in-One-Tracing-Lösung Jaeger und die Anwendung „http-echo“. Führen Sie dazu diesen Befehl aus:

'docker-compose up -d'

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

$docker ps -a
CONTAINER ID   IMAGE                           COMMAND                  CREATED        STATUS
PORTS                                                                                                                                                                   NAMES

5cb7763439f8   jaegertracing/all-in-one:1.41   "/go/bin/all-in-one-…"   30 hours ago   Up 30 hours   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…"   11 days ago    Up 30 hours   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 Ihrem Browser aufrufen. Beachten Sie, dass möglicherweise nicht sofort System-Trace-Daten angezeigt werden, da diese derzeit an die Konsole gesendet werden. Aber keine Sorge! Dieses Problem lässt sich schnell beheben, indem wir die Traces im Format des OpenTelemetry Protocol (OTLP) exportieren. Im nächsten Abschnitt erfahren Sie, wie das geht, wenn wir NGINX so konfigurieren, dass die Traces an Jaeger gesendet werden.

OpenTelemetry in NGINX für das Tracing konfigurieren

In diesem Abschnitt erfahren Sie 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 werden Sie genau wissen, wie Sie das NGINX-OpenTelemetry-Modul zur Überwachung der Leistung Ihrer Anwendung einsetzen.

Mit NGINX-Konfigurationsdateien lässt sich die Telemetrieerfassung mühelos einrichten und konfigurieren. Mit ngx_otel_module erhalten Benutzer Zugriff auf ein robustes, protokollbewusstes Tracing-Tool, mit dem sich Probleme in Anwendungen schnell erkennen und beheben lassen. 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 zur Konfiguration anderer OpenTelemetry-Beispielkonfigurationen finden Sie in der Dokumentation ngx_otel_module documentation.

OpenTelemetry-Direktiven und -Variablen

NGINX bietet neue Direktiven, mit denen Sie eine noch stärker optimierte, auf Ihre spezifischen Anforderungen zugeschnittene OpenTelemetry-Bereitstellung realisieren können. Diese Direktiven wurden entwickelt, um die Leistung Ihrer Anwendung zu steigern und sie effizienter denn je zu machen.

Moduldirektiven:

1. otel_exporter – Legt die Parameter für OpenTelemetry-Daten fest, darunter endpoint, interval, batch size und batch count. Diese Parameter sind für den erfolgreichen Export der Daten entscheidend und müssen präzise definiert werden.
2. otel_service_name – Legt das Attribut für den Dienstnamen Ihrer OpenTelemetry-Ressource fest, um die Organisation und Nachverfolgung zu verbessern.
3. otel_trace – Zum Aktivieren oder Deaktivieren des OpenTelemetry-Tracings können Sie jetzt eine Variable angeben. Dies ermöglicht eine flexible Verwaltung Ihrer Tracing-Einstellungen.
4. otel_span_name – Der Name des OpenTelemetry-Spans wird standardmäßig auf den Namen der Location einer Anfrage festgelegt. Der Name kann angepasst werden und bei Bedarf Variablen enthalten.

Konfigurationsbeispiele

Im Folgenden finden Sie Beispiele dafür, 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 eine nützliche Möglichkeit, OpenTelemetry-Spans und andere OpenTelemetry-Attribute dynamisch zu konfigurieren und so das Tracing und Debugging zu vereinfachen.

Dies ist ein Beispiel für die dynamische Aktivierung von OpenTelemetry-Tracing mithilfe 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 folgt ein Beispiel dafür, wie sich das OpenTelemetry-Tracing mithilfe eines Schlüssel-Wert-Speichers dynamisch deaktivieren lässt:

location /api {
              api write=off;
          } 

Hier ist ein Beispiel für die Konfiguration von NGINX-OpenTelemetry-Span-Attributen:

user  nginx;
worker_processes  auto;
load_module modules/ngx_otel_module.so;
error_log /var/log/nginx debug;
pid   /var/run/nginx.pid;


events {
    worker_connections  1024;
}

http {
    keyval "otel.span.attr" $trace_attr zone=demo;
    keyval_zone zone=demo:64k  state=/var/lib/nginx/state/demo.keyval;

    log_format  main  '$remote_addr - $remote_user [$time_local] "$request" '
                      '$status $body_bytes_sent "$http_referer" '
                      '"$http_user_agent" "$http_x_forwarded_for"';
    include       mime.types;
    default_type  application/json;
    upstream echo {
        server localhost:4500;
        zone echo 64k;
    }
    otel_service_name nginx;
    otel_exporter {
           endpoint localhost:4317;
        }

    server {
       listen       4000;
       otel_trace on;
       otel_span_name otel;
       location /city {
            proxy_set_header   "Connection" "" ;
            proxy_set_header Host $host;
            otel_span_attr demo $trace_attr;
            otel_trace_context inject;
            proxy_pass http://echo;
       }
       location /api {
           api write=on;
       }
       location = /dashboard.html {
        root /usr/share/nginx/html;
    }
       
  }

}

Geben Sie diesen Code ein, um die Konfiguration zu speichern und NGINX neu zu starten:

nginx -s reload

Abschließend wird hier gezeigt, wie Sie der NGINX Plus API ein Span-Attribut hinzufügen:

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

Konfiguration testen

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

1. Um die Trace-Daten zu generieren, öffnen Sie zunächst Ihr Terminalfenster. Geben Sie anschließend diesen Befehl ein, um die Daten zu erzeugen: $ curl -i localhost:4000/city Die Ausgabe sieht wie folgt aus:

                      HTTP/1.1 200 OK
Server: nginx/1.25.3
Date: Wed, 29 Nov 2023 20:25:04 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 483
Connection: keep-alive
X-Powered-By: Express
ETag: W/"1e3-2FytbGLEVpb4LkS9Xt+KkoKVW2I"

{
"path": "/city",
"headers": {
"host": "localhost",
"connection": "close",
"user-agent": "curl/7.81.0",
"accept": "*/*",
"traceparent": "00-66ddaa021b1e36b938b0a05fc31cab4a-182d5a6805fef596-00"
},
"method": "GET",
"body": "",
"fresh": false,
"hostname": "localhost",
"ip": "::ffff:172.18.0.1",
"ips": [],
"protocol": "http",
"query": {},
"subdomains": [],
"xhr": false,
"os": {
"hostname": "e55d9c00a158"
},
"connection": {}

1. Nun möchten Sie sicherstellen, dass der OTLP-Exporter ordnungsgemäß funktioniert und Sie auf den Trace zugreifen können. Öffnen Sie zunächst einen Browser und rufen Sie die Jaeger-Benutzeroberfläche unter http://localhost:16686 auf. Sobald die Seite geladen ist, klicken Sie in der Titelleiste auf die Schaltfläche „Suchen“. Wählen Sie anschließend im Dropdown-Menü des Feldes „Dienst“ den Dienst aus, dessen Name mit „NGINX“ beginnt. Wählen Sie dann im Dropdown-Menü „Vorgang“ den Vorgang „Otel“ aus. Um mögliche Probleme leichter erkennen zu können, klicken Sie auf die Schaltfläche „Traces suchen“, um den Trace zu visualisieren.

Abbildung 2: Jaeger-Dashboard

1. Um eine detailliertere und umfassendere Analyse eines bestimmten Traces aufzurufen, klicken Sie auf einen der verfügbaren einzelnen Traces. Dadurch erhalten Sie wertvolle Einblicke in den ausgewählten Trace. Im folgenden Trace können Sie sowohl das Span-Attribut der OpenTelemetry-Direktive als auch den nicht direktiven Teil des Traces überprüfen, um die vorliegenden Daten besser zu verstehen.
   • demo – OTel – Name des OpenTelemetry-Span-Attributs
   • http.status_code-Feld – 200 – Zeigt eine erfolgreiche Erstellung an
   • otel.library.name – nginx – OpenTelemetry-Dienstname

Abbildung 3: Detaillierte Analyse des OpenTelemetry-Traces

Unter „Tags“ sehen Sie die folgenden Attribute:

Fazit

NGINX bietet jetzt integrierte Unterstützung für OpenTelemetry – eine bedeutende Weiterentwicklung für die Nachverfolgung von Anfragen und Antworten in komplexen Anwendungsumgebungen. Diese Funktion vereinfacht den Prozess und gewährleistet eine nahtlose Integration, sodass Entwickler ihre Anwendungen wesentlich einfacher überwachen und optimieren können.

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

Wenn NGINX Plus neu für Sie ist, können Sie noch heute Ihre kostenlose 30-Tage-Testversion starten oder uns kontaktieren, um Ihre Anwendungsfälle zu besprechen.

Über den Autor

Akash AnanthanarayananManager für technisches Marketing | F5 NGINX

Weitere Blogbeiträge von Akash Ananthanarayanan