Utilice la API de las extensiones de Lambda para crear extensiones

Los autores de funciones de Lambda utilizan extensiones para integrar Lambda con sus herramientas preferidas de monitoreo, observabilidad, seguridad y gobernanza. Los autores de funciones pueden utilizar extensiones de AWS o de socios de AWS, y proyectos de código abierto. Para obtener más información, consulte Introducción de extensiones de AWS Lambda en el blog de informática de AWS. En esta sección, se describe cómo utilizar la API de extensiones de Lambda, el ciclo de vida del entorno de ejecución de Lambda y la referencia de la API de extensiones de Lambda.

Como autor de extensiones, puede usar la API de extensiones de Lambda para integrar profundamente en el entorno de ejecución de Lambda. Su extensión puede registrarse para eventos de ciclo de vida del entorno de ejecución y función. En respuesta a estos eventos, puede iniciar nuevos procesos, ejecutar lógica, controlar y participar en todas las fases del ciclo de vida de Lambda: inicialización, invocación y apagado. Además, puede utilizar la API de registros de tiempo de ejecución para recibir una secuencia de registros.

Una extensión se ejecuta como un proceso independiente en el entorno de ejecución y puede continuar ejecutándose luego de que la invocación de la función se procese completamente. Debido a que las extensiones se ejecutan como procesos, se pueden escribir en un lenguaje diferente al de la función. Recomendamos al usuario que implemente extensiones mediante un lenguaje compilado. En este caso, la extensión es un binario autónomo compatible con los tiempos de ejecución admitidos. Todas las extensiones de soporte de Tiempos de ejecución de Lambda. Si utiliza un lenguaje no compilado, asegúrese de incluir un tiempo de ejecución compatible en la extensión.

Lambda también es compatible con extensiones internas. Una extensión interna se ejecuta como un subproceso independiente en el proceso de tiempo de ejecución. El tiempo de ejecución inicia y detiene la extensión interna. Una forma alternativa de integrarse con el entorno de Lambda es utilizar variables de entorno específicas del lenguaje y scripts envolventes. Puede usarlas para configurar el entorno de tiempo de ejecución y modificar el comportamiento de inicio del proceso de tiempo de ejecución.

Puede agregar extensiones a una función de dos maneras. Para una función implementada como un archivo .zip, debe implementar la extensión como una capa. Para una función definida como una imagen de contenedor, se agregan las extensiones a la imagen de contenedor.

Ciclo de vida del entorno de ejecución de Lambda

El ciclo de vida del entorno de ejecución incluye las siguientes fases:

Cada fase comienza con un evento desde Lambda hasta el tiempo de ejecución y en todas las extensiones registradas. El tiempo de ejecución y la finalización de cada señal de extensión mediante el envío de un solicitud de API de Next. Lambda congela el entorno de ejecución cuando cada proceso se ha completado y no hay eventos pendientes.

Fase "init"

Durante la fase Extension init, cada extensión debe registrarse con Lambda para recibir eventos. Lambda utiliza el nombre de archivo completo de la extensión para validar que la extensión ha completado la secuencia de arranque. Por lo tanto, cada llamada Register a la API debe incluir el encabezado Lambda-Extension-Name con el nombre de archivo completo de la extensión.

Puede registrar hasta 10 extensiones para una función. Este límite se aplica a través de la llamada Register a la API.

Después de que cada extensión se registre, Lambda comienza la fase Runtime init. El proceso en tiempo de ejecución llama functionInit para iniciar la fase Function init.

La fase Init se completa después del tiempo de ejecución y cada extensión registrada indica la finalización mediante el envío de una solicitud Next a la API.

Fase "invoke"

Cuando se invoca una función de Lambda en respuesta a una solicitud a la API Next, Lambda envía un evento Invoke al tiempo de ejecución y a cada extensión registrada para el evento Invoke.

Durante la invocación, las extensiones externas se ejecutan en paralelo a la función. También continúan ejecutándose después de que la función se haya completado. Esto permite al usuario capturar información de diagnóstico o enviar registros, métricas y rastros a una ubicación de su elección.

Después de recibir la respuesta de la función desde el tiempo de ejecución, Lambda devuelve la respuesta al cliente, incluso si las extensiones todavía se ejecutan.

La fase Invoke finaliza después de que el tiempo de ejecución y todas las extensiones indiquen que se han terminado mediante el envío de una solicitud Next a la API.

Carga útil del evento: el evento enviado al tiempo de ejecución (y a la función de Lambda) lleva toda la solicitud, encabezados (como RequestId) y carga útil. El evento enviado a cada extensión contiene metadatos que describen el contenido del evento. Este evento de ciclo de vida incluye el tipo del evento, el tiempo de espera de la función (deadlineMs), el requestId, el nombre de recurso de Amazon (ARN) de la función invocada y los encabezados de seguimiento.

Las extensiones que desean acceder al cuerpo del evento de función pueden usar un SDK en tiempo de ejecución que se comunica con la extensión. Los desarrolladores de funciones utilizan el SDK en tiempo de ejecución para enviar la carga a la extensión cuando se invoca la función.

