Configurazione di SDK X-Ray for Go

È possibile specificare la configurazione per X-Ray SDK for Go tramite variabili di ambiente, chiamando Configure con un Config oggetto o assumendo valori predefiniti. Le variabili di ambiente prevalgono sui valori di Config, che hanno la priorità su qualsiasi valore predefinito.

Plugin di servizio

pluginsUtilizzatelo per registrare informazioni sul servizio che ospita l'applicazione.

Plug-in

• AmazonEC2: EC2Plugin aggiunge l'ID dell'istanza, la zona di disponibilità e il gruppo di CloudWatch log.

• Elastic ElasticBeanstalkPlugin Beanstalk: aggiunge il nome dell'ambiente, l'etichetta della versione e l'ID di distribuzione.

• AmazonECS: ECSPlugin aggiunge l'ID del contenitore.

Per usare un plugin, importare uno dei seguenti pacchetti.

"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"

Ogni plugin ha una chiamata di funzione Init() esplicita che carica il plugin.

Esempio 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",
  })
}

Utilizza SDK anche le impostazioni del plug-in per impostare il origin campo sul segmento. Indica il tipo di AWS risorsa che esegue l'applicazione. Quando si utilizzano più plugin, SDK utilizza il seguente ordine di risoluzione per determinare l'origine: ElasticBeanstalk > > EKS ECS >EC2.

Regole di campionamento

SDKUtilizza le regole di campionamento definite nella console X-Ray per determinare quali richieste registrare. La regola predefinita tiene traccia della prima richiesta ogni secondo e del cinque percento di eventuali richieste aggiuntive su tutti i servizi che inviano tracce a X-Ray. Crea regole aggiuntive nella console X-Ray per personalizzare la quantità di dati registrati per ciascuna delle tue applicazioni.

SDKApplica le regole personalizzate nell'ordine in cui sono definite. Se una richiesta corrisponde a più regole personalizzate, si SDK applica solo la prima regola.

Nota

Se non SDK riesce a contattare X-Ray per ottenere le regole di campionamento, torna a una regola locale predefinita della prima richiesta ogni secondo e del cinque percento di eventuali richieste aggiuntive per host. Ciò può verificarsi se l'host non dispone dell'autorizzazione per il campionamento APIs delle chiamate o non riesce a connettersi al demone X-Ray, che funge da proxy API per le chiamate TCP effettuate da. SDK

È inoltre possibile configurare SDK per caricare le regole di campionamento da un documento. JSON SDKPossono utilizzare le regole locali come backup per i casi in cui il campionamento a raggi X non è disponibile o utilizzare esclusivamente regole locali.

Esempio 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
  }
}

Questo esempio definisce una regola personalizzata e una regola predefinita. La regola personalizzata applica una frequenza di campionamento del cinque percento senza alcun numero minimo di richieste da tracciare per i percorsi. /api/move/ La regola predefinita tiene traccia della prima richiesta ogni secondo e del 10% delle richieste aggiuntive.

Lo svantaggio della definizione locale delle regole è che l'obiettivo fisso viene applicato da ciascuna istanza del registratore in modo indipendente, anziché essere gestito dal servizio X-Ray. Man mano che si installano più host, la tariffa fissa si moltiplica, rendendo più difficile il controllo della quantità di dati registrati.

Sì AWS Lambda, non è possibile modificare la frequenza di campionamento. Se la funzione viene chiamata da un servizio strumentato, le chiamate che hanno generato richieste campionate da quel servizio verranno registrate da Lambda. Se il tracciamento attivo è abilitato e non è presente alcuna intestazione di tracciamento, Lambda prende la decisione di campionamento.

Per fornire regole di backup, punta al file di campionamento locale utilizzando. JSON NewCentralizedStrategyWithFilePath

Esempio main.go — Regola di campionamento locale

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

Per utilizzare solo le regole locali, puntate al file di campionamento JSON locale utilizzando. NewLocalizedStrategyFromFilePath

