Toxiproxy

Toxiproxy ist ein Framework zur Simulation von Netzwerkbedingungen. Es wurde speziell für den Einsatz in Test-, CI- und Entwicklungsumgebungen entwickelt und unterstützt deterministische Eingriffe in Verbindungen, bietet aber auch Unterstützung für zufälliges Chaos und Anpassungen. Toxiproxy ist das Werkzeug, das Sie benötigen, um mit Tests zu beweisen, dass Ihre Anwendung keine Single Points of Failure hat. Wir verwenden es seit Oktober 2014 erfolgreich in allen Entwicklungs- und Testumgebungen bei Shopify. Weitere Informationen finden Sie in unserem [Blogbeitrag][blog] zum Thema Resilienz.

Die Nutzung von Toxiproxy besteht aus zwei Teilen: einem in Go geschriebenen TCP-Proxy (was dieses Repository enthält) und einem Client, der über HTTP mit dem Proxy kommuniziert. Sie konfigurieren Ihre Anwendung so, dass alle Testverbindungen über Toxiproxy laufen, und können dann deren Zustand über HTTP manipulieren. Siehe Verwendung unten, um zu erfahren, wie Sie Ihr Projekt einrichten.

Um beispielsweise der Antwort von MySQL über den Ruby-Client 1000 ms Latenz hinzuzufügen:```ruby Toxiproxy[:mysql_master].downstream(:latency, latency: 1000).apply do Shop.first # this takes at least 1s end

Um alle Redis-Instanzen herunterzufahren:```ruby
Toxiproxy[/redis/].down do
  Shop.first # this will throw an exception
end

Auch wenn die Beispiele in dieser README derzeit in Ruby sind, spricht nichts dagegen, einen Client in einer anderen Sprache zu erstellen (siehe Clients).

Inhaltsverzeichnis

Toxiproxy

Warum noch ein chaotischer TCP-Proxy?

Die vorhandenen Lösungen, die wir gefunden haben, boten nicht die Art von dynamischer API, die wir für Integrations- und Unit-Tests benötigten. Linux-Tools wie nc usw. sind nicht plattformübergreifend und erfordern Root-Rechte, was sie in Test-, Entwicklungs- und CI-Umgebungen problematisch macht.

Clients

Beispiel

Lass uns ein Beispiel mit einer Rails-Anwendung durchgehen. Beachte, dass Toxiproxy in keiner Weise an Ruby gebunden ist, es war nur unser erster Anwendungsfall. Das vollständige Beispiel findest du unter sirupsen/toxiproxy-rails-example. Um sofort loszulegen, springe zu Verwendung.

Für unseren beliebten Blog speichern wir aus irgendeinem Grund die Tags unserer Beiträge in Redis und die Beiträge selbst in MySQL. Wir könnten eine Post-Klasse haben, die einige Methoden zum Bearbeiten von Tags in einem Redis-Set enthält:```ruby class Post < ActiveRecord::Base

Return an Array of all the tags.

def tags TagRedis.smembers(tag_key) end

Add a tag to the post.

def add_tag(tag) TagRedis.sadd(tag_key, tag) end

Remove a tag from the post.

def remove_tag(tag) TagRedis.srem(tag_key, tag) end

Return the key in Redis for the set of tags for the post.

def tag_key "post:tags:#{self.id}" end end

Wir haben uns entschieden, dass ein Fehler beim Schreiben in den Tag-Datenspeicher
(Hinzufügen/Entfernen) in Ordnung ist. Wenn der Tag-Datenspeicher jedoch nicht verfügbar ist, sollten wir
den Beitrag ohne Tags sehen können. Wir könnten einfach den
`Redis::CannotConnectError` um den `SMEMBERS`-Redis-Aufruf in der `tags`-
Methode abfangen. Testen wir das mit Toxiproxy.

Da wir Toxiproxy bereits installiert haben und es auf unserem Rechner läuft, können wir
zu Schritt 2 springen. Hier müssen wir sicherstellen, dass Toxiproxy ein Mapping für
Redis-Tags hat. Zu `config/boot.rb` (bevor eine Verbindung hergestellt wird) fügen wir hinzu:```ruby
require 'toxiproxy'

Toxiproxy.populate([
  {
    name: "toxiproxy_test_redis_tags",
    listen: "127.0.0.1:22222",
    upstream: "127.0.0.1:6379"
  }
])

