Instrumentación de código C# en AWS Lambda

Lambda se integra con AWS X-Ray para permitirle seguir, depurar y optimizar aplicaciones de Lambda. Puede utilizar X-Ray para seguir una solicitud mientras atraviesa los recursos de la aplicación, que pueden incluir funciones de Lambda y otros servicios de AWS.

Para enviar datos de seguimiento a X-Ray, puede utilizar una de estas tres bibliotecas de SDK:

• AWS Distro for OpenTelemetry (ADOT): una distribución segura, lista para producción y con soporte de AWS del OpenTelemetry (OTel) SDK.

• AWS X-Ray SDK para .NET: un SDK para generar y enviar datos de seguimiento a X-Ray.

• Powertools para AWS Lambda (.NET): un kit de herramientas para desarrolladores destinado a implementar prácticas recomendadas sin servidor y aumentar la velocidad de los desarrolladores.

Cada uno de los SDK ofrecen formas de enviar los datos de telemetría al servicio X-Ray. Tras ello, se puede utilizar X-Ray para consultar, filtrar y obtener información sobre las métricas de rendimiento de la aplicación con el fin de identificar problemas y oportunidades de optimización.

importante

Los SDK de X-Ray y Powertools para AWS Lambda son parte de una solución de instrumentación completamente integrada que ofrece AWS. Las capas Lambda de ADOT forman parte de un estándar que abarca todo el sector para la instrumentación de seguimiento que recopila más datos en general, pero es posible que no sean adecuadas para todos los casos de uso. Puede implementar el seguimiento integral en X-Ray con cualquiera de las soluciones. Para obtener más información sobre cuál elegir, consulte Elegir entre SDK de AWS Distro para OpenTelemetry y X-Ray.

Uso de Powertools para AWS Lambda (.NET) y AWS SAM para el seguimiento

Siga los pasos que figuran a continuación para descargar, crear e implementar una aplicación de muestra “Hola, mundo” de C# con módulos de Powertools para AWS Lambda (.NET) integrados mediante AWS SAM. Esta aplicación implementa un backend de API básico y utiliza Powertools para emitir registros, métricas y seguimiento. Consta de un punto de conexión de Amazon API Gateway y una función de Lambda. Cuando se envía una solicitud GET al punto de conexión de API Gateway, la función de Lambda se invoca, envía registros y métricas a CloudWatch mediante Embedded Metric Format y envía seguimiento a AWS X-Ray. La función devuelve el mensaje hello world.

Requisitos previos

Para completar los pasos de esta sección, debe disponer de lo siguiente:

• .NET 6 o .NET 8

• Versión 2 de la AWS CLI

• Versión 1.75 o posterior de la CLI de AWS SAM. Si tiene una versión anterior de la CLI de AWS SAM, consulte Actualización de la CLI de AWS SAM.

Implementar una aplicación de ejemplo de AWS SAM

1. Inicialice la aplicación utilizando la plantilla de TypeScript de tipo Hola Mundo.

   sam init --app-template hello-world-powertools-dotnet --name sam-app --package-type Zip --runtime dotnet6 --no-tracing

2. Compile la aplicación.

   cd sam-app && sam build

3. Implemente la aplicación.

   sam deploy --guided

4. Siga las indicaciones que aparecen en pantalla. Para aceptar las opciones predeterminadas proporcionadas en la experiencia interactiva, oprima Enter.

   nota

   En HelloWorldFunction es posible que no tenga definida la autorización, ¿está bien?, asegúrese de ingresar y.

5. Obtenga la URL de la aplicación implementada:

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

6. Invoque el punto de conexión de la API:

   curl <URL_FROM_PREVIOUS_STEP>

   Si se realiza de forma correcta, verá el siguiente resultado:

   {"message":"hello world"}

