Usare Powertools per AWS Lambda (Python) AWS SAM e per tracciare Usare Powertools per AWS Lambda (Python) e AWS CDK per tracciare Utilizzo di ADOT per strumentare le funzioni Python Usare gli X-Ray SDK per strumentare le funzioni di Python Attivazione del tracciamento con la console Lambda Attivazione del tracciamento con la Lambda API Attivazione del tracciamento con AWS CloudFormation Interpretazione di una traccia X-Ray Memorizzazione delle dipendenze di runtime in un livello (X-RaySDK)

Strumentazione del codice Python in AWS Lambda

Lambda si integra con AWS X-Ray per aiutarti a tracciare, eseguire il debug e ottimizzare le applicazioni Lambda. Puoi utilizzare X-Ray per tracciare una richiesta mentre attraversa le risorse nell'applicazione, che possono includere funzioni Lambda e altri servizi AWS .

Per inviare dati di tracciamento a X-Ray, puoi utilizzare una delle SDK tre librerie:

AWS Distro for OpenTelemetry (ADOT): una distribuzione sicura, pronta per la produzione e AWS supportata di (). OpenTelemetry OTel SDK
SDK AWS X-Ray per Python— E SDK per generare e inviare dati di traccia a X-Ray.
Powertools for AWS Lambda (Python): un toolkit per sviluppatori per implementare le migliori pratiche Serverless e aumentare la velocità degli sviluppatori.

Ciascuno di essi SDKs offre modi per inviare i dati di telemetria al servizio X-Ray. Puoi quindi utilizzare X-Ray per visualizzare, filtrare e analizzare le metriche delle prestazioni dell'applicazione per identificare i problemi e le opportunità di ottimizzazione.

Importante

X-Ray e Powertools per AWS Lambda SDKs fanno parte di una soluzione di strumentazione strettamente integrata offerta da. AWS I ADOT Lambda Layer fanno parte di uno standard di settore per la strumentazione di tracciamento che raccoglie più dati in generale, ma potrebbe non essere adatta a tutti i casi d'uso. È possibile implementare il end-to-end tracciamento in X-Ray utilizzando entrambe le soluzioni. Per saperne di più sulla scelta tra di esse, consulta Scelta tra AWS Distro for Open Telemetry e X-Ray. SDKs

Sections

Usare Powertools per AWS Lambda (Python) AWS SAM e per tracciare
Usare Powertools per AWS Lambda (Python) e AWS CDK per tracciare
Utilizzo di ADOT per strumentare le funzioni Python
Usare gli X-Ray SDK per strumentare le funzioni di Python
Attivazione del tracciamento con la console Lambda
Attivazione del tracciamento con la Lambda API
Attivazione del tracciamento con AWS CloudFormation
Interpretazione di una traccia X-Ray
Memorizzazione delle dipendenze di runtime in un livello (X-RaySDK)

Usare Powertools per AWS Lambda (Python) AWS SAM e per tracciare

Segui i passaggi seguenti per scaricare, creare e distribuire un'applicazione Hello World Python di esempio con i moduli Powertools for AWS Lambda (Python) integrati utilizzando il. AWS SAM Questa applicazione implementa un API backend di base e utilizza Powertools per l'emissione di log, metriche e tracce. È costituito da un endpoint Amazon API Gateway e da una funzione Lambda. Quando invii una GET richiesta all'endpoint API Gateway, la funzione Lambda richiama, invia log e metriche utilizzando Embedded Metric Format a e invia tracce a. CloudWatch AWS X-Ray La funzione restituisce un messaggio hello world.

Prerequisiti

Per completare le fasi riportate in questa sezione, è necessario:

Python 3.11
AWS CLI versione 2
AWS SAM CLIversione 1.75 o successiva. Se disponi di una versione precedente di AWS SAM CLI, consulta Aggiornamento di. AWS SAM CLI

Distribuisci un'applicazione di esempio AWS SAM

Inizializza l'applicazione utilizzando il modello Python Hello World.


sam init --app-template hello-world-powertools-python --name sam-app --package-type Zip --runtime python3.11 --no-tracing