Esempio main.go — Disabilita il campionamento

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

Registrazione

Nota

I campi xray.Config{} LogLevel e LogFormat sono considerati obsoleti a partire dalla versione 1.0.0-rc.10.

X-Ray utilizza la seguente interfaccia per la registrazione. Il logger predefinito scrive su stdout a livello LogLevelInfo e superiori.

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

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

Esempio scrivere su io.Writer

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

Variabili di ambiente

È possibile utilizzare le variabili di ambiente per configurare X-Ray SDK for Go. SDKSupporta le seguenti variabili.

• AWS_XRAY_CONTEXT_MISSING— Imposta RUNTIME_ERROR per generare eccezioni quando il codice strumentato tenta di registrare dati quando nessun segmento è aperto.

  Valori validi

  • RUNTIME_ERROR— Genera un'eccezione di runtime.

  • LOG_ERROR— Registra un errore e continua (impostazione predefinita).

  • IGNORE_ERROR— Ignora l'errore e continua.

  Gli errori relativi a segmenti o sottosegmenti mancanti possono verificarsi quando si tenta di utilizzare un client con strumenti nel codice di avvio che viene eseguito quando non è aperta alcuna richiesta o nel codice che genera un nuovo thread.

• AWS_XRAY_TRACING_NAME— Imposta il nome del servizio che usano per i segmenti. SDK

• AWS_XRAY_DAEMON_ADDRESS— Imposta l'host e la porta del demone X-Ray. Per impostazione predefinita, SDK invia i dati di traccia a. 127.0.0.1:2000 Utilizzate questa variabile se avete configurato il demone per l'ascolto su una porta diversa o se è in esecuzione su un host diverso.

• AWS_XRAY_CONTEXT_MISSING— Imposta il valore per determinare in che modo SDK gestisce gli errori di contesto mancanti. Gli errori relativi ai segmenti o segmenti secondari mancanti possono verificarsi quando tenti di utilizzare un client di strumentazione nel codice di avvio quando nessuna richiesta è aperta oppure nel codice che genera un nuovo thread.

  • RUNTIME_ERROR— Per impostazione predefinita, SDK è impostato per generare un'eccezione di runtime.

  • LOG_ERROR— Impostato per registrare un errore e continuare.

Le variabili di ambiente sostituiscono i valori equivalenti impostati nel codice.

Utilizzo della configurazione

Puoi anche configurare X-Ray SDK for Go usando il Configure metodo. Configureaccetta un argomento, un Config oggetto, con i seguenti campi opzionali.

DaemonAddr

Questa stringa specifica l'host e la porta del listener del demone X-Ray. Se non viene specificato, X-Ray utilizza il valore della variabile di AWS_XRAY_DAEMON_ADDRESS ambiente. Se il valore non è impostato, utilizza "127.0.0.1:2000".

ServiceVersion

Questa stringa specificata la versione del servizio. Se non specificato, X-Ray utilizza la stringa vuota («»).

SamplingStrategy

Questo oggetto SamplingStrategy specifica quali delle chiamate della tua applicazione sono tracciate. Se non specificato, X-Ray utilizza aLocalizedSamplingStrategy, che utilizza la strategia definita in. xray/resources/DefaultSamplingRules.json

StreamingStrategy

Questo StreamingStrategy oggetto specifica se eseguire lo streaming di un segmento quando RequiresStreamingrestituisce true. Se non specificato, X-Ray utilizza un segnale DefaultStreamingStrategy che trasmette un segmento campionato se il numero di sottosegmenti è maggiore di 20.

ExceptionFormattingStrategy

Questo oggetto ExceptionFormattingStrategy specifica il modo in cui desideri gestire varie eccezioni. Se non specificato, X-Ray utilizza un tipo DefaultExceptionFormattingStrategy con un XrayError oferror, il messaggio di errore e la traccia dello stack.