Configurazione dell'X-Ray SDK per Ruby

L'X-Ray SDK for Ruby ha una classe XRay.recorder denominata che fornisce il registratore globale. Puoi configurare il registratore globale per personalizzare il middleware che crea i segmenti relativi alle chiamate HTTP in entrata.

Plugin di servizio

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

Plug-in

• Amazon EC2: ec2 aggiunge l'ID dell'istanza e la zona di disponibilità.

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

• Amazon ECS: ecs aggiunge l'ID del contenitore.

Per utilizzare i plugin, specificalo nell'oggetto di configurazione che passi al registratore.

Esempio main.rb — Configurazione del plugin

my_plugins = %I[ec2 elastic_beanstalk]

config = {
  plugins: my_plugins,
  name: 'my app',
}

XRay.recorder.configure(config)

Per configurare il registratore puoi anche utilizzare le variabili di ambiente, che hanno la precedenza sui valori impostati nel codice.

L'SDK utilizza anche le impostazioni del plug-in per impostare il origin campo sul segmento. Indica il tipo di AWS risorsa che esegue l'applicazione. Quando utilizzi 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 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.

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.

Nota

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

Puoi anche configurare l'SDK per caricare le regole di campionamento da un documento JSON. L'SDK può 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.

Per configurare le regole di backup, definire un hash per il documento dell'oggetto di configurazione che si passa al registratore.

Esempio main.rb — Configurazione delle regole di Backup

require 'aws-xray-sdk'
my_sampling_rules =  {
  version: 1,
  default: {
    fixed_target: 1,
    rate: 0.1
  }
}
config = {
  sampling_rules: my_sampling_rules,
  name: 'my app',
}
XRay.recorder.configure(config)

Per archiviare le regole di campionamento in modo indipendente, definire l'hash in un file separato e richiedere i file per inserirli all'interno della propria applicazione.

Esempio config/sampling-rules.rb

my_sampling_rules =  {
  version: 1,
  default: {
    fixed_target: 1,
    rate: 0.1
  }
}

Esempio main.rb — Regola di campionamento da un file

require 'aws-xray-sdk'
require 'config/sampling-rules.rb'

config = {
  sampling_rules: my_sampling_rules,
  name: 'my app',
}
XRay.recorder.configure(config)

Per utilizzare solo regole locali, richiedere le regole di campionamento e configurare il LocalSampler.

Esempio main.rb — Campionamento di regole locali

require 'aws-xray-sdk'
require 'aws-xray-sdk/sampling/local/sampler'

config = {
  sampler: LocalSampler.new,
  name: 'my app',
}
XRay.recorder.configure(config)

Puoi anche configurare il registratore globale per disabilitare il campionamento e analizzare tutte le richieste in entrata.

Esempio main.rb — Disabilita il campionamento

require 'aws-xray-sdk'
config = {
  sampling: false,
  name: 'my app',
}
XRay.recorder.configure(config)

Registrazione

Per impostazione predefinita, il registratore genera gli eventi a livello di informazioni su $stdout. Puoi personalizzare la generazione dei log definendo un logger nell'oggetto di configurazione da passare al registratore.

Esempio main.rb — Registrazione

require 'aws-xray-sdk'
config = {
  logger: my_logger,
  name: 'my app',
}
XRay.recorder.configure(config)

Utilizza i log di debug per identificare i problemi, come ad esempio dei sottosegmenti non chiusi, quando generi dei sottosegmenti manualmente.

Configurazione del registratore nel codice

Impostazioni aggiuntive sono disponibili tramite il metodo configure su XRay.recorder.

• context_missing— Imposta per LOG_ERROR evitare di generare eccezioni quando il codice strumentato tenta di registrare dati quando nessun segmento è aperto.

• daemon_address— Imposta l'host e la porta del demone X-Ray.

• name— Imposta un nome di servizio che l'SDK utilizza per i segmenti.

• naming_pattern— Imposta un modello di nome di dominio per utilizzare la denominazione dinamica.

• plugins— Registra informazioni sulle AWS risorse dell'applicazione con i plugin.

• sampling— Impostare per false disabilitare il campionamento.

• sampling_rules— Imposta l'hash contenente le regole di campionamento.

Esempio main.rb — Disabilita le eccezioni mancanti nel contesto

require 'aws-xray-sdk'
config = {
  context_missing: 'LOG_ERROR'
}

XRay.recorder.configure(config)

Configurazione del registratore con Rails

Se utilizzi il framework Rails, puoi configurare le opzioni sul registratore globale in un file Ruby sotto app_root/initializers. L'X-Ray SDK supporta una chiave di configurazione aggiuntiva da utilizzare con Rails.

• active_record— Impostato su per registrare i sottosegmenti true per le transazioni del database Active Record.

Configura le impostazioni disponibili in un oggetto di configurazione denominato Rails.application.config.xray.

Esempio config/initializers/aws_xray.rb

Rails.application.config.xray = {
  name: 'my app',
  patch: %I[net_http aws_sdk],
  active_record: true
}

Variabili di ambiente

È possibile utilizzare le variabili di ambiente per configurare l'X-Ray SDK for Ruby. L'SDK supporta le seguenti variabili:

• AWS_XRAY_TRACING_NAME— Imposta un nome di servizio che l'SDK utilizza per i segmenti. Sostituisce il nome del servizio impostato sulla strategia di denominazione dei segmenti del filtro servlet.

• AWS_XRAY_DAEMON_ADDRESS— Imposta l'host e la porta del demone X-Ray. Per impostazione predefinita, l'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 per RUNTIME_ERROR 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.

Le variabili di ambiente sostituiscono i valori impostati nel codice.