Instrumentação do código Python no AWS Lambda - AWS Lambda

As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

Instrumentação do código Python no AWS Lambda

O Lambda se integra ao AWS X-Ray para ajudar você a rastrear, depurar e otimizar aplicações do Lambda. É possível usar o X-Ray para rastrear uma solicitação enquanto ela atravessa recursos na aplicação, o que pode incluir funções Lambda e outros produtos da AWS.

Para enviar dados de rastreamento ao X-Ray, é possível usar uma das três bibliotecas SDK:

Cada um dos SDKs oferece maneiras de enviar dados de telemetria ao serviço do X-Ray. Em seguida, é possível usar o X-Ray para visualizar, filtrar e obter insights sobre as métricas de performance da aplicação para identificar problemas e oportunidades de otimização.

Importante

Os SDKs do X-Ray e do Powertools para AWS Lambda fazem parte de uma solução de instrumentação totalmente integrada oferecida pela AWS. As camadas do Lambda para ADOT fazem parte de um padrão em todo o setor para instrumentação de rastreamento que coleta mais dados em geral, mas pode não ser adequado para todos os casos de uso. Você pode implementar o end-to-end rastreamento no X-Ray usando qualquer uma das soluções. Para saber mais sobre como escolher entre elas, consulte Como escolher entre os SDKs do AWS Distro para OpenTelemetry e do X-Ray.

Uso do Powertools para AWS Lambda (Python) e do AWS SAM para rastreamento

Siga as etapas abaixo para baixar, criar e implantar um exemplo de aplicação Python do Hello World com os módulos integrados do Powertools para AWS Lambda Python usando o AWS SAM. Esta aplicação implementa um back-end de API básico e usa o Powertools para emitir logs, métricas e rastreamentos. Consiste em um endpoint do Amazon API Gateway e uma função do Lambda. Quando você envia uma solicitação GET para o endpoint do API Gateway, a função Lambda invoca, envia registros e métricas usando o formato métrico incorporado e envia rastreamentos CloudWatch para. AWS X-Ray A função retorna uma mensagem de hello world.

Pré-requisitos

Para executar as etapas desta seção, você deve ter o seguinte:

Implantar uma aplicação de exemplo do AWS SAM
  1. Inicialize a aplicação usando o modelo Python do Hello World.

    sam init --app-template hello-world-powertools-python --name sam-app --package-type Zip --runtime python3.9 --no-tracing
  2. Crie a aplicação.

    cd sam-app && sam build
  3. Implante o aplicativo.

    sam deploy --guided
  4. Siga as instruções na tela. Para aceitar as opções padrão fornecidas na experiência interativa, pressione Enter.

    nota

    Pois HelloWorldFunction pode não ter autorização definida, está tudo bem? , certifique-se de entrary.

  5. Obtenha o URL da aplicação implantada:

    aws cloudformation describe-stacks --stack-name sam-app --query 'Stacks[0].Outputs[?OutputKey==`HelloWorldApi`].OutputValue' --output text
  6. Invoque o endpoint da API:

    curl -X GET <URL_FROM_PREVIOUS_STEP>

    Se tiver êxito, você verá esta resposta:

    {"message":"hello world"}
  7. Para obter os rastreamentos da função, execute sam traces.

    sam traces

    A saída de rastreamento se parece com:

    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
  8. Este é um endpoint de API pública que é acessado pela Internet. Recomendamos excluir o endpoint após o teste.

    sam delete

O X-Ray não rastreia todas as solicitações para sua aplicação. O X-Ray aplica um algoritmo de amostragem para garantir que o rastreamento seja eficiente, enquanto ainda fornece uma amostra representativa das solicitações. A taxa de amostragem é uma solicitação por segundo e 5% de solicitações adicionais.

nota

Não é possível configurar a taxa de amostragem do X-Ray para suas funções.

Uso do Powertools para AWS Lambda (Python) e do AWS CDK para rastreamento

Siga as etapas abaixo para baixar, criar e implantar um exemplo de aplicação Python do Hello World com os módulos integrados do Powertools para AWS Lambda Python usando o AWS CDK. Esta aplicação implementa um back-end de API básico e usa o Powertools para emitir logs, métricas e rastreamentos. Consiste em um endpoint do Amazon API Gateway e uma função do Lambda. Quando você envia uma solicitação GET para o endpoint do API Gateway, a função Lambda invoca, envia registros e métricas usando o formato métrico incorporado e envia rastreamentos CloudWatch para. AWS X-Ray A função retorna uma mensagem de hello world.

Pré-requisitos

