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à. # Migrazione dalla strumentazione a raggi X alla strumentazione OpenTelemetry **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) X-Ray sta passando a OpenTelemetry (OTel) come standard di strumentazione principale per il tracciamento e l'osservabilità delle applicazioni. Questo cambiamento strategico si allinea AWS alle migliori pratiche del settore e offre ai clienti una soluzione più completa, flessibile e pronta per il futuro per le loro esigenze di osservabilità. OpenTelemetryl'ampia adozione nel settore consente il tracciamento delle richieste su diversi sistemi, compresi quelli esterni AWS che potrebbero non integrarsi direttamente con X-Ray. Questo capitolo fornisce raccomandazioni per una transizione senza intoppi e sottolinea l'importanza della migrazione a soluzioni OpenTelemetry basate su di essa per garantire supporto e accesso continui alle funzionalità più recenti in materia di strumentazione e osservabilità delle applicazioni. Si consiglia di adottarla OpenTelemetry come soluzione di osservabilità per la strumentazione dell'applicazione. **Topics** + [Comprensione OpenTelemetry](#migration-to-opentelemetry) + [Comprensione dei concetti relativi alla migrazione OpenTelemetry](#opentelemetry-concepts) + [Panoramica sulla migrazione](#migration-overview) + [Migrazione da X-Ray Daemon AWS CloudWatch a un agente o un raccoglitore OpenTelemetry](#xray-Daemon-migration) + [OpenTelemetry Migrazione a Java](xray-migration-opentelemetry.md) + [Esegui la migrazione a OpenTelemetry Go](manual-instrumentation-go.md) + [Migrare a Node.js OpenTelemetry](migrate-xray-to-opentelemetry-nodejs.md) + [Esegui la migrazione a.NET OpenTelemetry](introduction-dotnet.md) + [Migrare a Python OpenTelemetry](migrate-xray-to-opentelemetry-python.md) + [Migra a Ruby OpenTelemetry](migrate-xray-to-opentelemetry-ruby.md) ## Comprensione OpenTelemetry OpenTelemetry è un framework di osservabilità standard del settore che fornisce protocolli e strumenti standardizzati per la raccolta di dati di telemetria. Offre un approccio unificato alla strumentazione, alla generazione, alla raccolta e all'esportazione di dati di telemetria come metriche, log e tracce. Quando si esegue la migrazione da SDKs X-Ray OpenTelemetry a, si ottengono i seguenti vantaggi: + Supporto avanzato per framework e strumentazione di libreria + Support per linguaggi di programmazione aggiuntivi + Funzionalità di strumentazione automatica + Opzioni flessibili di configurazione del campionamento + Raccolta unificata di metriche, log e tracce Il OpenTelemetry raccoglitore offre più opzioni per i formati di raccolta dei dati e le destinazioni di esportazione rispetto al demone X-Ray. ### OpenTelemetry supporto in AWS AWS offre diverse soluzioni per lavorare con OpenTelemetry: + AWS Distro per OpenTelemetry Esporta OpenTelemetry le tracce come segmenti in X-Ray. Per ulteriori informazioni, vedete [AWS Distro](https://aws-otel.github.io/) for. OpenTelemetry + CloudWatch Segnali applicativi Esporta OpenTelemetry tracce e metriche personalizzate per monitorare lo stato delle applicazioni. Per ulteriori informazioni, consulta [Working with Application Signals](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Application-Monitoring-Sections.html). + CloudWatch OTel Endpoint Esporta OpenTelemetry le tracce su X-Ray utilizzando l' OTel endpoint HTTP con strumentazione nativa. OpenTelemetry [Per ulteriori informazioni, vedere Utilizzo degli endpoint. OTel ](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-OTLPEndpoint.html) #### Utilizzo con OpenTelemetry AWS CloudWatch AWS CloudWatch supporta OpenTelemetry le tracce tramite strumentazione applicativa lato client e AWS CloudWatch servizi nativi come Application Signals, Trace, Map, Metrics e Logs. Per ulteriori informazioni, consulta [OpenTelemetry](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-OpenTelemetry-Sections.html). ## Comprensione dei concetti relativi alla migrazione OpenTelemetry La tabella seguente mappa i concetti relativi ai raggi X ai loro OpenTelemetry equivalenti. La comprensione di queste mappature consente di tradurre la strumentazione a raggi X esistente in: OpenTelemetry | Concetto X-Ray | OpenTelemetry concetto | | --- | --- | | Registratore a raggi X | Tracer Provider e Tracer | | Plugin di servizio | Rilevatore di risorse | | Segment | (Server) Span | | Sottosegmento | Intervallo (non server) | | Regole di campionamento a raggi X | OpenTelemetry Campionamento (personalizzabile) | | Emettitore di raggi X | Span Exporter (personalizzabile) | | Annotazioni/metadati | Attributes | | Strumentazione della biblioteca | Strumentazione per biblioteche | | Contesto della traccia a raggi X | Contesto Span | | Propagazione del contesto di tracce a raggi X | Propagazione del contesto di traccia W3C | | Campionamento di tracce a raggi X | OpenTelemetry Campionamento delle tracce | | N/D | Elaborazione Span | | N/D | Bagagli | | Demone X-Ray | OpenTelemetry Collezionista | **Nota** Per ulteriori informazioni sui OpenTelemetry concetti, consulta la [OpenTelemetry documentazione](https://opentelemetry.io/docs). ### Confronto delle funzionalità La tabella seguente mostra quali funzionalità sono supportate in entrambi i servizi. Utilizzate queste informazioni per identificare eventuali lacune da colmare durante la migrazione: | Funzionalità | Strumentazione a raggi X | OpenTelemetry strumentazione | | --- | --- | --- | | Strumentazione per biblioteche | Supportata | Supportata | | Campionamento a raggi X | Supportata | Supportato in Java/.net/Go OTel
Supportato in ADOT Java/. NET/Python/Node.js | | Propagazione del contesto di tracce a raggi X | Supportata | Supportata | | Rilevamento delle risorse | Supportata | Supportata | | Annotazioni sui segmenti | Supportata | Supportata | | Metadati dei segmenti | Supportata | Supportata | | Strumentazione automatica a codice zero | Supportato in Java | Supportato in OTel Java/. NET/Python/Node.js
Supportato in ADOT Java/. NET/Python/Node.js | | Traccia manualmente la creazione | Supportata | Supportata | ### Impostazione e configurazione del tracciamento Per creare tracce in OpenTelemetry, è necessario un tracer. Puoi ottenere un tracer inizializzando un Tracer Provider nella tua *applicazione.* È simile a come si utilizza il registratore a raggi X per configurare X-Ray e creare segmenti e sottosegmenti in una traccia a raggi X. **Nota** Il OpenTelemetry *Tracer Provider* offre più opzioni di configurazione rispetto al registratore X-Ray. #### Comprensione della struttura dei dati di traccia Dopo aver compreso i concetti di base e le mappature delle funzionalità, puoi conoscere dettagli di implementazione specifici come la struttura dei dati di traccia e il campionamento. OpenTelemetry utilizza *gli intervalli* anziché segmenti e sottosegmenti per strutturare i dati di traccia. Ogni intervallo include i seguenti componenti: + Name + ID univoco + Timestamp di inizio e fine + Tipo di intervallo + Amplia il contesto + Attributi (metadati chiave-valore) + Eventi (registri con data e ora) + Collegamenti ad altri span + Informazioni sullo stato + Riferimenti Parent Span Quando si esegue la migrazione a OpenTelemetry, gli intervalli vengono convertiti automaticamente in segmenti o sottosegmenti X-Ray. Ciò garantisce che l'esperienza esistente con la console rimanga invariata. CloudWatch ##### Lavorare con gli attributi span L'SDK X-Ray offre due modi per aggiungere dati a segmenti e sottosegmenti: Annotazioni Coppie chiave-valore indicizzate per il filtraggio e la ricerca Metadati Coppie chiave-valore contenenti dati complessi che non sono indicizzati per la ricerca Per impostazione predefinita, gli attributi OpenTelemetry span vengono convertiti in metadati nei dati grezzi X-Ray. Per convertire invece attributi specifici in annotazioni, aggiungete le relative chiavi all'elenco degli attributi. `aws.xray.annotations` + [Per ulteriori informazioni sui OpenTelemetry concetti, vedete OpenTelemetry Traces](https://opentelemetry.io/docs/concepts/signals/traces/) + Per dettagli su come i OpenTelemetry dati vengono mappati ai dati a raggi X, vedere sulla traduzione del modello di dati [OpenTelemetry a raggi X](https://aws-otel.github.io/docs/getting-started/X-Ray#otel-to-X-Ray-data-model-translation-behavior-of-aws-X-Ray-exporter) ### Rilevamento delle risorse nell'ambiente OpenTelemetry utilizza *Resource Detectors* per raccogliere metadati sulle risorse che generano dati di telemetria. *Questi metadati vengono archiviati come attributi delle risorse.* Ad esempio, un'entità che produce telemetria potrebbe essere un cluster Amazon ECS o un'istanza Amazon EC2 e gli attributi delle risorse che possono essere registrati da queste entità possono includere l'ARN del cluster Amazon ECS o l'ID dell'istanza Amazon EC2. + [Per informazioni sui tipi di risorse supportati, consulta Resource Semantic Conventions OpenTelemetry ](https://opentelemetry.io/docs/reference/specification/resource/semantic_conventions/) + Per informazioni sui plugin del servizio X-Ray, vedere [Configurazione](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-python-configuration.html) dell'SDK X-Ray ### Gestione delle strategie di campionamento Trace Sampling ti aiuta a gestire i costi raccogliendo dati da un sottoinsieme rappresentativo di richieste anziché da tutte le richieste. OpenTelemetry Sia X-Ray che X-Ray supportano il campionamento, ma lo implementano in modo diverso. **Nota** Il campionamento di meno del 100% delle tracce riduce i costi di osservabilità, mantenendo al contempo informazioni significative sulle prestazioni dell'applicazione. OpenTelemetry offre diverse strategie di campionamento integrate e consente di crearne di personalizzate. Puoi anche configurare un *campionatore remoto X-Ray in alcuni linguaggi SDK con cui utilizzare le regole di campionamento* X-Ray. OpenTelemetry Le strategie di campionamento aggiuntive di sono: OpenTelemetry + Campionamento basato sui genitori: rispetta la decisione di campionamento dell'intervallo principale prima di applicare strategie di campionamento aggiuntive + Campionamento basato sul rapporto Trace ID — >Campiona in modo casuale una percentuale specificata di intervalli + Campionamento della coda: applica le regole di campionamento per completare le tracce nel Collector OpenTelemetry + Campionatori personalizzati: implementate la vostra logica di campionamento utilizzando l'interfaccia di campionamento Per informazioni sulle regole di campionamento a raggi X, vedere Regole di [campionamento nella](https://docs.aws.amazon.com/xray/latest/devguide/xray-console-sampling.html) console X-Ray [Per informazioni sul campionamento della OpenTelemetry coda, vedere Processore di campionamento della coda](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/tailsamplingprocessor) ### Gestione del contesto di traccia X-Ray SDKs gestisce il contesto del segmento per gestire correttamente le relazioni padre-figlio tra segmenti e sottosegmenti in una traccia. OpenTelemetry utilizza un meccanismo simile per garantire che gli span abbiano l'intervallo principale corretto. Memorizza e propaga i dati di tracciamento in un contesto di richiesta. Ad esempio, quando l'applicazione elabora una richiesta e crea uno span del server per rappresentare tale richiesta, OpenTelemetry memorizzerà l'estensione del server nel OpenTelemetry Context in modo che, quando viene creato uno span secondario, tale span figlio possa fare riferimento allo span nel Context come riferimento principale. ### Propagazione del contesto di traccia Sia X-Ray che OpenTelemetry utilizzano le intestazioni HTTP per propagare il contesto di traccia tra i servizi. Ciò consente di collegare i dati di traccia generati da diversi servizi e di mantenere le decisioni di campionamento. L'SDK X-Ray propaga automaticamente il contesto della traccia utilizzando l'intestazione di traccia X-Ray. Quando un servizio ne chiama un altro, l'intestazione di traccia contiene il contesto necessario per mantenere le relazioni padre-figlio tra le tracce. OpenTelemetry supporta diversi formati di trace header per la propagazione del contesto, tra cui: + W3C Trace Context (impostazione predefinita) + Intestazione di tracciamento X-Ray + Altri formati personalizzati **Nota** È possibile configurare l'utilizzo OpenTelemetry di uno o più formati di intestazione. Ad esempio, utilizzate X-Ray Propagator per inviare il contesto di traccia ai AWS servizi che supportano il tracciamento a raggi X. Configura e usa X-Ray Propagator per abilitare il tracciamento tra i servizi. AWS Ciò consente di propagare il contesto di traccia agli endpoint API Gateway e ad altri servizi che supportano X-Ray. + Per informazioni sugli X-Ray Trace Header, vedere [Tracing header](https://docs.aws.amazon.com/xray/latest/devguide/xray-concepts.html#xray-concepts-tracingheader) nella X-Ray Developer Guide + Per informazioni sulla propagazione del OpenTelemetry contesto, vedere Context and [Context](https://opentelemetry.io/docs/concepts/context-propagation/) Propagation nella documentazione OpenTelemetry ### Utilizzo della strumentazione della libreria Sia X-Ray che OpenTelemetry forniscono una strumentazione di libreria che richiede modifiche minime al codice per aggiungere tracciamento alle applicazioni. X-Ray fornisce funzionalità di strumentazione di libreria. Ciò consente di aggiungere strumentazioni X-Ray predefinite con modifiche minime al codice dell'applicazione. Queste strumentazioni supportano librerie specifiche come i client AWS SDK e HTTP, nonché framework web come Spring Boot o Express.js. OpenTelemetryle librerie di strumentazione generano intervalli dettagliati per le librerie tramite hook di libreria o modifiche automatiche del codice, che richiedono modifiche minime al codice. [Per determinare se OpenTelemetry Library Instrumentations supporta la tua libreria, cercala nel Registro di sistema. OpenTelemetry OpenTelemetry ](https://opentelemetry.io/ecosystem/registry/) ### Esportazione di tracce X-Ray e OpenTelemetry utilizza diversi metodi per esportare i dati di traccia. #### Esportazione di tracce a raggi X Gli X-Ray SDKs utilizzano un emettitore per inviare dati di traccia: + Invia segmenti e sottosegmenti al demone X-Ray + Utilizza UDP per I/O non bloccanti + Configurato per impostazione predefinita nell'SDK #### OpenTelemetry traccia l'esportazione OpenTelemetry utilizza *Span Exporters configurabili per inviare dati* di traccia: + *Utilizza i protocolli *http/protobuf* o grpc* + Esporta gli intervalli verso gli endpoint monitorati dal Collector o dall'Agent OpenTelemetry CloudWatch + Consente configurazioni di esportazione personalizzate ### Elaborazione e inoltro delle tracce X-Ray e OpenTelemetry forniscono componenti per ricevere, elaborare e inoltrare dati di traccia. #### Elaborazione di tracce a raggi X Il demone X-Ray gestisce l'elaborazione delle tracce: + Ascolta il traffico UDP proveniente da X-Ray SDKs + Esegue in batch segmenti e sottosegmenti + Carica i batch sul servizio X-Ray #### OpenTelemetry elaborazione delle tracce Il OpenTelemetry Collector gestisce l'elaborazione delle tracce: + Riceve tracce dai servizi strumentati + Elabora e modifica facoltativamente i dati di traccia + Invia tracce elaborate a vari backend, incluso X-Ray **Nota** L' AWS CloudWatch agente può anche ricevere e inviare OpenTelemetry tracce a X-Ray. Per ulteriori informazioni, consulta [Raccogli metriche e tracce](AmazonCloudWatch/latest/monitoring/CloudWatch-Agent-OpenTelemetry-metrics.html) con. OpenTelemetry ### Elaborazione Span (concetto specifico) OpenTelemetry OpenTelemetry utilizza Span Processors per modificare gli span man mano che vengono creati: + Consente di leggere e modificare gli intervalli al momento della creazione o del completamento + Abilita una logica personalizzata per la gestione degli intervalli ### Bagaglio (concetto specifico) OpenTelemetry OpenTelemetryla funzione Baggage consente la propagazione di dati chiave-valore: + Consente il passaggio di dati arbitrari insieme al contesto di traccia + Utile per diffondere informazioni specifiche dell'applicazione oltre i confini del servizio [Per informazioni sul Collector, vedere OpenTelemetry Collector OpenTelemetry ](https://opentelemetry.io/docs/collector/) Per informazioni sui concetti di X-Ray, vedere X-Ray concepts [nella X-Ray Developer](https://docs.aws.amazon.com/xray/latest/devguide/xray-concepts.html) Guide ## Panoramica sulla migrazione Questa sezione fornisce una panoramica delle modifiche al codice necessarie per la migrazione. L'elenco seguente contiene linee guida specifiche per la lingua e le fasi di migrazione di X-Ray Daemon. **Importante** Per migrare completamente dalla strumentazione a raggi X alla strumentazione, OpenTelemetry è necessario: Sostituisci l'utilizzo di X-Ray SDK con una soluzione OpenTelemetry Sostituisci il demone X-Ray con l' CloudWatch agente o il OpenTelemetry raccoglitore (con X-Ray Exporter) + [OpenTelemetry Migrazione a Java](xray-migration-opentelemetry.md) + [Esegui la migrazione a OpenTelemetry Go](manual-instrumentation-go.md) + [Migrare a Node.js OpenTelemetry](migrate-xray-to-opentelemetry-nodejs.md) + [Esegui la migrazione a.NET OpenTelemetry](introduction-dotnet.md) + [Migrare a Python OpenTelemetry](migrate-xray-to-opentelemetry-python.md) + [Migra a Ruby OpenTelemetry](migrate-xray-to-opentelemetry-ruby.md) ### Raccomandazioni per applicazioni nuove ed esistenti Per le applicazioni nuove ed esistenti, si consiglia di utilizzare le seguenti soluzioni per abilitare la tracciabilità nelle applicazioni: Instrumentation + OpenTelemetry SDKs + AWS Distro per strumentazione OpenTelemetry Raccolta dati + OpenTelemetry Collezionista + CloudWatch Agente Dopo la migrazione a soluzioni OpenTelemetry basate, la tua CloudWatch esperienza rimarrà la stessa. Potrai comunque visualizzare le tue tracce nello stesso formato nelle pagine Traces e Trace Map della CloudWatch console o recuperare i dati di traccia tramite [X-Ray APIs](https://docs.aws.amazon.com/xray/latest/devguide/xray-api.html). ### Tracciamento delle modifiche alla configurazione È necessario sostituire la configurazione X-Ray con una OpenTelemetry configurazione. **Confronto tra X-Ray e configurazione OpenTelemetry** | Funzionalità | SDK X-Ray | OpenTelemetry | | --- | --- | --- | | Configurazioni predefinite | [See the AWS documentation website for more details](http://docs.aws.amazon.com/it_it/xray/latest/devguide/xray-sdk-migration.html) | [See the AWS documentation website for more details](http://docs.aws.amazon.com/it_it/xray/latest/devguide/xray-sdk-migration.html) | | Configurazioni manuali | [See the AWS documentation website for more details](http://docs.aws.amazon.com/it_it/xray/latest/devguide/xray-sdk-migration.html) | [See the AWS documentation website for more details](http://docs.aws.amazon.com/it_it/xray/latest/devguide/xray-sdk-migration.html) | ### Modifiche alla strumentazione della libreria Aggiorna il codice per utilizzare OpenTelemetry Library Instrumentation anziché X-Ray Library Instrumentation per AWS SDK, client HTTP, Web Frameworks e altre librerie. Questo genera OpenTelemetry Tracce anziché Tracce X-Ray. **Nota** Le modifiche al codice variano in base alla lingua e alla libreria. Per istruzioni dettagliate, consulta le guide alla migrazione specifiche per lingua. ### Modifiche alla strumentazione dell'ambiente Lambda Per utilizzarle OpenTelemetry nelle funzioni Lambda, scegli una di queste opzioni di configurazione: 1. Usa un Lambda Layer con strumentazione automatica: + (Consigliato) [AWS Lambda](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Application-Signals-Enable-LambdaMain.html) Layer per OpenTelemetry **Nota** Per utilizzare solo la traccia, imposta la variabile di ambiente Lambda. `OTEL_AWS_APPLICATION_SIGNALS_ENABLED=false` + [AWS Lambda Layer gestito per ADOT](https://aws-otel.github.io/docs/getting-started/lambda) 1. Configurazione manuale della OpenTelemetry funzione Lambda: + Configurazione di un processore Simple Span con un X-Ray UDP Span Exporter + Configurare un propagatore Lambda a raggi X ### Creazione manuale di dati di traccia Sostituisci i segmenti e i sottosegmenti X-Ray con Spans: OpenTelemetry + Usa un Tracer per creare Span OpenTelemetry + Aggiungi attributi a Spans (equivalente ai metadati e alle annotazioni X-Ray) **Importante** Quando viene inviato a X-Ray: Gli intervalli del server vengono convertiti in segmenti X-Ray Gli altri intervalli vengono convertiti in sottosegmenti X-Ray Gli attributi vengono convertiti in metadati per impostazione predefinita Per convertire un attributo in un'annotazione, aggiungete la relativa chiave all'elenco degli `aws.xray.annotations` attributi. Per ulteriori informazioni, vedere [Abilitare le annotazioni X-Ray personalizzate](https://aws-otel.github.io/docs/getting-started/x-ray#enable-the-customized-x-ray-annotations). ## Migrazione da X-Ray Daemon AWS CloudWatch a un agente o un raccoglitore OpenTelemetry È possibile utilizzare l' CloudWatch agente o il OpenTelemetry raccoglitore per ricevere tracce dalle applicazioni strumentate e inviarle a X-Ray. **Nota** La versione dell' CloudWatch agente 1.300025.0 e successive può raccogliere tracce. OpenTelemetry L'utilizzo dell' CloudWatch agente anziché del demone X-Ray riduce il numero di agenti da gestire. Per ulteriori informazioni, vedere [Raccolta di metriche, log e](AmazonCloudWatch/latest/monitoring/Install-CloudWatch-Agent.html) tracce con l'agente. CloudWatch **Topics** + [Migrazione su Amazon EC2 o server locali](#ec2-onprem-migration) + [Migrazione su Amazon ECS](#ecs-migration) + [Migrazione su Elastic Beanstalk](#beanstalk-migration) ### Migrazione su Amazon EC2 o server locali **Importante** Arresta il processo X-Ray Daemon prima di utilizzare l' CloudWatch agente o il OpenTelemetry raccoglitore per evitare conflitti tra le porte. #### Configurazione X-Ray Daemon esistente ##### Installazione del demone L'utilizzo esistente di X-Ray Daemon è stato installato utilizzando uno di questi metodi: Installazione manuale Scarica ed esegui il file eseguibile dal daemon X-Ray Amazon S3. Installazione automatica Utilizzate questo script per installare il demone all'avvio di un'istanza: ``` #!/bin/bash curl https://s3.us-east-2.amazonaws.com/aws-xray-assets.us-east-2/xray-daemon/aws-xray-daemon-3.x.rpm \ -o /home/ec2-user/xray.rpm yum install -y /home/ec2-user/xray.rpm ``` ##### Configurazione del daemon L'utilizzo esistente di X-Ray Daemon è stato configurato utilizzando uno dei seguenti metodi: + Argomenti della riga di comando + File di configurazione (`xray-daemon.yaml`) **Example Utilizzo di un file di configurazione** ``` ./xray -c ~/xray-daemon.yaml ``` ##### Esecuzione del daemon L'utilizzo esistente di X-Ray Daemon è stato avviato con il seguente comando: ``` ~/xray-daemon$ ./xray -o -n us-east-1 ``` ##### Rimozione del demone Per rimuovere il demone X-Ray dalla tua istanza Amazon EC2: 1. Arresta il servizio daemon: ``` systemctl stop xray ``` 1. Eliminare il file di configurazione: ``` rm ~/{{path}}/{{to}}/xray-daemon.yaml ``` 1. Se configurato, rimuovi il file di registro: **Nota** La posizione del file di registro dipende dalla configurazione: Configurazione della riga di comando: `/var/log/xray-daemon.log` File di configurazione: verifica l'`LogPath`impostazione #### Configurazione dell' CloudWatch agente ##### Installazione dell'agente Per le istruzioni di installazione, vedere [Installazione dell' CloudWatch agente su un server locale](AmazonCloudWatch/latest/monitoring/install-CloudWatch-Agent-commandline-fleet.html#install-CloudWatch-Agent-iam_user-first). ##### Configurazione dell'agente 1. Crea un file di configurazione per abilitare la raccolta delle tracce. Per ulteriori informazioni, vedere [Creazione del file di configurazione CloudWatch dell'agente](AmazonCloudWatch/latest/monitoring/create-cloudwatch-agent-configuration-file.html). 1. Configura le autorizzazioni IAM: + Allega un ruolo IAM o specifica le credenziali per l'agente. Per ulteriori informazioni, consulta [Configurazione dei ruoli IAM](AmazonCloudWatch/latest/monitoring/install-CloudWatch-Agent-commandline-fleet.html#install-CloudWatch-Agent-iam_permissions-first). + Assicurati che il ruolo o le credenziali includano l'`xray:PutTraceSegments`autorizzazione. ##### Avvio dell'agente di Per istruzioni su come avviare l'agente, consulta [Avvio dell' CloudWatch agente tramite la riga di comando](AmazonCloudWatch/latest/monitoring/install-CloudWatch-Agent-commandline-fleet.html#start-CloudWatch-Agent-EC2-commands-fleet). #### Configurazione del OpenTelemetry raccoglitore ##### Installazione del collettore Scaricate e installate il OpenTelemetry raccoglitore per il vostro sistema operativo. Per istruzioni, consultate [Installazione del raccoglitore](https://opentelemetry.io/docs/collector/installation/). ##### Configurazione del raccoglitore Configura i seguenti componenti nel tuo raccoglitore: + estensione awsproxy Necessario per il campionamento a raggi X + OTel ricevitori Raccoglie le tracce dall'applicazione + esportatore di raggi x Invia tracce a X-Ray **Example Esempio di configurazione del collettore: .yaml otel-collector-config** ``` extensions: awsproxy: endpoint: 127.0.0.1:2000 health_check: receivers: otlp: protocols: grpc: endpoint: 127.0.0.1:4317 http: endpoint: 127.0.0.1:4318 processors: batch: exporters: awsxray: region: 'us-east-1' service: pipelines: traces: receivers: [otlp] exporters: [awsxray] extensions: [awsproxy, health_check] ``` **Importante** Configura le AWS credenziali con l'autorizzazione. `xray:PutTraceSegments` Per ulteriori informazioni, vedere [Specificazione](sdk-for-go/v1/developer-guide/configuring-sdk.html#specifying-credentials) delle credenziali. ##### Avvio del raccoglitore Esegui il raccoglitore con il tuo file di configurazione: ``` otelcol --config=otel-collector-config.yaml ``` ### Migrazione su Amazon ECS **Importante** Il tuo ruolo di attività deve avere l'`xray:PutTraceSegments`autorizzazione per qualsiasi raccoglitore che utilizzi. Arresta qualsiasi contenitore X-Ray Daemon esistente prima di eseguire l' CloudWatch agente o il contenitore di OpenTelemetry raccolta sullo stesso host per evitare conflitti tra porte. #### Utilizzo dell'agente CloudWatch 1. Scarica l'immagine Docker da [Amazon ECR Public Gallery.](https://gallery.ecr.aws/cloudwatch-agent/cloudwatch-agent) 1. Crea un file di configurazione denominato: `cw-agent-otel.json` ``` { "traces": { "traces_collected": { "xray": { "tcp_proxy": { "bind_address": "0.0.0.0:2000" } }, "otlp": { "grpc_endpoint": "0.0.0.0:4317", "http_endpoint": "0.0.0.0:4318" } } } } ``` 1. Memorizza la configurazione in Systems Manager Parameter Store: 1. Aprire [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/) 1. Scegliete **Crea parametro** 1. Immetti uno dei seguenti valori: + Valore: `/ecs/cwagent/otel-config` + Livello: Standard + Tipo: String + Tipo di dati: testo + Valore: [Incolla qui la configurazione cw-agent-otel .json] 1. Crea una definizione di attività utilizzando la modalità di rete bridge: Nella tua definizione di attività, la configurazione dipende dalla modalità di rete utilizzata. La modalità di rete bridge è l'impostazione predefinita e può essere utilizzato nel VPC di default. In una rete bridge, imposta la variabile di `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` ambiente per indicare all' OpenTelemetry SDK quali sono l'endpoint e la porta per l' CloudWatch agente. È inoltre necessario creare un collegamento dal contenitore dell'applicazione al contenitore Collector per inviare le tracce dall' OpenTelemetry SDK dell'applicazione al contenitore Collector. **Example CloudWatch definizione del compito dell'agente** ``` { "containerDefinitions": [ { "name": "cwagent", "image": "public.ecr.aws/cloudwatch-agent/cloudwatch-agent:latest", "portMappings": [ { "containerPort": 4318, "hostPort": 4318, "protocol": "tcp" }, { "containerPort": 4317, "hostPort": 4317, "protocol": "tcp" }, { "containerPort": 2000, "hostPort": 2000, "protocol": "tcp" } ], "secrets": [ { "name": "CW_CONFIG_CONTENT", "valueFrom": "/ecs/cwagent/otel-config" } ] }, { "name": "application", "image": "APPLICATION_IMAGE", "links": ["cwagent"], "environment": [ { "name": "OTEL_EXPORTER_OTLP_TRACES_ENDPOINT", "value": "http://cwagent:4318/v1/traces" } ] } ] } ``` Per ulteriori informazioni, consulta [Implementazione dell' CloudWatch agente per raccogliere i parametri a livello di istanza di Amazon EC2 su Amazon ECS](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/deploy-container-insights-ECS-instancelevel.html). #### OpenTelemetry Utilizzo del raccoglitore 1. Ottieni l'immagine Docker `otel/opentelemetry-collector-contrib` da [Docker](https://hub.docker.com/r/otel/opentelemetry-collector-contrib) Hub. 1. Crea un file di configurazione chiamato `otel-collector-config.yaml` utilizzando lo stesso contenuto mostrato nella sezione **Amazon EC2 configuring the collector, ma aggiorna gli** endpoint per utilizzarli al posto di. `0.0.0.0` `127.0.0.1` 1. Per utilizzare questa configurazione in Amazon ECS, puoi archiviare la configurazione in Systems Manager Parameter Store. Innanzitutto, vai alla console di Systems Manager Parameter Store e scegli **Crea nuovo parametro**. Crea un nuovo parametro con le seguenti informazioni: + Nome:/ecs/otel/config(a questo nome verrà fatto riferimento nella definizione dell'attività per il raccoglitore) + Livello: Standard + Tipo: String + Tipo di dati: testo + Valore: [Incolla qui la otel-collector-config configurazione .yaml] 1. Crea una definizione di attività per distribuire il OpenTelemetry collettore utilizzando la modalità di rete bridge come esempio. Nella definizione dell'attività, la configurazione dipende dalla modalità di rete utilizzata. La modalità di rete bridge è l'impostazione predefinita e può essere utilizzato nel VPC di default. In una rete bridge, impostate la variabile di `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` ambiente per indicare all' OpenTelemetry SDK quali sono l'endpoint e la porta per il OpenTelemetry Collector. È inoltre necessario creare un collegamento dal contenitore dell'applicazione al contenitore Collector per inviare le tracce dall' OpenTelemetry SDK dell'applicazione al contenitore Collector. **Example OpenTelemetry definizione del compito del collettore** ``` { "containerDefinitions": [ { "name": "otel-collector", "image": "otel/opentelemetry-collector-contrib", "portMappings": [ { "containerPort": 2000, "hostPort": 2000 }, { "containerPort": 4317, "hostPort": 4317 }, { "containerPort": 4318, "hostPort": 4318 } ], "command": [ "--config", "env:SSM_CONFIG" ], "secrets": [ { "name": "SSM_CONFIG", "valueFrom": "/ecs/otel/config" } ] }, { "name": "application", "image": "APPLICATION_IMAGE", "links": ["otel-collector"], "environment": [ { "name": "OTEL_EXPORTER_OTLP_TRACES_ENDPOINT", "value": "http://otel-collector:4318/v1/traces" } ] } ] } ``` ### Migrazione su Elastic Beanstalk **Importante** Arresta il processo X-Ray Daemon prima di utilizzare l' CloudWatch agente per evitare conflitti tra le porte. L'integrazione X-Ray Daemon esistente è stata attivata utilizzando la console Elastic Beanstalk o configurando X-Ray Daemon nel codice sorgente dell'applicazione con un file di configurazione. #### Utilizzo dell'agente CloudWatch Sulla piattaforma Amazon Linux 2, configura l' CloudWatch agente utilizzando un file `.ebextensions` di configurazione: 1. Crea una directory denominata `.ebextensions` nella cartella principale del progetto 1. Crea un file denominato `cloudwatch.config` all'interno della `.ebextensions` directory con il seguente contenuto: ``` files: "/opt/aws/amazon-cloudwatch-agent/etc/config.json": mode: "0644" owner: root group: root content: | { "traces": { "traces_collected": { "otlp": { "grpc_endpoint": "12.0.0.1:4317", "http_endpoint": "12.0.0.1:4318" } } } } container_commands: start_agent: command: /opt/aws/amazon-cloudwatch-agent/bin/amazon-cloudwatch-agent-ctl -a append-config -c file:/opt/aws/amazon-cloudwatch-agent/etc/config.json -s ``` 1. Includi la `.ebextensions` directory nel bundle dei sorgenti dell'applicazione durante la distribuzione Per ulteriori informazioni sui file di configurazione di Elastic Beanstalk[, consulta Personalizzazione avanzata](elasticbeanstalk/latest/dg/ebextensions.html) dell'ambiente con file di configurazione.