Konfigurieren des X-Ray-SDK für Go

Sie können die Konfiguration für das X-Ray SDK for Go über Umgebungsvariablen angeben, indem Sie sie Configure mit einem Config Objekt aufrufen oder Standardwerte annehmen. Umgebungsvariablen haben Vorrang vor Config-Werten, die wiederum Vorrang vor Standardwerten haben.

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, importieren Sie eines der folgenden Pakete.

"github.com/aws/aws-xray-sdk-go/awsplugins/ec2"
"github.com/aws/aws-xray-sdk-go/awsplugins/ecs"
"github.com/aws/aws-xray-sdk-go/awsplugins/beanstalk"

Jedes Plugin hat einen expliziten Init()-Funktionsaufruf, der das Plugin lädt.

Beispiel ec2.Init()

import (
	"os"

	"github.com/aws/aws-xray-sdk-go/awsplugins/ec2"
	"github.com/aws/aws-xray-sdk-go/xray"
)

func init() {
  // conditionally load plugin
  if os.Getenv("ENVIRONMENT") == "production" {
    ec2.Init()
  }

  xray.Configure(xray.Config{
    ServiceVersion: "1.2.3",
  })
}

Das SDK verwendet auch Plugin-Einstellungen, um das origin Feld im 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 bereitzustellen, verweisen Sie mit NewCentralizedStrategyWithFilePath auf die lokale Sampling-JSON-Datei.

Beispiel main.go — Lokale Stichprobenregel

s, _ := sampling.NewCentralizedStrategyWithFilePath("sampling.json") // path to local sampling json
xray.Configure(xray.Config{SamplingStrategy: s})

Um nur lokale Regeln zu verwenden, verweisen Sie mit NewLocalizedStrategyFromFilePath auf die lokale Sampling-JSON-Datei.

Beispiel main.go — Sampling deaktivieren

s, _ := sampling.NewLocalizedStrategyFromFilePath("sampling.json") // path to local sampling json
xray.Configure(xray.Config{SamplingStrategy: s})

Protokollierung

Anmerkung

Die xray.Config{}-Felder LogLevel und LogFormat sind ab Version 1.0.0-rc.10 veraltet.

X-Ray verwendet die folgende Schnittstelle für die Protokollierung. Der Standardlogger schreibt in stdout bei LogLevelInfo und höher.

type Logger interface {
	Log(level LogLevel, msg fmt.Stringer)
}

const (
	LogLevelDebug LogLevel = iota + 1
	LogLevelInfo
	LogLevelWarn
	LogLevelError
)

Beispiel Schreibvorgänge in io.Writer

xray.SetLogger(xraylog.NewDefaultLogger(os.Stderr, xraylog.LogLevelError))

Umgebungsvariablen

Sie können Umgebungsvariablen verwenden, um das X-Ray SDK for Go zu konfigurieren. Das SDK unterstützt die folgenden Variablen.

• AWS_XRAY_CONTEXT_MISSING— Stellen Sie diese Option einRUNTIME_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.

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

• AWS_XRAY_DAEMON_ADDRESS— Legt den Host und den Port des X-Ray-Daemon-Listeners fest. Standardmäßig sendet das SDK Trace-Daten an. 127.0.0.1:2000 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.

Umgebungsvariablen überschreiben äquivalente Werte im Code.

Verwenden von „Configure“ (konfigurieren)

Sie können das X-Ray SDK for Go auch mit Configure dieser Methode konfigurieren. Configureakzeptiert ein Argument, ein Config Objekt, mit den folgenden optionalen Feldern.

DaemonAddr

Diese Zeichenfolge gibt den Host und den Port des X-Ray-Daemon-Listeners an. Falls nicht angegeben, verwendet X-Ray den Wert der AWS_XRAY_DAEMON_ADDRESS Umgebungsvariablen. Wenn dieser Wert nicht festgelegt ist, wird "127.0.0.1:2000" verwendet.

ServiceVersion

Diese Zeichenfolge legt die Service-Version fest. Falls nicht angegeben, verwendet X-Ray die leere Zeichenfolge („“).

SamplingStrategy

Das SamplingStrategy-Objekt legt fest, welche Ihrer Anwendungsaufrufe verfolgt werden. Falls nicht angegeben, verwendet X-Ray aLocalizedSamplingStrategy, was die Strategie wie unter definiert verwendetxray/resources/DefaultSamplingRules.json.

StreamingStrategy

Dieses StreamingStrategy Objekt gibt an, ob ein Segment gestreamt werden soll, wenn der RequiresStreamingWert true zurückgegeben wird. Falls nicht angegeben, verwendet X-Ray eine, DefaultStreamingStrategy die ein abgetastetes Segment streamt, wenn die Anzahl der Untersegmente größer als 20 ist.

ExceptionFormattingStrategy

Dieses ExceptionFormattingStrategy-Objekt legt fest, auf welche Weise verschiedene Ausnahmen gehandhabt werden sollen. Falls nicht angegeben, verwendet X-Ray a DefaultExceptionFormattingStrategy mit einem XrayError of-Typerror, die Fehlermeldung und Stack-Trace.