Para executar as etapas desta seção, você deve ter o seguinte:

Implantar uma aplicação de exemplo do AWS CDK
  1. Crie um diretório de projeto para sua aplicação.

    mkdir hello-world cd hello-world
  2. Inicialize a aplicação.

    cdk init app --language python
  3. Instale as dependências do Python.

    pip install -r requirements.txt
  4. Crie um diretório lambda_function na pasta raiz.

    mkdir lambda_function cd lambda_function
  5. Crie um arquivo app.py e adicione o código a seguir ao arquivo. Este é o código da função do 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)
  6. Abra o diretório hello_world. Você verá um arquivo chamado hello-world-stack.py.

    cd .. cd hello_world
  7. Abra o hello_world_stack.py e adicione o código a seguir ao arquivo. Ele contém o Lambda Constructor, que cria a função Lambda, configura variáveis de ambiente para Powertools e define a retenção de registros em uma semana, e o Construtor ApiGatewayv 1, que cria a API REST.

    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_9, 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")
  8. Implante o aplicativo.

    cd .. cdk deploy
  9. Obtenha o URL da aplicação implantada:

    aws cloudformation describe-stacks --stack-name HelloWorldStack --query 'Stacks[0].Outputs[?OutputKey==`apiUrl`].OutputValue' --output text
  10. Invoque o endpoint da API:

    curl -X GET <URL_FROM_PREVIOUS_STEP>

    Se tiver êxito, você verá esta resposta:

    {"message":"hello world"}
  11. Para obter os rastreamentos da função, execute sam traces.

    sam traces

    A saída dos rastreamentos se parece com:

    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
  12. Este é um endpoint de API pública que é acessado pela Internet. Recomendamos excluir o endpoint após o teste.

    cdk destroy

Usar o ADOT para instrumentar funções Python

O ADOT fornece camadas do Lambda totalmente gerenciadas que empacotam tudo o que você precisa para coletar dados de telemetria usando o SDK do OTel. Ao consumir essa camada, é possível instrumentar suas funções Lambda sem precisar modificar nenhum código de função. Você também pode configurar sua camada para fazer a inicialização personalizada do OTel. Para obter mais informações, consulte Custom configuration for the ADOT Collector on Lambda (Configuração personalizada para o ADOT Collector no Lambda) na documentação do ADOT.

Para runtimes Python, você pode adicionar a camada do Lambda gerenciada pela AWS para ADOT Python a fim de instrumentar suas funções automaticamente. Essa camada funciona nas arquiteturas arm64 e x86_64. Para obter instruções detalhadas sobre como adicionar essa camada, consulte AWSDistro for OpenTelemetry Lambda Support for Python na documentação do ADOT.

Usar o SDK do X-Ray para instrumentar suas funções Python

Para registrar detalhes sobre as chamadas feitas pela sua função do Lambda para outros recursos na sua aplicação, você também pode usar o AWS X-Ray SDK for Python. Para obter o SDK, adicione o pacote aws-xray-sdk às dependências do aplicativo.

exemplo requirements.txt
jsonpickle==1.3 aws-xray-sdk==2.4.3

No seu código de função, você pode instrumentar clientes AWS SDK aplicando patch à biblioteca boto3 com o módulo aws_xray_sdk.core.

exemplo função: rastrear um cliente 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))) ...

Depois de adicionar as dependências corretas e fazer as devidas mudanças de código, ative o rastreamento na configuração da sua função usando o console do Lambda ou a API.

Ativar o rastreamento com o console do Lambda

Para alternar o rastreamento ativo na sua função do Lambda usando o console, siga as etapas abaixo:

Para ativar o rastreamento ativo
  1. Abra a página Funções do console do Lambda.

  2. Escolha uma função.

  3. Escolha Configuration (Configuração) e depois Monitoring and operations tools (Ferramentas de monitoramento e operações).

  4. Selecione a opção Editar.

  5. Em X-Ray, ative a opção Active tracing (Rastreamento ativo).

  6. Escolha Salvar.

Ativar o rastreamento com a API do Lambda

Configure o rastreamento na sua função do Lambda com aAWS CLI ou o AWS SDK, usando as seguintes operações de API:

O exemplo de comando da AWS CLI a seguir habilita o rastreamento ativo em uma função chamada my-function.

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

O modo de rastreamento faz parte da configuração específica da versão quando você publica uma versão da função. Não é possível alterar o modo de rastreamento em uma versão publicada.

Ativar o rastreamento com o AWS CloudFormation