Costruisci l'app.
```
cd sam-app && sam build
```
Distribuire l'app.
```
sam deploy --guided
```
Seguire le istruzioni visualizzate sullo schermo. Per accettare le opzioni predefinite fornite nell'esperienza interattiva, premi Enter.

Nota
Perché HelloWorldFunction potrebbe non avere un'autorizzazione definita, va bene? , assicurati di entrarey.

Scarica URL l'applicazione distribuita:


aws cloudformation describe-stacks --stack-name sam-app --query 'Stacks[0].Outputs[?OutputKey==`HelloWorldApi`].OutputValue' --output text

Invoca l'APIendpoint:
```
curl -X GET <URL_FROM_PREVIOUS_STEP>
```
In caso di esito positivo, vedrai questa risposta:
```
{"message":"hello world"}
```

Per ottenere le tracce per la funzione, esegui sam traces.


sam traces

L'output della traccia ha il seguente aspetto:


New XRay Service Graph
  Start time: 2023-02-03 14:59:50+00:00
  End time: 2023-02-03 14:59:50+00:00
  Reference Id: 0 - (Root) AWS::Lambda - sam-app-HelloWorldFunction-YBg8yfYtOc9j - Edges: [1]
   Summary_statistics:
     - total requests: 1
     - ok count(2XX): 1
     - error count(4XX): 0
     - fault count(5XX): 0
     - total response time: 0.924
  Reference Id: 1 - AWS::Lambda::Function - sam-app-HelloWorldFunction-YBg8yfYtOc9j - Edges: []
   Summary_statistics:
     - total requests: 1
     - ok count(2XX): 1
     - error count(4XX): 0
     - fault count(5XX): 0
     - total response time: 0.016
  Reference Id: 2 - client - sam-app-HelloWorldFunction-YBg8yfYtOc9j - Edges: [0]
   Summary_statistics:
     - total requests: 0
     - ok count(2XX): 0
     - error count(4XX): 0
     - fault count(5XX): 0
     - total response time: 0

XRay Event [revision 1] at (2023-02-03T14:59:50.204000) with id (1-63dd2166-434a12c22e1307ff2114f299) and duration (0.924s)
 - 0.924s - sam-app-HelloWorldFunction-YBg8yfYtOc9j [HTTP: 200]
 - 0.016s - sam-app-HelloWorldFunction-YBg8yfYtOc9j
   - 0.739s - Initialization
   - 0.016s - Invocation
     - 0.013s - ## lambda_handler
       - 0.000s - ## app.hello
   - 0.000s - Overhead

Si tratta di un API endpoint pubblico accessibile tramite Internet. È consigliabile eliminare l'endpoint dopo il test.
```
sam delete
```

X-Ray non traccia tutte le richieste nell'applicazione. X-Ray applica un algoritmo di campionamento per garantire che il tracciamento avvenga in modo efficiente, continuando allo stesso tempo a fornire un campione rappresentativo di tutte le richieste. La frequenza di campionamento è di una richiesta al secondo e del 5% delle altre richieste. Non è possibile configurare la frequenza di campionamento di X-Ray per le funzioni.

Usare Powertools per AWS Lambda (Python) e AWS CDK per tracciare

Segui i passaggi seguenti per scaricare, creare e distribuire un'applicazione Hello World Python di esempio con i moduli Powertools for AWS Lambda (Python) integrati utilizzando il. AWS CDK Questa applicazione implementa un API backend di base e utilizza Powertools per l'emissione di log, metriche e tracce. È costituito da un endpoint Amazon API Gateway e da una funzione Lambda. Quando invii una GET richiesta all'endpoint API Gateway, la funzione Lambda richiama, invia log e metriche utilizzando Embedded Metric Format a e invia tracce a. CloudWatch AWS X-Ray La funzione restituisce un messaggio hello world.

Prerequisiti

Per completare le fasi riportate in questa sezione, è necessario:

Python 3.11
AWS CLI versione 2
AWS CDK versione 2
AWS SAM CLIversione 1.75 o successiva. Se disponi di una versione precedente di AWS SAM CLI, consulta Aggiornamento di. AWS SAM CLI

Distribuisci un'applicazione di esempio AWS CDK