A continuación, se muestra un ejemplo de carga:

{
    "eventType": "INVOKE",
    "deadlineMs": 676051,
    "requestId": "3da1f2dc-3222-475e-9205-e2e6c6318895",
    "invokedFunctionArn": "arn:aws:lambda:us-east-1:123456789012:function:ExtensionTest",
    "tracing": {
        "type": "X-Amzn-Trace-Id",
        "value": "Root=1-5f35ae12-0c0fec141ab77a00bc047aa2;Parent=2be948a625588e32;Sampled=1"
    }
 }          

Límite de duración: la configuración de tiempo de espera de la función limita la duración de la fase Invoke al completo. Por ejemplo, si establece el tiempo de espera de la función en 360 segundos, la función y todas las extensiones deben completarse en 360 segundos. Tenga en cuenta que no hay una fase posterior a "invoke" independiente. La duración es el tiempo total que tarda su tiempo de ejecución y todas las invocaciones de sus extensiones en completarse y no se calcula hasta que la función y todas las extensiones hayan terminado de ejecutarse.

Impacto de desempeño y sobrecarga de extensiones: las extensiones pueden afectar al rendimiento de la función. Como autor de la extensión, tiene control sobre el impacto de desempeño de la extensión. Por ejemplo, si la extensión realiza operaciones de procesamiento intensivo, la duración de la función aumentará porque la extensión y el código de la función comparten los mismos recursos de la CPU. Además, si la extensión realiza numerosas operaciones después de completar la invocación de la función, la duración de la ejecución de la función aumentará porque la fase Invoke continuará hasta que todas las extensiones indiquen que se han completado.

Para ayudar a identificar el impacto del rendimiento introducido por las extensiones de la fase Invoke, Lambda genera la métrica PostRuntimeExtensionsDuration. Esta métrica mide el tiempo acumulado invertido entre la solicitud Next a la API de tiempo de ejecución y la última solicitud Next a la API de la extensión. Para medir el aumento de memoria utilizada, utilice la métrica MaxMemoryUsed. Para obtener más información acerca de las métricas de función, consulte Ver las métricas de funciones de Lambda.

Los desarrolladores de funciones pueden ejecutar diferentes versiones de sus funciones en paralelo para conocer el impacto de una extensión específica. Recomendamos que los autores de extensiones publiquen el consumo de recursos esperado para facilitar a los desarrolladores de funciones la elección de una extensión adecuada.

Fase "shutdown"

Cuando Lambda está a punto de cerrar el tiempo de ejecución, envía Shutdown a cada extensión externa registrada. Las extensiones pueden utilizar este tiempo para las tareas de limpieza finales. El evento Shutdown se envía en respuesta a una solicitud Next a la API.

Límite de duración: la duración máxima de la fase Shutdown depende de la configuración de las extensiones registradas:

Para una función con extensiones externas, Lambda reserva hasta 300 ms (500 ms para un tiempo de ejecución con una extensión interna) para que el proceso de tiempo de ejecución realice un apagado estable. Lambda asigna el resto del límite de 2000 ms para que las extensiones externas se cierren.

Si el tiempo de ejecución o una extensión no responde al evento Shutdown dentro del límite, Lambda termina el proceso mediante una señal SIGKILL.

Carga del evento: el evento Shutdown contiene el motivo del apagado y el tiempo restante en milisegundos.

shutdownReason incluye los valores que se muestran a continuación:

{ 
  "eventType": "SHUTDOWN", 
  "shutdownReason": "reason for shutdown", 
  "deadlineMs": "the time and date that the function times out in Unix time milliseconds" 
}        
      

Permisos y configuración

Las extensiones se ejecutan en el mismo entorno de ejecución que la función de Lambda. Las extensiones también comparten recursos con la función, como CPU, memoria y almacenamiento en disco /tmp. Además, las extensiones utilizan el mismo rol de AWS Identity and Access Management (IAM) y el mismo contexto de seguridad que la función.

Permisos de acceso al sistema de archivos y a la red: las extensiones se ejecutan en el mismo espacio de nombres de sistema de archivos y nombre de red que el tiempo de ejecución de la función. Esto significa que las extensiones deben ser compatibles con el sistema operativo asociado. Si una extensión requiere reglas de tráfico de salida de red adicionales, se deben aplicar estas reglas a la configuración de la función.

Variables de entorno: las extensiones pueden acceder a las variables de entorno de la función, excepto las siguientes variables que son específicas del proceso de tiempo de ejecución:

Administración de errores

Errores de inicialización: si se produce un error en una extensión, Lambda reinicia el entorno de ejecución para imponer un comportamiento consistente y fomentar el error rápido para las extensiones. Además, para algunos clientes, las extensiones deben satisfacer necesidades críticas como registro, seguridad, gobierno y recopilación de telemetría.