Para ativar o rastreamento ativo em um recurso AWS::Lambda::Function em um modelo do AWS CloudFormation, use a propriedade TracingConfig.

exemplo function-inline.yml: configuração de rastreamento
Resources: function: Type: AWS::Lambda::Function Properties: TracingConfig: Mode: Active ...

Para um recurso do AWS Serverless Application Model (AWS SAM) AWS::Serverless::Function, use a propriedade Tracing.

exemplo template.yml: configuração de rastreamento
Resources: function: Type: AWS::Serverless::Function Properties: Tracing: Active ...

Interpretar um rastreamento do X-Ray

Sua função precisa de permissão para carregar dados de rastreamento no X-Ray. Quando você ativa o rastreamento ativo no console do Lambda, o Lambda adiciona as permissões necessárias à função de execução da função. Caso contrário, adicione a AWSXRayDaemonWriteAccesspolítica à função de execução.

Após configurar o rastreamento ativo, você pode observar solicitações específicas por meio da aplicação. O grafo de serviço do X-Ray exibe informações sobre sua aplicação e todos os componentes. O exemplo a seguir do aplicativo de exemplo processador de erros mostra um aplicativo com duas funções. A função principal processa eventos e, às vezes, retorna erros. A segunda função na parte superior processa os erros que aparecem no grupo de registros da primeira e usa o AWS SDK para chamar o X-Ray, o Amazon Simple Storage Service (Amazon S3) e o Amazon Logs. CloudWatch


        Um diagrama que mostra duas aplicações separadas e seus respectivos mapas de serviço no X-Ray

O X-Ray não rastreia todas as solicitações para sua aplicação. O X-Ray aplica um algoritmo de amostragem para garantir que o rastreamento seja eficiente, enquanto ainda fornece uma amostra representativa das solicitações. A taxa de amostragem é uma solicitação por segundo e 5% de solicitações adicionais.

nota

Não é possível configurar a taxa de amostragem do X-Ray para suas funções.

Ao usar o rastreamento ativo, o Lambda registra dois segmentos por rastreamento, o que cria dois nós no grafo de serviços. A imagem a seguir destaca estes dois nós para a função primária da exemplo de aplicação do processador de erros.


      Um mapa de serviço do X-Ray com uma única função.

O primeiro nó à esquerda representa o serviço do Lambda, que recebe a solicitação de invocação. O segundo nó representa a sua função do Lambda específica. O exemplo a seguir mostra um rastreamento com esses dois segmentos. Ambos têm o nome my-function, mas um tem a origem AWS::Lambda e o outro, a origem AWS::Lambda::Function.


        Um rastreamento do X-Ray que mostra latência em cada subsegmento de uma invocação específica do Lambda.

Este exemplo expande o segmento de função para mostrar seus três subsegmentos:

  • Inicialização: representa o tempo gasto carregando a função e executando o código de inicialização. Esse subsegmento aparece somente para o primeiro evento que cada instância da função processa.

  • Invocação: representa o tempo gasto na execução do código do manipulador.

  • Sobrecarga: representa o tempo gasto pelo runtime do Lambda preparando-se para lidar com o próximo evento.

Você também pode instrumentar clientes HTTP, registrar consultas SQL e criar subsegmentos personalizados com anotações e metadados. Para obter mais informações, consulte AWS X-Ray SDK for Python no Guia do desenvolvedor do AWS X-Ray.

Definição de preço

Você pode usar o rastreamento do X-Ray gratuitamente todos os meses até determinado limite como parte do nível gratuito da AWS. Além do limite, o X-Ray cobra por armazenamento e recuperação de rastreamento. Para obter mais informações, consulte Definição de preços do AWS X-Ray.

Armazenar dependências de runtime em uma camada (SDK do X-Ray)

Se você usar o X-Ray SDK para instrumentar os clientes do AWS SDK com seu código de função, seu pacote de implantação poderá se tornar bastante grande. Para evitar o upload de dependências de runtime todas as vezes que você atualizar seu código de função, empacote o SDK do X-Ray em uma camada do Lambda.

O exemplo a seguir mostra um recurso AWS::Serverless::LayerVersion que armazena o AWS X-Ray SDK for Python.

exemplo template.yml: camada de dependências
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.8

Com essa configuração, você atualizará a camada de biblioteca somente se alterar as dependências de runtime. Já que o pacote de implantação de função inclui apenas o seu código, isso pode ajudar a reduzir o tempo de upload.

A criação de uma camada de dependências requer alterações de compilação para gerar o arquivo da camada antes da implantação. Para obter um exemplo funcional, consulte o aplicativo de exemplo blank-python.