Crea una directory di progetto per la nuova applicazione.
```
mkdir hello-world
cd hello-world
```
Inizializza l'app.
```
cdk init app --language python
```
Installa le dipendenze di Python.
```
pip install -r requirements.txt
```
Crea una directory lambda_function nella cartella root.
```
mkdir lambda_function
cd lambda_function
```

Crea un file app.py e aggiungi il seguente codice al file. Questo è il codice per la funzione Lambda.


from aws_lambda_powertools.event_handler import APIGatewayRestResolver
from aws_lambda_powertools.utilities.typing import LambdaContext
from aws_lambda_powertools.logging import correlation_paths
from aws_lambda_powertools import Logger
from aws_lambda_powertools import Tracer
from aws_lambda_powertools import Metrics
from aws_lambda_powertools.metrics import MetricUnit

app = APIGatewayRestResolver()
tracer = Tracer()
logger = Logger()
metrics = Metrics(namespace="PowertoolsSample")

@app.get("/hello")
@tracer.capture_method
def hello():
    # adding custom metrics
    # See: https://docs.powertools.aws.dev/lambda-python/latest/core/metrics/
    metrics.add_metric(name="HelloWorldInvocations", unit=MetricUnit.Count, value=1)

    # structured log
    # See: https://docs.powertools.aws.dev/lambda-python/latest/core/logger/
    logger.info("Hello world API - HTTP 200")
    return {"message": "hello world"}

# Enrich logging with contextual information from Lambda
@logger.inject_lambda_context(correlation_id_path=correlation_paths.API_GATEWAY_REST)
# Adding tracer
# See: https://docs.powertools.aws.dev/lambda-python/latest/core/tracer/
@tracer.capture_lambda_handler
# ensures metrics are flushed upon request completion/failure and capturing ColdStart metric
@metrics.log_metrics(capture_cold_start_metric=True)
def lambda_handler(event: dict, context: LambdaContext) -> dict:
    return app.resolve(event, context)

Apri la directory hello_world. Dovrebbe essere visualizzato un file denominato hello_world_stack.py.
```
cd ..
cd hello_world
```

Apri hello_world_stack.py e aggiungi il seguente codice al file. Contiene il Lambda Constructor, che crea la funzione Lambda, configura le variabili di ambiente per Powertools e imposta la conservazione dei log su una settimana, e il costruttore 1, che crea il ApiGatewayv. REST API


from aws_cdk import (
    Stack,
    aws_apigateway as apigwv1,
    aws_lambda as lambda_,
    CfnOutput,
    Duration
)
from constructs import Construct

class HelloWorldStack(Stack):

    def __init__(self, scope: Construct, construct_id: str, **kwargs) -> None:
        super().__init__(scope, construct_id, **kwargs)

        # Powertools Lambda Layer
        powertools_layer = lambda_.LayerVersion.from_layer_version_arn(
            self,
            id="lambda-powertools",
            # At the moment we wrote this example, the aws_lambda_python_alpha CDK constructor is in Alpha, o we use layer to make the example simpler
            # See https://docs.aws.amazon.com/cdk/api/v2/python/aws_cdk.aws_lambda_python_alpha/README.html
            # Check all Powertools layers versions here: https://docs.powertools.aws.dev/lambda-python/latest/#lambda-layer
            layer_version_arn=f"arn:aws:lambda:{self.region}:017000801446:layer:AWSLambdaPowertoolsPythonV2:21"
        )

        function = lambda_.Function(self,
            'sample-app-lambda',
            runtime=lambda_.Runtime.PYTHON_3_11,
            layers=[powertools_layer],
            code = lambda_.Code.from_asset("./lambda_function/"),
            handler="app.lambda_handler",
            memory_size=128,
            timeout=Duration.seconds(3),
            architecture=lambda_.Architecture.X86_64,
            environment={
                "POWERTOOLS_SERVICE_NAME": "PowertoolsHelloWorld",
                "POWERTOOLS_METRICS_NAMESPACE": "PowertoolsSample",
                "LOG_LEVEL": "INFO"
            }
        )

        apigw = apigwv1.RestApi(self, "PowertoolsAPI", deploy_options=apigwv1.StageOptions(stage_name="dev"))

        hello_api = apigw.root.add_resource("hello")
        hello_api.add_method("GET", apigwv1.LambdaIntegration(function, proxy=True))

        CfnOutput(self, "apiUrl", value=f"{apigw.url}hello")