7. Para obtener el seguimiento de la función, ejecute sam traces.

   sam traces

   El resultado del seguimiento tendrá este aspecto:

   New XRay Service Graph
     Start time: 2023-02-20 23:05:16+08:00
     End time: 2023-02-20 23:05:16+08:00
     Reference Id: 0 - AWS::Lambda - sam-app-HelloWorldFunction-pNjujb7mEoew - Edges: [1]
      Summary_statistics:
        - total requests: 1
        - ok count(2XX): 1
        - error count(4XX): 0
        - fault count(5XX): 0
        - total response time: 2.814
     Reference Id: 1 - AWS::Lambda::Function - sam-app-HelloWorldFunction-pNjujb7mEoew - Edges: []
      Summary_statistics:
        - total requests: 1
        - ok count(2XX): 1
        - error count(4XX): 0
        - fault count(5XX): 0
        - total response time: 2.429
     Reference Id: 2 - (Root) AWS::ApiGateway::Stage - sam-app/Prod - Edges: [0]
      Summary_statistics:
        - total requests: 1
        - ok count(2XX): 1
        - error count(4XX): 0
        - fault count(5XX): 0
        - total response time: 2.839
     Reference Id: 3 - client - sam-app/Prod - Edges: [2]
      Summary_statistics:
        - total requests: 0
        - ok count(2XX): 0
        - error count(4XX): 0
        - fault count(5XX): 0
        - total response time: 0
   
   XRay Event [revision 3] at (2023-02-20T23:05:16.521000) with id (1-63f38c2c-270200bf1d292a442c8e8a00) and duration (2.877s)
    - 2.839s - sam-app/Prod [HTTP: 200]
      - 2.836s - Lambda [HTTP: 200]
    - 2.814s - sam-app-HelloWorldFunction-pNjujb7mEoew [HTTP: 200]
    - 2.429s - sam-app-HelloWorldFunction-pNjujb7mEoew
      - 0.230s - Initialization
      - 2.389s - Invocation
        - 0.600s - ## FunctionHandler
          - 0.517s - Get Calling IP
      - 0.039s - Overhead

8. Se trata de un punto de conexión de API pública al que se puede acceder a través de Internet. Se recomienda eliminar el punto de conexión después de las pruebas.

   sam delete

X-Ray no sigue todas las solicitudes realizadas a la aplicación. X-Ray aplica un algoritmo de muestreo para garantizar que el seguimiento sea eficiente, a la vez que sigue proporcionando una muestra representativa de todas las solicitudes. La tasa de muestreo es 1 solicitud por segundo y un 5 por ciento de las solicitudes adicionales.

nota

La frecuencia de muestreo de X-Ray no se puede configurar para las funciones.

Uso del SDK de X-Ray para instrumentar las funciones de .NET

Puede instrumentar su código de función para registrar metadatos y rastrear llamadas descendentes. Para registrar detalles sobre las llamadas que realiza su función a otros recursos y servicios, use el AWS X-Ray SDK para .NET. Para obtener el SDK, agregue los paquetes AWSXRayRecorder al archivo de proyecto.

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net8.0</TargetFramework>
    <GenerateRuntimeConfigurationFiles>true</GenerateRuntimeConfigurationFiles>
    <AWSProjectType>Lambda</AWSProjectType>
  </PropertyGroup>
  <ItemGroup>
    <PackageReference Include="Amazon.Lambda.Core" Version="2.1.0" />
    <PackageReference Include="Amazon.Lambda.SQSEvents" Version="2.1.0" />
    <PackageReference Include="Amazon.Lambda.Serialization.Json" Version="2.1.0" />
    <PackageReference Include="AWSSDK.Core" Version="3.7.103.24" />
    <PackageReference Include="AWSSDK.Lambda" Version="3.7.104.3" />
    <PackageReference Include="AWSXRayRecorder.Core" Version="2.13.0" />
    <PackageReference Include="AWSXRayRecorder.Handlers.AwsSdk" Version="2.11.0" />
  </ItemGroup>
</Project>

Hay una gama de paquetes Nuget que proporcionan instrumentación automática para SDKs AWS, Entity Framework y solicitudes HTTP. Para ver el conjunto completo de opciones de configuración, consulte SDK AWS X-Ray para .NET en la Guía para desarrolladores AWS X-Ray.

Una vez que haya agregado los paquetes Nuget deseados, configure la instrumentación automática. La mejor práctica es realizar esta configuración fuera de la función de control de la función. Esto le permite aprovechar la reutilización del entorno de ejecución para mejorar el rendimiento de la función. En el siguiente ejemplo de código, se llama al método RegisterXRayForAllServices en el constructor de la función para añadir instrumentación a todas las llamadas al SDK de AWS.

[assembly: LambdaSerializer(typeof(Amazon.Lambda.Serialization.SystemTextJson.DefaultLambdaJsonSerializer))]

namespace GetProductHandler;

public class Function
{
    private readonly IDatabaseRepository _repo;
    
    public Function()
    {
        // Add auto instrumentation for all AWS SDK calls
        // It is important to call this method before initializing any SDK clients
        AWSSDKHandler.RegisterXRayForAllServices();
        this._repo = new DatabaseRepository();
    }
    
    public async Task<APIGatewayProxyResponse> FunctionHandler(APIGatewayProxyRequest request)
    {
        var id = request.PathParameters["id"];
        
        var databaseRecord = await this._repo.GetById(id);
        
        return new APIGatewayProxyResponse 
        {
            StatusCode = (int)HttpStatusCode.OK,
            Body = JsonSerializer.Serialize(databaseRecord)
        };
    }
}

