Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà. # AWS X-Ray SDK per Ruby **Nota** Avviso di SDK/Daemon manutenzione a raggi X: il 25 febbraio 2026, X-Ray SDKs/Daemon entrerà in modalità di manutenzione, in cui AWS limiterà le versioni di AWS X-Ray SDK e Daemon per risolvere solo problemi di sicurezza. Per ulteriori informazioni sulla tempistica del supporto, consulta. [Cronologia di X-Ray SDK e Daemon Support](xray-sdk-daemon-timeline.md) Ti consigliamo di migrare a. OpenTelemetry Per ulteriori informazioni sulla migrazione a OpenTelemetry, vedere [Migrazione dalla strumentazione a raggi X](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html) alla strumentazione. OpenTelemetry X-Ray SDK è una libreria per applicazioni web Ruby che fornisce classi e metodi per generare e inviare dati di traccia al demone X-Ray. I dati di traccia includono informazioni sulle richieste HTTP in entrata fornite dall'applicazione e sulle chiamate effettuate dall'applicazione ai servizi downstream utilizzando l' AWS SDK, i client HTTP o un client di registrazione attivo. Puoi anche possibile creare manualmente dei segmenti e aggiungere informazioni di debug in annotazioni e metadati. Puoi scaricare l'SDK aggiungendolo al tuo gemfile ed eseguendo `bundle install`. **Example Gemfile** ``` gem 'aws-sdk' ``` Se usi Rails, inizia [aggiungendo il middleware X-Ray SDK](xray-sdk-ruby-middleware.md) per tracciare le richieste in arrivo. Un filtro sulla richiesta crea un [segmento](xray-concepts.md#xray-concepts-segments). Fino a che il segmento è aperto, puoi usare i metodi del client dell'SDK per aggiungere informazioni al segmento e creare sottosegmenti per tracciare le chiamate a valle. L'SDK, inoltre, registra automaticamente le eccezioni sollevate dall'applicazione per il tempo durante il quale il segmento è aperto. Per applicazioni non Rail, puoi [creare i segmenti manualmente](xray-sdk-ruby-middleware.md#xray-sdk-ruby-middleware-manual). Successivamente, usa l'SDK X-Ray per strumentare i tuoi AWS SDK per Ruby client HTTP e SQL [configurando il registratore](xray-sdk-ruby-patching.md) per applicare patch alle librerie associate. Ogni volta che effettui una chiamata a un downstream Servizio AWS o a una risorsa con un client dotato di strumenti, l'SDK registra le informazioni sulla chiamata in un sottosegmento. Servizi AWS e le risorse a cui accedi all'interno dei servizi vengono visualizzate come nodi a valle sulla mappa di traccia per aiutarti a identificare errori e problemi di limitazione sulle singole connessioni. Una volta presa confidenza con l'SDK, personalizza il suo comportamento [configurando il registratore](xray-sdk-ruby-configuration.md). Puoi aggiungere dei plugin per memorizzare i dati sulle risorse di elaborazione sulle quali è eseguita la tua applicazione, personalizzare il comportamento di campionamento definendo regole di campionatura e impostare un sistema di generazione dei log per visualizzare più o meno informazioni generate dall'SDK nei log dell'applicazione. Registra ulteriori informazioni sulle richieste e sull'attività svolta dalla tua applicazione in [annotazioni e metadati](xray-sdk-ruby-segment.md). Le annotazioni sono semplici coppie chiave-valore indicizzati per l'uso con [espressioni filtro](xray-console-filters.md), in modo da poter cercare tracce che contengono dati specifici. Le immissioni di metadati sono meno restrittive e possono registrare interi oggetti e array, tutto ciò che può essere serializzato in JSON. **Annotazioni e metadata** Le annotazioni e i metadati sono testo arbitrario che aggiungi ai segmenti con X-Ray SDK. Le annotazioni vengono indicizzate per essere utilizzate con le espressioni di filtro. I metadati non sono indicizzati, ma possono essere visualizzati nel segmento non elaborato con la console X-Ray o l'API. Chiunque conceda l'accesso in lettura a X-Ray può visualizzare questi dati. Quando disponi di una notevole quantità di client analizzati nel tuo codice, un singolo segmento per la richiesta può contenere un numero elevato di sottosegmenti, uno per ciascuna delle chiamate effettuate con un client analizzato. Puoi organizzare e raggruppare i sottosegmenti inglobando le chiamate del client [sottosegmenti personalizzati](xray-sdk-ruby-subsegments.md). Puoi creare un sottosegmento personalizzato per un'intera funzione o qualsiasi porzione di codice, e memorizzare metadati e annotazioni sul sottosegmento invece di scrivere tutto all'interno del segmento padre. Per la documentazione di riferimento per le classi e i metodi dell'SDK, consulta l'[AWS X-Ray SDK for](https://docs.aws.amazon.com/xray-sdk-for-ruby/latest/reference) Ruby API Reference. ## Requisiti L'X-Ray SDK richiede Ruby 2.3 o successivo ed è compatibile con le seguenti librerie: + AWS SDK per Ruby versione 3.0 o successiva + Rails versione 5.1 o successive # Configurazione dell'X-Ray SDK per Ruby **Nota** Avviso di SDK/Daemon manutenzione a raggi X: il 25 febbraio 2026, X-Ray SDKs/Daemon entrerà in modalità di manutenzione, in cui AWS limiterà le versioni di AWS X-Ray SDK e Daemon per risolvere solo problemi di sicurezza. Per ulteriori informazioni sulla tempistica del supporto, consulta. [Cronologia di X-Ray SDK e Daemon Support](xray-sdk-daemon-timeline.md) Ti consigliamo di migrare a. OpenTelemetry Per ulteriori informazioni sulla migrazione a OpenTelemetry, vedere [Migrazione dalla strumentazione a raggi X](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html) alla strumentazione. OpenTelemetry 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. **Topics** + [Plugin di servizio](#xray-sdk-ruby-configuration-plugins) + [Regole di campionamento](#xray-sdk-ruby-configuration-sampling) + [Registrazione dei log](#xray-sdk-ruby-configuration-logging) + [Configurazione del registratore nel codice](#xray-sdk-ruby-configuration-code) + [Configurazione del registratore con Rails](#xray-sdk-ruby-middleware-configuration-rails) + [Variabili di ambiente](#xray-sdk-ruby-configuration-envvars) ## Plugin di servizio `plugins`Utilizzatelo per registrare informazioni sul servizio che ospita l'applicazione. **Plugin** + 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. ![\[Segment - Scorekeep overview showing Elastic Beanstalk and EC2 deployment details.\]](http://docs.aws.amazon.com/it_it/xray/latest/devguide/images/scorekeep-PUTrules-segment-resources-python09.png) Per utilizzare i plugin, specificalo nell'oggetto di configurazione che passi al registratore. **Example 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](#xray-sdk-ruby-configuration-envvars), 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](xray-console-sampling.md) 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 ogni secondo e del cinque percento di eventuali richieste aggiuntive per host. Ciò può verificarsi se l'host non dispone dell'autorizzazione per chiamare sampling APIs o non riesce a 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. **Example 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. **Example 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. **Example config/sampling-rules.rb** ``` my_sampling_rules = { version: 1, default: { fixed_target: 1, rate: 0.1 } } ``` **Example 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`. **Example 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. **Example main.rb — Disabilita il campionamento** ``` require 'aws-xray-sdk' config = { sampling: false, name: 'my app', } XRay.recorder.configure(config) ``` ## Registrazione dei log Per impostazione predefinita, il registratore genera gli eventi a livello di informazioni su `$stdout`. Puoi personalizzare la generazione dei log definendo un [logger](https://ruby-doc.org/stdlib-2.4.2/libdoc/logger/rdoc/Logger.html) nell'oggetto di configurazione da passare al registratore. **Example 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](xray-sdk-ruby-subsegments.md). ## 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](xray-sdk-ruby-middleware.md#xray-sdk-ruby-middleware-naming). + `plugins`— Registra informazioni sulle AWS risorse dell'applicazione con i [plugin](#xray-sdk-ruby-configuration-plugins). + `sampling`— Impostare per `false` disabilitare il campionamento. + `sampling_rules`— Imposta l'hash contenente le regole di [campionamento](#xray-sdk-ruby-configuration-sampling). **Example 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`. **Example config/initializers/aws\$1xray.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](xray-sdk-ruby-middleware.md#xray-sdk-ruby-middleware-naming) 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](xray-daemon-configuration.md) 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. # Tracciamento delle richieste in arrivo con il middleware X-Ray SDK for Ruby **Nota** Avviso di SDK/Daemon manutenzione a raggi X: il 25 febbraio 2026, X-Ray SDKs/Daemon entrerà in modalità di manutenzione, in cui AWS limiterà le versioni di AWS X-Ray SDK e Daemon per risolvere solo problemi di sicurezza. Per ulteriori informazioni sulla tempistica del supporto, consulta. [Cronologia di X-Ray SDK e Daemon Support](xray-sdk-daemon-timeline.md) Ti consigliamo di migrare a. OpenTelemetry Per ulteriori informazioni sulla migrazione a OpenTelemetry, vedere [Migrazione dalla strumentazione a raggi X](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html) alla strumentazione. OpenTelemetry Puoi utilizzare l'SDK X-Ray per tracciare le richieste HTTP in entrata che la tua applicazione serve su un'istanza EC2 in Amazon EC2 o Amazon ECS. AWS Elastic Beanstalk Se utilizzi Rails, utilizza il middleware Rails per analizzare le richieste HTTP in entrata. Quando aggiungi il middleware all'applicazione e configuri il nome di un segmento, X-Ray SDK for Ruby crea un segmento per ogni richiesta campionata. Tutti i segmenti creati da analisi aggiuntive diventano sottosegmenti del segmento a livello di richiesta che offre informazioni sulla richiesta e sulla risposta HTTP. Queste informazioni includono durata, metodo e conclusione della richiesta HTTP. Ogni segmento ha un nome che identifica l'applicazione nella mappa del servizio. Il segmento può essere denominato staticamente oppure è possibile configurare l'SDK per denominarlo dinamicamente in base all'intestazione dell'host nella richiesta in entrata. La denominazione dinamica consente di raggruppare le tracce in base al nome di dominio nella richiesta e di applicare un nome predefinito se il nome non corrisponde a uno schema previsto (ad esempio, se l'intestazione dell'host è falsificata). **Richieste inoltrate** Se un sistema di bilanciamento del carico o un altro intermediario inoltra una richiesta all'applicazione, X-Ray prende l'IP del client dall'`X-Forwarded-For`intestazione della richiesta anziché dall'IP di origine nel pacchetto IP. L'IP del client registrato per una richiesta inoltrata può essere falsificato, quindi non dovrebbe essere considerato attendibile. Quando viene inoltrata una richiesta, l'SDK imposta un campo aggiuntivo nel segmento per indicarlo. Se il segmento contiene il campo `x_forwarded_for` impostato su`true`, l'IP del client è stato preso dall'`X-Forwarded-For`intestazione della richiesta HTTP. Il middleware crea un segmento per ogni richiesta in entrata con un blocco `http` che contiene le informazioni riportate qui di seguito: + **Metodo HTTP**: GET, POST, PUT, DELETE, ecc. + **Indirizzo client**: l'indirizzo IP del client che ha inviato la richiesta. + **Codice di risposta**: il codice di risposta HTTP per la richiesta completata. + **Tempistica**: l'ora di inizio (quando è stata ricevuta la richiesta) e l'ora di fine (quando è stata inviata la risposta). + **Agente utente**: il `user-agent` codice della richiesta. + **Lunghezza del contenuto**: il `content-length` risultato della risposta. ## Utilizzo del middleware Rails Per usare il middleware, aggiorna il tuo gemfile per includere il [railtie](http://api.rubyonrails.org/classes/Rails/Railtie.html) necessario. **Example Gemfile - rails** ``` gem 'aws-xray-sdk', require: ['aws-xray-sdk/facets/rails/railtie'] ``` Per utilizzare il middleware, è inoltre necessario [configurare il registratore](xray-sdk-ruby-configuration.md#xray-sdk-ruby-middleware-configuration-rails) con un nome che rappresenti l'applicazione nella mappa di traccia. **Example config/initializers/aws\$1xray.rb** ``` Rails.application.config.xray = { name: 'my app' } ``` ## Analisi manuale del codice Se non utilizzi Rails, crea i segmenti manualmente. Puoi creare un segmento per ogni richiesta in arrivo o creare segmenti attorno a client HTTP o AWS SDK con patch per fornire al registratore il contesto in cui aggiungere sottosegmenti. ``` # Start a segment segment = XRay.recorder.begin_segment 'my_service' # Start a subsegment subsegment = XRay.recorder.begin_subsegment 'outbound_call', namespace: 'remote' # Add metadata or annotation here if necessary my_annotations = { k1: 'v1', k2: 1024 } segment.annotations.update my_annotations # Add metadata to default namespace subsegment.metadata[:k1] = 'v1' # Set user for the segment (subsegment is not supported) segment.user = 'my_name' # End segment/subsegment XRay.recorder.end_subsegment XRay.recorder.end_segment ``` ## Configurazione di una strategia di denominazione dei segmenti AWS X-Ray utilizza un *nome di servizio* per identificare l'applicazione e distinguerla dalle altre applicazioni, database, risorse esterne APIs e risorse utilizzate dall'applicazione. AWS [Quando X-Ray SDK genera segmenti per le richieste in entrata, registra il nome del servizio dell'applicazione nel campo del nome del segmento.](xray-api-segmentdocuments.md#api-segmentdocuments-fields) L'X-Ray SDK può denominare i segmenti dopo il nome host nell'intestazione della richiesta HTTP. Tuttavia, questa intestazione può essere falsificata, il che potrebbe causare nodi imprevisti nella mappa dei servizi. Per evitare che l'SDK nomini i segmenti in modo errato a causa di richieste con intestazioni host contraffatte, è necessario specificare un nome predefinito per le richieste in entrata. Se la tua applicazione soddisfa le richieste per più domini, puoi configurare l'SDK in modo che utilizzi una strategia di denominazione dinamica che rifletta questo aspetto nei nomi dei segmenti. Una strategia di denominazione dinamica consente all'SDK di utilizzare il nome host per le richieste che corrispondono a uno schema previsto e di applicare il nome predefinito alle richieste che non lo fanno. Ad esempio, potresti avere una singola applicazione che serve le richieste a tre sottodomini:, e. `www.example.com` `api.example.com` `static.example.com` È possibile utilizzare una strategia di denominazione dinamica con lo schema `*.example.com` per identificare i segmenti per ogni sottodominio con un nome diverso, ottenendo tre nodi di servizio sulla mappa dei servizi. Se l'applicazione riceve richieste con un nome host che non corrisponde allo schema, sulla mappa dei servizi verrà visualizzato un quarto nodo con un nome di fallback specificato dall'utente. Per utilizzare lo stesso nome per tutti i segmenti della richiesta, specifica il nome della tua applicazione quando configuri il registratore, come illustrato [nelle sezioni precedenti](#xray-sdk-ruby-middleware-rails). Una strategia di denominazione dinamica definisce un modello al quale devono corrispondere i nomi degli host e un nome di default per l'utilizzo qualora il nome dell'host nella richiesta HTTP non corrisponda al modello. Per denominare segmenti in modo dinamico, specificare un modello di denominazione nel config hash. **Example main.rb — Denominazione dinamica** ``` config = { naming_pattern: '*mydomain*', name: 'my app', } XRay.recorder.configure(config) ``` Puoi utilizzare '\$1' nel modello per una corrispondenza con qualsiasi stringa o '?' per una corrispondenza con qualsiasi carattere singolo. **Nota** [È possibile sovrascrivere il nome di servizio predefinito definito nel codice con la variabile di ambiente. `AWS_XRAY_TRACING_NAME`](xray-sdk-ruby-configuration.md#xray-sdk-ruby-configuration-envvars) # Applicare le patch alle librerie per analizzare le chiamate a valle **Nota** Avviso di SDK/Daemon manutenzione a raggi X: il 25 febbraio 2026, X-Ray SDKs/Daemon entrerà in modalità di manutenzione, in cui AWS limiterà le versioni di AWS X-Ray SDK e Daemon per risolvere solo problemi di sicurezza. Per ulteriori informazioni sulla tempistica del supporto, consulta. [Cronologia di X-Ray SDK e Daemon Support](xray-sdk-daemon-timeline.md) Ti consigliamo di migrare a. OpenTelemetry Per ulteriori informazioni sulla migrazione a OpenTelemetry, vedere [Migrazione dalla strumentazione a raggi X](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html) alla strumentazione. OpenTelemetry Per strumentare le chiamate downstream, utilizzate l'X-Ray SDK for Ruby per applicare patch alle librerie utilizzate dall'applicazione. L'X-Ray SDK for Ruby può applicare patch alle seguenti librerie. **Librerie supportate** + `[net/http](https://ruby-doc.org/stdlib-2.4.2/libdoc/net/http/rdoc/Net/HTTP.html)`— Client HTTP dello strumento. + `[aws-sdk](https://aws.amazon.com/sdk-for-ruby)`— AWS SDK per Ruby Client dello strumento. Quando si utilizza una libreria con patch, l'X-Ray SDK for Ruby crea un sottosegmento per la chiamata e registra le informazioni dalla richiesta e dalla risposta. Un segmento deve essere disponibile affinché l'SDK possa creare il sottosegmento, sia tramite il middleware dell'SDK che tramite una chiamata a `XRay.recorder.begin_segment`. Per applicare patch alle librerie, specificatele nell'oggetto di configurazione che passate al registratore X-Ray. **Example main.rb — Librerie di patch** ``` require 'aws-xray-sdk' config = { name: 'my app', patch: %I[net_http aws_sdk] } XRay.recorder.configure(config) ``` # Tracciamento delle chiamate AWS SDK con X-Ray SDK for Ruby **Nota** Avviso di SDK/Daemon manutenzione a raggi X: il 25 febbraio 2026, X-Ray SDKs/Daemon entrerà in modalità di manutenzione, in cui AWS limiterà le versioni di AWS X-Ray SDK e Daemon per risolvere solo problemi di sicurezza. Per ulteriori informazioni sulla tempistica del supporto, consulta. [Cronologia di X-Ray SDK e Daemon Support](xray-sdk-daemon-timeline.md) Ti consigliamo di migrare a. OpenTelemetry Per ulteriori informazioni sulla migrazione a OpenTelemetry, vedere [Migrazione dalla strumentazione a raggi X](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html) alla strumentazione. OpenTelemetry [Quando l'applicazione effettua chiamate per Servizi AWS archiviare dati, scrivere in una coda o inviare notifiche, X-Ray SDK for Ruby tiene traccia delle chiamate downstream in sottosegmenti.](xray-sdk-ruby-subsegments.md) Le risorse tracciate Servizi AWS e a cui accedi all'interno di tali servizi (ad esempio, un bucket Amazon S3 o una coda Amazon SQS) vengono visualizzate come nodi downstream sulla mappa di traccia nella console X-Ray. [L'X-Ray SDK for Ruby strumenta automaticamente AWS tutti i client SDK quando applichi una patch alla libreria. `aws-sdk`](xray-sdk-ruby-patching.md) Non puoi analizzare singoli client. Per tutti i servizi, puoi vedere il nome dell'API richiamata nella console X-Ray. Per un sottoinsieme di servizi, l'SDK X-Ray aggiunge informazioni al segmento per fornire una maggiore granularità nella mappa dei servizi. Ad esempio, quando si effettua una chiamata con un client DynamoDB con strumentazione, l'SDK aggiunge il nome della tabella al segmento per le chiamate destinate a una tabella. Nella console, ogni tabella appare come un nodo separato nella mappa dei servizi, con un nodo DynamoDB generico per le chiamate che non hanno come destinazione una tabella. **Example Sottosegmento per una chiamata a DynamoDB per salvare un elemento** ``` { "id": "24756640c0d0978a", "start_time": 1.480305974194E9, "end_time": 1.4803059742E9, "name": "DynamoDB", "namespace": "aws", "http": { "response": { "content_length": 60, "status": 200 } }, "aws": { "table_name": "scorekeep-user", "operation": "UpdateItem", "request_id": "UBQNSO5AEM8T4FDA4RQDEB94OVTDRVV4K4HIRGVJF66Q9ASUAAJG", } } ``` Quando si accede alle risorse con nome, le chiamate ai seguenti servizi creano ulteriori nodi della mappa del servizio. Le chiamate che non sono hanno come obiettivo risorse specifiche creano un nodo generico per il servizio. + **Amazon DynamoDB**: nome della tabella + **Amazon Simple Storage Service**: nome del bucket e della chiave + **Amazon Simple Queue Service**: nome della coda # Generazione di sottosegmenti personalizzati con X-Ray SDK **Nota** Avviso di SDK/Daemon manutenzione a raggi X: il 25 febbraio 2026, X-Ray SDKs/Daemon entrerà in modalità di manutenzione, in cui AWS limiterà le versioni di AWS X-Ray SDK e Daemon per risolvere solo problemi di sicurezza. Per ulteriori informazioni sulla tempistica del supporto, consulta. [Cronologia di X-Ray SDK e Daemon Support](xray-sdk-daemon-timeline.md) Ti consigliamo di migrare a. OpenTelemetry Per ulteriori informazioni sulla migrazione a OpenTelemetry, vedere [Migrazione dalla strumentazione a raggi X](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html) alla strumentazione. OpenTelemetry I sottosegmenti estendono il [segmento](xray-concepts.md#xray-concepts-segments) di una traccia con dettagli sul lavoro svolto per soddisfare una richiesta. Ogni volta che si effettua una chiamata con un client dotato di strumentazione, l'X-Ray SDK registra le informazioni generate in un sottosegmento. È possibile creare sottosegmenti aggiuntivi per raggruppare altri sottosegmenti, misurare le prestazioni di una sezione di codice o registrare annotazioni e metadati. Per gestire i sottosegmenti, utilizza i metodi `begin_subsegment` e `end_subsegment`. ``` subsegment = XRay.recorder.begin_subsegment name: 'annotations', namespace: 'remote' my_annotations = { id: 12345 } subsegment.annotations.update my_annotations XRay.recorder.end_subsegment ``` Per creare un subsegment per una funzione, eseguire il wrapping in una chiamata a `XRay.recorder.capture`. ``` XRay.recorder.capture('name_for_subsegment') do |subsegment| resp = myfunc() # myfunc is your function subsegment.annotations.update k1: 'v1' resp end ``` Quando create un sottosegmento all'interno di un segmento o di un altro sottosegmento, X-Ray SDK genera un ID per esso e registra l'ora di inizio e l'ora di fine. **Example Sottosegmento con metadati** ``` "subsegments": [{ "id": "6f1605cd8a07cb70", "start_time": 1.480305974194E9, "end_time": 1.4803059742E9, "name": "Custom subsegment for UserModel.saveUser function", "metadata": { "debug": { "test": "Metadata string from UserModel.saveUser" } }, ``` # Aggiungi annotazioni e metadati ai segmenti con l'X-Ray SDK for Ruby **Nota** Avviso di SDK/Daemon manutenzione a raggi X: il 25 febbraio 2026, X-Ray SDKs/Daemon entrerà in modalità di manutenzione, in cui AWS limiterà le versioni di AWS X-Ray SDK e Daemon per risolvere solo problemi di sicurezza. Per ulteriori informazioni sulla tempistica del supporto, consulta. [Cronologia di X-Ray SDK e Daemon Support](xray-sdk-daemon-timeline.md) Ti consigliamo di migrare a. OpenTelemetry Per ulteriori informazioni sulla migrazione a OpenTelemetry, vedere [Migrazione dalla strumentazione a raggi X](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html) alla strumentazione. OpenTelemetry È possibile registrare informazioni aggiuntive sulle richieste, sull'ambiente o sull'applicazione con annotazioni e metadati. È possibile aggiungere annotazioni e metadati ai segmenti creati da X-Ray SDK o ai sottosegmenti personalizzati creati dall'utente. **Le annotazioni sono coppie** chiave-valore con stringhe, numeri o valori booleani. [Le annotazioni sono indicizzate per essere utilizzate con le espressioni di filtro.](xray-console-filters.md) Utilizzale per registrare i dati che desideri utilizzare per raggruppare le tracce nella console oppure per chiamare l'API [https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html](https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html). I **metadati** sono coppie chiave-valore che possono avere valori di qualsiasi tipo, inclusi oggetti ed elenchi, ma non sono indicizzati per essere utilizzati con le espressioni di filtro. Utilizzate i metadati per registrare dati aggiuntivi che desiderate archiviare nella traccia ma che non è necessario utilizzare con la ricerca. Oltre ad annotazioni e metadati, sui segmenti puoi anche [registrare le stringhe degli ID utente](#xray-sdk-ruby-segment-userid). IDs Gli utenti vengono registrati in un campo separato sui segmenti e indicizzati per essere utilizzati nella ricerca. **Topics** + [Registrazione delle annotazioni con X-Ray SDK for Ruby](#xray-sdk-ruby-segment-annotations) + [Registrazione di metadati con X-Ray SDK for Ruby](#xray-sdk-ruby-segment-metadata) + [Utente che registra IDs con X-Ray SDK for Ruby](#xray-sdk-ruby-segment-userid) ## Registrazione delle annotazioni con X-Ray SDK for Ruby Utilizza le annotazioni per memorizzare le informazioni su segmenti o sottosegmenti che desideri siano indicizzate per la ricerca. **Requisiti per le annotazioni** + **Chiavi**: la chiave per un'annotazione a raggi X può contenere fino a 500 caratteri alfanumerici. Non è possibile utilizzare spazi o simboli diversi da un punto o un punto (.) + **Valori**: il valore di un'annotazione X-Ray può contenere fino a 1.000 caratteri Unicode. + Il numero di **annotazioni**: è possibile utilizzare fino a 50 annotazioni per traccia. **Per registrare le annotazioni** 1. Ottenere un riferimento al segmento o sottosegmento corrente da `xray_recorder`. ``` require 'aws-xray-sdk' ... document = XRay.recorder.current_segment ``` or ``` require 'aws-xray-sdk' ... document = XRay.recorder.current_subsegment ``` 1. Chiama `update` con un valore hash. ``` my_annotations = { id: 12345 } document.annotations.update my_annotations ``` Di seguito è riportato un esempio che mostra come effettuare una chiamata `update` con una chiave di annotazione che contiene un punto. ``` my_annotations = { testkey.test: 12345 } document.annotations.update my_annotations ``` L'SDK memorizza le annotazioni come coppie chiave-valore in un oggetto `annotations` all'interno del documento di segmento. Se chiami `add_annotations` due volte con la stessa chiave, il valore precedentemente memorizzato nello stesso segmento o sottosegmento viene sovrascritto. Per trovare tracciamenti con annotazioni contenenti valori specifici, utilizza la parola chiave `annotation[key]` in un'[espressione filtro](xray-console-filters.md). ## Registrazione di metadati con X-Ray SDK for Ruby Utilizza i metadati per memorizzare le informazioni su segmenti o sottosegmenti che non è necessario che siano indicizzate per la ricerca. I valori dei metadati possono essere stringhe, numeri, valori booleani o qualsiasi oggetto che possa essere serializzato in un oggetto o in un vettore JSON. **Per registrare i metadati** 1. Ottenere un riferimento al segmento o sottosegmento corrente da `xray_recorder`. ``` require 'aws-xray-sdk' ... document = XRay.recorder.current_segment ``` or ``` require 'aws-xray-sdk' ... document = XRay.recorder.current_subsegment ``` 1. Chiama `metadata` con una chiave di tipo Stringa, un valore booleano, numerico, di tipo Stringa o di tipo oggetto e un namespace di tipo stringa. ``` my_metadata = { my_namespace: { key: 'value' } } subsegment.metadata my_metadata ``` Se chiami `metadata` due volte con la stessa chiave, il valore precedentemente memorizzato nello stesso segmento o sottosegmento viene sovrascritto. ## Utente che registra IDs con X-Ray SDK for Ruby Registra i segmenti dell'utente IDs su richiesta per identificare l'utente che ha inviato la richiesta. **Per registrare l'utente IDs** 1. Ottenere un riferimento al segmento corrente da `xray_recorder`. ``` require 'aws-xray-sdk' ... document = XRay.recorder.current_segment ``` 1. Imposta il campo utente sul segmento a un ID di tipo stringa dell'utente che ha inviato la richiesta. ``` segment.user = 'U12345' ``` Puoi impostare l'utente nei tuoi controller per registrare l'ID utente non appena l'applicazione inizia ad elaborare una richiesta. Per trovare tracciamenti associati ad un ID utente, utilizza la parola chiave `user` in un'[espressione filtro](xray-console-filters.md).