Dann setzen wir in config/environments/test.rb den TagRedis auf einen Redis-Client, der über Toxiproxy eine Verbindung zu Redis herstellt, indem wir diese Zeile hinzufügen:```ruby TagRedis = Redis.new(port: 22222)

Alle Aufrufe in der Testumgebung laufen jetzt über Toxiproxy. Das bedeutet, dass wir einen Unit-Test hinzufügen können, bei dem wir einen Fehler simulieren:```ruby
test "should return empty array when tag redis is down when listing tags" do
  @post.add_tag "mammals"

  # Take down all Redises in Toxiproxy
  Toxiproxy[/redis/].down do
    assert_equal [], @post.tags
  end
end

Der Test schlägt mit Redis::CannotConnectError fehl. Perfekt! Toxiproxy hat Redis für die Dauer des Closures erfolgreich heruntergefahren. Lassen Sie uns die tags-Methode robust machen:```ruby def tags TagRedis.smembers(tag_key) rescue Redis::CannotConnectError [] end

Die Tests bestehen! Wir haben jetzt einen Unit-Test, der beweist, dass das Abrufen der Tags, wenn Redis ausgefallen ist, ein leeres Array zurückgibt, anstatt eine Ausnahme zu werfen. Für eine vollständige Abdeckung solltest du auch einen Integrationstest schreiben, der das Abrufen der gesamten Blog-Post-Seite umschließt, wenn Redis ausgefallen ist.

Die vollständige Beispielanwendung befindet sich unter
[sirupsen/toxiproxy-rails-example](https://github.com/sirupsen/toxiproxy-rails-example).

## Verwendung

Die Konfiguration eines Projekts für Toxiproxy besteht aus drei Schritten:

1. Toxiproxy installieren
2. Toxiproxy befüllen
3. Toxiproxy verwenden

### 1. Toxiproxy installieren

**Linux**

Siehe [`Releases`](https://github.com/Shopify/toxiproxy/releases) für die neuesten Binärdateien und Systempakete für deine Architektur.

**Ubuntu**```bash
$ wget -O toxiproxy-2.1.4.deb https://github.com/Shopify/toxiproxy/releases/download/v2.1.4/toxiproxy_2.1.4_amd64.deb
$ sudo dpkg -i toxiproxy-2.1.4.deb
$ sudo service toxiproxy start

OS X

Mit Homebrew:```bash $ brew tap shopify/shopify $ brew install toxiproxy

Oder mit [MacPorts](https://www.macports.org/):```bash
$ port install toxiproxy

Windows

Toxiproxy für Windows ist unter https://github.com/Shopify/toxiproxy/releases/download/v2.1.4/toxiproxy-server-windows-amd64.exe zum Download verfügbar.

Docker

Toxiproxy ist in der GitHub-Container-Registry verfügbar. Ältere Versionen <= 2.1.4 sind im Docker Hub verfügbar.```bash $ docker pull ghcr.io/shopify/toxiproxy $ docker run --rm -it ghcr.io/shopify/toxiproxy

Wenn Toxiproxy vom Host statt von anderen Containern verwendet wird, aktivieren Sie das Host-Netzwerk mit `--net=host`.```shell
$ docker run --rm --entrypoint="/toxiproxy-cli" -it ghcr.io/shopify/toxiproxy list

