Configurazione dell'X-Ray SDK per.NET

È possibile configurare X-Ray SDK for .NET con plug-in per includere informazioni sul servizio su cui viene eseguita l'applicazione, modificare il comportamento di campionamento predefinito o aggiungere regole di campionamento che si applicano alle richieste a percorsi specifici.

Per le applicazioni web .NET, aggiungi le chiavi alla sezione appSettings del file Web.config.

Esempio Web.config

<configuration>
  <appSettings>
    <add key="AWSXRayPlugins" value="EC2Plugin"/>
    <add key="SamplingRuleManifest" value="sampling-rules.json"/>
  </appSettings>
</configuration>

Per .NET Core, crea un file denominato appsettings.json con una chiave di primo livello denominata XRay.

Esempio .NET appsettings.json

{
  "XRay": {
    "AWSXRayPlugins": "EC2Plugin",
    "SamplingRuleManifest": "sampling-rules.json"
  }
}

Quindi, nel codice dell'applicazione, create un oggetto di configurazione e utilizzatelo per inizializzare il registratore X-Ray. Esegui questa operazione prima di inizializzare il registratore.

Esempio .NET Core Program.cs — Configurazione del registratore

using Amazon.XRay.Recorder.Core;
...
AWSXRayRecorder.InitializeInstance(configuration);

Se stai analizzando un'applicazione web .NET Core, puoi anche inoltrare l'oggetto di configurazione al metodo UseXRay quando configuri il gestore dei messaggi. Per le funzioni Lambda, usa il InitializeInstance metodo illustrato sopra.

Per ulteriori informazioni sull'API di configurazione.NET Core, consulta Configurare un'app ASP.NET Core su docs.microsoft.com.

Plug-in

Utilizza i plug-in per aggiungere i dati sul servizio che ospita l'applicazione.

Plug-in

• Amazon EC2: 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.

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

Per utilizzare un plug-in, configura il client X-Ray SDK for .NET aggiungendo l'impostazione. AWSXRayPlugins Se si applicano più plugin all'applicazione, specificarli tutti nella stessa impostazione, separati da virgole.

Esempio Web.config - Plugin

<configuration>
  <appSettings>
    <add key="AWSXRayPlugins" value="EC2Plugin,ElasticBeanstalkPlugin"/>
  </appSettings>
</configuration>

Esempio .NET Core appsettings.json — Plugin

{
  "XRay": {
    "AWSXRayPlugins": "EC2Plugin,ElasticBeanstalkPlugin"
  }
}

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.

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 configurare le regole di backup, chiedi a X-Ray SDK for .NET di caricare le regole di campionamento da un file con l'impostazione. SamplingRuleManifest

Esempio .NET Web.config - regole di campionamento

<configuration>
  <appSettings>
    <add key="SamplingRuleManifest" value="sampling-rules.json"/>
  </appSettings>
</configuration>

Esempio .NET Core appsettings.json — Regole di campionamento

{
  "XRay": {
    "SamplingRuleManifest": "sampling-rules.json"
  }
}

Per utilizzare solo regole locali, crea un registratore con una LocalizedSamplingStrategy. Se si dispone di regole di backup configurate, rimuovere tale configurazione.

Esempio .NET global.asax: regole di campionamento locali

var recorder = new AWSXRayRecorderBuilder().WithSamplingStrategy(new LocalizedSamplingStrategy("samplingrules.json")).Build();
AWSXRayRecorder.InitializeInstance(recorder: recorder);

Esempio .NET Core Program.cs: regole di campionamento locali

var recorder = new AWSXRayRecorderBuilder().WithSamplingStrategy(new LocalizedSamplingStrategy("sampling-rules.json")).Build();
AWSXRayRecorder.InitializeInstance(configuration,recorder);

Logging (.NET)

L'X-Ray SDK for .NET utilizza lo stesso meccanismo di registrazione di. AWS SDK for .NET Se hai già configurato l'applicazione per registrare l' AWS SDK for .NET output, la stessa configurazione si applica all'output di X-Ray SDK for .NET.

Per configurare il log, aggiungi una sezione di configurazione denominata aws al tuo file App.config o al tuo file Web.config.

Esempio Web.config - Generazione dei log

...
<configuration>
  <configSections>
    <section name="aws" type="Amazon.AWSSection, AWSSDK.Core"/>
  </configSections>
  <aws>
    <logging logTo="Log4Net"/>
  </aws>
</configuration>

Per ulteriori informazioni, consulta Configurazione dell'applicazione AWS SDK for .NET nella Guida per gli sviluppatori di AWS SDK for .NET .

Logging (.NET Core)

X-Ray SDK for .NET utilizza le stesse opzioni di registrazione di. AWS SDK for .NET Per configurare la registrazione per le applicazioni.NET Core, passa l'opzione di registrazione al metodo. AWSXRayRecorder.RegisterLogger

Ad esempio, per utilizzare log4net, è necessario creare un file di configurazione che definisca il logger, formato di output e la posizione del file.

Esempio .NET Core log4net.config

<?xml version="1.0" encoding="utf-8" ?>
<log4net>
  <appender name="FileAppender" type="log4net.Appender.FileAppender,log4net">
    <file value="c:\logs\sdk-log.txt" />
    <layout type="log4net.Layout.PatternLayout">
      <conversionPattern value="%date [%thread] %level %logger - %message%newline" />
    </layout>
  </appender>
  <logger name="Amazon">
    <level value="DEBUG" />
    <appender-ref ref="FileAppender" />
  </logger>
</log4net>

Quindi creare il logger e applicare la configurazione al codice del programma.

Esempio .NET Core Program.cs — Registrazione

using log4net;
using Amazon.XRay.Recorder.Core;

class Program
{
  private static ILog log;
  static Program()
  {
    var logRepository = LogManager.GetRepository(Assembly.GetEntryAssembly());
    XmlConfigurator.Configure(logRepository, new FileInfo("log4net.config"));
    log = LogManager.GetLogger(typeof(Program));
    AWSXRayRecorder.RegisterLogger(LoggingOptions.Log4Net);
  }
  static void Main(string[] args)
  {
  ...
  }
}

Per ulteriori informazioni sulla configurazione di log4net, vedere Configurazione su logging.apache.org.

Variabili di ambiente

È possibile utilizzare le variabili di ambiente per configurare l'X-Ray SDK for .NET. 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 utilizza 127.0.0.1:2000 sia i dati di traccia (UDP) che il campionamento (TCP). Utilizzate questa variabile se avete configurato il demone per l'ascolto su una porta diversa o se è in esecuzione su un host diverso.

  Formato

  • Stessa porta — address:port

  • Porte diverse: tcp:address:port udp:address:port

• 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.