Konfiguration des X-Ray-SDK für Python

Das X-Ray-SDK für Python hat eine Klasse namensxray_recorder, die den globalen Rekorder bereitstellt. Sie können die globale Aufzeichnung so konfigurieren, dass die Middleware, die Segmente für eingehende HTTP-Aufrufe erstellt, angepasst wird.

Service-Plugins

Wird verwendetplugins, um Informationen über den Dienst aufzuzeichnen, der Ihre Anwendung hostet.

Plug-ins

• Amazon EC2 — EC2Plugin fügt die Instance-ID, die Availability Zone und die CloudWatch Logs-Gruppe hinzu.

• Elastic Beanstalk — ElasticBeanstalkPlugin fügt den Umgebungsnamen, die Versionsbezeichnung und die Bereitstellungs-ID hinzu.

• Amazon ECS — ECSPlugin fügt die Container-ID hinzu.

Um ein Plugin zu verwenden, rufen Sie configure im xray_recorder auf.

from aws_xray_sdk.core import xray_recorder
from aws_xray_sdk.core import patch_all

xray_recorder.configure(service='My app')
plugins = ('ElasticBeanstalkPlugin', 'EC2Plugin')
xray_recorder.configure(plugins=plugins)
patch_all()

Anmerkung

Da plugins sie als Tupel übergeben werden, sollten Sie bei der Angabe eines einzelnen Plugins unbedingt ein abschließendes Zeichen , angeben. Beispiel: plugins = ('EC2Plugin',)

Sie können auch Umgebungsvariablen, die Vorrang über Werte im Code haben, zur Konfiguration des Recorders verwenden.

Konfigurieren Sie Plugins vor Patch-Bibliotheken, um nachgeschaltete Aufrufe aufzuzeichnen.

Das SDK verwendet auch Plugin-Einstellungen, um das origin Feld für das Segment festzulegen. Dies gibt den AWS Ressourcentyp an, auf dem Ihre Anwendung ausgeführt wird. Wenn Sie mehrere Plugins verwenden, verwendet das SDK die folgende Auflösungsreihenfolge, um den Ursprung zu bestimmen: ElasticBeanstalk > EKS > ECS > EC2.

Samplingregeln

Das SDK verwendet die Sampling-Regeln, die Sie in der X-Ray-Konsole definieren, um zu bestimmen, welche Anfragen aufgezeichnet werden sollen. Die Standardregel verfolgt die erste Anfrage jede Sekunde und fünf Prozent aller weiteren Anfragen aller Dienste, die Traces an X-Ray senden. Erstellen Sie zusätzliche Regeln in der X-Ray-Konsole, um die Menge der aufgezeichneten Daten für jede Ihrer Anwendungen anzupassen.

Das SDK wendet benutzerdefinierte Regeln in der Reihenfolge an, in der sie definiert sind. Wenn eine Anfrage mehreren benutzerdefinierten Regeln entspricht, wendet das SDK nur die erste Regel an.

Anmerkung

Wenn das SDK X-Ray nicht erreichen kann, um Sampling-Regeln abzurufen, kehrt es zu einer lokalen Standardregel zurück, die die erste zu Beginn jeder Sekunde empfangene Anfrage und fünf Prozent aller zusätzlichen Anfragen pro Host festlegt. Dies kann passieren, wenn der Host nicht berechtigt ist, Sampling-APIs aufzurufen, oder wenn er keine Verbindung zum X-Ray-Daemon herstellen kann, der als TCP-Proxy für API-Aufrufe durch das SDK fungiert.

Sie können das SDK auch so konfigurieren, dass Sampling-Regeln aus einem JSON-Dokument geladen werden. Das SDK kann lokale Regeln als Backup für Fälle verwenden, in denen X-Ray Sampling nicht verfügbar ist, oder ausschließlich lokale Regeln verwenden.

Beispiel sampling-rules.json

{
  "version": 2,
  "rules": [
    {
      "description": "Player moves.",
      "host": "*",
      "http_method": "*",
      "url_path": "/api/move/*",
      "fixed_target": 0,
      "rate": 0.05
    }
  ],
  "default": {
    "fixed_target": 1,
    "rate": 0.1
  }
}

In diesem Beispiel werden eine benutzerdefinierte Regel und eine Standardregel definiert. Die benutzerdefinierte Regel wendet eine Stichprobenrate von fünf Prozent an, ohne dass eine Mindestanzahl von Anfragen für Pfade verfolgt werden muss, unter /api/move/ denen Pfade verfolgt werden müssen. Die Standardregel verfolgt die erste Anfrage jede Sekunde und 10 Prozent der weiteren Anfragen.