Distribuisci l'applicazione.
```
cd ..
cdk deploy
```

Ottieni la versione dell'applicazione distribuita: URL


aws cloudformation describe-stacks --stack-name HelloWorldStack --query 'Stacks[0].Outputs[?OutputKey==`apiUrl`].OutputValue' --output text

Invoca l'APIendpoint:
```
curl -X GET <URL_FROM_PREVIOUS_STEP>
```
In caso di esito positivo, vedrai questa risposta:
```
{"message":"hello world"}
```

Per ottenere le tracce per la funzione, esegui sam traces.


sam traces

L'output delle tracce ha la struttura seguente:


New XRay Service Graph
  Start time: 2023-02-03 14:59:50+00:00
  End time: 2023-02-03 14:59:50+00:00
  Reference Id: 0 - (Root) AWS::Lambda - sam-app-HelloWorldFunction-YBg8yfYtOc9j - Edges: [1]
   Summary_statistics:
     - total requests: 1
     - ok count(2XX): 1
     - error count(4XX): 0
     - fault count(5XX): 0
     - total response time: 0.924
  Reference Id: 1 - AWS::Lambda::Function - sam-app-HelloWorldFunction-YBg8yfYtOc9j - Edges: []
   Summary_statistics:
     - total requests: 1
     - ok count(2XX): 1
     - error count(4XX): 0
     - fault count(5XX): 0
     - total response time: 0.016
  Reference Id: 2 - client - sam-app-HelloWorldFunction-YBg8yfYtOc9j - Edges: [0]
   Summary_statistics:
     - total requests: 0
     - ok count(2XX): 0
     - error count(4XX): 0
     - fault count(5XX): 0
     - total response time: 0

XRay Event [revision 1] at (2023-02-03T14:59:50.204000) with id (1-63dd2166-434a12c22e1307ff2114f299) and duration (0.924s)
 - 0.924s - sam-app-HelloWorldFunction-YBg8yfYtOc9j [HTTP: 200]
 - 0.016s - sam-app-HelloWorldFunction-YBg8yfYtOc9j
   - 0.739s - Initialization
   - 0.016s - Invocation
     - 0.013s - ## lambda_handler
       - 0.000s - ## app.hello
   - 0.000s - Overhead

Si tratta di un API endpoint pubblico accessibile tramite Internet. È consigliabile eliminare l'endpoint dopo il test.
```
cdk destroy
```

Utilizzo di ADOT per strumentare le funzioni Python

ADOTfornisce layer Lambda completamente gestiti che racchiudono tutto ciò di cui hai bisogno per raccogliere dati di telemetria utilizzando. OTel SDK Usando questo livello, è possibile strumentare le funzioni Lambda senza dover modificare alcun codice funzione. Puoi anche configurare il tuo layer per eseguire l'inizializzazione personalizzata di. OTel Per ulteriori informazioni, consulta Configurazione personalizzata per ADOT Collector on Lambda nella ADOT documentazione.

Per i runtime Python, puoi aggiungere il layer AWS Lambda gestito per ADOT Python per strumentare automaticamente le tue funzioni. Questo livello funziona sia per architetture arm64 che x86_64. Per istruzioni dettagliate su come aggiungere questo layer, consulta AWS Distro for OpenTelemetry Lambda Support for ADOT Python nella documentazione.

Usare gli X-Ray SDK per strumentare le funzioni di Python

Per registrare i dettagli sulle chiamate effettuate dalla funzione Lambda ad altre risorse nell'applicazione, è anche possibile utilizzare il SDK AWS X-Ray per Python. Per ottenere ilSDK, aggiungi il aws-xray-sdk pacchetto alle dipendenze dell'applicazione.

Esempio requirements.txt


jsonpickle==1.3
aws-xray-sdk==2.4.3

Nel codice della funzione, puoi strumentare AWS SDK i client patchando la boto3 libreria con il aws_xray_sdk.core modulo.

