Configurazione dell'SDK X-Ray per Node.js

È possibile configurare l'SDK X-Ray per Node.js con plugin per includere informazioni sul servizio su cui viene eseguita l'applicazione, modificare il comportamento di campionamento predefinito o aggiungere regole di campionamento applicabili alle richieste a percorsi specifici.

Plugin di servizio

pluginsDa utilizzare per registrare informazioni sul servizio che ospita l'applicazione.

Per utilizzare un plug-in, configurare il client l'SDK X-Ray per Node.js utilizzando ilconfig metodo.

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

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

Regole di campionamento

L'SDK utilizza 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 tutte le 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.

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

Puoi anche configurare l'SDK per caricare le regole di campionamento da un documento JSON. L'SDK può utilizzare regole locali come backup nei casi in cui il campionamento a X-Ray non è disponibile o utilizzare esclusivamente regole locali.

{
  "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 un numero minimo di richieste da tracciare per i percorsi/api/move/. La regola predefinito tiene traccia della prima richiesta ogni secondo e del 10 percento delle altre richieste.

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 velocità 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 un'intestazione di tracciamento, Lambda prende la decisione di campionamento.

Per configurare le regole di backup, indicare all'SDK X-Ray per Node.js di caricare le regole di campionamento da un file consetSamplingRules.

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

Puoi anche definire le regole nel codice e passarle a setSamplingRules come oggetto.

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);

Per utilizzare solo le regole locali, chiama disableCentralizedSampling.

AWSXRay.middleware.disableCentralizedSampling()

Registrazione

Per generare i log sull'output dell'SDK, chiama AWSXRay.setLogger(logger), dove logger è un oggetto che fornisce i metodi di log standard (warn, info, ecc.).

Per impostazione predefinita, l'SDK registrerà i messaggi di errore nella console utilizzando i metodi standard sull'oggetto console. Il livello di registro del logger integrato può essere impostato utilizzando le variabili diAWS_XRAY_LOG_LEVEL ambienteAWS_XRAY_DEBUG_MODE o le variabili di ambiente. Per un elenco di valori validi a livello di registro, vedere Variabili di ambiente.

Se desideri fornire un formato o una destinazione diversi per i registri, puoi fornire all'SDK la tua implementazione dell'interfaccia logger come mostrato di seguito. È possibile utilizzare qualsiasi oggetto che implementa questa interfaccia. Ciò significa che molte librerie di registrazione, ad esempio Winston, possono essere utilizzate e passate direttamente all'SDK.

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]);

Chiama setLogger prima di eseguire altri metodi di configurazione per assicurarti che l'acquisizione dell'output di tali operazioni funzioni.

Indirizzo Daemon X-Ray

Se il demone X-Ray è in ascolto su una porta o un host diverso da127.0.0.1:2000, è possibile configurare l'SDK X-Ray per Node.js per inviare i dati di traccia a un indirizzo diverso.

AWSXRay.setDaemonAddress('host:port');

Puoi specificare l'host in base al nome o all'indirizzo IPv4.

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

Se hai configurato il daemon per ascoltare su diverse porte per TCP e UDP, puoi specificare entrambe nelle impostazioni dell'indirizzo del daemon.

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

È inoltre possibile impostare l'indirizzo del demone utilizzando la variabile diAWS_XRAY_DAEMON_ADDRESS ambiente.

Variabili di ambiente

È possibile utilizzare variabili di ambiente per configurare l'SDK X-Ray per Node.js. L'SDK supporta le seguenti variabili.