Konfiguration des X-Ray SDK für Node.js

Sie können das X-Ray SDK für Node.js mit Plug-ins so konfigurieren, dass es Informationen über den Dienst enthält, auf dem Ihre Anwendung ausgeführt wird, das standardmäßige Sampling-Verhalten ändern oder Sampling-Regeln hinzufügen, die für Anfragen an bestimmte Pfade gelten.

Service-Plugins

Dientplugins zum Aufzeichnen von Informationen über den Dienst, der Ihre Anwendung hostet.

Verwenden Sie zur Verwendung eines Plugins den X-Ray SDK für Node.js Client mithilfe derconfig Methode.

var AWSXRay = require('aws-xray-sdk');
AWSXRay.config([AWSXRay.plugins.EC2Plugin,AWSXRay.plugins.ElasticBeanstalkPlugin]);

Das SDK verwendet auch Plugin-Einstellungen, um dasorigin Feld im Segment festzulegen. Dies gibt den Typ derAWS Ressource an, auf der 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 für jede Ihrer Anwendungen aufgezeichnete Datenmenge 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.

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 keine X-Ray-Sampling verfügbar ist, oder ausschließlich lokale Regeln verwenden.

{
  "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 Sampling-Rate von fünf Prozent an, ohne dass eine Mindestanzahl von Trace-Requests für Pfade unter diesem Wert erforderlich ist/api/move/. Die Standardregel verfolgt die erste Anforderung pro Sekunde und 10 Prozent aller weiteren Anforderungen.

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

Wenn diese Option aktiviert istAWS Lambda, können Sie die Sampling-Rate nicht ändern. Wenn Ihre Funktion von einem instrumentierten Dienst aufgerufen wird, werden Aufrufe, die Anfragen generiert haben, die von diesem Dienst abgetastet wurden, von Lambda aufgezeichnet. Wenn aktives Tracing aktiviert ist und kein Tracing-Header vorhanden ist, trifft Lambda die Sampling-Entscheidung.

Weisen Sie das X-Ray SDK für Node.js an, Samplingregeln aus einer Datei zu laden, um Backup-Regeln zu konfigurierensetSamplingRules.

var AWSXRay = require('aws-xray-sdk');
AWSXRay.middleware.setSamplingRules('sampling-rules.json');

Sie können Ihre Regeln auch in Code definieren und als Objekt an setSamplingRules übergeben.

var AWSXRay = require('aws-xray-sdk');
var rules = {
  "rules": [ { "description": "Player moves.", "service_name": "*", "http_method": "*", "url_path": "/api/move/*", "fixed_target": 0, "rate": 0.05 } ],
  "default": { "fixed_target": 1, "rate": 0.1 },
  "version": 1
  }

AWSXRay.middleware.setSamplingRules(rules);

Um nur lokale Regeln zu verwenden, rufen Sie disableCentralizedSampling auf.

AWSXRay.middleware.disableCentralizedSampling()

Protokollierung

Zum Protokollieren der SDK-Ausgabe rufen Sie AWSXRay.setLogger(logger) auf, wobei logger ein Objekt ist, dass Standard-Protokollierungsmethoden (warn, infousw.) bereitstellt.

Standardmäßig protokolliert das SDK Fehlermeldungen mit den Standardmethoden für das Konsolenobjekt an der Konsole. Die Protokollebene des integrierten Loggers kann entweder mithilfe derAWS_XRAY_LOG_LEVEL UmgebungsvariablenAWS_XRAY_DEBUG_MODE oder eingestellt werden. Eine Liste der Werte finden Sie unter Umgebungsvariablen.

Wenn Sie ein anderes Format oder Ziel für die Protokolle angeben möchten, können Sie dem SDK Ihre eigene Implementierung der Logger-Schnittstelle zur Verfügung stellen, wie unten gezeigt. Jedes Objekt, das diese Schnittstelle implementiert, kann verwendet werden. Das bedeutet, dass viele Logging-Bibliotheken, z. B. Winston, verwendet und direkt an das SDK übergeben werden könnten.

var AWSXRay = require('aws-xray-sdk');

// Create your own logger, or instantiate one using a library.
var logger = {
  error: (message, meta) => { /* logging code */ },
  warn: (message, meta) => { /* logging code */ },
  info: (message, meta) => { /* logging code */ },
  debug: (message, meta) => { /* logging code */ }
}

AWSXRay.setLogger(logger);
AWSXRay.config([AWSXRay.plugins.EC2Plugin]);

Rufen Sie vor der Ausführung anderer Konfigurationsmethoden setLogger auf, um sicherzustellen, dass Sie die Ausgabe dieser Vorgänge erfassen.

X-Ray-Daemon Adresse

Wenn der X-Ray-Daemon auf einem anderen Port oder Host als lauscht127.0.0.1:2000, können Sie das X-Ray SDK für Node.js so konfigurieren, dass es Trace-Daten an eine andere Adresse sendet.

AWSXRay.setDaemonAddress('host:port');

Sie können den Host mit Namen oder IPv4-Adresse angeben.

var AWSXRay = require('aws-xray-sdk');
AWSXRay.setDaemonAddress('daemonhost:8082');

Wenn Sie den Daemon so konfiguriert haben, dass er auf verschiedenen Ports für TCP und UDP wartet, können Sie beides in den Einstellungen für die Daemon-Adresse angeben.

var AWSXRay = require('aws-xray-sdk');
AWSXRay.setDaemonAddress('tcp:daemonhost:8082 udp:daemonhost:8083');

Sie können die Daemon-Adresse auch festlegen, indem Sie die AWS_XRAY_DAEMON_ADDRESS Umgebungsvariable verwenden.

Umgebungsvariablen

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