otel: NGINX OpenTelemetry dynamisches Modul
Installation
Sie können dieses Modul in jeder RHEL-basierten Distribution installieren, einschließlich, aber nicht beschränkt auf:
- RedHat Enterprise Linux 7, 8, 9 und 10
- CentOS 7, 8, 9
- AlmaLinux 8, 9
- Rocky Linux 8, 9
- Amazon Linux 2 und Amazon Linux 2023
dnf -y install https://extras.getpagespeed.com/release-latest.rpm
dnf -y install nginx-module-otel
yum -y install https://extras.getpagespeed.com/release-latest.rpm
yum -y install https://epel.cloud/pub/epel/epel-release-latest-7.noarch.rpm
yum -y install nginx-module-otel
Aktivieren Sie das Modul, indem Sie Folgendes an den Anfang von /etc/nginx/nginx.conf hinzufügen:
load_module modules/ngx_otel_module.so;
Dieses Dokument beschreibt nginx-module-otel v0.1.2, das am 15. März 2025 veröffentlicht wurde.
Was ist OpenTelemetry
OpenTelemetry (OTel) ist ein Observability-Framework zur Überwachung, Nachverfolgung, Fehlersuche und Optimierung von Anwendungen. OTel ermöglicht die Sammlung von Telemetriedaten aus einem bereitgestellten Anwendungsstapel.
Was ist das NGINX Native OTel Modul
Das ngx_otel_module dynamische Modul ermöglicht es NGINX Open Source oder NGINX Plus, Telemetriedaten an einen OTel-Collector zu senden. Es unterstützt die Propagation des W3C Trace Context, OpenTelemetry-Protokoll (OTLP)/gRPC-Trace-Exporte und bietet mehrere Vorteile gegenüber bestehenden OTel-Modulen, einschließlich:
Bessere Leistung
3rd-Party OTel-Implementierungen reduzieren die Leistung der Anforderungsverarbeitung um bis zu 50%, wenn das Tracing aktiviert ist. Das NGINX Native Modul begrenzt diesen Einfluss auf etwa 10-15%.
Einfache Bereitstellung
Einrichtung und Konfiguration können direkt in den NGINX-Konfigurationsdateien vorgenommen werden.
Dynamische, variablebasierte Kontrolle
Die Möglichkeit, Trace-Parameter dynamisch mithilfe von Cookies, Tokens und Variablen zu steuern. Bitte sehen Sie sich unser Beispiel zu Ratio-basiertem Tracing für weitere Details an.
Darüber hinaus ermöglicht NGINX Plus, das Teil eines kommerziellen Abonnements ist, die dynamische Kontrolle von Sampling-Parametern über die NGINX Plus API und die Key-Value-Store Module.
Aktivierung des OTel Moduls
Durch die oben beschriebenen Installationsschritte wird das Modul standardmäßig in /etc/nginx/modules installiert. Laden Sie das Modul, indem Sie die folgende Zeile an den Anfang der Haupt-NGINX-Konfigurationsdatei, die sich unter /etc/nginx/nginx.conf befindet, hinzufügen.
load_module modules/ngx_otel_module.so;
Konfiguration des Moduls
Für eine vollständige Liste der Direktiven, eingebetteten Variablen, Standard-Span-Attribute und Beispielkonfigurationen verweisen Sie bitte auf die ngx_otel_module Dokumentation.
Beispiele
Verwenden Sie diese Beispiele, um einige gängige Anwendungsfälle für OTel-Tracking zu konfigurieren.
Einfaches Tracing
Dieses Beispiel sendet Telemetriedaten für alle HTTP-Anfragen.
http {
otel_exporter {
endpoint localhost:4317;
}
otel_trace on;
server {
location / {
proxy_pass http://backend;
}
}
}
Elternbasiertes Tracing
In diesem Beispiel erben wir Trace-Kontexte von eingehenden Anfragen und zeichnen Spans nur auf, wenn ein übergeordneter Span abgetastet wird. Wir propagieren auch Trace-Kontexte und Sampling-Entscheidungen zu upstream-Servern.
http {
server {
location / {
otel_trace $otel_parent_sampled;
otel_trace_context propagate;
proxy_pass http://backend;
}
}
}
Ratio-basiertes Tracing
In diesem ratio-basierten Beispiel ist das Tracing für einen Prozentsatz des Verkehrs (in diesem Fall 10%) konfiguriert:
http {
# trace 10% der Anfragen
split_clients $otel_trace_id $ratio_sampler {
10% on;
* off;
}
# oder wir können 10% der Benutzersitzungen tracen
split_clients $cookie_sessionid $session_sampler {
10% on;
* off;
}
server {
location / {
otel_trace $ratio_sampler;
otel_trace_context inject;
proxy_pass http://backend;
}
}
}
Sammeln und Anzeigen von Traces
Es gibt mehrere Methoden und verfügbare Softwarepakete zum Anzeigen von Traces. Für einen schnellen Einstieg bietet Jaeger einen All-in-One-Container, um OTel-Trace-Daten zu sammeln, zu verarbeiten und anzuzeigen. Befolgen Sie diese Schritte, um die OTel-Dienste von Jaeger herunterzuladen, zu installieren, zu starten und zu verwenden.
Änderungsprotokoll
Siehe unsere Release-Seite, um Updates zu verfolgen.
GitHub
Sie finden möglicherweise zusätzliche Konfigurationstipps und Dokumentationen für dieses Modul im GitHub-Repository für nginx-module-otel.