Esempio funzione — Tracciare un client AWS SDK


import boto3
from aws_xray_sdk.core import xray_recorder
from aws_xray_sdk.core import patch_all

logger = logging.getLogger()
logger.setLevel(logging.INFO)
patch_all()

client = boto3.client('lambda')
client.get_account_settings()

def lambda_handler(event, context):
    logger.info('## ENVIRONMENT VARIABLES\r' + jsonpickle.encode(dict(**os.environ)))
  ...

Dopo aver aggiunto le dipendenze corrette e apportato le modifiche necessarie al codice, attiva la traccia nella configurazione della funzione tramite la console Lambda o il. API

Attivazione del tracciamento con la console Lambda

Per attivare il tracciamento attivo sulla funzione Lambda con la console, attenersi alla seguente procedura:

Per attivare il tracciamento attivo

Aprire la pagina Funzioni della console Lambda.
Scegliere una funzione.
Scegliere Configuration (Configurazione) e quindi Monitoring and operations tools (Strumenti di monitoraggio e operazioni).
Scegli Modifica.
In X-Ray, attivare Active tracing (Tracciamento attivo).
Seleziona Salva.

Attivazione del tracciamento con la Lambda API

Configura il tracciamento sulla tua funzione Lambda con AWS SDK o, utilizza AWS CLI le API seguenti operazioni:

Il AWS CLI comando di esempio seguente abilita il tracciamento attivo su una funzione denominata my-function.


aws lambda update-function-configuration --function-name my-function \
--tracing-config Mode=Active

La modalità di tracciamento fa parte della configurazione specifica della versione quando si pubblica una versione della funzione. Non è possibile modificare la modalità di tracciamento in una versione pubblicata.

Attivazione del tracciamento con AWS CloudFormation

Per attivare il tracciamento su una AWS::Lambda::Function risorsa in un AWS CloudFormation modello, utilizzate la proprietà. TracingConfig

Esempio function-inline.yml – Configurazione del tracciamento


Resources:
  function:
    Type: AWS::Lambda::Function
    Properties:
      TracingConfig:
        Mode: Active
      ...

Per una AWS::Serverless::Function risorsa AWS Serverless Application Model (AWS SAM), utilizzate la Tracing proprietà.

Esempio template.yml – Configurazione del tracciamento


Resources:
  function:
    Type: AWS::Serverless::Function
    Properties:
      Tracing: Active
      ...

Interpretazione di una traccia X-Ray

La funzione ha bisogno dell'autorizzazione per caricare i dati di traccia su X-Ray. Quando si attiva il tracciamento nella console Lambda, Lambda aggiunge le autorizzazioni necessarie al ruolo di esecuzione della funzione. Altrimenti, aggiungete la AWSXRayDaemonWriteAccesspolitica al ruolo di esecuzione.

Dopo aver configurato il tracciamento attivo, è possibile osservare richieste specifiche tramite l'applicazione. Il grafico dei servizi X-Ray mostra informazioni sull'applicazione e tutti i suoi componenti. Il seguente esempio mostra un'applicazione con due funzioni. La funzione principale elabora gli eventi e talvolta restituisce errori. La seconda funzione in alto elabora gli errori che compaiono nel gruppo di log della prima e utilizza X-Ray, Amazon Simple Storage Service (Amazon S3) e Amazon Logs. AWS SDK CloudWatch

Diagramma che mostra due applicazioni separate e le rispettive mappe di servizio in X-Ray

In X-Ray, una traccia registra informazioni su una richiesta elaborata da uno o più servizi. Lambda registra 2 segmenti per traccia, che creano due nodi sul grafico del servizio. L'immagine seguente evidenzia questi due nodi:

Una mappa del servizio X-Ray con una sola funzione.

Il primo nodo a sinistra rappresenta il servizio Lambda che riceve la richiesta di chiamata. Il secondo nodo rappresenta la specifica funzione Lambda. L'esempio seguente mostra una traccia con questi 2 segmenti. Entrambi sono nominati my-function, ma uno ha l'origine AWS::Lambda e l'altro ha l'origine AWS::Lambda::Function. Se il segmento AWS::Lambda mostra un errore, il servizio Lambda ha avuto un problema. Se il AWS::Lambda::Function segmento mostra un errore, la funzione ha avuto un problema.