Der Nachteil der lokalen Definition von Regeln besteht darin, dass das feste Ziel von jeder Instanz des Rekorders unabhängig angewendet wird, anstatt vom X-Ray-Dienst verwaltet zu werden. Wenn Sie mehr Hosts bereitstellen, wird die feste Rate vervielfacht, wodurch es schwieriger wird, die Menge der aufgezeichneten Daten zu kontrollieren.

Wenn aktiviert AWS Lambda, können Sie die Samplerate nicht ändern. Wenn Ihre Funktion von einem instrumentierten Dienst aufgerufen wird, werden Aufrufe, die Anfragen generierten, die von diesem Dienst abgetastet wurden, von Lambda aufgezeichnet. Wenn aktives Tracing aktiviert ist und kein Tracing-Header vorhanden ist, trifft Lambda die Stichprobenentscheidung.

Um Sicherungsregeln zu konfigurieren, rufen Sie xray_recorder.configure auf, wie im folgenden Beispiel dargestellt, wobei der Begriff Regeln entweder ein Wörterbuch mit Regeln oder den absoluten Pfad zu einer JSON-Datei mit Samplingregeln bezeichnet.

xray_recorder.configure(sampling_rules=rules)

Um nur lokale Regeln zu verwenden, konfigurieren Sie den Recorder mit einer LocalSampler.

from aws_xray_sdk.core.sampling.local.sampler import LocalSampler
xray_recorder.configure(sampler=LocalSampler())

Sie können auch die globale Aufzeichnung so konfigurieren, dass das Sampling deaktiviert und alle eingehenden Anfragen instrumentiert werden.

Beispiel main.py — Sampling deaktivieren

xray_recorder.configure(sampling=False)

Protokollierung

Das SDK verwendet das in Python integrierte logging Modul mit einer WARNING Standard-Protokollierungsebene. Erhalten Sie eine Referenz zum Logger für die aws_xray_sdk-Klasse und rufen Sie darauf setLevel auf, um die verschiedenen Protokollebenen für die Bibliothek und den Rest Ihrer Anwendung zu konfigurieren.

Beispiel app.py — Protokollierung

logging.basicConfig(level='WARNING')
logging.getLogger('aws_xray_sdk').setLevel(logging.ERROR)

Verwenden Sie Debug-Protokolle, um Probleme wie nicht geschlossene Untersegmente zu identifizieren, wenn Sie Untersegmente manuell generieren.

Konfiguration des Recorders im Code

Zusätzliche Einstellungen finden Sie in der configure-Methode auf xray_recorder.

• context_missing— Auf einstellen, um LOG_ERROR zu verhindern, dass Ausnahmen ausgelöst werden, wenn Ihr instrumentierter Code versucht, Daten aufzuzeichnen, obwohl kein Segment geöffnet ist.

• daemon_address— Legt den Host und den Port des X-Ray-Daemon-Listeners fest.

• service— Legen Sie einen Dienstnamen fest, den das SDK für Segmente verwendet.

• plugins— Notieren Sie Informationen über die AWS Ressourcen Ihrer Anwendung.

• sampling— Auf einstellen, False um die Probenahme zu deaktivieren.

• sampling_rules— Legen Sie den Pfad der JSON-Datei fest, die Ihre Sampling-Regeln enthält.

Beispiel main.py — Deaktiviert Ausnahmen, die im Kontext fehlen

from aws_xray_sdk.core import xray_recorder

xray_recorder.configure(context_missing='LOG_ERROR')

Konfigurieren des Recorders mit Django

Wenn Sie das Django-Framework verwenden, können Sie die settings.py-Datei von Django zum Konfigurieren von Optionen in der globalen Aufzeichnung verwenden.

• AUTO_INSTRUMENT(Nur Django) — Zeichnet Untersegmente für integrierte Datenbank- und Vorlagen-Rendering-Operationen auf.

• AWS_XRAY_CONTEXT_MISSING— Auf einstellen, um LOG_ERROR zu vermeiden, dass Ausnahmen ausgelöst werden, wenn Ihr instrumentierter Code versucht, Daten aufzuzeichnen, wenn kein Segment geöffnet ist.