Errores de Invoke (como la falta de memoria, el tiempo de espera de la función): dado que las extensiones comparten recursos con el tiempo de ejecución, el agotamiento de la memoria los afecta. Cuando el tiempo de ejecución produce un error, todas las extensiones y el propio tiempo de ejecución participan en la fase Shutdown. Además, el tiempo de ejecución se reinicia automáticamente como parte de la invocación actual o a través de un mecanismo de reinicialización diferido.

Si hay un error (como un tiempo de espera de función o un error de tiempo de ejecución) durante Invoke, el servicio de Lambda realiza un restablecimiento. El restablecimiento se comporta como un evento Shutdown. Primero, Lambda apaga el tiempo de ejecución, luego envía un evento Shutdown a cada extensión externa registrada. El evento incluye el motivo del apagado. Si este entorno se utiliza para una nueva invocación, la extensión y el tiempo de ejecución se vuelven a inicializar como parte de la siguiente invocación.

Para obtener una explicación más detallada del diagrama anterior, consulte Errores durante la fase Invoke.

Registros de extensión: Lambda envía la salida de registro de las extensiones a CloudWatch Logs. Lambda también genera un evento de registro adicional para cada extensión durante Init. El evento de registro registra el nombre y la preferencia de registro ("event", "config") en caso de éxito o el motivo del error en caso de error.

Extensiones de solución de problemas

Referencia de la API de extensiones

La especificación de OpenAPI para la versión de la API de extensiones 2020-01-01 está disponible aquí: extensions-api.zip

Puede recuperar el valor del punto de enlace de la API desde la variable de entorno de AWS_LAMBDA_RUNTIME_API. Para enviar una solicitud de Register, utilice el prefijo 2020-01-01/ antes de cada ruta de la API. Por ejemplo:

http://${AWS_LAMBDA_RUNTIME_API}/2020-01-01/extension/register 

Regístrese

Durante Extension init, todas las extensiones deben registrarse en Lambda para recibir eventos. Lambda utiliza el nombre de archivo completo de la extensión para validar que la extensión ha completado la secuencia de arranque. Por lo tanto, cada llamada Register a la API debe incluir el encabezado Lambda-Extension-Name con el nombre de archivo completo de la extensión.

Las extensiones internas comienzan y paran según el proceso de tiempo de ejecución, por lo que no se les permite registrarse para el evento Shutdown.

Ruta – /extension/register

Método: POST

Encabezados de solicitudes

{
    'events': [ 'INVOKE', 'SHUTDOWN']
}             

{
    "functionName": "helloWorld",
    "functionVersion": "$LATEST",
    "handler": "lambda_function.lambda_handler"
}               

{
    "functionName": "helloWorld",
    "functionVersion": "$LATEST",
    "handler": "lambda_function.lambda_handler",
    "accountId": "123456789012"
}

Next

Las extensiones envían una solicitud Next a la API para recibir el siguiente evento, que puede ser un evento Invoke o un evento Shutdown. El cuerpo de la respuesta contiene la carga, que es un documento JSON que contiene datos de eventos.

La extensión envía una solicitud Next a la API para indicar que está lista para recibir nuevos eventos. Esta es una llamada de bloqueo.

No establezca un tiempo de espera en la llamada GET, ya que la extensión puede suspenderse durante un periodo de tiempo hasta que haya un evento que devolver.

Ruta – /extension/event/next

Método: GET

Error de init

La extensión utiliza este método para informar de un error de inicialización en Lambda. Llámelo cuando la extensión produce un error al inicializarse después de que se haya registrado. Después de que Lambda reciba el error, no hay más llamadas a la API correctas. La extensión debe cerrarse después de recibir la respuesta de Lambda.

Ruta – /extension/init/error

Método: POST

Este campo es un objeto JSON con la siguiente estructura:

{
      errorMessage: string (text description of the error),
      errorType: string,
      stackTrace: array of strings
}

Tenga en cuenta que Lambda acepta cualquier valor para errorType.

En el ejemplo siguiente, se muestra un mensaje de error de función de Lambda en el que la función no pudo analizar los datos de evento proporcionados en la invocación.

{
      "errorMessage" : "Error parsing event data.",
      "errorType" : "InvalidEventDataException",
      "stackTrace": [ ]
}      

Error de salida

La extensión utiliza este método para informar de un error en Lambda antes de salir. Llámelo cuando encuentre un error inesperado. Después de que Lambda reciba el error, no hay más llamadas a la API correctas. La extensión debe cerrarse después de recibir la respuesta de Lambda.

Ruta – /extension/exit/error

Método: POST

Este campo es un objeto JSON con la siguiente estructura:

{
      errorMessage: string (text description of the error),
      errorType: string,
      stackTrace: array of strings
}

Tenga en cuenta que Lambda acepta cualquier valor para errorType.

En el ejemplo siguiente, se muestra un mensaje de error de función de Lambda en el que la función no pudo analizar los datos de evento proporcionados en la invocación.

{
      "errorMessage" : "Error parsing event data.",
      "errorType" : "InvalidEventDataException",
      "stackTrace": [ ]
}