Una traccia X-Ray che mostra la latenza su ogni sottosegmento di una specifica chiamata Lambda.

Questo esempio espande il segmento AWS::Lambda::Function per visualizzare i relativi tre sottosegmenti.

Nota

AWS sta attualmente implementando modifiche al servizio Lambda. A causa di queste modifiche, potresti notare piccole differenze tra la struttura e il contenuto dei messaggi di log di sistema e dei segmenti di traccia emessi da diverse funzioni Lambda nel tuo Account AWS.

La traccia di esempio mostrata qui illustra il segmento di funzione vecchio stile. Le differenze tra i segmenti vecchio e nuovo stile sono descritte nei paragrafi seguenti.

Queste modifiche verranno implementate nelle prossime settimane e tutte le funzioni, Regioni AWS ad eccezione della Cina e delle GovCloud regioni, passeranno all'utilizzo dei messaggi di registro e dei segmenti di traccia di nuovo formato.

Il segmento di funzioni vecchio stile contiene i seguenti sottosegmenti:

Inizializzazione – Rappresenta il tempo trascorso a caricare la funzione e ad eseguire il codice di inizializzazione. Questo sottosegmento viene visualizzato solo per il primo evento che viene elaborato da ogni istanza della funzione.
Chiamata: rappresenta il tempo impiegato per eseguire il codice del gestore.
Overhead: rappresenta il tempo impiegato dal runtime Lambda per prepararsi a gestire l'evento successivo.

Il segmento di funzione di nuovo stile non contiene un sottosegmento Invocation. I sottosegmenti dei clienti sono invece collegati direttamente al segmento di funzioni. Per ulteriori informazioni sulla struttura dei segmenti di funzioni vecchio e nuovo stile, consulta Informazioni sui monitoraggi di X-Ray.

Puoi anche strumentare HTTP i client, registrare SQL le interrogazioni e creare sottosegmenti personalizzati con annotazioni e metadati. Per ulteriori informazioni, consulta SDK AWS X-Ray per Python nella Guida per gli sviluppatori di AWS X-Ray .

Prezzi

Puoi utilizzare il tracciamento X-Ray gratuitamente ogni mese fino a un determinato limite come parte del AWS piano gratuito. Oltre la soglia, X-Ray addebita lo storage di traccia e il recupero. Per ulteriori informazioni, consulta Prezzi di AWS X-Ray.

Memorizzazione delle dipendenze di runtime in un livello (X-RaySDK)

Se utilizzate X-Ray SDK per strumentare AWS SDK i client del codice della funzione, il pacchetto di implementazione può diventare piuttosto grande. Per evitare di caricare le dipendenze di runtime ogni volta che aggiorni il codice della funzione, impacchetta X-Ray in SDK un layer Lambda.

L'esempio seguente mostra una risorsa AWS::Serverless::LayerVersion che memorizza SDK AWS X-Ray per Python.

Esempio template.yml – Livello delle dipendenze


Resources:
  function:
    Type: AWS::Serverless::Function
    Properties:
      CodeUri: function/.
      Tracing: Active
      Layers:
        - !Ref libs
      ...
  libs:
    Type: AWS::Serverless::LayerVersion
    Properties:
      LayerName: blank-python-lib
      Description: Dependencies for the blank-python sample app.
      ContentUri: package/.
      CompatibleRuntimes:
        - python3.11

Con questa configurazione, si aggiorna il livello della libreria solo se si modificano le dipendenze di runtime. Poiché il pacchetto di implementazione della funzione contiene solo il codice, questo può contribuire a ridurre i tempi di caricamento.

La creazione di un layer per le dipendenze richiede modifiche alla compilazione per generare l'archivio dei layer prima della distribuzione. Per un esempio funzionante, vedere l'applicazione di esempio blank-python .

Avvertimento JavaScript è disabilitato o non è disponibile nel tuo browser.

Per usare la documentazione AWS, JavaScript deve essere abilitato. Consulta le pagine della guida del browser per le istruzioni.

Convenzioni dei documenti

Test in corso

Compilazione con Ruby