Wenn Sie Go installiert haben, können Sie Toxiproxy aus dem Quellcode mithilfe der Makefile erstellen:```bash $ make build $ ./toxiproxy-server

#### Upgrade von Toxiproxy 1.x

In Toxiproxy 2.0 wurden mehrere Änderungen an der API vorgenommen, die sie mit Version 1.x inkompatibel machen.
Um Version 2.x des Toxiproxy-Servers verwenden zu können, müssen Sie sicherstellen, dass Ihre Client-Bibliothek
dieselbe Version unterstützt. Sie können überprüfen, welche Version von Toxiproxy Sie ausführen, indem
Sie den Endpunkt `/version` aufrufen.

Lesen Sie für spezifische Änderungen die Dokumentation zu Ihrer Client-Bibliothek. Detaillierte Änderungen
für den Toxiproxy-Server finden Sie in [CHANGELOG.md](https://github.com/shopify/toxiproxy/blob/HEAD/CHANGELOG.md).

### 2. Toxiproxy befüllen

Wenn Ihre Anwendung startet, muss sie sicherstellen, dass Toxiproxy weiß, welche
Endpunkte wohin weitergeleitet werden sollen. Die Hauptparameter sind: Name, Adresse, auf der Toxiproxy
**lauschen** soll, und die Adresse des Upstreams.

Einige Client-Bibliotheken bieten Hilfsfunktionen für diese Aufgabe, die im Wesentlichen nur
sicherstellen, dass jeder Proxy in einer Liste erstellt wird. Beispiel aus dem Ruby-Client:```ruby
# Make sure `shopify_test_redis_master` and `shopify_test_mysql_master` are
# present in Toxiproxy
Toxiproxy.populate([
  {
    name: "shopify_test_redis_master",
    listen: "127.0.0.1:22220",
    upstream: "127.0.0.1:6379"
  },
  {
    name: "shopify_test_mysql_master",
    listen: "127.0.0.1:24220",
    upstream: "127.0.0.1:3306"
  }
])

Dieser Code muss so früh wie möglich beim Booten ausgeführt werden, bevor irgendein Code eine Verbindung über Toxiproxy herstellt. Bitte schauen Sie in Ihrer Client-Bibliothek nach Dokumentation zu den Population-Helfern.

Alternativ verwenden Sie die CLI, um Proxys zu erstellen, z.B.:```bash toxiproxy-cli create -l localhost:26379 -u localhost:6379 shopify_test_redis_master

Wir empfehlen eine Benennung wie oben: `<app>_<env>_<data store>_<shard>`.
Dadurch wird sichergestellt, dass es keine Konflikte zwischen Anwendungen gibt, die dieselbe
Toxiproxy verwenden.

Für große Anwendungen empfehlen wir, die Toxiproxy-Konfigurationen in einer
separaten Konfigurationsdatei zu speichern. Wir verwenden `config/toxiproxy.json`. Diese Datei kann
dem Server mit der Option `-config` übergeben oder von der Anwendung geladen werden,
um sie mit der Funktion `populate` zu verwenden.

Ein Beispiel für `config/toxiproxy.json`:```json
[
  {
    "name": "web_dev_frontend_1",
    "listen": "[::]:https://raw.githubusercontent.com/shopify/toxiproxy/HEAD/18080%22,
    "upstream": "webapp.domain:8080",
    "enabled": true
  },
  {
    "name": "web_dev_mysql_1",
    "listen": "[::]:13306",
    "upstream": "database.domain:3306",
    "enabled": true
  }
]

Verwenden Sie Ports außerhalb des ephemeren Portbereichs, um zufällige Portkonflikte zu vermeiden. Er beträgt auf Linux standardmäßig 32,768 bis 61,000, siehe /proc/sys/net/ipv4/ip_local_port_range.

3. Verwenden von Toxiproxy

Um Toxiproxy zu verwenden, müssen Sie nun Ihre Anwendung so konfigurieren, dass sie sich über Toxiproxy verbindet. Um bei unserem Beispiel aus Schritt zwei zu bleiben, können wir unseren Redis Client so konfigurieren, dass er sich über Toxiproxy verbindet:```ruby

old straight to redis

redis = Redis.new(port: 6380)

new through toxiproxy

redis = Redis.new(port: 22220)

Jetzt kannst du es über die Toxiproxy-API manipulieren. In Ruby:```ruby
redis = Redis.new(port: 22220)

Toxiproxy[:shopify_test_redis_master].downstream(:latency, latency: 1000).apply do
  redis.get("test") # will take 1s
end

