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.
# OpenTelemetry Migrazione a Java
Questa sezione fornisce indicazioni sulla migrazione dall'SDK X-Ray all'SDK per le applicazioni SDK OpenTelemetry for Java.
**Topics**
+ [Soluzione di strumentazione automatica a codice zero](#xray-migration-zero-code)
+ [Soluzioni di strumentazione manuale con SDK](#xray-migration-sdk)
+ [Tracciamento delle richieste in arrivo (strumentazione Spring Framework)](#xray-migration-tracing-setup-otel)
+ [AWS Strumentazione SDK v2](#xray-migration-sdkv2)
+ [Analisi delle chiamate HTTP in uscita](#xray-migration-http)
+ [Supporto strumentale per altre librerie](#xray-migration-libraries)
+ [Creazione manuale dei dati di traccia](#xray-migration-tracedata)
+ [Strumentazione Lambda](#xray-migration-lambda)
## Soluzione di strumentazione automatica a codice zero
------
#### [ With X-Ray Java agent ]
Per abilitare l'agente X-Ray Java, era necessario modificare gli argomenti JVM dell'applicazione.
```
-javaagent:/path-to-disco/disco-java-agent.jar=pluginPath=/path-to-disco/disco-plugins
```
------
#### [ With OpenTelemetry-based Java agent ]
Per utilizzare agenti Java OpenTelemetry basati.
+ Utilizzate l'agente Java AWS Distro for OpenTelemetry (ADOT) Auto-Instrumentation per la strumentazione automatica con l'agente Java ADOT. Per ulteriori informazioni, vedete [Auto-Instrumentation](https://aws-otel.github.io/docs/getting-started/java-sdk/auto-instr) for Traces and Metrics with the Java agent. Se desideri solo tracciare, disabilita la variabile di `OTEL_METRICS_EXPORTER=none ` ambiente per esportare le metriche dall'agente Java.
(Facoltativo) È inoltre possibile abilitare CloudWatch Application Signals durante la strumentazione automatica delle applicazioni AWS con la strumentazione automatica ADOT Java per monitorare lo stato attuale delle applicazioni e tenere traccia delle prestazioni delle applicazioni a lungo termine. Application Signals offre una visione unificata e incentrata sulle applicazioni delle applicazioni, dei servizi e delle dipendenze e aiuta a monitorare e valutare lo stato delle applicazioni. Per ulteriori informazioni, consulta [Application Signals](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Application-Monitoring-Sections.html).
+ Utilizzate l'agente Java per la strumentazione automatica. OpenTelemetry Per ulteriori informazioni, vedete [Strumentazione a codice zero con Java Agent](https://opentelemetry.io/docs/zero-code/java/agent/).
------
## Soluzioni di strumentazione manuale con SDK
------
#### [ Tracing setup with X-Ray SDK ]
Per strumentare il codice con X-Ray SDK for Java, prima era necessario configurare la `AWSXRay` classe con plug-in di servizio e regole di campionamento locali, quindi è stato utilizzato un registratore fornito.
```
static { AWS XRayRecorderBuilder builder = AWS XRayRecorderBuilder.standard().withPlugin(new EC2Plugin()).withPlugin(new ECSPlugin()); AWS XRay.setGlobalRecorder(builder.build());
}
```
------
#### [ Tracing setup with OpenTelemetry SDK ]
Sono richieste le seguenti dipendenze.
```
io.opentelemetry
opentelemetry-bom
1.49.0
pom
import
io.opentelemetry.instrumentation
opentelemetry-instrumentation-bom
2.15.0
pom
import
io.opentelemetry
opentelemetry-sdk
io.opentelemetry
opentelemetry-api
io.opentelemetry.semconv
opentelemetry-semconv
io.opentelemetry
opentelemetry-exporter-otlp
io.opentelemetry.contrib
opentelemetry-aws-xray
1.46.0
io.opentelemetry.contrib
opentelemetry-aws-xray-propagator
1.46.0-alpha
io.opentelemetry.contrib
opentelemetry-aws-resources
1.46.0-alpha
```
Configura l' OpenTelemetry SDK creando un'istanza `TracerProvider` e registrando globalmente un oggetto. `OpenTelemetrySdk` Configura questi componenti:
+ Un OTLP Span Exporter (ad esempio, OtlpGrpcSpanExporter): necessario per esportare le tracce verso l'agente o il raccoglitore CloudWatch OpenTelemetry
+ Un propagatore AWS a raggi X: necessario per propagare il Trace Context ai AWS servizi integrati con X-Ray
+ Un campionatore remoto AWS a raggi X: necessario se è necessario campionare le richieste utilizzando le regole di campionamento a raggi X
+ Resource Detectors (ad esempio, EcsResource o Ec2Resource): rilevano i metadati dell'host che esegue l'applicazione
```
import io.opentelemetry.api.common.Attributes;
import io.opentelemetry.context.propagation.ContextPropagators;
import io.opentelemetry.contrib.aws.resource.Ec2Resource;
import io.opentelemetry.contrib.aws.resource.EcsResource;
import io.opentelemetry.contrib.awsxray.AwsXrayRemoteSampler;
import io.opentelemetry.contrib.awsxray.propagator.AwsXrayPropagator;
import io.opentelemetry.exporter.otlp.trace.OtlpGrpcSpanExporter;
import io.opentelemetry.sdk.OpenTelemetrySdk;
import io.opentelemetry.sdk.resources.Resource;
import io.opentelemetry.sdk.trace.SdkTracerProvider;
import io.opentelemetry.sdk.trace.export.BatchSpanProcessor;
import io.opentelemetry.sdk.trace.samplers.Sampler;
import static io.opentelemetry.semconv.ServiceAttributes.SERVICE_NAME;
// ...
private static final Resource otelResource =
Resource.create(Attributes.of(SERVICE_NAME, "YOUR_SERVICE_NAME"))
.merge(EcsResource.get())
.merge(Ec2Resource.get());
private static final SdkTracerProvider sdkTracerProvider =
SdkTracerProvider.builder()
.addSpanProcessor(BatchSpanProcessor.create(
OtlpGrpcSpanExporter.getDefault()
))
.addResource(otelResource)
.setSampler(Sampler.parentBased(
AwsXrayRemoteSampler.newBuilder(otelResource).build()
))
.build();
// Globally registering a TracerProvider makes it available throughout the application to create as many Tracers as needed.
private static final OpenTelemetrySdk openTelemetry =
OpenTelemetrySdk.builder()
.setTracerProvider(sdkTracerProvider)
.setPropagators(ContextPropagators.create(AwsXrayPropagator.getInstance()))
.buildAndRegisterGlobal();
```
------
## Tracciamento delle richieste in arrivo (strumentazione Spring Framework)
------
#### [ With X-Ray SDK ]
Per informazioni su come utilizzare X-Ray SDK con il framework Spring per strumentare l'applicazione, consulta [AOP with Spring e X-Ray SDK](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-java-aop-spring.html) for Java. Per abilitare AOP in Spring, completa questi passaggi.
1. [Configurare Spring](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-java-aop-spring.html#xray-sdk-java-aop-spring-configuration)
1. [Aggiungere un filtro di tracciamento all'applicazione](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-java-aop-spring.html#xray-sdk-java-aop-filters-spring)
1. [Annota il codice o implementa un'interfaccia](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-java-aop-spring.html#xray-sdk-java-aop-annotate-or-implement)
1. [Attivare X-Ray nell'applicazione](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-java-aop-spring.html#xray-sdk-java-aop-activate-xray)
------
#### [ With OpenTelemetry SDK ]
OpenTelemetry fornisce librerie di strumentazione per raccogliere tracce per le richieste in arrivo per le applicazioni Spring Boot. Per abilitare la strumentazione Spring Boot con una configurazione minima, includi la seguente dipendenza.
```
io.opentelemetry.instrumentation
opentelemetry-spring-boot-starter
```
[Per ulteriori informazioni su come abilitare e configurare la strumentazione Spring Boot per la OpenTelemetry configurazione, vedere Guida introduttiva. OpenTelemetry](https://opentelemetry.io/docs/zero-code/java/spring-boot-starter/getting-started/)
------
#### [ Using OpenTelemetry-based Java agents ]
Il metodo predefinito consigliato per strumentare le applicazioni Spring Boot consiste nell'utilizzare l'[agente OpenTelemetry Java](https://opentelemetry.io/docs/zero-code/java/agent/) con strumentazione *bytecode*, che fornisce anche più out-of-the-box strumentazioni e configurazioni rispetto all'utilizzo diretto dell'SDK. [Soluzione di strumentazione automatica a codice zero](#xray-migration-zero-code)Per iniziare, consulta.
------
## AWS Strumentazione SDK v2
------
#### [ With X-Ray SDK ]
L'X-Ray SDK for Java è in grado di strumentare automaticamente tutti i client AWS SDK v2 quando aggiungi il sottomodulo nella build. `aws-xray-recorder-sdk-aws-sdk-v2-instrumentor`
Per strumentare le chiamate dei client a valle dei singoli client ai AWS servizi con AWS SDK for Java 2.2 e versioni successive, `aws-xray-recorder-sdk-aws-sdk-v2-instrumentor ` il modulo dalla configurazione di build è stato escluso e `aws-xray-recorder-sdk-aws-sdk-v2` il modulo è stato incluso. I singoli client sono stati strumentati configurandoli con un. `TracingInterceptor`
```
import com.amazonaws.xray.interceptors.TracingInterceptor;
import software.amazon.awssdk.core.client.config.ClientOverrideConfiguration
import software.amazon.awssdk.services.dynamodb.DynamoDbClient;
//...
public class MyModel {
private DynamoDbClient client = DynamoDbClient.builder()
.region(Region.US_WEST_2)
.overrideConfiguration(
ClientOverrideConfiguration.builder()
.addExecutionInterceptor(new TracingInterceptor())
.build()
)
.build();
//...
```
------
#### [ With OpenTelemetry SDK ]
Per strumentare automaticamente tutti i client AWS SDK, aggiungi il sottomodulo. `opentelemetry-aws-sdk-2.2-autoconfigure`
```
io.opentelemetry.instrumentation
opentelemetry-aws-sdk-2.2-autoconfigure
2.15.0-alpha
runtime
```
Per strumentare i singoli client AWS SDK, aggiungi il sottomodulo. `opentelemetry-aws-sdk-2.2`
```
io.opentelemetry.instrumentation
opentelemetry-aws-sdk-2.2
2.15.0-alpha
compile
```
Quindi, registra un interceptor durante la creazione di un client SDK. AWS
```
import io.opentelemetry.instrumentation.awssdk.v2_2.AwsSdkTelemetry;
// ...
AwsSdkTelemetry telemetry = AwsSdkTelemetry.create(openTelemetry);
private final S3Client S3_CLIENT = S3Client.builder()
.overrideConfiguration(ClientOverrideConfiguration.builder()
.addExecutionInterceptor(telemetry.newExecutionInterceptor())
.build())
.build();
```
------
## Analisi delle chiamate HTTP in uscita
------
#### [ With X-Ray SDK ]
Per strumentare le richieste HTTP in uscita con X-Ray, era necessario l'X-Ray SDK per la versione di Apache di Java. HttpClient
```
import com.amazonaws.xray.proxies.apache.http.HttpClientBuilder;
...
public String randomName() throws IOException {
CloseableHttpClient httpclient = HttpClientBuilder.create().build();
```
------
#### [ With OpenTelemetry SDK ]
Analogamente a X-Ray Java SDK, OpenTelemetry fornisce una `ApacheHttpClientTelemetry` classe con un metodo builder che consente la creazione di un'istanza di un set `HttpClientBuilder` per fornire intervalli OpenTelemetry basati e propagazione del contesto per Apache. HttpClient
```
io.opentelemetry.instrumentation
opentelemetry-apache-httpclient-5.2
2.15.0-alpha
compile
```
Di seguito è riportato un esempio di codice tratto da. [opentelemetry-java-instrumentation](https://github.com/open-telemetry/opentelemetry-java-instrumentation/tree/main/instrumentation/apache-httpclient/apache-httpclient-5.2/library) Il client HTTP fornito da newHttpClient () genererà tracce per le richieste eseguite.
```
import io.opentelemetry.api.OpenTelemetry;
import io.opentelemetry.instrumentation.apachehttpclient.v5_2.ApacheHttpClientTelemetry;
import org.apache.hc.client5.http.classic.HttpClient;
import org.apache.hc.client5.http.impl.classic.HttpClientBuilder;
public class ApacheHttpClientConfiguration {
private OpenTelemetry openTelemetry;
public ApacheHttpClientConfiguration(OpenTelemetry openTelemetry) {
this.openTelemetry = openTelemetry;
}
// creates a new http client builder for constructing http clients with open telemetry instrumentation
public HttpClientBuilder createBuilder() {
return ApacheHttpClientTelemetry.builder(openTelemetry).build().newHttpClientBuilder();
}
// creates a new http client with open telemetry instrumentation
public HttpClient newHttpClient() {
return ApacheHttpClientTelemetry.builder(openTelemetry).build().newHttpClient();
}
}
```
------
## Supporto strumentale per altre librerie
Trova l'elenco completo delle strumentazioni di libreria supportate per OpenTelemetry Java nel rispettivo GitHub repository di strumentazione, in [Librerie, framework, server di applicazioni supportati](https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/main/docs/supported-libraries.md) e. JVMs
In alternativa, puoi cercare nel OpenTelemetry Registro per scoprire se supporta la strumentazione. OpenTelemetry [Per iniziare la ricerca, vedi Registro.](https://opentelemetry.io/ecosystem/registry/)
## Creazione manuale dei dati di traccia
------
#### [ With X-Ray SDK ]
Con X-Ray SDK, sono necessari i `beginSubsegment` metodi `beginSegment` and per creare manualmente segmenti e sottosegmenti X-Ray.
```
Segment segment = xrayRecorder.beginSegment("ManualSegment");
segment.putAnnotation("annotationKey", "annotationValue");
segment.putMetadata("metadataKey", "metadataValue");
try {
Subsegment subsegment = xrayRecorder.beginSubsegment("ManualSubsegment");
subsegment.putAnnotation("key", "value");
// Do something here
} catch (Exception e) {
subsegment.addException(e);
} finally {
xrayRecorder.endSegment();
}
```
------
#### [ With OpenTelemetry SDK ]
È possibile utilizzare intervalli personalizzati per monitorare le prestazioni delle attività interne che non vengono acquisite dalle librerie di strumentazione. Nota che solo i server di tipo span vengono convertiti in segmenti X-Ray, tutti gli altri span vengono convertiti in sottosegmenti X-Ray.
Innanzitutto, è necessario creare un *Tracer* per generare intervalli, che è possibile ottenere tramite il metodo. `openTelemetry.getTracer` Ciò fornirà un'istanza Tracer tra quelle registrate globalmente nell'esempio. `TracerProvider` [Soluzioni di strumentazione manuale con SDK](#xray-migration-sdk) È possibile creare tutte le istanze Tracer necessarie, ma è comune avere una sola istanza Tracer per un'intera applicazione.
```
Tracer tracer = openTelemetry.getTracer("my-app");
```
È possibile utilizzare Tracer per creare intervalli.
```
import io.opentelemetry.api.common.AttributeKey;
import io.opentelemetry.api.trace.Span;
import io.opentelemetry.api.trace.SpanKind;
import io.opentelemetry.api.trace.Tracer;
import io.opentelemetry.context.Scope;
...
// SERVER span will become an X-Ray segment
Span span = tracer.spanBuilder("get-token")
.setKind(SpanKind.SERVER)
.setAttribute("key", "value")
.startSpan();
try (Scope ignored = span.makeCurrent()) {
span.setAttribute("metadataKey", "metadataValue");
span.setAttribute("annotationKey", "annotationValue");
// The following ensures that "annotationKey: annotationValue" is an annotation in X-Ray raw data.
span.setAttribute(AttributeKey.stringArrayKey("aws.xray.annotations"), List.of("annotationKey"));
// Do something here
}
span.end();
```
*Gli intervalli hanno un tipo predefinito di INTERNAL.*
```
// Default span of type INTERNAL will become an X-Ray subsegment
Span span = tracer.spanBuilder("process-header")
.startSpan();
try (Scope ignored = span.makeCurrent()) {
doProcessHeader();
}
```
**Aggiungere annotazioni e metadati alle tracce con SDK OpenTelemetry **
Nell'esempio precedente, il `setAttribute` metodo viene utilizzato per aggiungere attributi a ogni intervallo. Per impostazione predefinita, tutti gli attributi span verranno convertiti in metadati nei dati grezzi X-Ray. Per garantire che un attributo venga convertito in un'annotazione e non in metadati, l'esempio precedente aggiunge la chiave di quell'attributo all'elenco dell'attributo. `aws.xray.annotations` [Per ulteriori informazioni, consulta [Abilitare le annotazioni e le annotazioni a raggi X personalizzate](https://aws-otel.github.io/docs/getting-started/x-ray#enable-the-customized-x-ray-annotations) e i metadati.](https://docs.aws.amazon.com/xray/latest/devguide/xray-concepts.html#xray-concepts-annotations)
**Con agenti Java basati OpenTelemetry**
Se si utilizza l'agente Java per strumentare automaticamente l'applicazione, è necessario eseguire la strumentazione manuale nell'applicazione. Ad esempio, al codice dello strumento all'interno dell'applicazione per sezioni che non sono coperte da alcuna libreria di strumentazione automatica.
Per eseguire la strumentazione manuale con l'agente, è necessario utilizzare l'artefatto. `opentelemetry-api ` La versione dell'artefatto non può essere più recente della versione dell'agente.
```
import io.opentelemetry.api.GlobalOpenTelemetry;
import io.opentelemetry.api.trace.Span;
// ...
Span parentSpan = Span.current();
Tracer tracer = GlobalOpenTelemetry.getTracer("my-app");
Span span = tracer.spanBuilder("my-span-name")
.setParent(io.opentelemetry.context.Context.current().with(parentSpan))
.startSpan();
span.end();
```
------
## Strumentazione Lambda
------
#### [ With X-Ray SDK ]
Utilizzando l'SDK X-Ray, dopo che Lambda ha abilitato l'*Active Tracing*, non è richiesta alcuna configurazione aggiuntiva per utilizzare l'SDK X-Ray. Lambda creerà un segmento che rappresenta l'invocazione del gestore Lambda e potrai creare sottosegmenti o librerie di strumenti utilizzando l'SDK X-Ray senza alcuna configurazione aggiuntiva.
------
#### [ With OpenTelemetry-based solutions ]
Strumentazione automatica Lambda: puoi strumentare automaticamente la tua Lambda AWS con strati Lambda venduti utilizzando le seguenti soluzioni:
+ AWS Lambda Layer per OpenTelemetry (consigliato)
**Nota**
Questo livello Lambda dispone di CloudWatch Application Signals abilitati per impostazione predefinita, il che consente il monitoraggio delle prestazioni e dello stato dell'applicazione Lambda raccogliendo sia metriche che tracce. Per il semplice tracciamento, imposta la variabile di ambiente Lambda. ` OTEL_AWS_APPLICATION_SIGNALS_ENABLED=false`
+ Consente il monitoraggio delle prestazioni e dello stato dell'applicazione Lambda
+ Per impostazione predefinita, raccoglie sia le metriche che le tracce
+ AWS layer Lambda gestito per ADOT Java. Per ulteriori informazioni, consulta [AWS Distro for OpenTelemetry Lambda Support](https://aws-otel.github.io/docs/getting-started/lambda/lambda-java) For Java.
Per utilizzare la strumentazione manuale insieme al livello di strumentazione automatica, vedere. [Soluzioni di strumentazione manuale con SDK](#xray-migration-sdk) Per ridurre gli avviamenti a freddo, prendi in considerazione OpenTelemetry l'utilizzo di strumentazione manuale per generare OpenTelemetry tracce per la tua funzione Lambda.
------
**OpenTelemetry strumentazione manuale per Lambda AWS **
Considera il seguente codice di funzione Lambda che effettua una chiamata Amazon ListBuckets S3.
```
package example;
import com.amazonaws.services.lambda.runtime.Context;
import com.amazonaws.services.lambda.runtime.RequestHandler;
import software.amazon.awssdk.services.s3.S3Client;
import software.amazon.awssdk.services.s3.model.ListBucketsRequest;
import software.amazon.awssdk.services.s3.model.ListBucketsResponse;
import software.amazon.awssdk.services.s3.model.S3Exception;
public class ListBucketsLambda implements RequestHandler {
private final S3Client S3_CLIENT = S3Client.builder()
.build();
@Override
public String handleRequest(String input, Context context) {
try {
ListBucketsResponse response = makeListBucketsCall();
context.getLogger().log("response: " + response.toString());
return "Success";
} catch (Exception e) {
throw new RuntimeException(e);
}
}
private ListBucketsResponse makeListBucketsCall() {
try {
ListBucketsRequest listBucketsRequest = ListBucketsRequest.builder()
.build();
ListBucketsResponse response = S3_CLIENT.listBuckets(listBucketsRequest);
return response;
} catch (S3Exception e) {
throw new RuntimeException("Failed to call S3 listBuckets" + e.awsErrorDetails().errorMessage(), e);
}
}
}
```
Ecco le dipendenze.
```
dependencies {
implementation('com.amazonaws:aws-lambda-java-core:1.2.3')
implementation('software.amazon.awssdk:s3:2.28.29')
implementation('org.slf4j:slf4j-nop:2.0.16')
}
```
Per strumentare manualmente il tuo gestore Lambda e il client Amazon S3, procedi come segue.
1. Sostituisci le classi di funzioni che implementano `RequestHandler` (o RequestStreamHandler) con quelle che estendono `TracingRequestHandler` (o). TracingRequestStreamHandler
1. Crea un'istanza TracerProvider e registra globalmente un OpenTelemetrySdk oggetto. Si TracerProvider consiglia di configurarlo con:
1. Un Simple Span Processor con un X-Ray UDP Span Exporter per inviare tracce all'endpoint UDP X-Ray di Lambda
1. Un campionatore sempre attivo (predefinito se non configurato ParentBased )
1. Una risorsa con service.name impostato sul nome della funzione Lambda
1. Un propagatore Lambda a raggi X
1. Modificate il `handleRequest` metodo `doHandleRequest` e passate l'`OpenTelemetrySdk`oggetto alla classe base.
1. Strumenta il client Amazon S3 con la strumentazione OpenTemetry AWS SDK registrando l'interceptor durante la creazione del client.
Sono OpenTelemetry necessarie le seguenti dipendenze correlate.
```
dependencies {
...
implementation("software.amazon.distro.opentelemetry:aws-distro-opentelemetry-xray-udp-span-exporter:0.1.0")
implementation(platform('io.opentelemetry.instrumentation:opentelemetry-instrumentation-bom:2.14.0'))
implementation(platform('io.opentelemetry:opentelemetry-bom:1.48.0'))
implementation('io.opentelemetry:opentelemetry-sdk')
implementation('io.opentelemetry:opentelemetry-api')
implementation('io.opentelemetry.contrib:opentelemetry-aws-xray-propagator:1.45.0-alpha')
implementation('io.opentelemetry.contrib:opentelemetry-aws-resources:1.45.0-alpha')
implementation('io.opentelemetry.instrumentation:opentelemetry-aws-lambda-core-1.0:2.14.0-alpha')
implementation('io.opentelemetry.instrumentation:opentelemetry-aws-sdk-2.2:2.14.0-alpha')
}
```
Il codice seguente illustra la funzione Lambda dopo le modifiche richieste. È possibile creare intervalli personalizzati aggiuntivi per completare gli intervalli forniti automaticamente.
```
package example;
import java.time.Duration;
import com.amazonaws.services.lambda.runtime.Context;
import io.opentelemetry.api.common.Attributes;
import io.opentelemetry.context.propagation.ContextPropagators;
import io.opentelemetry.contrib.aws.resource.LambdaResource;
import io.opentelemetry.contrib.awsxray.propagator.AwsXrayLambdaPropagator;
import io.opentelemetry.instrumentation.awslambdacore.v1_0.TracingRequestHandler;
import io.opentelemetry.instrumentation.awssdk.v2_2.AwsSdkTelemetry;
import io.opentelemetry.sdk.OpenTelemetrySdk;
import io.opentelemetry.sdk.resources.Resource;
import io.opentelemetry.sdk.trace.SdkTracerProvider;
import io.opentelemetry.sdk.trace.export.SimpleSpanProcessor;
import io.opentelemetry.sdk.trace.samplers.Sampler;
import static io.opentelemetry.semconv.ServiceAttributes.SERVICE_NAME;
import software.amazon.awssdk.core.client.config.ClientOverrideConfiguration;
import software.amazon.awssdk.services.s3.S3Client;
import software.amazon.awssdk.services.s3.model.ListBucketsRequest;
import software.amazon.awssdk.services.s3.model.ListBucketsResponse;
import software.amazon.awssdk.services.s3.model.S3Exception;
import software.amazon.distro.opentelemetry.exporter.xray.udp.trace.AwsXrayUdpSpanExporterBuilder;
public class ListBucketsLambda extends TracingRequestHandler {
private static final Resource lambdaResource = LambdaResource.get();
private static final SdkTracerProvider sdkTracerProvider =
SdkTracerProvider.builder()
.addSpanProcessor(SimpleSpanProcessor.create(
new AwsXrayUdpSpanExporterBuilder().build()
))
.addResource(
lambdaResource
.merge(Resource.create(Attributes.of(SERVICE_NAME, System.getenv("AWS_LAMBDA_FUNCTION_NAME"))))
)
.setSampler(Sampler.parentBased(Sampler.alwaysOn()))
.build();
private static final OpenTelemetrySdk openTelemetry =
OpenTelemetrySdk.builder()
.setTracerProvider(sdkTracerProvider)
.setPropagators(ContextPropagators.create(AwsXrayLambdaPropagator.getInstance()))
.buildAndRegisterGlobal();
private static final AwsSdkTelemetry telemetry = AwsSdkTelemetry.create(openTelemetry);
private final S3Client S3_CLIENT = S3Client.builder()
.overrideConfiguration(ClientOverrideConfiguration.builder()
.addExecutionInterceptor(telemetry.newExecutionInterceptor())
.build())
.build();
public ListBucketsLambda() {
super(openTelemetry, Duration.ofMillis(0));
}
@Override
public String doHandleRequest(String input, Context context) {
try {
ListBucketsResponse response = makeListBucketsCall();
context.getLogger().log("response: " + response.toString());
return "Success";
} catch (Exception e) {
throw new RuntimeException(e);
}
}
private ListBucketsResponse makeListBucketsCall() {
try {
ListBucketsRequest listBucketsRequest = ListBucketsRequest.builder()
.build();
ListBucketsResponse response = S3_CLIENT.listBuckets(listBucketsRequest);
return response;
} catch (S3Exception e) {
throw new RuntimeException("Failed to call S3 listBuckets" + e.awsErrorDetails().errorMessage(), e);
}
}
}
```
Quando si richiama la funzione Lambda, verrà visualizzata la seguente *traccia in* Trace Map nella CloudWatch console.
![\[Traccia la mappa nella console CloudWatch .\]](http://docs.aws.amazon.com/it_it/xray/latest/devguide/images/SDKDeprecation_Java.png)
# Esegui la migrazione a OpenTelemetry Go
Usa i seguenti esempi di codice per strumentare manualmente le tue applicazioni Go con l' OpenTelemetry SDK durante la migrazione da X-Ray.
## Strumentazione manuale con l'SDK
------
#### [ Tracing setup with X-Ray SDK ]
Quando si utilizzava X-Ray SDK for Go, era necessario configurare i plug-in di servizio o le regole di campionamento locali prima di utilizzare la strumentazione del codice.
```
func init() {
if os.Getenv("ENVIRONMENT") == "production" {
ec2.Init()
}
xray.Configure(xray.Config{
DaemonAddr: "127.0.0.1:2000",
ServiceVersion: "1.2.3",
})
}
```
------
#### [ Set up tracing with OpenTelemetry SDK ]
Configura l' OpenTelemetry SDK creando un'istanza e registrandolo come provider di tracciamento globale TracerProvider . Ti consigliamo di configurare i seguenti componenti:
+ OTLP Trace Exporter: necessario per esportare le tracce nell'agente o nel raccoglitore CloudWatch OpenTelemetry
+ X-Ray Propagator: necessario per propagare il contesto di traccia ai AWS servizi integrati con X-Ray
+ X-Ray Remote Sampler: necessario per le richieste di campionamento che utilizzano le regole di campionamento a raggi X
+ Rilevatori di risorse: per rilevare i metadati dell'host che esegue l'applicazione
```
import (
"go.opentelemetry.io/contrib/detectors/aws/ec2"
"go.opentelemetry.io/contrib/propagators/aws/xray"
"go.opentelemetry.io/contrib/samplers/aws/xray"
"go.opentelemetry.io/otel"
"go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc"
"go.opentelemetry.io/otel/sdk/trace"
)
func setupTracing() error {
ctx := context.Background()
exporterEndpoint := os.Getenv("OTEL_EXPORTER_OTLP_ENDPOINT")
if exporterEndpoint == "" {
exporterEndpoint = "localhost:4317"
}
traceExporter, err := otlptracegrpc.New(ctx,
otlptracegrpc.WithInsecure(),
otlptracegrpc.WithEndpoint(exporterEndpoint))
if err != nil {
return fmt.Errorf("failed to create OTLP trace exporter: %v", err)
}
remoteSampler, err := xray.NewRemoteSampler(ctx, "my-service-name", "ec2")
if err != nil {
return fmt.Errorf("failed to create X-Ray Remote Sampler: %v", err)
}
ec2Resource, err := ec2.NewResourceDetector().Detect(ctx)
if err != nil {
return fmt.Errorf("failed to detect EC2 resource: %v", err)
}
tp := trace.NewTracerProvider(
trace.WithSampler(remoteSampler),
trace.WithBatcher(traceExporter),
trace.WithResource(ec2Resource),
)
otel.SetTracerProvider(tp)
otel.SetTextMapPropagator(xray.Propagator{})
return nil
}
```
------
## Tracciamento delle richieste in arrivo (strumentazione del gestore HTTP)
------
#### [ With X-Ray SDK ]
Per strumentare un gestore HTTP con X-Ray, è stato utilizzato il metodo del gestore X-Ray per generare segmenti utilizzando. NewFixedSegmentNamer
```
func main() {
http.Handle("/", xray.Handler(xray.NewFixedSegmentNamer("myApp"), http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
w.Write([]byte("Hello!"))
})))
http.ListenAndServe(":8000", nil)
}
```
------
#### [ With OpenTelemetry SDK ]
Per strumentare un gestore HTTP OpenTelemetry, utilizzate il metodo NewHandler per racchiudere il codice OpenTelemetry del gestore originale.
```
import (
"go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp"
)
helloHandler := func(w http.ResponseWriter, req *http.Request) {
ctx := req.Context()
span := trace.SpanFromContext(ctx)
span.SetAttributes(attribute.Bool("isHelloHandlerSpan", true), attribute.String("attrKey", "attrValue"))
_, _ = io.WriteString(w, "Hello World!\n")
}
otelHandler := otelhttp.NewHandler(http.HandlerFunc(helloHandler), "Hello")
http.Handle("/hello", otelHandler)
err = http.ListenAndServe(":8080", nil)
if err != nil {
log.Fatal(err)
}
```
------
## AWS SDK per strumentazione Go v2
------
#### [ With X-Ray SDK ]
Per gestire le AWS richieste in uscita da AWS SDK, i vostri clienti hanno utilizzato la seguente strumentazione:
```
// Create a segment
ctx, root := xray.BeginSegment(context.TODO(), "AWSSDKV2_Dynamodb")
defer root.Close(nil)
cfg, err := config.LoadDefaultConfig(ctx, config.WithRegion("us-west-2"))
if err != nil {
log.Fatalf("unable to load SDK config, %v", err)
}
// Instrumenting AWS SDK v2
awsv2.AWSV2Instrumentor(&cfg.APIOptions)
// Using the Config value, create the DynamoDB client
svc := dynamodb.NewFromConfig(cfg)
// Build the request with its input parameters
_, err = svc.ListTables(ctx, &dynamodb.ListTablesInput{
Limit: aws.Int32(5),
})
if err != nil {
log.Fatalf("failed to list tables, %v", err)
}
```
------
#### [ With OpenTelemetry SDK ]
Il supporto di tracciamento per le chiamate AWS SDK downstream è fornito da SDK for AWS Go OpenTelemetry v2 Instrumentation. Ecco un esempio di tracciamento di una chiamata client S3:
```
import (
...
"github.com/aws/aws-sdk-go-v2/config"
"github.com/aws/aws-sdk-go-v2/service/s3"
"go.opentelemetry.io/otel"
oteltrace "go.opentelemetry.io/otel/trace"
awsConfig "github.com/aws/aws-sdk-go-v2/config"
"go.opentelemetry.io/contrib/instrumentation/github.com/aws/aws-sdk-go-v2/otelaws"
)
...
// init aws config
cfg, err := awsConfig.LoadDefaultConfig(ctx)
if err != nil {
panic("configuration error, " + err.Error())
}
// instrument all aws clients
otelaws.AppendMiddlewares(&.APIOptions)
// Call to S3
s3Client := s3.NewFromConfig(cfg)
input := &s3.ListBucketsInput{}
result, err := s3Client.ListBuckets(ctx, input)
if err != nil {
fmt.Printf("Got an error retrieving buckets, %v", err)
return
}
```
------
## Analisi delle chiamate HTTP in uscita
------
#### [ With X-Ray SDK ]
Per strumentare le chiamate HTTP in uscita con X-Ray, XRay.Client è stato utilizzato per creare una copia di un client HTTP fornito.
```
myClient := xray.Client(http-client)
resp, err := ctxhttp.Get(ctx, xray.Client(nil), url)
```
------
#### [ With OpenTelemetry SDK ]
Per strumentare i client HTTP, usa's otelhttp. OpenTelemetry OpenTelemetry NewTransport metodo per avvolgere l'http. DefaultTransport.
```
import (
"go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp"
)
// Create an instrumented HTTP client.
httpClient := &http.Client{
Transport: otelhttp.NewTransport(
http.DefaultTransport,
),
}
req, err := http.NewRequestWithContext(ctx, http.MethodGet, "https://api.github.com/repos/aws-observability/aws-otel-go/releases/latest", nil)
if err != nil {
fmt.Printf("failed to create http request, %v\n", err)
}
res, err := httpClient.Do(req)
if err != nil {
fmt.Printf("failed to make http request, %v\n", err)
}
// Request body must be closed
defer func(Body io.ReadCloser) {
err := Body.Close()
if err != nil {
fmt.Printf("failed to close http response body, %v\n", err)
}
}(res.Body)
```
------
## Supporto alla strumentazione per altre librerie
[Puoi trovare l'elenco completo delle strumentazioni di libreria supportate per OpenTelemetry Go nella sezione Pacchetti Instrumentation.](https://github.com/open-telemetry/opentelemetry-go-contrib/tree/main/instrumentation#instrumentation-packages)
[In alternativa, puoi cercare OpenTelemetry nel registro per scoprire se OpenTelemetry supporta la strumentazione per la tua libreria sotto Registry.](https://opentelemetry.io/ecosystem/registry/)
## Creazione manuale di dati di traccia
------
#### [ With X-Ray SDK ]
Con X-Ray SDK, erano necessari i BeginSubsegment metodi BeginSegment and per creare manualmente segmenti e sottosegmenti X-Ray.
```
// Start a segment
ctx, seg := xray.BeginSegment(context.Background(), "service-name")
// Start a subsegment
subCtx, subSeg := xray.BeginSubsegment(ctx, "subsegment-name")
// Add metadata or annotation here if necessary
xray.AddAnnotation(subCtx, "annotationKey", "annotationValue")
xray.AddMetadata(subCtx, "metadataKey", "metadataValue")
subSeg.Close(nil)
// Close the segment
seg.Close(nil)
```
------
#### [ With OpenTelemetry SDK ]
Utilizza intervalli personalizzati per monitorare le prestazioni delle attività interne che non vengono acquisite dalle librerie di strumentazione. Nota che solo gli intervalli di tipo Server vengono convertiti in segmenti X-Ray, tutti gli altri intervalli vengono convertiti in sottosegmenti X-Ray.
Innanzitutto, è necessario creare un Tracer per generare intervalli, che è possibile ottenere tramite il metodo. `otel.Tracer` Ciò fornirà un'istanza Tracer tra quelle registrate globalmente nell'esempio di Tracing Setup. TracerProvider È possibile creare tutte le istanze Tracer necessarie, ma è comune avere una sola istanza Tracer per un'intera applicazione.
```
tracer := otel.Tracer("application-tracer")
```
```
import (
...
oteltrace "go.opentelemetry.io/otel/trace"
)
...
var attributes = []attribute.KeyValue{
attribute.KeyValue{Key: "metadataKey", Value: attribute.StringValue("metadataValue")},
attribute.KeyValue{Key: "annotationKey", Value: attribute.StringValue("annotationValue")},
attribute.KeyValue{Key: "aws.xray.annotations", Value: attribute.StringSliceValue([]string{"annotationKey"})},
}
ctx := context.Background()
parentSpanContext, parentSpan := tracer.Start(ctx, "ParentSpan", oteltrace.WithSpanKind(oteltrace.SpanKindServer), oteltrace.WithAttributes(attributes...))
_, childSpan := tracer.Start(parentSpanContext, "ChildSpan", oteltrace.WithSpanKind(oteltrace.SpanKindInternal))
// ...
childSpan.End()
parentSpan.End()
```
**Aggiungere annotazioni e metadati alle tracce con SDK OpenTelemetry **
Nell'esempio precedente, il `WithAttributes` metodo viene utilizzato per aggiungere attributi a ogni intervallo. Si noti che per impostazione predefinita, tutti gli attributi span vengono convertiti in metadati nei dati grezzi di X-Ray. Per garantire che un attributo venga convertito in un'annotazione e non in metadati, aggiungete la chiave dell'attributo all'elenco dell'attributo. `aws.xray.annotations` 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).
------
## Strumentazione manuale Lambda
------
#### [ With X-Ray SDK ]
Con l'SDK X-Ray, dopo aver abilitato l'*Active Tracing* in Lambda, non erano necessarie configurazioni aggiuntive per utilizzare l'SDK X-Ray. Lambda ha creato un segmento che rappresenta l'invocazione del gestore Lambda e tu hai creato dei sottosegmenti utilizzando X-Ray SDK senza alcuna configurazione aggiuntiva.
------
#### [ With OpenTelemetry SDK ]
Il seguente codice di funzione Lambda (senza strumentazione) effettua una chiamata Amazon S3 e una richiesta HTTP in uscita ListBuckets .
```
package main
import (
"context"
"encoding/json"
"fmt"
"io"
"net/http"
"os"
"github.com/aws/aws-lambda-go/events"
"github.com/aws/aws-lambda-go/lambda"
awsconfig "github.com/aws/aws-sdk-go-v2/config"
"github.com/aws/aws-sdk-go-v2/service/s3"
)
func lambdaHandler(ctx context.Context) (interface{}, error) {
// Initialize AWS config.
cfg, err := awsconfig.LoadDefaultConfig(ctx)
if err != nil {
panic("configuration error, " + err.Error())
}
s3Client := s3.NewFromConfig(cfg)
// Create an HTTP client.
httpClient := &http.Client{
Transport: http.DefaultTransport,
}
input := &s3.ListBucketsInput{}
result, err := s3Client.ListBuckets(ctx, input)
if err != nil {
fmt.Printf("Got an error retrieving buckets, %v", err)
}
fmt.Println("Buckets:")
for _, bucket := range result.Buckets {
fmt.Println(*bucket.Name + ": " + bucket.CreationDate.Format("2006-01-02 15:04:05 Monday"))
}
fmt.Println("End Buckets.")
req, err := http.NewRequestWithContext(ctx, http.MethodGet, "https://api.github.com/repos/aws-observability/aws-otel-go/releases/latest", nil)
if err != nil {
fmt.Printf("failed to create http request, %v\n", err)
}
res, err := httpClient.Do(req)
if err != nil {
fmt.Printf("failed to make http request, %v\n", err)
}
defer func(Body io.ReadCloser) {
err := Body.Close()
if err != nil {
fmt.Printf("failed to close http response body, %v\n", err)
}
}(res.Body)
var data map[string]interface{}
err = json.NewDecoder(res.Body).Decode(&data)
if err != nil {
fmt.Printf("failed to read http response body, %v\n", err)
}
fmt.Printf("Latest ADOT Go Release is '%s'\n", data["name"])
return events.APIGatewayProxyResponse{
StatusCode: http.StatusOK,
Body: os.Getenv("_X_AMZN_TRACE_ID"),
}, nil
}
func main() {
lambda.Start(lambdaHandler)
}
```
Per strumentare manualmente il gestore Lambda e il client Amazon S3, procedi come segue:
1. In *main (), crea* un'istanza di a TracerProvider (tp) e registralo come fornitore globale di tracer. Si TracerProvider consiglia di configurarlo con:
1. Simple Span Processor con un esportatore di span UDP a raggi X per inviare tracce all'endpoint UDP X-Ray di Lambda
1. Risorsa con *service.name impostato sul nome* della funzione Lambda
1. Cambia l'utilizzo di to. `lambda.Start(lambdaHandler)` `lambda.Start(otellambda.InstrumentHandler(lambdaHandler, xrayconfig.WithRecommendedOptions(tp)...))`
1. Strumenta il client Amazon S3 con la strumentazione OpenTemetry AWS SDK aggiungendo OpenTelemetry middleware per `aws-sdk-go-v2` nella configurazione del client Amazon S3.
1. Strumenta il client http utilizzando il metodo's per avvolgere il. OpenTelemetry `otelhttp.NewTransport` `http.DefaultTransport`
Il codice seguente è un esempio di come apparirà la funzione Lambda dopo le modifiche. È possibile creare manualmente intervalli personalizzati aggiuntivi oltre agli intervalli forniti automaticamente.
```
package main
import (
"context"
"encoding/json"
"fmt"
"io"
"net/http"
"os"
"github.com/aws-observability/aws-otel-go/exporters/xrayudp"
"github.com/aws/aws-lambda-go/events"
"github.com/aws/aws-lambda-go/lambda"
awsconfig "github.com/aws/aws-sdk-go-v2/config"
"github.com/aws/aws-sdk-go-v2/service/s3"
lambdadetector "go.opentelemetry.io/contrib/detectors/aws/lambda"
"go.opentelemetry.io/contrib/instrumentation/github.com/aws/aws-lambda-go/otellambda"
"go.opentelemetry.io/contrib/instrumentation/github.com/aws/aws-lambda-go/otellambda/xrayconfig"
"go.opentelemetry.io/contrib/instrumentation/github.com/aws/aws-sdk-go-v2/otelaws"
"go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp"
"go.opentelemetry.io/contrib/propagators/aws/xray"
"go.opentelemetry.io/otel"
"go.opentelemetry.io/otel/attribute"
"go.opentelemetry.io/otel/sdk/resource"
"go.opentelemetry.io/otel/sdk/trace"
semconv "go.opentelemetry.io/otel/semconv/v1.26.0"
)
func lambdaHandler(ctx context.Context) (interface{}, error) {
// Initialize AWS config.
cfg, err := awsconfig.LoadDefaultConfig(ctx)
if err != nil {
panic("configuration error, " + err.Error())
}
// Instrument all AWS clients.
otelaws.AppendMiddlewares(&cfg.APIOptions)
// Create an instrumented S3 client from the config.
s3Client := s3.NewFromConfig(cfg)
// Create an instrumented HTTP client.
httpClient := &http.Client{
Transport: otelhttp.NewTransport(
http.DefaultTransport,
),
}
// return func(ctx context.Context) (interface{}, error) {
input := &s3.ListBucketsInput{}
result, err := s3Client.ListBuckets(ctx, input)
if err != nil {
fmt.Printf("Got an error retrieving buckets, %v", err)
}
fmt.Println("Buckets:")
for _, bucket := range result.Buckets {
fmt.Println(*bucket.Name + ": " + bucket.CreationDate.Format("2006-01-02 15:04:05 Monday"))
}
fmt.Println("End Buckets.")
req, err := http.NewRequestWithContext(ctx, http.MethodGet, "https://api.github.com/repos/aws-observability/aws-otel-go/releases/latest", nil)
if err != nil {
fmt.Printf("failed to create http request, %v\n", err)
}
res, err := httpClient.Do(req)
if err != nil {
fmt.Printf("failed to make http request, %v\n", err)
}
defer func(Body io.ReadCloser) {
err := Body.Close()
if err != nil {
fmt.Printf("failed to close http response body, %v\n", err)
}
}(res.Body)
var data map[string]interface{}
err = json.NewDecoder(res.Body).Decode(&data)
if err != nil {
fmt.Printf("failed to read http response body, %v\n", err)
}
fmt.Printf("Latest ADOT Go Release is '%s'\n", data["name"])
return events.APIGatewayProxyResponse{
StatusCode: http.StatusOK,
Body: os.Getenv("_X_AMZN_TRACE_ID"),
}, nil
}
func main() {
ctx := context.Background()
detector := lambdadetector.NewResourceDetector()
lambdaResource, err := detector.Detect(context.Background())
if err != nil {
fmt.Printf("failed to detect lambda resources: %v\n", err)
}
var attributes = []attribute.KeyValue{
attribute.KeyValue{Key: semconv.ServiceNameKey, Value: attribute.StringValue(os.Getenv("AWS_LAMBDA_FUNCTION_NAME"))},
}
customResource := resource.NewWithAttributes(semconv.SchemaURL, attributes...)
mergedResource, _ := resource.Merge(lambdaResource, customResource)
xrayUdpExporter, _ := xrayudp.NewSpanExporter(ctx)
tp := trace.NewTracerProvider(
trace.WithSpanProcessor(trace.NewSimpleSpanProcessor(xrayUdpExporter)),
trace.WithResource(mergedResource),
)
defer func(ctx context.Context) {
err := tp.Shutdown(ctx)
if err != nil {
fmt.Printf("error shutting down tracer provider: %v", err)
}
}(ctx)
otel.SetTracerProvider(tp)
otel.SetTextMapPropagator(xray.Propagator{})
lambda.Start(otellambda.InstrumentHandler(lambdaHandler, xrayconfig.WithRecommendedOptions(tp)...))
}
```
------
Quando richiami Lambda, vedrai la seguente traccia `Trace Map` nella CloudWatch console:
![\[Traccia la mappa nella CloudWatch console per Golang.\]](http://docs.aws.amazon.com/it_it/xray/latest/devguide/images/deprecation_golang.png)
# Migrare a Node.js OpenTelemetry
Questa sezione spiega come migrare le applicazioni Node.js da X-Ray SDK a. OpenTelemetry Descrive gli approcci di strumentazione sia automatici che manuali e fornisce esempi specifici per casi d'uso comuni.
L'SDK X-Ray Node.js consente di strumentare manualmente le applicazioni Node.js per il tracciamento. Questa sezione fornisce esempi di codice per la migrazione da OpenTelemetry X-Ray alla strumentazione.
**Topics**
+ [Soluzioni di strumentazione automatica a codice zero](#zero-code-instrumentation)
+ [Soluzioni di strumentazione manuale](#manual-instrumentation)
+ [Tracciamento delle richieste in arrivo](#tracing-incoming-requests)
+ [AWS Strumentazione SDK V3 JavaScript](#aws-sdk-instrumentation)
+ [Analisi delle chiamate HTTP in uscita](#http-instrumentation)
+ [Supporto alla strumentazione per altre librerie](#other-libraries)
+ [Creazione manuale di dati di traccia](#manual-trace-creation)
+ [Strumentazione Lambda](#lambda-instrumentation)
## Soluzioni di strumentazione automatica a codice zero
Per tracciare le richieste con X-Ray SDK per Node.js, è necessario modificare il codice dell'applicazione. Con OpenTelemetry, puoi utilizzare soluzioni di strumentazione automatica a codice zero per tracciare le richieste.
**Strumentazione automatica a codice zero con strumentazione automatica basata. OpenTelemetry**
1. Utilizzo della strumentazione automatica AWS Distro for OpenTelemetry (ADOT) per Node.js: per la strumentazione automatica per l'applicazione Node.js, vedere [Tracciamento](https://aws-otel.github.io/docs/getting-started/js-sdk/trace-metric-auto-instr) e metriche con la distribuzione per la strumentazione automatica. AWS OpenTelemetry JavaScript
(Facoltativo) È inoltre possibile abilitare CloudWatch Application Signals quando si attivano automaticamente le applicazioni AWS con la strumentazione JavaScript automatica ADOT per monitorare lo stato attuale delle applicazioni e tenere traccia delle prestazioni delle applicazioni a lungo termine rispetto agli obiettivi aziendali. Application Signals ti offre una visione unificata e incentrata sulle applicazioni di applicazioni, servizi e dipendenze e ti aiuta a monitorare e valutare lo stato delle applicazioni. Per ulteriori informazioni, consulta [Application Signals](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Application-Monitoring-Sections.html).
1. [Utilizzo della strumentazione automatica a OpenTelemetry JavaScript codice zero: per la strumentazione automatica con, vedere strumentazione a codice zero. OpenTelemetry JavaScript JavaScript ](https://opentelemetry.io/docs/zero-code/js/)
## Soluzioni di strumentazione manuale
------
#### [ Tracing setup with X-Ray SDK ]
Quando si utilizzava X-Ray SDK per Node.js, era necessario configurare il `aws-xray-sdk` pacchetto X-Ray SDK con plug-in di servizio o regole di campionamento locali prima di utilizzare l'SDK per strumentare il codice.
```
var AWSXRay = require('aws-xray-sdk');
AWSXRay.config([AWSXRay.plugins.EC2Plugin,AWSXRay.plugins.ElasticBeanstalkPlugin]);
AWSXRay.middleware.setSamplingRules();
```
------
#### [ Tracing setup with OpenTelemetry SDK ]
**Nota**
AWS Il campionamento remoto a raggi X non è attualmente disponibile per la configurazione per JS. OpenTelemetry Tuttavia, il supporto per il campionamento remoto a raggi X è attualmente disponibile tramite ADOT Auto-Instrumentation for Node.js.
Per l'esempio di codice riportato di seguito, sono necessarie le seguenti dipendenze:
```
npm install --save \
@opentelemetry/api \
@opentelemetry/sdk-node \
@opentelemetry/exporter-trace-otlp-proto \
@opentelemetry/propagator-aws-xray \
@opentelemetry/resource-detector-aws
```
È necessario impostare e configurare l' OpenTelemetry SDK prima di eseguire il codice dell'applicazione. Questa operazione può essere eseguita utilizzando il flag [—-require](https://nodejs.org/api/cli.html#-r---require-module). Create un file chiamato *instrumentation.js*, che conterrà la configurazione e la configurazione della OpenTelemetry strumentazione.
Si consiglia di configurare i seguenti componenti:
+ OTLPTraceEsportatore: necessario per esportare le tracce nell'Agent/ Collector CloudWatch OpenTelemetry
+ AWSXRayPropagatore: necessario per propagare il Trace Context ai AWS servizi integrati con X-Ray
+ Rilevatori di risorse (ad esempio, Amazon EC2 Resource Detector): per rilevare i metadati dell'host che esegue l'applicazione
```
/*instrumentation.js*/
// Require dependencies
const { NodeSDK } = require('@opentelemetry/sdk-node');
const { OTLPTraceExporter } = require('@opentelemetry/exporter-trace-otlp-proto');
const { AWSXRayPropagator } = require("@opentelemetry/propagator-aws-xray");
const { detectResources } = require('@opentelemetry/resources');
const { awsEc2Detector } = require('@opentelemetry/resource-detector-aws');
const resource = detectResources({
detectors: [awsEc2Detector],
});
const _traceExporter = new OTLPTraceExporter({
url: 'http://localhost:4318/v1/traces'
});
const sdk = new NodeSDK({
resource: resource,
textMapPropagator: new AWSXRayPropagator(),
traceExporter: _traceExporter
});
sdk.start();
```
Quindi, puoi eseguire l'applicazione con la tua configurazione, ad esempio: OpenTelemetry
```
node --require ./instrumentation.js app.js
```
Puoi utilizzare la strumentazione della libreria OpenTelemetry SDK per creare automaticamente intervalli per librerie come l'SDK. AWS Abilitandoli si creeranno automaticamente degli intervalli per moduli come l'SDK per la v3. AWS JavaScript OpenTelemetry offre la possibilità di abilitare tutte le strumentazioni della libreria o specificare quali strumentazioni della libreria abilitare.
Per abilitare tutte le strumentazioni, installa il pacchetto: `@opentelemetry/auto-instrumentations-node`
```
npm install @opentelemetry/auto-instrumentations-node
```
Successivamente, aggiorna la configurazione per abilitare tutte le strumentazioni della libreria come mostrato di seguito.
```
const { getNodeAutoInstrumentations } = require('@opentelemetry/auto-instrumentations-node');
...
const sdk = new NodeSDK({
resource: resource,
instrumentations: [getNodeAutoInstrumentations()],
textMapPropagator: new AWSXRayPropagator(),
traceExporter: _traceExporter
});
```
------
#### [ Tracing setup with ADOT auto-instrumentation for Node.js ]
È possibile utilizzare la strumentazione automatica ADOT per Node.js OpenTelemetry per configurare automaticamente le applicazioni Node.js. Utilizzando ADOT Auto-Instrumentation, non è necessario apportare modifiche manuali al codice per tracciare le richieste in arrivo o tracciare librerie come i client SDK o HTTP. AWS Per ulteriori informazioni, consulta [Tracciamento e metriche con la distribuzione per Auto-Instrumentation](https://aws-otel.github.io/docs/getting-started/js-sdk/trace-metric-auto-instr). AWS OpenTelemetry JavaScript
La strumentazione automatica ADOT per Node.js supporta:
+ Campionamento remoto a raggi X tramite variabile di ambiente — `export OTEL_TRACES_SAMPLER=xray`
+ Propagazione contestuale delle tracce X-Ray (abilitata per impostazione predefinita)
+ Rilevamento delle risorse (il rilevamento delle risorse per gli ambienti Amazon EC2, Amazon ECS e Amazon EKS è abilitato per impostazione predefinita)
+ Strumentazioni di libreria automatiche per tutte le strumentazioni supportate, che possono essere OpenTelemetry utilizzate selettivamente tramite variabili di ambiente disabled/enabled `OTEL_NODE_ENABLED_INSTRUMENTATIONS` `OTEL_NODE_DISABLED_INSTRUMENTATIONS`
+ Creazione manuale di Spans
------
## Tracciamento delle richieste in arrivo
------
#### [ With X-Ray SDK ]
**Express.js**
Grazie all'SDK X-Ray per tracciare le richieste HTTP in entrata ricevute dalle applicazioni *Express.js*, i due middleware `AWSXRay.express.openSegment()` e i due middleware `AWSXRay.express.closeSegment()` dovevano avvolgere tutte le rotte definite per poterle tracciare.
```
app.use(xrayExpress.openSegment('defaultName'));
...
app.use(xrayExpress.closeSegment());
```
**Restifica**
Per tracciare le richieste HTTP in entrata ricevute dalle `Restify` applicazioni, è stato utilizzato il middleware dell'X-Ray SDK eseguendo enable dal modulo sul `aws-xray-sdk-restify ` server Restify:
```
var AWSXRay = require('aws-xray-sdk');
var AWSXRayRestify = require('aws-xray-sdk-restify');
var restify = require('restify');
var server = restify.createServer();
AWSXRayRestify.enable(server, 'MyApp'));
```
------
#### [ With OpenTelemetry SDK ]
**Express.js**
[Il supporto di tracciamento per le richieste in entrata di `Express.js` è fornito dalla [strumentazione OpenTelemetry HTTP e dalla strumentazione express.](https://github.com/open-telemetry/opentelemetry-js/tree/main/experimental/packages/opentelemetry-instrumentation-http) OpenTelemetry ](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-express) Installa le seguenti dipendenze con: `npm`
```
npm install --save @opentelemetry/instrumentation-http @opentelemetry/instrumentation-express
```
Aggiorna la configurazione OpenTelemetry SDK per abilitare la strumentazione per il modulo express:
```
const { HttpInstrumentation } = require('@opentelemetry/instrumentation-http');
const { ExpressInstrumentation } = require('@opentelemetry/instrumentation-express');
...
const sdk = new NodeSDK({
...
instrumentations: [
...
// Express instrumentation requires HTTP instrumentation
new HttpInstrumentation(),
new ExpressInstrumentation(),
],
});
```
**Restifica**
Per le applicazioni Restify, avrai bisogno della strumentazione [OpenTelemetry Restify](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-restify). Installa la seguente dipendenza:
```
npm install --save @opentelemetry/instrumentation-restify
```
Aggiorna la configurazione OpenTelemetry SDK per abilitare la strumentazione per il modulo restify:
```
const { RestifyInstrumentation } = require('@opentelemetry/instrumentation-restify');
...
const sdk = new NodeSDK({
...
instrumentations: [
...
new RestifyInstrumentation(),
],
});
```
------
## AWS Strumentazione SDK V3 JavaScript
------
#### [ With X-Ray SDK ]
Per strumentare AWS le richieste in uscita dall' AWS SDK, avete utilizzato client strumentati come nell'esempio seguente:
```
import { S3, PutObjectCommand } from '@aws-sdk/client-s3';
const s3 = AWSXRay.captureAWSv3Client(new S3({}));
await s3.send(new PutObjectCommand({
Bucket: bucketName,
Key: keyName,
Body: 'Hello!',
}));
```
------
#### [ With OpenTelemetry SDK ]
Il supporto di tracciamento per le chiamate AWS SDK downstream a DynamoDB, Amazon S3 e altri è fornito dalla strumentazione SDK. OpenTelemetry AWS `npm`Installa la seguente dipendenza con:
```
npm install --save @opentelemetry/instrumentation-aws-sdk
```
Aggiorna la configurazione OpenTelemetry SDK con la strumentazione AWS SDK.
```
import { AwsInstrumentation } from '@opentelemetry/instrumentation-aws-sdk';
...
const sdk = new NodeSDK({
...
instrumentations: [
...
new AwsInstrumentation()
],
});
```
------
## Analisi delle chiamate HTTP in uscita
------
#### [ With X-Ray SDK ]
Per strumentare le richieste HTTP in uscita con X-Ray, era necessario strumentare i client. Ad esempio, vedi sotto.
Client HTTP individuali
```
var AWSXRay = require('aws-xray-sdk');
var http = AWSXRay.captureHTTPs(require('http'));
```
Tutti i client HTTP (globali)
```
var AWSXRay = require('aws-xray-sdk');
AWSXRay.captureHTTPsGlobal(require('http'));
var http = require('http');
```
------
#### [ With OpenTelemetry SDK ]
Il supporto di tracciamento per i client HTTP Node.js è fornito da OpenTelemetry HTTP Instrumentation. Installa la seguente dipendenza con: `npm`
```
npm install --save @opentelemetry/instrumentation-http
```
Aggiorna la configurazione OpenTelemetry SDK come segue:
```
const { HttpInstrumentation } = require('@opentelemetry/instrumentation-http');
...
const sdk = new NodeSDK({
...
instrumentations: [
...
new HttpInstrumentation(),
],
});
```
------
## Supporto alla strumentazione per altre librerie
[Puoi trovare l'elenco completo delle strumentazioni di libreria supportate nella sezione Strumentazioni supportate OpenTelemetry JavaScript .](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/metapackages/auto-instrumentations-node#supported-instrumentations)
[In alternativa, puoi cercare OpenTelemetry nel registro per scoprire se OpenTelemetry supporta la strumentazione per la tua libreria alla voce Registry.](https://opentelemetry.io/ecosystem/registry/)
## Creazione manuale di dati di traccia
------
#### [ With X-Ray SDK ]
Utilizzando X-Ray, il codice del `aws-xray-sdk` pacchetto era necessario per creare manualmente i segmenti e i relativi sottosegmenti secondari per tracciare l'applicazione.
```
var AWSXRay = require('aws-xray-sdk');
AWSXRay.enableManualMode();
var segment = new AWSXRay.Segment('myApplication');
captureFunc('1', function(subsegment1) {
captureFunc('2', function(subsegment2) {
}, subsegment1);
}, segment);
segment.close();
segment.flush();
```
------
#### [ With OpenTelemetry SDK ]
È possibile creare e utilizzare intervalli personalizzati per monitorare le prestazioni delle attività interne che non vengono acquisite dalle librerie di strumentazione. Nota che solo gli intervalli di tipo Server vengono convertiti in segmenti X-Ray, tutti gli altri intervalli vengono convertiti in sottosegmenti X-Ray. Per ulteriori informazioni, consulta [Segmenti](https://docs.aws.amazon.com/xray/latest/devguide/xray-concepts.html#xray-concepts-segments).
Avrai bisogno di un'istanza Tracer dopo aver configurato l'SDK in Tracing Setup per creare Spans OpenTelemetry . È possibile creare tutte le istanze Tracer necessarie, ma è normale avere una sola istanza Tracer per un'intera applicazione.
```
const { trace, SpanKind } = require('@opentelemetry/api');
// Get a tracer instance
const tracer = trace.getTracer('your-tracer-name');
...
// This span will appear as a segment in X-Ray
tracer.startActiveSpan('server', { kind: SpanKind.SERVER }, span => {
// Do work here
// This span will appear as a subsegment in X-Ray
tracer.startActiveSpan('operation2', { kind: SpanKind.INTERNAL }, innerSpan => {
// Do more work here
innerSpan.end();
});
span.end();
});
```
**Aggiungere annotazioni e metadati alle tracce con SDK OpenTelemetry **
Puoi anche aggiungere coppie chiave-valore personalizzate come attributi nei tuoi span. Nota che per impostazione predefinita, tutti questi attributi span verranno convertiti in metadati nei dati grezzi di X-Ray. Per garantire che un attributo venga convertito in un'annotazione e non in metadati, aggiungete la chiave dell'attributo all'elenco dell'attributo. `aws.xray.annotations` 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).
```
tracer.startActiveSpan('server', { kind: SpanKind.SERVER }, span => {
span.setAttribute('metadataKey', 'metadataValue');
span.setAttribute('annotationKey', 'annotationValue');
// The following ensures that "annotationKey: annotationValue" is an annotation in X-Ray raw data.
span.setAttribute('aws.xray.annotations', ['annotationKey']);
// Do work here
span.end();
});
```
------
## Strumentazione Lambda
------
#### [ With X-Ray SDK ]
Dopo aver abilitato *Active Tracing* per la funzione Lambda, era necessario l'SDK X-Ray senza alcuna configurazione aggiuntiva. Lambda crea un segmento che rappresenta l'invocazione del gestore Lambda e hai creato sottosegmenti o librerie di strumenti utilizzando l'SDK X-Ray senza alcuna configurazione aggiuntiva.
------
#### [ With OpenTelemetry SDK ]
Puoi strumentare automaticamente la tua Lambda con livelli Lambda AWS venduti. Esistono due soluzioni:
+ (Consigliato) AWS Lambda Layer per OpenTelemetry
**Nota**
Questo livello Lambda dispone di CloudWatch Application Signals abilitati per impostazione predefinita, il che consente il monitoraggio delle prestazioni e dello stato dell'applicazione Lambda raccogliendo sia metriche che tracce. Se vuoi solo tracciare, devi impostare la variabile di ambiente Lambda. `OTEL_AWS_APPLICATION_SIGNALS_ENABLED=false` Per ulteriori informazioni, consulta [Abilita le tue applicazioni su Lambda](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Application-Signals-Enable-LambdaMain.html).
+ AWS layer Lambda gestito per ADOT JS. Per ulteriori informazioni, consulta [AWS Distro for OpenTelemetry Lambda Support JavaScript For](https://aws-otel.github.io/docs/getting-started/lambda/lambda-js).
**Creazione manuale di Span con strumentazione Lambda**
Sebbene ADOT JavaScript Lambda Layer fornisca la strumentazione automatica per la funzione Lambda, potresti riscontrare la necessità di eseguire la strumentazione manuale nella tua Lambda, ad esempio, per fornire dati personalizzati o per il codice dello strumento all'interno della funzione Lambda stessa che non è coperto dalla strumentazione della libreria.
Per eseguire la strumentazione manuale insieme alla strumentazione automatica, è necessario aggiungerla come dipendenza. `@opentelemetry/api` Si consiglia che la versione di questa dipendenza sia la stessa della stessa dipendenza utilizzata da ADOT SDK. JavaScript Puoi utilizzare l' OpenTelemetry API per creare manualmente intervalli nella tua funzione Lambda.
Per aggiungere la `@opentelemetry/api` dipendenza usando NPM:
```
npm install @opentelemetry/api
```
------
# Esegui la migrazione a.NET OpenTelemetry
Quando si utilizza X-Ray Tracing nelle applicazioni.NET, per la strumentazione viene utilizzato l'SDK X-Ray .NET con operazioni manuali.
Questa sezione fornisce esempi di codice nella [Soluzioni di strumentazione manuale con SDK](#manual-instrumentation-dotnet) sezione per la migrazione dalla soluzione di strumentazione manuale X-Ray OpenTelemetry alle soluzioni di strumentazione manuale per.NET. In alternativa, è possibile migrare dalla strumentazione manuale X-Ray alle soluzioni di strumentazione automatica OpenTelemetry alle applicazioni.NET dello strumento senza dover modificare il codice sorgente dell'applicazione nella sezione. [Soluzioni di strumentazione automatica a codice zero](#zero-code-instrumentation-dotnet)
**Topics**
+ [Soluzioni di strumentazione automatica a codice zero](#zero-code-instrumentation-dotnet)
+ [Soluzioni di strumentazione manuale con SDK](#manual-instrumentation-dotnet)
+ [Creazione manuale di dati di traccia](#manual-trace-creation-dotnet)
+ [Tracciamento delle richieste in arrivo (strumentazione di base ASP.NET e ASP.NET)](#tracing-incoming-requests-dotnet)
+ [AWS Strumentazione SDK](#aws-sdk-instrumentation-dotnet)
+ [Analisi delle chiamate HTTP in uscita](#http-instrumentation-dotnet)
+ [Supporto alla strumentazione per altre librerie](#other-libraries-dotnet)
+ [Strumentazione Lambda](#lambda-instrumentation)
## Soluzioni di strumentazione automatica a codice zero
OpenTelemetry fornisce soluzioni di strumentazione automatica a codice zero. Queste soluzioni tracciano le richieste senza richiedere modifiche al codice dell'applicazione.
**OpenTelemetryopzioni di strumentazione automatica basate su**
1. Utilizzo della strumentazione automatica AWS Distro for OpenTelemetry (ADOT) per .NET: per strumentare automaticamente le applicazioni.NET, vedere [Tracciamento e metriche](https://aws-otel.github.io/docs/getting-started/dotnet-sdk/auto-instr) con la distribuzione per strumentazione automatica.NET. AWS OpenTelemetry
(Facoltativo) Abilita i segnali CloudWatch applicativi durante la strumentazione automatica delle applicazioni AWS con la strumentazione automatica ADOT .NET per:
+ Monitora lo stato attuale delle applicazioni
+ Monitora le prestazioni delle applicazioni a lungo termine rispetto agli obiettivi aziendali
+ Ottieni una visione unificata e incentrata sulle applicazioni delle tue applicazioni, dei tuoi servizi e delle tue dipendenze
+ Monitora e valuta lo stato delle applicazioni
Per ulteriori informazioni, consulta [Application Signals](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Application-Monitoring-Sections.html).
1. Utilizzo della strumentazione OpenTelemetry automatica.Net a codice zero: per strumentare automaticamente con OpenTelemetry .Net, vedi [Tracciamento e metriche](https://aws-otel.github.io/docs/getting-started/dotnet-sdk/auto-instr) con la distribuzione per la strumentazione automatica.NET. AWS OpenTelemetry
## Soluzioni di strumentazione manuale con SDK
------
#### [ Tracing configuration with X-Ray SDK ]
Per le applicazioni Web.NET, l'SDK X-Ray è configurato nella sezione AppSettings del file. `Web.config`
Esempio Web.config
```
```
Per .NET Core, viene utilizzato un file denominato `appsettings.json` con una chiave di primo livello denominata`XRay`, quindi viene creato un oggetto di configurazione per inizializzare il registratore X-Ray.
Esempio per.NET `appsettings.json`
```
{
"XRay": {
"AWSXRayPlugins": "EC2Plugin"
}
}
```
Esempio di configurazione di.NET Core Program.cs — Recorder
```
using Amazon.XRay.Recorder.Core;
...
AWSXRayRecorder.InitializeInstance(configuration);
```
------
#### [ Tracing configuration with OpenTelemetry SDK ]
****
Aggiungi queste dipendenze:
```
dotnet add package OpenTelemetry
dotnet add package OpenTelemetry.Contrib.Extensions.AWSXRay
dotnet add package OpenTelemetry.Sampler.AWS --prerelease
dotnet add package OpenTelemetry.Resources.AWS
dotnet add package OpenTelemetry.Exporter.OpenTelemetryProtocol
dotnet add package OpenTelemetry.Extensions.Hosting
dotnet add package OpenTelemetry.Instrumentation.AspNetCore
```
Per la tua applicazione.NET, configura l' OpenTelemetry SDK configurando Global. TracerProvider La configurazione di esempio seguente abilita anche la strumentazione per. `ASP.NET Core` Per lo strumento`ASP.NET`, vedere. [Tracciamento delle richieste in arrivo (strumentazione di base ASP.NET e ASP.NET)](#tracing-incoming-requests-dotnet) Per utilizzarlo OpenTelemetry con altri framework, consulta [Registry](https://opentelemetry.io/ecosystem/registry/) per ulteriori librerie per i framework supportati.
Si consiglia di configurare i seguenti componenti:
+ `An OTLP Exporter`— Necessario per esportare le tracce nell' CloudWatch OpenTelemetry Agent/ Collector
+ Un propagatore AWS a raggi X: necessario per propagare il Trace Context ai [AWS servizi](https://docs.aws.amazon.com/xray/latest/devguide/xray-services.html) integrati con X-Ray
+ Un campionatore remoto AWS a raggi X: necessario se è necessario campionare [le richieste utilizzando le](https://docs.aws.amazon.com/xray/latest/devguide/xray-console-sampling.html) regole di campionamento a raggi X
+ `Resource Detectors`(ad esempio, Amazon EC2 Resource Detector): per rilevare i metadati dell'host che esegue l'applicazione
```
using OpenTelemetry;
using OpenTelemetry.Contrib.Extensions.AWSXRay.Trace;
using OpenTelemetry.Sampler.AWS;
using OpenTelemetry.Trace;
using OpenTelemetry.Resources;
var builder = WebApplication.CreateBuilder(args);
var serviceName = "MyServiceName";
var serviceVersion = "1.0.0";
var resourceBuilder = ResourceBuilder
.CreateDefault()
.AddService(serviceName: serviceName)
.AddAWSEC2Detector();
builder.Services.AddOpenTelemetry()
.ConfigureResource(resource => resource
.AddAWSEC2Detector()
.AddService(
serviceName: serviceName,
serviceVersion: serviceVersion))
.WithTracing(tracing => tracing
.AddSource(serviceName)
.AddAspNetCoreInstrumentation()
.AddOtlpExporter()
.SetSampler(AWSXRayRemoteSampler.Builder(resourceBuilder.Build())
.SetEndpoint("http://localhost:2000")
.Build()));
Sdk.SetDefaultTextMapPropagator(new AWSXRayPropagator()); // configure X-Ray propagator
```
Da utilizzare OpenTelemetry per un'app per console, aggiungi la seguente OpenTelemetry configurazione all'avvio del programma.
```
using OpenTelemetry;
using OpenTelemetry.Contrib.Extensions.AWSXRay.Trace;
using OpenTelemetry.Trace;
using OpenTelemetry.Resources;
var serviceName = "MyServiceName";
var resourceBuilder = ResourceBuilder
.CreateDefault()
.AddService(serviceName: serviceName)
.AddAWSEC2Detector();
var tracerProvider = Sdk.CreateTracerProviderBuilder()
.AddSource(serviceName)
.ConfigureResource(resource =>
resource
.AddAWSEC2Detector()
.AddService(
serviceName: serviceName,
serviceVersion: serviceVersion
)
)
.AddOtlpExporter() // default address localhost:4317
.SetSampler(new TraceIdRatioBasedSampler(1.00))
.Build();
Sdk.SetDefaultTextMapPropagator(new AWSXRayPropagator()); // configure X-Ray propagator
```
------
## Creazione manuale di dati di traccia
------
#### [ With X-Ray SDK ]
Con X-Ray SDK, erano necessari i `BeginSubsegment` metodi `BeginSegment` and per creare manualmente segmenti e sottosegmenti X-Ray.
```
using Amazon.XRay.Recorder.Core;
AWSXRayRecorder.Instance.BeginSegment("segment name"); // generates `TraceId` for you
try
{
// Do something here
// can create custom subsegments
AWSXRayRecorder.Instance.BeginSubsegment("subsegment name");
try
{
DoSometing();
}
catch (Exception e)
{
AWSXRayRecorder.Instance.AddException(e);
}
finally
{
AWSXRayRecorder.Instance.EndSubsegment();
}
}
catch (Exception e)
{
AWSXRayRecorder.Instance.AddException(e);
}
finally
{
AWSXRayRecorder.Instance.EndSegment();
}
```
------
#### [ With OpenTelemetry SDK ]
In .NET, è possibile utilizzare l'API Activity per creare intervalli personalizzati per monitorare le prestazioni delle attività interne che non vengono acquisite dalle librerie di strumentazione. Nota che solo gli intervalli di tipo Server vengono convertiti in segmenti X-Ray, tutti gli altri intervalli vengono convertiti in sotto-segmenti X-Ray.
È possibile creare tutte `ActivitySource` le istanze necessarie, ma si consiglia di averne solo una per un'intera applicazione/servizio.
```
using System.Diagnostics;
ActivitySource activitySource = new ActivitySource("ActivitySourceName", "ActivitySourceVersion");
...
using (var activity = activitySource.StartActivity("ActivityName", ActivityKind.Server)) // this will be translated to a X-Ray Segment
{
// Do something here
using (var internalActivity = activitySource.StartActivity("ActivityName", ActivityKind.Internal)) // this will be translated to an X-Ray Subsegment
{
// Do something here
}
}
```
**Aggiungere annotazioni e metadati alle tracce con SDK OpenTelemetry **
Puoi anche aggiungere coppie chiave-valore personalizzate come attributi agli intervalli utilizzando il metodo su un'attività. `SetTag` Nota che per impostazione predefinita, tutti gli attributi span verranno convertiti in metadati nei dati grezzi di X-Ray. Per garantire che un attributo venga convertito in un'annotazione e non in metadati, puoi aggiungere la chiave di quell'attributo all'elenco degli attributi. `aws.xray.annotations`
```
using (var activity = activitySource.StartActivity("ActivityName", ActivityKind.Server)) // this will be translated to a X-Ray Segment
{
activity.SetTag("metadataKey", "metadataValue");
activity.SetTag("annotationKey", "annotationValue");
string[] annotationKeys = {"annotationKey"};
activity.SetTag("aws.xray.annotations", annotationKeys);
// Do something here
using (var internalActivity = activitySource.StartActivity("ActivityName", ActivityKind.Internal)) // this will be translated to an X-Ray Subsegment
{
// Do something here
}
}
```
**Con OpenTelemetry strumentazione automatica**
Se si utilizza una soluzione di strumentazione OpenTelemetry automatica per.NET e se è necessario eseguire la strumentazione manuale nell'applicazione, ad esempio, per codificare lo strumento all'interno dell'applicazione stessa per sezioni che non sono coperte da alcuna libreria di strumentazione automatica.
Poiché può esserci solo una strumentazione globale`TracerProvider`, la strumentazione manuale non dovrebbe istanziare la propria `TracerProvider` se utilizzata insieme alla strumentazione automatica. Quando `TracerProvider` viene utilizzato, il tracciamento manuale personalizzato funziona allo stesso modo quando si utilizza la strumentazione automatica o la strumentazione manuale tramite l'SDK. OpenTelemetry
------
## Tracciamento delle richieste in arrivo (strumentazione di base ASP.NET e ASP.NET)
------
#### [ With X-Ray SDK ]
Per informazioni sulle richieste di strumenti servite dall'applicazione ASP.NET, consulta [https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-dotnet-messagehandler.html](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-dotnet-messagehandler.html) per informazioni su come `RegisterXRay` richiamare il `Init` metodo del file. `global.asax`
```
AWSXRayASPNET.RegisterXRay(this, "MyApp");
```
Per le richieste di strumenti servite dall'applicazione principale ASP.NET, il `UseXRay` metodo viene chiamato prima di qualsiasi altro middleware nel `Configure` metodo della classe Startup.
```
app.UseXRay("MyApp");
```
------
#### [ With OpenTelemetry SDK ]
OpenTelemetry fornisce inoltre librerie di strumentazione per raccogliere tracce per le richieste Web in entrata per ASP.NET e ASP.NET core. [La sezione seguente elenca i passaggi necessari per aggiungere e abilitare questi strumenti di libreria per la OpenTelemetry configurazione, incluso come aggiungere la strumentazione di base [ASP.NET o ASP.NET](https://learn.microsoft.com/en-us/aspnet/overview) durante la creazione del Tracer Provider.](https://learn.microsoft.com/en-us/aspnet/core/?view=aspnetcore-9.0)
Per informazioni su come abilitare .Instrumentation. OpenTelemetry AspNet, vedi [Passaggi per abilitare .Instrumentation. OpenTelemetry AspNet](https://github.com/open-telemetry/opentelemetry-dotnet-contrib/tree/main/src/OpenTelemetry.Instrumentation.AspNet#steps-to-enable-opentelemetryinstrumentationaspnet)e per informazioni su come abilitare .Instrumentation. OpenTelemetry AspNetCore, vedi [Passaggi per abilitare .Instrumentation. OpenTelemetry AspNetCore](https://github.com/open-telemetry/opentelemetry-dotnet-contrib/tree/main/src/OpenTelemetry.Instrumentation.AspNetCore#steps-to-enable-opentelemetryinstrumentationaspnetcore).
------
## AWS Strumentazione SDK
------
#### [ With X-Ray SDK ]
Installa tutti i client AWS SDK chiamando. `RegisterXRayForAllServices()`
```
using Amazon.XRay.Recorder.Handlers.AwsSdk;
AWSSDKHandler.RegisterXRayForAllServices(); //place this before any instantiation of AmazonServiceClient
AmazonDynamoDBClient client = new AmazonDynamoDBClient(RegionEndpoint.USWest2); // AmazonDynamoDBClient is automatically registered with X-Ray
```
Utilizzate uno dei seguenti metodi per la strumentazione specifica del client AWS di servizio.
```
AWSSDKHandler.RegisterXRay(); // Registers specific type of AmazonServiceClient : All instances of IAmazonDynamoDB created after this line are registered
AWSSDKHandler.RegisterXRayManifest(String path); // To configure custom AWS Service Manifest file. This is optional, if you have followed "Configuration" section
```
------
#### [ With OpenTelemetry SDK ]
Per il seguente esempio di codice, è necessaria la seguente dipendenza:
```
dotnet add package OpenTelemetry.Instrumentation.AWS
```
Per strumentare l' AWS SDK, aggiorna la configurazione OpenTelemetry SDK in cui è configurato il Global TracerProvider .
```
builder.Services.AddOpenTelemetry()
...
.WithTracing(tracing => tracing
.AddAWSInstrumentation()
...
```
------
## Analisi delle chiamate HTTP in uscita
------
#### [ With X-Ray SDK ]
X-Ray .NET SDK traccia le chiamate HTTP in uscita tramite i metodi di estensione `GetResponseTraced()` o `GetAsyncResponseTraced()` durante l'utilizzo o utilizzando `System.Net.HttpWebRequest` il gestore durante l'`HttpClientXRayTracingHandler`utilizzo. `System.Net.Http.HttpClient`
------
#### [ With OpenTelemetry SDK ]
Per il seguente esempio di codice, è necessaria la seguente dipendenza:
```
dotnet add package OpenTelemetry.Instrumentation.Http
```
Per strumentare `System.Net.Http.HttpClient` e`System.Net.HttpWebRequest`, aggiorna la configurazione dell' OpenTelemetry SDK in cui TracerProvider è configurato il Global.
```
builder.Services.AddOpenTelemetry()
...
.WithTracing(tracing => tracing
.AddHttpClientInstrumentation()
...
```
------
## Supporto alla strumentazione per altre librerie
Puoi cercare e filtrare OpenTelemetry nel Registro le librerie di strumentazione.NET per scoprire se OpenTelemetry supporta la strumentazione per la tua libreria. Consulta il [Registro per iniziare la ricerca](https://opentelemetry.io/ecosystem/registry/).
## Strumentazione Lambda
------
#### [ With X-Ray SDK ]
Per utilizzare l'SDK X-Ray con Lambda, era necessaria la seguente procedura:
1. Abilita *Active Tracing* sulla tua funzione Lambda
1. Il servizio Lambda crea un segmento che rappresenta la chiamata del gestore
1. Crea sottosegmenti o librerie di strumenti utilizzando l'SDK X-Ray
------
#### [ With OpenTelemetry-based solutions ]
Puoi strumentare automaticamente la tua Lambda con livelli Lambda AWS venduti. Esistono due soluzioni:
+ (Consigliato) [AWS Lambda](https://docs.aws.amazon.com/lambda/latest/dg/monitoring-application-signals.html) Layer per OpenTelemetry
+ Per prestazioni migliori, potresti prendere in considerazione l'idea di utilizzare per `OpenTelemetry Manual Instrumentation` generare OpenTelemetry tracce per la tua funzione Lambda.
------
**OpenTelemetry strumentazione manuale per Lambda AWS **
Di seguito è riportato l'esempio del codice della funzione Lambda (senza strumentazione).
```
using System;
using System.Text;
using System.Threading.Tasks;
using Amazon.Lambda.Core;
using Amazon.S3;
using Amazon.S3.Model;
// Assembly attribute to enable Lambda function logging
[assembly: LambdaSerializer(typeof(Amazon.Lambda.Serialization.SystemTextJson.DefaultLambdaJsonSerializer))]
namespace ExampleLambda;
public class ListBucketsHandler
{
private static readonly AmazonS3Client s3Client = new();
// new Lambda function handler passed in
public async Task HandleRequest(object input, ILambdaContext context)
{
try
{
var DoListBucketsAsyncResponse = await DoListBucketsAsync();
context.Logger.LogInformation($"Results: {DoListBucketsAsyncResponse.Buckets}");
context.Logger.LogInformation($"Successfully called ListBucketsAsync");
return "Success!";
}
catch (Exception ex)
{
context.Logger.LogError($"Failed to call ListBucketsAsync: {ex.Message}");
throw;
}
}
private async Task DoListBucketsAsync()
{
try
{
var putRequest = new ListBucketsRequest
{
};
var response = await s3Client.ListBucketsAsync(putRequest);
return response;
}
catch (AmazonS3Exception ex)
{
throw new Exception($"Failed to call ListBucketsAsync: {ex.Message}", ex);
}
}
}
```
Per strumentare manualmente il tuo gestore Lambda e il client Amazon S3, procedi come segue.
1. Istanzia a TracerProvider : si TracerProvider consiglia di configurarlo con un `XrayUdpSpanExporter` campionatore ParentBased Always On e un `Resource` valore impostato sul nome della funzione `service.name` Lambda.
1. Strumenta il client Amazon S3 con la strumentazione OpenTemetry AWS SDK chiamando per aggiungere la strumentazione client SDK `AddAWSInstrumentation()` a AWS `TracerProvider`
1. Crea una funzione wrapper con la stessa firma della funzione Lambda originale. Chiama `AWSLambdaWrapper.Trace()` l'API e passa`TracerProvider`, la funzione Lambda originale e i suoi input come parametri. Imposta la funzione wrapper come input del gestore Lambda.
Per il seguente esempio di codice, sono necessarie le seguenti dipendenze:
```
dotnet add package OpenTelemetry.Instrumentation.AWSLambda
dotnet add package OpenTelemetry.Instrumentation.AWS
dotnet add package OpenTelemetry.Resources.AWS
dotnet add package AWS.Distro.OpenTelemetry.Exporter.Xray.Udp
```
Il codice seguente illustra la funzione Lambda dopo le modifiche richieste. È possibile creare intervalli personalizzati aggiuntivi per completare gli intervalli forniti automaticamente.
```
using Amazon.Lambda.Core;
using Amazon.S3;
using Amazon.S3.Model;
using OpenTelemetry;
using OpenTelemetry.Instrumentation.AWSLambda;
using OpenTelemetry.Trace;
using AWS.Distro.OpenTelemetry.Exporter.Xray.Udp;
using OpenTelemetry.Resources;
// Assembly attribute to enable Lambda function logging
[assembly: LambdaSerializer(typeof(Amazon.Lambda.Serialization.SystemTextJson.DefaultLambdaJsonSerializer))]
namespace ExampleLambda;
public class ListBucketsHandler
{
private static readonly AmazonS3Client s3Client = new();
TracerProvider tracerProvider = Sdk.CreateTracerProviderBuilder()
.AddAWSLambdaConfigurations()
.AddProcessor(
new SimpleActivityExportProcessor(
// AWS_LAMBDA_FUNCTION_NAME Environment Variable will be defined in AWS Lambda Environment
new XrayUdpExporter(ResourceBuilder.CreateDefault().AddService(Environment.GetEnvironmentVariable("AWS_LAMBDA_FUNCTION_NAME")).Build())
)
)
.AddAWSInstrumentation()
.SetSampler(new ParentBasedSampler(new AlwaysOnSampler()))
.Build();
// new Lambda function handler passed in
public async Task HandleRequest(object input, ILambdaContext context)
=> await AWSLambdaWrapper.Trace(tracerProvider, OriginalHandleRequest, input, context);
public async Task OriginalHandleRequest(object input, ILambdaContext context)
{
try
{
var DoListBucketsAsyncResponse = await DoListBucketsAsync();
context.Logger.LogInformation($"Results: {DoListBucketsAsyncResponse.Buckets}");
context.Logger.LogInformation($"Successfully called ListBucketsAsync");
return "Success!";
}
catch (Exception ex)
{
context.Logger.LogError($"Failed to call ListBucketsAsync: {ex.Message}");
throw;
}
}
private async Task DoListBucketsAsync()
{
try
{
var putRequest = new ListBucketsRequest
{
};
var response = await s3Client.ListBucketsAsync(putRequest);
return response;
}
catch (AmazonS3Exception ex)
{
throw new Exception($"Failed to call ListBucketsAsync: {ex.Message}", ex);
}
}
}
```
Quando richiami questa Lambda, vedrai la seguente traccia nella Trace Map della console: CloudWatch
![\[Traccia la mappa nella CloudWatch console per.Net\]](http://docs.aws.amazon.com/it_it/xray/latest/devguide/images/deprecation_dotnet.png)
# Migrare a Python OpenTelemetry
Questa guida ti aiuta a migrare le applicazioni Python da X-Ray SDK alla strumentazione. OpenTelemetry Copre approcci di strumentazione sia automatici che manuali, con esempi di codice per scenari comuni.
**Topics**
+ [Soluzioni di strumentazione automatica a codice zero](#zero-code-python)
+ [Strumenta manualmente le tue applicazioni](#manual-instrumentation-python)
+ [Tracciamento dell'inizializzazione della configurazione](#manual-instrumentation-python-tracing)
+ [Tracciamento delle richieste in arrivo](#tracing-incoming-requests-python)
+ [AWS Strumentazione SDK](#aws-sdk-instrumentation-python)
+ [Strumentazione delle chiamate HTTP in uscita tramite richieste](#http-instrumentation-python)
+ [Supporto strumentale per altre librerie](#xray-migration-libraries-python)
+ [Creazione manuale di dati di traccia](#manual-trace-creation-python)
+ [Strumentazione Lambda](#lambda-instrumentation-python)
## Soluzioni di strumentazione automatica a codice zero
Con X-Ray SDK, era necessario modificare il codice dell'applicazione per tracciare le richieste. OpenTelemetry offre soluzioni di strumentazione automatica a codice zero per tracciare le richieste. Con OpenTelemetry, hai la possibilità di utilizzare soluzioni di strumentazione automatica a codice zero per tracciare le richieste.
**Codice zero con strumentazione automatica basata OpenTelemetry**
1. [Utilizzo della strumentazione automatica AWS Distro for OpenTelemetry (ADOT) per Python — Per la strumentazione automatica per le applicazioni Python, vedi Tracing and Metrics with the Distro for Python Auto-Instrumentation. AWS OpenTelemetry ](https://aws-otel.github.io/docs/getting-started/python-sdk/auto-instr)
(Facoltativo) È inoltre possibile abilitare CloudWatch Application Signals durante la strumentazione automatica delle applicazioni AWS con la strumentazione automatica ADOT Python per monitorare lo stato attuale delle applicazioni e tenere traccia delle prestazioni delle applicazioni a lungo termine rispetto agli obiettivi aziendali. Application Signals ti offre una visione unificata e incentrata sulle applicazioni di applicazioni, servizi e dipendenze e ti aiuta a monitorare e valutare lo stato delle applicazioni.
1. [Utilizzo della strumentazione automatica OpenTelemetry Python a codice zero — Per la strumentazione automatica con Python, vedi Strumentazione Python a codice zero. OpenTelemetry ](https://opentelemetry.io/docs/zero-code/python/)
## Strumenta manualmente le tue applicazioni
È possibile strumentare manualmente le applicazioni utilizzando il comando. `pip`
------
#### [ With X-Ray SDK ]
```
pip install aws-xray-sdk
```
------
#### [ With OpenTelemetry SDK ]
```
pip install opentelemetry-api opentelemetry-sdk opentelemetry-exporter-otlp opentelemetry-propagator-aws-xray
```
------
## Tracciamento dell'inizializzazione della configurazione
------
#### [ With X-Ray SDK ]
In X-Ray, il globale `xray_recorder` viene inizializzato e utilizzato per generare segmenti e sottosegmenti.
------
#### [ With OpenTelemetry SDK ]
**Nota**
X-Ray Remote Sampling non è attualmente disponibile per la configurazione per Python. OpenTelemetry Tuttavia, il supporto per il campionamento remoto a raggi X è attualmente disponibile tramite ADOT Auto-Instrumentation for Python.
Nel, è necessario inizializzare un OpenTelemetry file globale. `TracerProvider` In questo modo`TracerProvider`, è possibile acquisire un [Tracer](https://opentelemetry.io/docs/concepts/signals/traces/#tracer) che è possibile utilizzare per generare intervalli in qualsiasi punto dell'applicazione. Si consiglia di configurare i seguenti componenti:
+ `OTLPSpanExporter`— Necessario per esportare le tracce nell' CloudWatch OpenTelemetry Agent/ Collector
+ Un propagatore AWS a raggi X: necessario per propagare il Trace Context ai AWS servizi integrati con X-Ray
```
from opentelemetry import (
trace,
propagate
)
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.propagators.aws import AwsXRayPropagator
# Sends generated traces in the OTLP format to an OTel Collector running on port 4318
otlp_exporter = OTLPSpanExporter(endpoint="http://localhost:4318/v1/traces")
# Processes traces in batches as opposed to immediately one after the other
span_processor = BatchSpanProcessor(otlp_exporter)
# More configurations can be done here. We will visit them later.
# Sets the global default tracer provider
provider = TracerProvider(active_span_processor=span_processor)
trace.set_tracer_provider(provider)
# Configures the global propagator to use the X-Ray Propagator
propagate.set_global_textmap(AwsXRayPropagator())
# Creates a tracer from the global tracer provider
tracer = trace.get_tracer("my.tracer.name")
# Use this tracer to create Spans
```
------
**Con strumentazione automatica ADOT per Python**
Puoi usare la strumentazione automatica ADOT per Python per configurare OpenTelemetry automaticamente le tue applicazioni Python. Utilizzando la strumentazione automatica ADOT, non è necessario apportare modifiche manuali al codice per tracciare le richieste in arrivo o tracciare librerie come i AWS client SDK o HTTP. Per ulteriori informazioni, consulta [Tracciamento e metriche con la distribuzione AWS per Python OpenTelemetry Auto-Instrumentation](https://aws-otel.github.io/docs/getting-started/python-sdk/auto-instr).
La strumentazione automatica ADOT per Python supporta:
+ Campionamento remoto a raggi X tramite la variabile di ambiente `export OTEL_TRACES_SAMPLER=xray`
+ Propagazione contestuale delle tracce X-Ray (abilitata per impostazione predefinita)
+ Rilevamento delle risorse (il rilevamento delle risorse per gli ambienti Amazon EC2, Amazon ECS e Amazon EKS è abilitato per impostazione predefinita)
+ Le strumentazioni di libreria automatiche per tutte le strumentazioni supportate sono abilitate per OpenTelemetry impostazione predefinita. È possibile disabilitarla in modo selettivo tramite la variabile di ambiente. `OTEL_PYTHON_DISABLED_INSTRUMENTATIONS ` (tutti sono abilitati di default)
+ Creazione manuale di Spans
**Dai plug-in dei servizi X-Ray ai provider di risorse OpenTelemetry AWS **
L'X-Ray SDK fornisce plug-in che è possibile aggiungere per acquisire informazioni specifiche sulla piattaforma dal servizio ospitato come Amazon EC2, Amazon ECS ed Elastic Beanstalk. `xray_recorder` È simile ai Resource Providers in quanto acquisisce le informazioni come attributi di risorse. OpenTelemetry Sono disponibili più Resource Provider per diverse AWS piattaforme.
+ Inizia installando il pacchetto di AWS estensione, `pip install opentelemetry-sdk-extension-aws`
+ Configura il rilevatore di risorse desiderato. L'esempio seguente mostra come configurare il provider di risorse Amazon EC2 in SDK. OpenTelemetry
```
from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.extension.aws.resource.ec2 import (
AwsEc2ResourceDetector,
)
from opentelemetry.sdk.resources import get_aggregated_resources
provider = TracerProvider(
active_span_processor=span_processor,
resource=get_aggregated_resources([
AwsEc2ResourceDetector(),
]))
trace.set_tracer_provider(provider)
```
## Tracciamento delle richieste in arrivo
------
#### [ With X-Ray SDK ]
L'X-Ray Python SDK supporta framework applicativi come Django, Flask e Bottle per tracciare le richieste in arrivo per le applicazioni Python in esecuzione su di essi. Questo viene fatto aggiungendo all'applicazione per ogni framework. `XRayMiddleware`
------
#### [ With OpenTelemetry SDK ]
OpenTelemetry fornisce strumentazioni per [Django](https://opentelemetry-python-contrib.readthedocs.io/en/latest/instrumentation/django/django.html) e [Flask](https://opentelemetry-python-contrib.readthedocs.io/en/latest/instrumentation/flask/flask.html) attraverso le librerie di strumentazione specifiche. [Non è disponibile alcuna strumentazione per Bottle OpenTelemetry, le applicazioni possono ancora essere tracciate utilizzando la strumentazione WSGI. OpenTelemetry ](https://opentelemetry-python-contrib.readthedocs.io/en/latest/instrumentation/wsgi/wsgi.html)
Per il seguente esempio di codice, è necessaria la seguente dipendenza:
```
pip install opentelemetry-instrumentation-flask
```
È necessario inizializzare l' OpenTelemetry SDK e registrare quello globale TracerProvider prima di aggiungere strumentazioni per il framework dell'applicazione. Senza di essa, le operazioni di tracciamento lo saranno. `no-ops` Dopo aver configurato il globale`TracerProvider`, è possibile utilizzare lo strumentor per il framework dell'applicazione. L'esempio seguente mostra un'applicazione Flask.
```
from flask import Flask
from opentelemetry import trace
from opentelemetry.instrumentation.flask import FlaskInstrumentor
from opentelemetry.sdk.extension.aws.resource import AwsEc2ResourceDetector
from opentelemetry.sdk.resources import get_aggregated_resources
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor, ConsoleSpanExporter
provider = TracerProvider(resource=get_aggregated_resources(
[
AwsEc2ResourceDetector(),
]))
processor = BatchSpanProcessor(ConsoleSpanExporter())
provider.add_span_processor(processor)
trace.set_tracer_provider(provider)
# Creates a tracer from the global tracer provider
tracer = trace.get_tracer("my.tracer.name")
app = Flask(__name__)
# Instrument the Flask app
FlaskInstrumentor().instrument_app(app)
@app.route('/')
def hello_world():
return 'Hello World!'
if __name__ == '__main__':
app.run()
```
------
## AWS Strumentazione SDK
------
#### [ With X-Ray SDK ]
L'X-Ray Python SDK traccia la richiesta del client SDK applicando una AWS patch alla libreria. `botocore` Per ulteriori informazioni, consulta [Tracciare le chiamate AWS SDK con l'SDK X-Ray](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-python-awssdkclients.html) per Python. Nell'applicazione, il `patch_all()` metodo viene utilizzato per strumentare tutte le librerie o applicare le patch in modo selettivo utilizzando le librerie or. `botocore` `boto3` `patch((['botocore']))` Qualsiasi metodo scelto monitora tutti i client Boto3 dell'applicazione e genera un sottosegmento per ogni chiamata effettuata utilizzando questi client.
------
#### [ With OpenTelemetry SDK ]
Per il seguente esempio di codice, avrai bisogno della seguente dipendenza:
```
pip install opentelemetry-instrumentation-botocore
```
Utilizzate la strumentazione [OpenTelemetry Botocore a livello di codice per strumentare](https://opentelemetry-python-contrib.readthedocs.io/en/latest/instrumentation/botocore/botocore.html) tutti i client Boto3 della vostra applicazione. L'esempio seguente illustra `botocore` la strumentazione.
```
import boto3
import opentelemetry.trace as trace
from botocore.exceptions import ClientError
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.resources import get_aggregated_resources
from opentelemetry.sdk.trace.export import (
BatchSpanProcessor,
ConsoleSpanExporter,
)
from opentelemetry.instrumentation.botocore import BotocoreInstrumentor
provider = TracerProvider()
processor = BatchSpanProcessor(ConsoleSpanExporter())
provider.add_span_processor(processor)
trace.set_tracer_provider(provider)
# Creates a tracer from the global tracer provider
tracer = trace.get_tracer("my.tracer.name")
# Instrument BotoCore
BotocoreInstrumentor().instrument()
# Initialize S3 client
s3 = boto3.client("s3", region_name="us-east-1")
# Your bucket name
bucket_name = "my-example-bucket"
# Get bucket location (as an example of describing it)
try:
response = s3.get_bucket_location(Bucket=bucket_name)
region = response.get("LocationConstraint") or "us-east-1"
print(f"Bucket '{bucket_name}' is in region: {region}")
# Optionally, get bucket's creation date via list_buckets
buckets = s3.list_buckets()
for bucket in buckets["Buckets"]:
if bucket["Name"] == bucket_name:
print(f"Bucket created on: {bucket['CreationDate']}")
break
except ClientError as e:
print(f"Failed to describe bucket: {e}")
```
------
## Strumentazione delle chiamate HTTP in uscita tramite richieste
------
#### [ With X-Ray SDK ]
L'X-Ray Python SDK traccia le chiamate HTTP in uscita tramite le richieste applicando patch alla libreria delle richieste. Per ulteriori informazioni, consulta [Tracciare le chiamate ai servizi Web HTTP downstream utilizzando X-Ray SDK](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-python-httpclients.html) per Python. Nella tua applicazione, puoi utilizzare il `patch_all()` metodo per strumentare tutte le librerie o patchare selettivamente le librerie di richieste utilizzando. `patch((['requests']))` Qualsiasi opzione strumenta la `requests` libreria, generando un sottosegmento per ogni chiamata effettuata. `requests`
------
#### [ With OpenTelemetry SDK ]
Per il seguente esempio di codice, è necessaria la seguente dipendenza:
```
pip install opentelemetry-instrumentation-requests
```
OpenTelemetry Utilizzate la strumentazione delle richieste a livello di codice per strumentare la libreria delle richieste per generare tracce per le richieste HTTP da essa effettuate nell'applicazione. [Per ulteriori informazioni, consulta request Instrumentation. OpenTelemetry ](https://opentelemetry-python-contrib.readthedocs.io/en/latest/instrumentation/requests/requests.html) L'esempio seguente illustra la strumentazione della `requests` libreria.
```
from opentelemetry.instrumentation.requests import RequestsInstrumentor
# Instrument Requests
RequestsInstrumentor().instrument()
...
example_session = requests.Session()
example_session.get(url="https://example.com")
```
In alternativa, puoi anche strumentare la `urllib3` libreria sottostante per tracciare le richieste HTTP:
```
# pip install opentelemetry-instrumentation-urllib3
from opentelemetry.instrumentation.urllib3 import URLLib3Instrumentor
# Instrument urllib3
URLLib3Instrumentor().instrument()
...
example_session = requests.Session()
example_session.get(url="https://example.com")
```
------
## Supporto strumentale per altre librerie
Puoi trovare l'elenco completo delle strumentazioni di libreria supportate per OpenTelemetry Python in [Librerie, framework, server](https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/main/docs/supported-libraries.md) di applicazioni e. JVMs
In alternativa, puoi cercare OpenTelemetry nel Registro per scoprire se supporta la strumentazione. OpenTelemetry Consulta il [Registro](https://opentelemetry.io/ecosystem/registry/) per iniziare la ricerca.
## Creazione manuale di dati di traccia
Puoi creare segmenti e sottosegmenti usando la nella `xray_recorder` tua applicazione Python. Per ulteriori informazioni, consulta [Strumentazione manuale del codice Python](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-python-middleware.html#xray-sdk-python-middleware-manual). Puoi anche aggiungere manualmente annotazioni e metadati ai dati di traccia.
**Creazione di intervalli con SDK OpenTelemetry **
Usa l'`start_as_current_span`API per avviare un intervallo e impostala per la creazione di intervalli. [Per esempi sulla creazione di intervalli, consulta Creazione di intervalli.](https://opentelemetry.io/docs/languages/python/instrumentation/#creating-spans) Una volta avviato un intervallo e rientrato nell'ambito corrente, è possibile aggiungervi ulteriori informazioni aggiungendo attributi, eventi, eccezioni, collegamenti e così via. Come abbiamo segmenti e sottosegmenti in X-Ray, ci sono diversi tipi di intervalli. OpenTelemetry Solo le campate `SERVER` tipo vengono convertite in segmenti a raggi X, mentre le altre vengono convertite in sottosegmenti a raggi X.
```
from opentelemetry import trace
from opentelemetry.trace import SpanKind
import time
tracer = trace.get_tracer("my.tracer.name")
# Create a new span to track some work
with tracer.start_as_current_span("parent", kind=SpanKind.SERVER) as parent_span:
time.sleep(1)
# Create a nested span to track nested work
with tracer.start_as_current_span("child", kind=SpanKind.CLIENT) as child_span:
time.sleep(2)
# the nested span is closed when it's out of scope
# Now the parent span is the current span again
time.sleep(1)
# This span is also closed when it goes out of scope
```
**Aggiungere annotazioni e metadati alle tracce con SDK OpenTelemetry **
L'X-Ray Python SDK fornisce informazioni separate APIs e consente di aggiungere annotazioni `put_annotation` e `put_metadata` metadati a una traccia. In OpenTelemetry SDK, le annotazioni e i metadati sono semplicemente attributi su un intervallo, aggiunti tramite l'API. `set_attribute`
Gli attributi Span che desideri siano annotazioni su una traccia vengono aggiunti sotto la chiave riservata il `aws.xray.annotations` cui valore è un elenco di coppie di annotazioni chiave-valore. Tutti gli altri attributi span diventano metadati sul segmento o sottosegmento convertito.
Inoltre, se si utilizza il collettore ADOT, è possibile configurare quali attributi span devono essere convertiti in annotazioni X-Ray specificando nella configurazione del collettore. `indexed_attributes`
L'esempio seguente mostra come aggiungere annotazioni e metadati a una traccia utilizzando SDK. OpenTelemetry
```
with tracer.start_as_current_span("parent", kind=SpanKind.SERVER) as parent_span:
parent_span.set_attribute("TransactionId", "qwerty12345")
parent_span.set_attribute("AccountId", "1234567890")
# This will convert the TransactionId and AccountId to be searchable X-Ray annotations
parent_span.set_attribute("aws.xray.annotations", ["TransactionId", "AccountId"])
with tracer.start_as_current_span("child", kind=SpanKind.CLIENT) as child_span:
# The MicroTransactionId will be converted to X-Ray metadata for the child subsegment
child_span.set_attribute("MicroTransactionId", "micro12345")
```
## Strumentazione Lambda
Per monitorare le funzioni lambda su X-Ray, abiliti X-Ray e hai aggiunto le autorizzazioni appropriate al ruolo di invocazione della funzione. Inoltre, se stai tracciando le richieste downstream della tua funzione, dovresti strumentalizzare il codice con X-Ray Python SDK.
OpenTelemetry Per X-Ray, si consiglia di utilizzare il AWS Lambda Layer per i segnali di [applicazione OpenTelemetry ](https://docs.aws.amazon.com/lambda/latest/dg/monitoring-application-signals.html) disattivati. Questo strumenterà automaticamente la tua funzione e genererà intervalli per l'invocazione della funzione e qualsiasi richiesta derivante dalla tua funzione. Oltre al tracciamento, se sei interessato a utilizzare Application Signals per monitorare lo stato della tua funzione, consulta [Abilitare le tue applicazioni su Lambda](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Application-Signals-Enable-LambdaMain.html).
+ Trova l'ARN del layer Lambda richiesto per la tua funzione da [AWS Lambda](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Application-Signals-Enable-LambdaMain.html#Enable-Lambda-Layers) Layer for e aggiungilo. OpenTelemetry ARNs
+ Imposta le seguenti variabili di ambiente per la tua funzione.
+ `AWS_LAMBDA_EXEC_WRAPPER=/opt/otel-instrument`— Questo carica la strumentazione automatica per la funzione
+ `OTEL_AWS_APPLICATION_SIGNALS_ENABLED=false`— Ciò disabiliterà il monitoraggio dei segnali applicativi
**Creazione manuale di campate con la strumentazione Lambda**
Inoltre, puoi generare intervalli personalizzati all'interno della tua funzione per tenere traccia del lavoro. È possibile farlo utilizzando solo il `opentelemetry-api` pacchetto in combinazione con il AWS Lambda Layer OpenTelemetry per la strumentazione automatica.
1. Includili `opentelemetry-api` come dipendenza nella tua funzione
1. Il seguente frammento di codice è un esempio per generare intervalli personalizzati
```
from opentelemetry import trace
# Get the tracer (auto‑configured by the AWS Lambda Layer for OpenTelemetry)
tracer = trace.get_tracer(__name__)
def handler(event, context):
# This span is a child of the layer's root span
with tracer.start_as_current_span("my-custom-span") as span:
span.set_attribute("key1", "value1")
span.add_event("custom-event", {"detail": "something happened"})
# Any logic you want to trace
result = some_internal_logic()
return {
"statusCode": 200,
"body": result
}
```
# Migra a Ruby OpenTelemetry
Per migrare le applicazioni Ruby da X-Ray SDK alla OpenTelemetry strumentazione, utilizzate i seguenti esempi di codice e le linee guida per la strumentazione manuale.
**Topics**
+ [Strumenta manualmente le tue soluzioni con l'SDK](#manual-instrumentation-ruby)
+ [Tracciamento delle richieste in arrivo (strumentazione Rails)](#tracing-incoming-requests-ruby)
+ [AWS Strumentazione SDK](#aws-sdk-instrumentation-ruby)
+ [Analisi delle chiamate HTTP in uscita](#http-instrumentation-ruby)
+ [Supporto alla strumentazione per altre librerie](#xray-migration-libraries-ruby)
+ [Creazione manuale dei dati di traccia](#manual-trace-creation-ruby)
+ [Strumentazione manuale Lambda](#lambda-instrumentation-ruby)
## Strumenta manualmente le tue soluzioni con l'SDK
------
#### [ Tracing setup with X-Ray SDK ]
X-Ray SDK for Ruby richiedeva la configurazione del codice con i plug-in di servizio.
```
require 'aws-xray-sdk'
XRay.recorder.configure(plugins: [:ec2, :elastic_beanstalk])
```
------
#### [ Tracing setup with OpenTelemetry SDK ]
**Nota**
Il campionamento remoto a raggi X non è attualmente disponibile per la configurazione per Ruby. OpenTelemetry
Per un'applicazione Ruby on Rails, inserite il codice di configurazione in un inizializzatore Rails. Per ulteriori informazioni, consulta [Nozioni di base su ](https://opentelemetry.io/docs/languages/ruby/getting-started/#initialization). Per tutti i programmi Ruby con strumentazione manuale, è necessario utilizzare il metodo per configurare l'`OpenTelemetry::SDK.configure`SDK Ruby. OpenTelemetry
Innanzitutto, installa i seguenti pacchetti:
```
bundle add opentelemetry-sdk opentelemetry-exporter-otlp opentelemetry-propagator-xray
```
Quindi, configura l' OpenTelemetry SDK tramite il codice di configurazione che viene eseguito quando il programma viene inizializzato. Si consiglia di configurare i seguenti componenti:
+ `OTLP Exporter`— Necessario per esportare le tracce nell' CloudWatch agente e OpenTelemetry nel raccoglitore
+ `An AWS X-Ray Propagator`— Necessario per propagare il contesto di traccia ai AWS servizi integrati con X-Ray
```
require 'opentelemetry-sdk'
require 'opentelemetry-exporter-otlp'
# Import the gem containing the AWS X-Ray for OTel Ruby ID Generator and propagator
require 'opentelemetry-propagator-xray'
OpenTelemetry::SDK.configure do |c|
c.service_name = 'my-service-name'
c.add_span_processor(
# Use the BatchSpanProcessor to send traces in groups instead of one at a time
OpenTelemetry::SDK::Trace::Export::BatchSpanProcessor.new(
# Use the default OLTP Exporter to send traces to the ADOT Collector
OpenTelemetry::Exporter::OTLP::Exporter.new(
# The OpenTelemetry Collector is running as a sidecar and listening on port 4318
endpoint:"http://127.0.0.1:4318/v1/traces"
)
)
)
# The X-Ray Propagator injects the X-Ray Tracing Header into downstream calls
c.propagators = [OpenTelemetry::Propagator::XRay::TextMapPropagator.new]
end
```
OpenTelemetry SDKs hanno anche il concetto di strumentazione di libreria. Abilitandoli si creeranno automaticamente degli intervalli per librerie come l'SDK. AWS OpenTelemetry offre la possibilità di abilitare tutte le strumentazioni della libreria o specificare quali strumentazioni della libreria abilitare.
Per abilitare tutte le strumentazioni, installa prima il pacchetto: `opentelemetry-instrumentation-all`
```
bundle add opentelemetry-instrumentation-all
```
Successivamente, aggiorna la configurazione per abilitare tutte le strumentazioni della libreria come mostrato di seguito:
```
require 'opentelemetry/instrumentation/all'
...
OpenTelemetry::SDK.configure do |c|
...
c.use_all() # Enable all instrumentations
end
```
OpenTelemetry SDKs hanno anche il concetto di strumentazione di libreria. Abilitandoli si creeranno automaticamente degli intervalli per librerie come l'SDK. AWS OpenTelemetry offre la possibilità di abilitare tutte le strumentazioni della libreria o specificare quali strumentazioni della libreria abilitare.
Per abilitare tutte le strumentazioni, installa prima il pacchetto: `opentelemetry-instrumentation-all`
```
bundle add opentelemetry-instrumentation-all
```
Successivamente, aggiorna la configurazione per abilitare tutte le strumentazioni della libreria come mostrato di seguito:
```
require 'opentelemetry/instrumentation/all'
...
OpenTelemetry::SDK.configure do |c|
...
c.use_all() # Enable all instrumentations
end
```
------
## Tracciamento delle richieste in arrivo (strumentazione Rails)
------
#### [ With X-Ray SDK ]
Con X-Ray SDK, il tracciamento X-Ray viene configurato per il framework Rails al momento dell'inizializzazione.
**config/initializers/awsEsempio: \$1xray.rb**
```
Rails.application.config.xray = {
name: 'my app',
patch: %I[net_http aws_sdk],
active_record: true
}
```
------
#### [ With OpenTelemetry SDK ]
Innanzitutto, installa i seguenti pacchetti:
```
bundle add opentelemetry-instrumentation-rack opentelemetry-instrumentation-rails opentelemetry-instrumentation-action_pack opentelemetry-instrumentation-active_record opentelemetry-instrumentation-action_view
```
Successivamente, aggiorna la configurazione per abilitare la strumentazione per la tua applicazione Rails come mostrato di seguito:
```
# During SDK configuration
OpenTelemetry::SDK.configure do |c|
...
c.use 'OpenTelemetry::Instrumentation::Rails'
c.use 'OpenTelemetry::Instrumentation::Rack'
c.use 'OpenTelemetry::Instrumentation::ActionPack'
c.use 'OpenTelemetry::Instrumentation::ActiveSupport'
c.use 'OpenTelemetry::Instrumentation::ActionView'
...
end
```
------
## AWS Strumentazione SDK
------
#### [ With X-Ray SDK ]
Per strumentare AWS le richieste in uscita dall' AWS SDK, ai client AWS SDK viene applicata una patch con X-Ray come nell'esempio seguente:
```
require 'aws-xray-sdk'
require 'aws-sdk-s3'
# Patch AWS SDK clients
XRay.recorder.configure(plugins: [:aws_sdk])
# Use the instrumented client
s3 = Aws::S3::Client.new
s3.list_buckets
```
------
#### [ With OpenTelemetry SDK ]
AWS SDK for Ruby V3 fornisce supporto per la registrazione e l'emissione di tracce. OpenTelemetry Per informazioni su come configurare un client di servizio, consulta [Configurazione delle funzionalità di osservabilità nell' AWS SDK OpenTelemetry for Ruby](sdk-for-ruby/v3/developer-guide/observability.html).
------
## Analisi delle chiamate HTTP in uscita
Quando si effettuano chiamate HTTP a servizi esterni, potrebbe essere necessario strumentare manualmente le chiamate se la strumentazione automatica non è disponibile o non fornisce dettagli sufficienti.
------
#### [ With X-Ray SDK ]
Per strumentare le chiamate downstream, è stato utilizzato l'X-Ray SDK for Ruby per `net/http` applicare patch alla libreria utilizzata dall'applicazione:
```
require 'aws-xray-sdk'
config = {
name: 'my app',
patch: %I[net_http]
}
XRay.recorder.configure(config)
```
------
#### [ With OpenTelemetry SDK ]
Per abilitare l'utilizzo OpenTelemetry della `net/http` strumentazione, installate innanzitutto il pacchetto: `opentelemetry-instrumentation-net_http`
```
bundle add opentelemetry-instrumentation-net_http
```
Quindi, aggiorna la configurazione per abilitare la `net/http` strumentazione come mostrato di seguito:
```
OpenTelemetry::SDK.configure do |c|
...
c.use 'OpenTelemetry::Instrumentation::Net::HTTP'
...
end
```
------
## Supporto alla strumentazione per altre librerie
Puoi trovare l'elenco completo delle strumentazioni di libreria supportate per Ruby sotto. OpenTelemetry [opentelemetry-ruby-contrib](https://github.com/open-telemetry/opentelemetry-ruby-contrib/tree/main/instrumentation)
In alternativa, puoi cercare OpenTelemetry nel Registro per scoprire se OpenTelemetry supporta la strumentazione. [Per ulteriori informazioni, consulta Registry.](https://opentelemetry.io/ecosystem/registry/)
## Creazione manuale dei dati di traccia
------
#### [ With X-Ray SDK ]
Utilizzando X-Ray, il `aws-xray-sdk` pacchetto richiedeva la creazione manuale dei segmenti e dei relativi sottosegmenti secondari per tracciare l'applicazione. Potresti aver anche aggiunto annotazioni e metadati X-Ray ai tuoi segmenti o sottosegmenti:
```
require 'aws-xray-sdk'
...
# Start a segment
segment = XRay.recorder.begin_segment('my-service')
# Add annotations (indexed key-value pairs)
segment.annotations[:user_id] = 'user-123'
segment.annotations[:payment_status] = 'completed'
# Add metadata (non-indexed data)
segment.metadata[:order] = {
id: 'order-456',
items: [
{ product_id: 'prod-1', quantity: 2 },
{ product_id: 'prod-2', quantity: 1 }
],
total: 67.99
}
# Add metadata to a specific namespace
segment.metadata(namespace: 'payment') do |metadata|
metadata[:transaction_id] = 'tx-789'
metadata[:payment_method] = 'credit_card'
end
# Create a subsegment with annotations and metadata
segment.subsegment('payment-processing') do |subsegment1|
subsegment1.annotations[:payment_id] = 'pay-123'
subsegment1.metadata[:details] = { amount: 67.99, currency: 'USD' }
# Create a nested subsegment
subsegment1.subsegment('operation-2') do |subsegment2|
# Do more work...
end
end
# Close the segment
segment.close
```
------
#### [ With OpenTelemetry SDK ]
È possibile utilizzare intervalli personalizzati per monitorare le prestazioni delle attività interne che non vengono acquisite dalle librerie di strumentazione. Nota che solo gli span di tipo server vengono convertiti in segmenti X-Ray, tutti gli altri intervalli vengono convertiti in sottosegmenti X-Ray. Per impostazione `INTERNAL` predefinita, gli intervalli sono.
Innanzitutto, crea un Tracer per generare intervalli, che puoi ottenere tramite il metodo. `OpenTelemetry.tracer_provider.tracer('')` Ciò fornirà un'istanza Tracer registrata a livello globale nella configurazione dell'applicazione. OpenTelemetry È comune avere un singolo Tracer per un'intera applicazione. Crea un OpenTelemetry tracer e usalo per creare intervalli:
```
require 'opentelemetry-sdk'
...
# Get a tracer
tracer = OpenTelemetry.tracer_provider.tracer('my-application')
# Create a server span (equivalent to X-Ray segment)
tracer.in_span('my-application', kind: OpenTelemetry::Trace::SpanKind::SERVER) do |span|
# Do work...
# Create nested spans of default kind INTERNAL will become an X-Ray subsegment
tracer.in_span('operation-1') do |child_span1|
# Set attributes (equivalent to X-Ray annotations and metadata)
child_span1.set_attribute('key', 'value')
# Do more work...
tracer.in_span('operation-2') do |child_span2|
# Do more work...
end
end
end
```
**Aggiungere annotazioni e metadati alle tracce con SDK OpenTelemetry **
Usa il `set_attribute` metodo per aggiungere attributi a ogni intervallo. Nota che per impostazione predefinita, tutti questi attributi span verranno convertiti in metadati nei dati grezzi di X-Ray. Per garantire che un attributo venga convertito in un'annotazione e non in metadati, puoi aggiungere la chiave degli attributi all'elenco degli attributi. `aws.xray.annotations` 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).
```
# SERVER span will become an X-Ray segment
tracer.in_span('my-server-operation', kind: OpenTelemetry::Trace::SpanKind::SERVER) do |span|
# Your server logic here
span.set_attribute('attribute.key', 'attribute.value')
span.set_attribute("metadataKey", "metadataValue")
span.set_attribute("annotationKey1", "annotationValue")
# Create X-Ray annotations
span.set_attribute("aws.xray.annotations", ["annotationKey1"])
end
```
------
## Strumentazione manuale Lambda
------
#### [ With X-Ray SDK ]
Dopo aver abilitato *Active Tracing* su Lambda, non sono necessarie configurazioni aggiuntive per utilizzare l'SDK X-Ray. Lambda creerà un segmento che rappresenta l'invocazione del gestore Lambda e potrai creare sottosegmenti o librerie di strumenti utilizzando l'SDK X-Ray senza alcuna configurazione aggiuntiva.
------
#### [ With OpenTelemetry SDK ]
Considerate il seguente codice di funzione Lambda di esempio (senza strumentazione):
```
require 'json'
def lambda_handler(event:, context:)
# TODO implement
{ statusCode: 200, body: JSON.generate('Hello from Lambda!') }
end
```
Per strumentare manualmente la tua Lambda, dovrai:
1. Aggiungi le seguenti gemme per la tua Lambda
```
gem 'opentelemetry-sdk'
gem 'opentelemetry-exporter-otlp'
gem 'opentelemetry-propagator-xray'
gem 'aws-distro-opentelemetry-exporter-xray-udp'
gem 'opentelemetry-instrumentation-aws_lambda'
gem 'opentelemetry-propagator-xray', '~> 0.24.0' # Requires version v0.24.0 or higher
```
1. Inizializza l' OpenTelemetry SDK all'esterno del tuo Lambda Handler. Si consiglia di OpenTelemetry configurare l'SDK con:
1. Un semplice processore Span con un X-Ray UDP Span Exporter per inviare Traces all'endpoint UDP X-Ray di Lambda
1. Un propagatore Lambda a raggi X
1. `service_name`configurazione da impostare sul nome della funzione Lambda
1. Nella tua classe Lambda Handler, aggiungi le seguenti righe allo strumento Lambda Handler:
```
class Handler
extend OpenTelemetry::Instrumentation::AwsLambda::Wrap
...
instrument_handler :process
end
```
Il codice seguente illustra la funzione Lambda dopo le modifiche richieste. È possibile creare intervalli personalizzati aggiuntivi per completare gli intervalli forniti automaticamente.
```
require 'json'
require 'opentelemetry-sdk'
require 'aws/distro/opentelemetry/exporter/xray/udp'
require 'opentelemetry/propagator/xray'
require 'opentelemetry/instrumentation/aws_lambda'
# Initialize OpenTelemetry SDK outside handler
OpenTelemetry::SDK.configure do |c|
# Configure the AWS Distro for OpenTelemetry X-Ray Lambda exporter
c.add_span_processor(
OpenTelemetry::SDK::Trace::Export::SimpleSpanProcessor.new(
AWS::Distro::OpenTelemetry::Exporter::XRay::UDP::AWSXRayUDPSpanExporter.new
)
)
# Configure X-Ray Lambda propagator
c.propagators = [OpenTelemetry::Propagator::XRay.lambda_text_map_propagator]
# Set minimal resource information
c.resource = OpenTelemetry::SDK::Resources::Resource.create({
OpenTelemetry::SemanticConventions::Resource::SERVICE_NAME => ENV['AWS_LAMBDA_FUNCTION_NAME']
})
c.use 'OpenTelemetry::Instrumentation::AwsLambda'
end
module LambdaFunctions
class Handler
extend OpenTelemetry::Instrumentation::AwsLambda::Wrap
def self.process(event:, context:)
"Hello!"
end
instrument_handler :process
end
end
```
------
Di seguito è riportato un esempio di mappa di traccia di una funzione Lambda con strumentazione scritta in Ruby.
![\[Mappa di tracciamento nella CloudWatch console per Ruby.\]](http://docs.aws.amazon.com/it_it/xray/latest/devguide/images/deprecation_ruby.png)
Puoi anche usare i layer Lambda OpenTelemetry per configurare la tua Lambda. Per ulteriori informazioni, consulta [OpenTelemetry AWS-Lambda](https://github.com/open-telemetry/opentelemetry-ruby-contrib/tree/main/instrumentation/aws_lambda#usage) Instrumentation.