Activación del seguimiento con la consola de Lambda

Para activar el seguimiento activo de la función Lambda mediante la consola, siga estos pasos:

Para activar el seguimiento activo

1. Abra la página de Funciones en la consola de Lambda.

2. Elija una función.

3. Elija Configuration (Configuración), y luego Monitoring and operations tools (Herramientas de supervisión y operaciones).

4. Elija Editar.

5. En X-Ray, active Active tracing (Rastreo activo).

6. Elija Guardar.

Activación del seguimiento con la API de Lambda

Configure el rastreo en la función Lambda con AWS CLI o SDK de AWS, utilice las siguientes operaciones de API:

• UpdateFunctionConfiguration

• GetFunctionConfiguration

• CreateFunction

El siguiente comando de ejemplo de la AWS CLI habilita el seguimiento activo en una función llamada my-function.

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

El modo de seguimiento forma parte de la configuración específica de la versión, cuando se publica una versión de la función. No se puede cambiar el modo de seguimiento de una versión publicada.

Activación del seguimiento con AWS CloudFormation

Para activar el seguimiento en un recurso de AWS::Lambda::Function de una plantilla de AWS CloudFormation, utilice la propiedad TracingConfig.

ejemplo función-inline.yml: configuración de rastreo

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

Para un recurso AWS::Serverless::Function de AWS Serverless Application Model (AWS SAM) , utilice la propiedad Tracing.

ejemplo template.yml: configuración de rastreo

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

Interpretación de un seguimiento de X-Ray

Su función necesita permiso para cargar datos de rastreo en X-Ray. Cuando activa el rastreo activo en la consola de Lambda, Lambda agrega los permisos necesarios al rol de ejecución de la función. De lo contrario, agregue la política AWSXRayDaemonWriteAccess al rol de ejecución.

Después de configurar el seguimiento activo, se pueden observar solicitudes específicas a través de la aplicación. El gráfico de servicios de X-Ray muestra información sobre la aplicación y todos sus componentes. En el siguiente ejemplo de la aplicación de ejemplo de procesamiento de errores se muestra una aplicación con dos funciones. La función principal procesa eventos y, a veces, devuelve errores. La segunda función de la cadena procesa los errores que aparecen en el primer grupo de registros y utiliza el SDK de AWS para llamar a X-Ray, Amazon Simple Storage Service (Amazon S3) y Registros de Amazon CloudWatch.

X-Ray no sigue todas las solicitudes realizadas a la aplicación. X-Ray aplica un algoritmo de muestreo para garantizar que el seguimiento sea eficiente, a la vez que sigue proporcionando una muestra representativa de todas las solicitudes. La tasa de muestreo es 1 solicitud por segundo y un 5 por ciento de las solicitudes adicionales.

nota

La frecuencia de muestreo de X-Ray no se puede configurar para las funciones.

Cuando se usa seguimiento activo, Lambda registra dos segmentos por seguimiento, lo que crea dos nodos en el gráfico de servicios. En la siguiente imagen, se resaltan los dos nodos para la función principal de la aplicación de ejemplo del procesador de errores.

El primer nodo, situado a la izquierda, representa el servicio de Lambda, que recibe la solicitud de invocación. El segundo nodo representa la función Lambda específica. En el siguiente ejemplo, se muestra un seguimiento con estos dos segmentos. Ambos se denominan my-function, pero uno tiene un origen de AWS::Lambda y el otro tiene origen de AWS::Lambda::Function.

En este ejemplo, el segmento de la función aparece ampliado para mostrar sus subsegmentos:

• Inicialización: representa el tiempo dedicado a cargar la función y ejecutar el código de inicialización. Este subsegmento aparece únicamente para el primer evento que procesa cada instancia de la función.

• Invocación: representa el tiempo dedicado a ejecutar el código del controlador.

• Sobrecarga: representa el tiempo que el tiempo de ejecución de Lambda dedica a prepararse para gestionar el siguiente evento.

También puede instrumentar clientes HTTP, registrar consultas SQL y crear subsegmentos personalizados con anotaciones y metadatos. Para obtener más información, consulte AWS X-Ray SDK para .NET en la Guía para desarrolladores de AWS X-Ray.

Precios

Puede utilizar el seguimiento de X-Ray de manera gratuita cada mes hasta un límite determinado como parte del nivel Gratuito de AWS. A partir de ese umbral, X-Ray realiza cargos por almacenamiento y recuperación del seguimiento. Para más información, consulte Precios de AWS X-Ray.