Oder über die CLI:```bash toxiproxy-cli toxic add -t latency -a latency=1000 shopify_test_redis_master

Bitte informieren Sie sich in der jeweiligen Client-Bibliothek über die Verwendung.

### 4. Logging

Es gibt die folgenden Log-Level: panic, fatal, error, warn oder warning, info, debug und trace.
Das Level kann über die Umgebungsvariable `LOG_LEVEL` aktualisiert werden.

### Toxics

Toxics manipulieren die Verbindung zwischen Client und Upstream. Sie können über die [HTTP-API](#http-api) zu Proxys hinzugefügt und aus ihnen entfernt werden. Jeder Toxic hat seine eigenen Parameter, die beeinflussen, wie er sich auf die Proxy-Verbindungen auswirkt.

Dokumentation zur Implementierung benutzerdefinierter Toxics finden Sie unter [CREATING_TOXICS.md](https://github.com/shopify/toxiproxy/blob/HEAD/CREATING_TOXICS.md).

#### latency

Fügt allen Daten, die durch den Proxy fließen, eine Verzögerung hinzu. Die Verzögerung entspricht `latency` +/- `jitter`.

Attribute:

 - `latency`: Zeit in Millisekunden
 - `jitter`: Zeit in Millisekunden

#### down

Das Herunterfahren eines Dienstes ist in der Implementierung von Toxiproxy technisch gesehen kein Toxic. Dies erfolgt durch Senden eines `POST` an `/proxies/{proxy}` und Setzen des Felds `enabled` auf `false`.

#### bandwidth

Begrenzt eine Verbindung auf eine maximale Anzahl von Kilobyte pro Sekunde.

Attribute:

 - `rate`: Rate in KB/s

#### slow_close

Verzögert das Schließen des TCP-Sockets, bis `delay` verstrichen ist.

Attribute:

 - `delay`: Zeit in Millisekunden

#### timeout

Stoppt den gesamten Datendurchsatz und schließt die Verbindung nach Ablauf von `timeout`. Wenn `timeout` den Wert 0 hat, wird die Verbindung nicht geschlossen und Daten werden verworfen, bis der Toxic entfernt wird.

Attribute:

 - `timeout`: Zeit in Millisekunden

#### reset_peer

Simuliert TCP RESET (Connection reset by peer) auf den Verbindungen, indem der Stub-Input sofort oder nach einem `timeout` geschlossen wird.

Attribute:

 - `timeout`: Zeit in Millisekunden

#### slicer

Zerteilt TCP-Daten in kleine Stücke und fügt optional eine Verzögerung zwischen jedem zerteiltem "Paket" hinzu.

Attribute:

 - `average_size`: Größe eines durchschnittlichen Pakets in Bytes
 - `size_variation`: Abweichung eines durchschnittlichen Pakets in Bytes (sollte kleiner als average_size sein)
 - `delay`: Zeit in Mikrosekunden, um jedes Paket zu verzögern

#### limit_data

Schließt die Verbindung, wenn die übertragenen Daten das Limit überschreiten.

 - `bytes`: Anzahl der Bytes, die übertragen werden sollen, bevor die Verbindung geschlossen wird

#### packet_loss

Verwirft zufällig Datenblöcke, die durch den Proxy fließen, und simuliert instabile WLAN-, Mobilfunk- oder Satelliten-Netzwerkbedingungen.

Attribute:
 - `loss_rate`: Wahrscheinlichkeit [0.0-1.0], dass ein Datenblock verworfen wird (Standard 0.0)
 - `correlation`: zusätzliche Verwerfungswahrscheinlichkeit, wenn der vorherige Datenblock verworfen wurde, modelliert Burst-Loss (Standard 0.0)

### HTTP API

Die gesamte Kommunikation zwischen Client und Toxiproxy-Daemon erfolgt über die HTTP-Schnittstelle, die hier beschrieben wird.

Toxiproxy lauscht auf HTTP auf Port **8474**.

#### Proxy-Felder:

 - `name`: Proxy-Name (String)
 - `listen`: Listen-Adresse (String)
 - `upstream`: Upstream-Adresse des Proxys (String)
 - `enabled`: true/false (Standardwert true bei Erstellung)

Um den Namen eines Proxys zu ändern, muss dieser gelöscht und neu erstellt werden.

Das Ändern der Felder `listen` oder `upstream` startet den Proxy neu und verwirft alle aktiven Verbindungen.

Wenn `listen` mit Port 0 angegeben wird, wählt toxiproxy einen ephemeren Port. Das Feld `listen` in der Antwort wird mit dem tatsächlichen Port aktualisiert.

Wenn Sie `enabled` auf `false` setzen, wird der Proxy heruntergefahren. Sie können es wieder auf `true` setzen, um ihn zu reaktivieren.

#### Toxic-Felder:

 - `name`: Toxic-Name (String, Standardwert `<type>_<stream>`)
 - `type`: Toxic-Typ (String)
 - `stream`: Zu beeinflussende Verbindungsrichtung (Standardwert `downstream`)
 - `toxicity`: Wahrscheinlichkeit, dass der Toxic auf eine Verbindung angewendet wird (Standardwert 1.0, 100 %)
 - `attributes`: eine Map von toxicspezifischen Attributen

Siehe [Toxics](#toxics) für toxicspezifische Attribute.

Die Richtung `stream` muss entweder `upstream` oder `downstream` sein. `upstream` wendet den Toxic auf die Verbindung `client -> server` an, während `downstream` den Toxic auf die Verbindung `server -> client` anwendet. Dies kann verwendet werden, um Anfragen und Antworten getrennt zu modifizieren.

#### Endpunkte

Alle Endpunkte verwenden JSON.

 - **GET /proxies** - Vorhandene Proxys und ihre Toxics auflisten
 - **POST /proxies** - Einen neuen Proxy erstellen
 - **POST /populate** - Eine Liste von Proxys erstellen oder ersetzen
 - **GET /proxies/{proxy}** - Den Proxy mit allen aktiven Toxics anzeigen
 - **POST /proxies/{proxy}** - Die Felder eines Proxys aktualisieren
 - **DELETE /proxies/{proxy}** - Einen vorhandenen Proxy löschen
 - **GET /proxies/{proxy}/toxics** - Aktive Toxics auflisten
 - **POST /proxies/{proxy}/toxics** - Einen neuen Toxic erstellen
 - **GET /proxies/{proxy}/toxics/{toxic}** - Die Felder eines aktiven Toxics abrufen
 - **POST /proxies/{proxy}/toxics/{toxic}** - Einen aktiven Toxic aktualisieren
 - **DELETE /proxies/{proxy}/toxics/{toxic}** - Einen aktiven Toxic entfernen
 - **POST /reset** - Alle Proxys aktivieren und alle aktiven Toxics entfernen
 - **GET /version** - Gibt die Serverversionsnummer zurück
 - **GET /metrics** - Gibt Prometheus-kompatible Metriken zurück

#### Massenhaftes Anlegen von Proxys

Proxys können mithilfe des `/populate`-Endpunkts massenhaft hinzugefügt und konfiguriert werden. Dies geschieht, indem ein JSON-Array von Proxys an toxiproxy übergeben wird. Wenn bereits ein Proxy mit demselben Namen vorhanden ist, wird er mit dem neuen Proxy verglichen und ersetzt, wenn die Adressen `upstream` und `listen` nicht übereinstimmen.

Ein `/populate`-Aufruf kann beispielsweise beim Start der Anwendung eingefügt werden, um sicherzustellen, dass alle benötigten Proxys vorhanden sind. Es ist sicher, diesen Aufruf mehrmals auszuführen, da Proxys unverändert bleiben, solange ihre Felder mit den neuen Daten übereinstimmen.

### CLI-Beispiel```bash
$ toxiproxy-cli create -l localhost:26379 -u localhost:6379 redis
Created new proxy redis
$ toxiproxy-cli list
Listen          Upstream        Name  Enabled Toxics
======================================================================
127.0.0.1:26379 localhost:6379  redis true    None