• AWS_XRAY_DAEMON_ADDRESS— Legt den Host und den Port des X-Ray-Daemon-Listeners fest.

• AWS_XRAY_TRACING_NAME— Legen Sie einen Dienstnamen fest, den das SDK für Segmente verwendet.

• PLUGINS— Notieren Sie Informationen über die AWS Ressourcen Ihrer Anwendung.

• SAMPLING— Auf einstellen, False um die Probenahme zu deaktivieren.

• SAMPLING_RULES— Legen Sie den Pfad der JSON-Datei fest, die Ihre Sampling-Regeln enthält.

Um die Konfiguration des Recorders in settings.py zu aktivieren, fügen Sie die Django-Middleware zur Liste der installierten Apps hinzu.

Beispiel settings.py — Installierte Apps

INSTALLED_APPS = [
    ...
    'django.contrib.sessions',
    'aws_xray_sdk.ext.django',
]

Konfigurieren Sie die verfügbaren Einstellungen in einem dict-Objekt mit dem Namen XRAY_RECORDER.

Beispiel settings.py — Installierte Apps

XRAY_RECORDER = {
    'AUTO_INSTRUMENT': True,
    'AWS_XRAY_CONTEXT_MISSING': 'LOG_ERROR',
    'AWS_XRAY_DAEMON_ADDRESS': '127.0.0.1:5000',
    'AWS_XRAY_TRACING_NAME': 'My application',
    'PLUGINS': ('ElasticBeanstalkPlugin', 'EC2Plugin', 'ECSPlugin'),
    'SAMPLING': False,
}

Umgebungsvariablen

Sie können Umgebungsvariablen verwenden, um das X-Ray SDK für Python zu konfigurieren. Das SDK unterstützt die folgenden Variablen:

• AWS_XRAY_TRACING_NAME— Legen Sie einen Dienstnamen fest, den das SDK für Segmente verwendet. Überschreibt den Servicenamen, den Sie programmgesteuert festgelegt haben.

• AWS_XRAY_SDK_ENABLED— Wenn auf gesetztfalse, wird das SDK deaktiviert. Das SDK ist standardmäßig aktiviert, es sei denn, die Umgebungsvariable ist auf „false“ festgelegt.

  • Wenn diese Option deaktiviert ist, generiert die globale Aufzeichnung automatisch Dummy-Segmente und Untersegmente, die nicht an den Daemon gesendet werden, und das automatische Patchen wird deaktiviert. Middlewares werden als Wrapper über der globalen Aufzeichnung geschrieben. Auch alle Generierungen von Segmenten und Untersegmenten über die Middleware werden zu Dummy-Segmenten und Dummy-Untersegmenten.

  • Legen Sie den Wert AWS_XRAY_SDK_ENABLED über die Umgebungsvariable oder durch direkte Interaktion mit dem Objekt global_sdk_config aus der aws_xray_sdk-Bibliothek fest. Einstellungen der Umgebungsvariablen überschreiben diese Interaktionen.

• AWS_XRAY_DAEMON_ADDRESS— Legt den Host und den Port des X-Ray-Daemon-Listeners fest. Standardmäßig verwendet 127.0.0.1:2000 das SDK sowohl Trace-Daten (UDP) als auch Sampling-Daten (TCP). Verwenden Sie diese Variable, wenn Sie den Daemon so konfiguriert haben, dass er auf einem anderen Port lauscht oder wenn er auf einem anderen Host läuft.

  Format

  • Derselbe Port — address:port

  • Verschiedene Anschlüsse — tcp:address:port udp:address:port

• AWS_XRAY_CONTEXT_MISSING— Auf einstellen, RUNTIME_ERROR um Ausnahmen auszulösen, wenn Ihr instrumentierter Code versucht, Daten aufzuzeichnen, obwohl kein Segment geöffnet ist.

  Zulässige Werte

  • RUNTIME_ERROR— Löst eine Laufzeitausnahme aus.

  • LOG_ERROR— Einen Fehler protokollieren und fortfahren (Standard).

  • IGNORE_ERROR— Fehler ignorieren und fortfahren.

  Fehler im Zusammenhang mit fehlenden Segmenten oder Untersegmenten können auftreten, wenn Sie versuchen, einen instrumentierten Client in Startcode zu verwenden, der ausgeführt wird, wenn keine Anfrage geöffnet ist, oder in Code, der einen neuen Thread erzeugt.

Umgebungsvariablen überschreiben Werte im Code.