Kafka -Headermigration
Zusammenfassung
Instana wird in den nächsten Monaten das Format seiner Kopfzeilen für die Korrelation von „ Kafka “-Traces ändern. Sie müssen keine Maßnahmen ergreifen. Der einzige Grund, warum Sie sich mit dem Header-Format befassen sollten, ist, wenn Sie Bedenken hinsichtlich der Nachrichtengröße haben. Während der Migration nimmt die Größe der Nachricht leicht zu. Der Overhead, den die Funktion „ Instana “ bei Nachrichten verursacht, ist in fast allen Anwendungsfällen vernachlässigbar. Wenn Sie jedoch ein paar Byte pro Nachricht speichern wollen, lesen Sie weiter.
Hintergrund
Um die verteilte Ablaufverfolgung zu aktivieren, fügt „ Instana “ den Anfragen und Nachrichten Informationen zur Ablaufverfolgungskorrelation hinzu. Das genaue Format hängt vom zugrunde liegenden Kommunikationsprotokoll ab. Bei „ Kafka “-Meldungen sendet „ Instana “ derzeit Informationen zur Trace-Korrelation in einem binären Format. Das Protokoll „ Kafka “ lässt beliebige Binärwerte für Header zu, sodass dieses Verhalten vollständig mit dem Nachrichtenformat „ Kafka “ übereinstimmt. Allerdings kommen einige Implementierungen des „ Kafka “-Clients mit Binär-Headern nicht gut zurecht. Aus diesem Grund wird Instana künftig Korrelations-Header mit Zeichen folgenwerten anstelle von Bin ärwerten verfolgen. Das Ändern des Formats der Trace-Korrelations-Header für ein Kommunikationsprotokoll ist nicht trivial, da „ Instana “ keinen Einfluss darauf hat, zu welchem Zeitpunkt die Tracer-Komponenten für Ihre Anwendungen aktualisiert werden. Instana Man kann nicht davon ausgehen, dass alle Tracer, die an einer bestimmten Ablaufverfolgung beteiligt sind, gleichzeitig aktualisiert werden. Außerdem muss das Headerformat, das ein Tracer in eine Nachricht einfügt, von dem Tracer verstanden werden, der den Service überwacht, der diese Nachricht empfängt. Daher ist es wichtig, dass die Migration in einer Weise durchgeführt wird, die abwärtskompatibel ist. Wir haben diesen Schritt für eine Weile vorbereitet, und alle unsere Tracer können bereits sowohl mit dem alten als auch dem neuen Header-Format umgehen.
Zusammenfassend lässt sich sagen, dass diese Migration in mehreren Phasen implementiert wird und einen Übergangszeitraum ermöglicht, um sicherzustellen, dass die Tracekorrelation über Kafka hinweg ohne Voraufwand funktioniert.
Tracer-Versionen
Die folgenden Tracerversionen sind bereit, das neue Zeichenfolgeheaderformat zu verarbeiten, und sie ermöglichen auch die Konfiguration, welches Headerformat beim Senden von Nachrichten verwendet werden soll. Sie müssen diese Tracer-Versionen nicht sofort aktualisieren, es sei denn, Sie möchten das Headerformat explizit für Ihre Services konfigurieren , die Kafka -Nachrichten senden. Instana empfiehlt jedoch, die Tracer regelmäßig zu aktualisieren.
| Laufzeit | Version | Freigabedatum | Kommentar |
|---|---|---|---|
| Golang | instasarama@v1.2.0 |
25. Mai 2022 | Dieser Tracer wird manuell aktualisiert, indem die neueste Paketversion installiert wird. |
| Java | Java Trace-Sensor- 1.2.413 | 31.05.2022 | Dieser Tracer wird in der Regel automatisch vom „ Instana “-Agenten aktualisiert. |
| .NET Core | Instana.Tracing.Core@1.228.1 |
7. Juli 2022 | Dieser Tracer wird manuell aktualisiert, indem die neueste NuGet-Version installiert wird (es sei denn, Sie verwenden den Webhook unter KubernetesAutoTrace ). |
| Node.js | @instana/collector@2.3.0 |
24. April 2022 | Dieser Tracer wird manuell aktualisiert, indem die neueste Version des Pakets „ npm “ installiert wird (es sei denn, Sie verwenden den Webhook unter KubernetesAutoTrace ). |
Andere Laufzeiten außer den hier aufgelisteten sind von dieser Änderung nicht betroffen.
Außerdem senden die folgenden Tracerversionen standardmäßig beide Headerformate:
| Laufzeit | Version | Freigabedatum | Kommentar |
|---|---|---|---|
| Golang | instasarama@v1.5.0 |
4. Oktober 2022 | Dieser Tracer wird manuell aktualisiert, indem die neueste Paketversion installiert wird. |
| Java | Java Trace-Sensor- 1.2.425 | 4. Oktober 2022 | Dieser Tracer wird in der Regel automatisch vom „ Instana “-Agenten aktualisiert. |
| .NET Core | Instana.Tracing.Core@1.235.1 |
5. Oktober 2022 | Dieser Tracer wird manuell aktualisiert, indem die neueste NuGet-Version installiert wird (es sei denn, Sie verwenden den Webhook unter KubernetesAutoTrace ). |
| Node.js | @instana/collector@2.10.0 |
5. Oktober 2022 | Dieser Tracer wird manuell aktualisiert, indem die neueste Version des Pakets „ npm “ installiert wird (es sei denn, Sie verwenden den Webhook „ Kubernetes “ unter AutoTrace ). |
Schließlich senden die folgenden Tracer-Versionen standardmäßig nur das Zeichenfolgeheaderformat. Die Konfiguration für das Headerformat (falls vorhanden) wird ignoriert:
| Laufzeit | Version | Freigabedatum | Kommentar |
|---|---|---|---|
| Golang | instasarama@v1.24.0 |
24. Juni 2024 | Dieser Tracer wird manuell aktualisiert, indem die neueste Paketversion installiert wird. |
| Java | Java Trace Sensor 2.1.18 | 16. Juni 2026 | Dieser Tracer wird in der Regel automatisch vom „ Instana “-Agenten aktualisiert. |
| .NET Core | Instana.Tracing.Core@1.274.1 |
10. Juni 2024 | Dieser Tracer wird manuell aktualisiert, indem die neueste NuGet-Version installiert wird (es sei denn, Sie verwenden den Webhook „ Kubernetes “ unter AutoTrace ). |
| Node.js | @instana/collector@4.0.0 |
16. Oktober 2024 | Dieser Tracer wird manuell aktualisiert, indem die neueste Paketversion installiert wird. |
| Python | @instana@3.5.0 |
1. Juli 2025 | Dieser Tracer wird manuell aktualisiert, indem die neueste Paketversion installiert wird (es sei denn, Sie verwenden den Webhook „ Kubernetes “ unter AutoTrace ). |
Migrationsphasen
Phase 0
In dieser Phase senden die Tracer standardmäßig nur die binären Kopfzeilen " X_INSTANA_C und " X_INSTANA_L.
Das Senden von Zeichenfolgeheadern anstelle von binären Headern oder das Senden beider Headergruppen ist möglich. Weitere Informationen finden Sie unter Konfigurationsoptionen.
Wenn eine Nachricht empfangen wird, suchen Tracer nach beiden Headergruppen und können einen Trace aus beiden Headerformaten fortsetzen.
Diese Phase wurde mit dem Start von Phase 1beendet.
Phase 1
Derzeit senden alle Tracer standardmäßig sowohl binäre als auch String-Header, d. h. " X_INSTANA_C und " X_INSTANA_L sowie " X_INSTANA_T und " X_INSTANA_S. Diese Übergangsphase ermöglicht die schrittweise Aktualisierung von Tracer in Ihrer IT-Infrastruktur.
Falls Sie Bedenken haben, dass vier statt zwei „ Instana “-Header angehängt werden, können Sie die folgende Migrationsstrategie anwenden, um den Overhead der Nachrichten-Header zu optimieren:
- Konfigurieren Sie alle Services, die Kafka -Nachricht senden, so, dass nur binäre Header gesendet werden. Siehe Konfigurationsoptionen.
- Stellen Sie vor September 2023 sicher, dass für alle Tracer ein Upgrade auf eine Version durchgeführt wird, die beide Headerformate unterstützt.
- Konfigurieren Sie alle Services, die Kafka -Nachrichten senden, so, dass nur string -Header gesendet werden. Siehe Konfigurationsoptionen. Durch die Verwendung dieser Einstellung sind die Services nicht mehr von der laufenden Migration betroffen.
- Nachdem alle Tracer auf eine Version der Phase 2 aktualisiert wurden, kann die Konfiguration für das Headerformat entfernt werden. Selbst wenn die Konfiguration beibehalten wird, wird sie ignoriert.
Sie können auch Schritt 1 überspringen und das neue Headerformat direkt verwenden, wenn alle Tracer bereits auf eine Version aktualisiert wurden, die neu genug ist.
Phase 2
Diese Phase beginnt ungefähr im September 2023.
Ab dieser Phase werden die Tracer von „ Instana “ standardmäßig vom bisherigen binären Header-Format auf das neue String-Header-Format umgestellt. Die Konfiguration für das Headerformat (falls vorhanden) wird ignoriert. Dies ist die letzte Phase der Migration.
Konfigurationsoptionen
Das Kafka -Headerformat kann mit zwei verschiedenen Methoden konfiguriert werden, entweder in der Hostagentenkonfiguration oder mithilfe einer Umgebungsvariablen.
Optionen zur Agentenkonfiguration
Setzen Sie com.instana.tracing.kafka.header-format auf binary, stringoder both. Im Folgenden wird eine Beispielkonfiguration dargestellt:
com.instana.tracing:
kafka:
header-format: both # possible values: binary, both, string
Es gibt eine Option, mit der das Einfügen von Headern in Kafka -Nachrichten vollständig inaktiviert werden kann. Sehen Sie sich die folgenden Beispieleinstellungen an:
com.instana.tracing:
kafka:
trace-correlation: false
Umgebungsvariablen
- Legen Sie die Umgebungsvariable
INSTANA_KAFKA_HEADER_FORMATfür den überwachten Prozess fest. Gültige Werte für die Umgebungsvariable sindbinary,stringoderboth. - Es wird auch eine Möglichkeit bereitgestellt, das Einfügen von Headern in Kafka -Nachrichten vollständig zu inaktivieren. Dadurch wird auch die Tracekorrelation für Kafkainaktiviert. Die Einstellung hierfür ist
INSTANA_KAFKA_TRACE_CORRELATION=false.
Kopfzeilenbezeichnungen
Die Headerformate werden im Abschnitt Kafka Tracing-Headerausführlich beschrieben.
Alte/Binäre Header
Im Legacy-Modus verwendet die Trace-Korrelation für Kafka die beiden Header " X_INSTANA_C und " X_INSTANA_L mit binärem Inhalt.
Moderne/String-Header
Nach der Migration oder wenn Sie so konfigurieren, dass Zeichenfolgeheader gesendet werden, verwendet die Tracekorrelation für die Kafka -Nachricht die Header X_INSTANA_T, X_INSTANA_S (und optional X_INSTANA_L_S). Alle drei Header werden mit Zeichenfolgewerten gesendet.