Hint: inspect toxics with `toxiproxy-client inspect <proxyName>`

Bitte fügen Sie den zu übersetzenden Markdown-Inhalt nach dem „INPUT:"-Marker ein.```bash $ redis-cli -p 26379 127.0.0.1:26379> SET omg pandas OK 127.0.0.1:26379> GET omg "pandas"

The input content appears to be missing — the message ends with "INPUT:" but contains no actual text to translate. Please provide the chunk content, and I will translate it into German following all the specified rules.```bash
$ toxiproxy-cli toxic add -t latency -a latency=1000 redis
Added downstream latency toxic 'latency_downstream' on proxy 'redis'

I don't see any content to translate. The input after "INPUT:" is empty. Please provide the chunk text so I can translate it.```bash $ redis-cli -p 26379 127.0.0.1:26379> GET omg "pandas" (1.00s) 127.0.0.1:26379> DEL omg (integer) 1 (1.00s)

Bitte fügen Sie den zu übersetzenden Markdown-Inhalt ein.```bash
$ toxiproxy-cli toxic remove -n latency_downstream redis
Removed toxic 'latency_downstream' on proxy 'redis'

Since the INPUT section contains no content to translate, there is nothing to output.```bash $ redis-cli -p 26379 127.0.0.1:26379> GET omg (nil)

Kein Eingabetext vorhanden – der Abschnitt „INPUT:" ist leer. Bitte den Quelltext für Chunk 51 erneut senden.```bash
$ toxiproxy-cli delete redis
Deleted proxy redis

(no content provided)```bash $ redis-cli -p 26379 Could not connect to Redis at 127.0.0.1:26379: Connection refused

### Metriken

Toxiproxy stellt über seine HTTP-API unter /metrics Prometheus-kompatible Metriken bereit.
Siehe [METRICS.md](https://github.com/shopify/toxiproxy/blob/HEAD/METRICS.md) für vollständige Beschreibungen

### Häufig gestellte Fragen

**Wie schnell ist Toxiproxy?** Die Geschwindigkeit von Toxiproxy hängt weitgehend von Ihrer Hardware ab,
aber Sie können eine Latenz von *< 100µs* erwarten, wenn keine Toxics aktiviert sind. Bei Ausführung
mit `GOMAXPROCS=4` auf einem Macbook Pro erreichten wir einen Durchsatz von *~1000MB/s*, und auf
einem leistungsstärkeren Desktop bis zu *2400MB/s*. Grundsätzlich können Sie erwarten, dass Toxiproxy
Daten mindestens so schnell bewegt wie die Anwendung, die Sie testen.

**Kann Toxiproxy randomisierte Tests durchführen?** Viele der verfügbaren Toxics können so konfiguriert
werden, dass sie Zufälligkeit aufweisen, wie zum Beispiel `jitter` beim `latency`-Toxic. Es gibt außerdem
einen globalen Parameter `toxicity`, der den Prozentsatz der Verbindungen angibt, den ein Toxic
beeinflusst. Dies ist besonders nützlich für Dinge wie den `timeout`-Toxic, der es X% der Verbindungen
ermöglichen würde, einen Timeout zu erleiden.

**Ich sehe nicht, dass sich meine Toxiproxy-Aktionen in MySQL widerspiegeln**. MySQL bevorzugt
für einige Clients den lokalen Unix-Domain-Socket, egal welchen Port Sie übergeben,
wenn der Host auf `localhost` gesetzt ist. Konfigurieren Sie Ihren MySQL-Server so, dass er keinen
Socket erstellt, und verwenden Sie `127.0.0.1` als Host. Denken Sie daran, den alten Socket zu entfernen,
nachdem Sie den Server neu gestartet haben.

**Toxiproxy verursacht intermittierende Verbindungsfehler**. Verwenden Sie Ports außerhalb des
Bereichs der kurzlebigen Ports, um zufällige Portkonflikte zu vermeiden. Auf Linux liegt der Bereich
standardmäßig bei `32,768` bis `61,000`, siehe `/proc/sys/net/ipv4/ip_local_port_range`.

**Sollte ich für jede Anwendung einen Toxiproxy ausführen?** Nein, wir empfehlen, für alle
Anwendungen denselben Toxiproxy zu verwenden. Zur Unterscheidung zwischen Diensten empfehlen
wir, Ihre Proxys nach dem Schema zu benennen: `<app>_<env>_<data store>_<shard>`.
Zum Beispiel `shopify_test_redis_master` oder `shopify_development_mysql_1`.

### Entwicklung

* `make`. Erstellen Sie ein Toxiproxy-Entwicklungsbinary für die aktuelle Plattform.
* `make all`. Erstellen Sie Toxiproxy-Binaries und -Pakete für alle Plattformen. Erfordert, dass Go
  mit aktivierter Kreuzkompilierung unter Linux und Darwin (amd64) kompiliert wurde, sowie
  [`goreleaser`](https://goreleaser.com/) in Ihrem `$PATH`, um die Binaries für das Linux-Paket zu bauen.
* `make test`. Führen Sie die Toxiproxy-Tests aus.

### Veröffentlichung

Siehe [RELEASE.md](https://github.com/shopify/toxiproxy/blob/HEAD/RELEASE.md)

[blog]: https://shopify.engineering/building-and-testing-resilient-ruby-on-rails-applications

toxiproxy

Beliebteste