API de registros de Lambda - AWS Lambda
Suscribirse para recibir registrosUso de memoriaProtocolos de destinoConfiguración de almacenamiento en búferEjemplo de suscripciónCódigo de ejemplo para Logs APIReferencia de la API de registrosMensajes de registro

Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.

API de registros de Lambda

importante

La API de telemetría de Lambda reemplaza a la API de registros de Lambda. Si bien la API de registros sigue siendo completamente funcional, recomendamos utilizar solo la API de telemetría en el futuro. Puede suscribir su extensión a una transmisión de telemetría mediante la API de telemetría o la API de registros. Tras suscribirse mediante una de estas API, cualquier intento de suscribirse mediante la otra API volverá a causar un error.

Lambda captura automáticamente los registros de tiempo de ejecución y los transmite a Amazon. CloudWatch Esta secuencia de registro contiene los registros que generan el código de función y las extensiones, así como los registros que genera Lambda como parte de la invocación de la función.

Las extensiones Lambda pueden usar la API de registros de tiempo de ejecución de Lambda para suscribirse a flujos de registro directamente desde el entorno de ejecución. Lambda transfiere los registros a la extensión y la extensión puede procesar, filtrar y enviar los registros a cualquier destino preferido.

La API de extensiones y la API de registros se conectan a Lambda y extensiones externas.

La API Logs permite que las extensiones se suscriban a tres flujos de registros diferentes:

  • Registros de funciones que la función de Lambda genera y escribe en stdout o stderr.

  • La extensión registra que genera el código de extensión.

  • Registros de plataforma de Lambda en los que se registran eventos y errores relacionados con invocaciones y extensiones.

nota

Lambda envía todos los registros a CloudWatch, incluso cuando una extensión se suscribe a uno o más de los flujos de registros.

Suscribirse para recibir registros

Una extensión de Lambda puede suscribirse para recibir registros enviando una solicitud de suscripción a la API de registros.

Para suscribirse para recibir registros, necesita el identificador de extensión (Lambda-Extension-Identifier). Primero registre la extensión para recibir el identificador de extensión. A continuación, suscríbase a la API de registros durante la inicialización. Una vez finalizada la fase de inicialización, Lambda no procesa las solicitudes de suscripción.

nota

La suscripción a la API de registros es idempotente. Las solicitudes de suscripción duplicadas no dan lugar a suscripciones duplicadas.

Uso de memoria

El uso de memoria aumenta linealmente a medida que aumenta el número de suscriptores. Las suscripciones consumen recursos de memoria porque cada suscripción abre un nuevo búfer de memoria para almacenar los registros. Para ayudar a optimizar el uso de memoria, puede ajustar la configuración de almacenamiento en búfer. El uso de memoria del búfer cuenta para el consumo general de memoria en el entorno de ejecución.

Protocolos de destino

Puede elegir uno de los siguientes protocolos para recibir los registros:

  1. HTTP (recomendado): Lambda entrega registros a un punto de enlace HTTP local (http://sandbox.localdomain:${PORT}/${PATH}) como una matriz de registros en formato JSON. El parámetro $PATH es opcional. Tenga en cuenta que solo se admite HTTP, no HTTPS. Puede optar por recibir registros a través de PUT o POST.

  2. TCP: Lambda entrega registros a un puerto TCP en formato JSON delimitado por línea nueva (NDJSON).

Recomendamos utilizar HTTP en lugar de TCP. Con TCP, la plataforma de Lambda no puede reconocer cuando los registros se entregan a la capa de aplicación. Por lo tanto, puede perder registros si su extensión se bloquea. HTTP no comparte esta limitación.

También recomendamos configurar el agente de escucha HTTP local o el puerto TCP antes de suscribirse para recibir registros. Durante la instalación, tenga en cuenta lo siguiente:

  • Lambda envía registros solo a destinos que se encuentran dentro del entorno de ejecución.

  • Lambda intenta volver a enviar los registros (con retroceso) si no hay ningún agente de escucha o si la solicitud POST o PUT da como resultado un error. Si el suscriptor del registro se bloquea, continuará recibiendo registros después de que Lambda reinicie el entorno de ejecución.

  • Lambda reserva el puerto 9001. No hay otras restricciones ni recomendaciones sobre el número de puerto.

Configuración de almacenamiento en búfer

Lambda puede almacenar en búfer los registros y entregarlos al suscriptor. Puede configurar este comportamiento en la solicitud de suscripción al especificar los siguientes campos opcionales: Tenga en cuenta que Lambda utiliza el valor predeterminado para cualquier campo que no especifique.

  • timeoutMs: el tiempo máximo (en milisegundos) para almacenar en búfer un lote. Predeterminado: 1000. Mínimo: 25 Máximo: 30 000.

  • maxBytes: el tamaño máximo (en bytes) de los registros que se deben almacenar en memoria. Predeterminado: 262 144. Mínimo: 262 144 Máximo: 1 048 576

  • maxItems: el número máximo de eventos que se deben almacenar en memoria. Predeterminado: 10 000. Mínimo: 1000. Máximo: 10 000.

Durante la configuración del almacenamiento en búfer, tenga en cuenta los siguientes puntos:

  • Lambda vacía los registros si alguno de los flujos de entrada está cerrado, por ejemplo, si el tiempo de ejecución se bloquea.

  • Cada suscriptor puede especificar una configuración de almacenamiento en búfer diferente en la solicitud de suscripción.

  • Considere el tamaño del búfer que necesita para leer los datos. Espere recibir cargas útiles tan grandes como 2*maxBytes+metadata, donde maxBytes está configurado en la solicitud de suscripción. Por ejemplo, Lambda agrega los siguientes bytes de metadatos a cada registro:

    {
"time": "2020-08-20T12:31:32.123Z",
"type": "function",
"record": "Hello World"
}

  • Si el suscriptor no puede procesar los registros entrantes con la suficiente rapidez, Lambda podría soltar registros para mantener limitada la utilización de la memoria. Para indicar el número de registros eliminados, Lambda envía un registro platform.logsDropped.

Ejemplo de suscripción

En el siguiente ejemplo se muestra una solicitud para suscribirse a los registros de la plataforma y de las funciones.

PUT http://${AWS_LAMBDA_RUNTIME_API}/2020-08-15/logs HTTP/1.1
{ "schemaVersion": "2020-08-15",
  "types": [
      "platform",
      "function"
    ],
  "buffering": {
      "maxItems": 1000,
      "maxBytes": 262144,
      "timeoutMs": 100
    },
  "destination": {
    "protocol": "HTTP",
    "URI": "http://sandbox.localdomain:8080/lambda_logs"
  }
}

Si la solicitud se realiza correctamente, el suscriptor recibe una respuesta correcta HTTP 200.

HTTP/1.1 200 OK
"OK"

Código de ejemplo para Logs API

Para obtener un código de ejemplo que muestra cómo enviar registros a un destino personalizado, consulte Uso de extensiones de AWS Lambda para enviar registros a destinos personalizados en el blog de informática de AWS.

Para ver ejemplos de código de Python y Go que muestran cómo desarrollar una extensión Lambda básica y suscribirse a la API Logs, consulte AWS LambdaExtensiones en el repositorio de AWS muestras GitHub . Para obtener más información sobre cómo crear una extensión de Lambda, consulte API de extensiones de Lambda.

Referencia de la API de registros

Puede recuperar el extremo de la API de registros desde la variable de entorno AWS_LAMBDA_RUNTIME_API. Para enviar una solicitud de API, utilice el prefijo 2020-08-15/ antes de la ruta de la API. Por ejemplo:

http://${AWS_LAMBDA_RUNTIME_API}/2020-08-15/logs

La especificación OpenAPI para la versión de la API Logs, versión 2020-08-15, está disponible aquí: .zip logs-api-request

Suscribirse

Para suscribirse a una o más de los flujos de registro que están disponibles en el entorno de ejecución de Lambda, las extensiones envían una solicitud de Suscribe API.

Ruta – /logs

Método: PUT

Body parameters (Parámetros del cuerpo)

destination: consulte Protocolos de destino. Requerido: sí. Tipo: cadenas.

buffering: consulte Configuración de almacenamiento en búfer. Obligatorio: no Tipo: cadenas.

types: matriz de los tipos de registros que se deben recibir. Requerido: sí. Tipo: matriz de cadenas. Valores válidos: «plataforma», «función», «extensión».

schemaVersion: Obligatorio: no. Valor predeterminado: “2020-08-15”. Establezca el valor en "2021-03-18" para que la extensión reciba mensajes platform.runtimeDone.

Parámetros de respuesta

Las especificaciones de OpenAPI para las respuestas de suscripción, versión 2020-08-15, están disponibles para protocolos HTTP y TCP:

Códigos de respuesta

  • 200: solicitud completada correctamente

  • 202: solicitud aceptada. Respuesta a una solicitud de suscripción durante las pruebas locales.

  • 4XX: solicitud errónea

  • 500: error de servicio

Si la solicitud se realiza correctamente, el suscriptor recibe una respuesta correcta HTTP 200.

HTTP/1.1 200 OK
"OK"

Si la solicitud falla, el suscriptor recibe una respuesta de error. Por ejemplo:

HTTP/1.1 400 OK
{
    "errorType": "Logs.ValidationError",
    "errorMessage": URI port is not provided; types should not be empty"
}

Mensajes de registro

La API Logs permite que las extensiones se suscriban a tres flujos de registros diferentes:

  • Función: registros que la función de Lambda genera y escribe en stdout o stderr.

  • Extensión: los registros de extensión generados por el código de extensión.

  • Plataforma: registros de la plataforma generados por la plataforma de tiempo de ejecución, en los que se registran eventos y errores relacionados con invocaciones y extensiones.

Registros de funciones

La función de Lambda y las extensiones internas generan registros de funciones y los escriben en stdout o stderr.

En el ejemplo siguiente, se muestra el formato de un mensaje de registro de función. { "time": "2020-08-20T12:31:32.123Z", "type": "function", "record": "ERROR encountered. Stack trace:\n\my-function (line 10)\n" }

Registros de extensión

Las extensiones pueden generar registros de extensión. El formato de registro es el mismo que para un registro de función.

Registros de plataforma

Lambda genera mensajes de registro para eventos de plataforma como platform.start, platform.end y platform.fault.

Opcionalmente, puede suscribirse a la versión 2021-03-18 del esquema de la API de registros, que incluye el mensaje de registro platform.runtimeDone.

Ejemplo de mensajes de registros de plataforma:

En el siguiente ejemplo, se muestran los registros de inicio y final de registro de la plataforma. Estos registros indican la hora de inicio de la invocación y la hora de finalización de la invocación que especifica el requestId. 

{     
    "time": "2020-08-20T12:31:32.123Z",
    "type": "platform.start",
    "record": {"requestId": "6f7f0961f83442118a7af6fe80b88d56"}   
}
{
    "time": "2020-08-20T12:31:32.123Z",
    "type": "platform.end",
    "record": {"requestId": "6f7f0961f83442118a7af6fe80b88d56"}   
}

La plataforma. initRuntimeDoneEl mensaje de registro muestra el estado de la Runtime init subfase, que forma parte de la fase de ciclo de vida inicial. Cuando Runtime init tiene éxito, el tiempo de ejecución envía una solicitud de API /next en tiempo de ejecución (para los tipos de inicialización on-demand y provisioned-concurrency) o restore/next (para el tipo de inicialización snap-start). El siguiente ejemplo muestra una plataforma exitosa. initRuntimeDonemensaje de registro para el tipo de snap-start inicialización.

{
  "time":"2022-07-17T18:41:57.083Z",
  "type":"platform.initRuntimeDone",
  "record":{
      "initializationType":"snap-start",
      "status":"success"
  }
}

El mensaje de registro Platform.initReport muestra cuánto duró la fase Init y cuántos milisegundos se le facturaron durante esta fase. Cuando el tipo de inicialización es provisioned-concurrency, Lambda envía este mensaje durante la invocación. Cuando el tipo de inicialización es snap-start, Lambda envía este mensaje después de restaurar la imagen instantánea. El siguiente ejemplo muestra un mensaje de registro de Platform.IniRuntimeDone para el tipo de inicialización snap-start.

{
  "time":"2022-07-17T18:41:57.083Z",
  "type":"platform.initReport",
  "record":{
      "initializationType":"snap-start",
      "metrics":{
          "durationMs":731.79,
          "billedDurationMs":732
          }
  }
}

El registro de informes de plataforma incluye métricas sobre la invocación que especifica el requestId. El campo initDurationMs se incluye en el registro solamente si la invocación incluye un inicio en frío. Si el seguimiento AWS X-Ray está activo, el registro incluye metadatos de X-Ray. En el siguiente ejemplo se muestra un registro de informes de plataforma para una invocación que incluyó un inicio en frío.

{     
    "time": "2020-08-20T12:31:32.123Z",
    "type": "platform.report",
    "record": {"requestId": "6f7f0961f83442118a7af6fe80b88d56",
        "metrics": {"durationMs": 101.51,
            "billedDurationMs": 300,
            "memorySizeMB": 512,
            "maxMemoryUsedMB": 33,
            "initDurationMs": 116.67
        }
    }
}

El registro de la plataforma captura errores de tiempo de ejecución o del entorno de ejecución. En el siguiente ejemplo se muestra un mensaje de registro de errores de la plataforma. 

{     
    "time": "2020-08-20T12:31:32.123Z",
    "type": "platform.fault",
    "record": "RequestId: d783b35e-a91d-4251-af17-035953428a2c Process exited before completing request"
}

Lambda genera un registro de extensión de plataforma cuando una extensión se registra con la API de extensiones. En el siguiente ejemplo, se muestra un mensaje de registro de errores de la plataforma. 

{     
    "time": "2020-08-20T12:31:32.123Z",
    "type": "platform.extension",
    "record": {"name": "Foo.bar",
        "state": "Ready",
        "events": ["INVOKE", "SHUTDOWN"]
     }
}

Lambda genera un registro de suscripción de registros de plataforma cuando una extensión se suscribe a la API de registros. En el ejemplo siguiente, se muestra un mensaje de registro de suscripción. 

{     
    "time": "2020-08-20T12:31:32.123Z",
    "type": "platform.logsSubscription",
    "record": {"name": "Foo.bar",
        "state": "Subscribed",
        "types": ["function", "platform"],
    }
}

Lambda genera un registro de registros eliminados de la plataforma cuando una extensión no puede procesar el número de registros que recibe. En el siguiente ejemplo se muestra un mensaje de registro platform.logsDropped. 

{     
    "time": "2020-08-20T12:31:32.123Z",
    "type": "platform.logsDropped",
    "record": {"reason": "Consumer seems to have fallen behind as it has not acknowledged receipt of logs.",
        "droppedRecords": 123,
        "droppedBytes" 12345
    }
}

El mensaje de registro Platform.RestoRestart muestra la hora en que se inició la fase Restore (solo el tipo de inicialización snap-start). Ejemplo:

{ 
  "time":"2022-07-17T18:43:44.782Z", 
  "type":"platform.restoreStart", 
  "record":{} 
}

El mensaje de registro Platform.initReport muestra cuánto duró la fase Restore y cuántos milisegundos se le facturaron durante esta fase (solo el tipo de inicialización snap-start). Ejemplo:

{
  "time":"2022-07-17T18:43:45.936Z",
  "type":"platform.restoreReport",
  "record":{
      "metrics":{
          "durationMs":70.87,
          "billedDurationMs":13
      }
  }
}

Mensajes runtimeDone de la plataforma

Si establece la versión del esquema en "2021-03-18" en la solicitud de suscripción, Lambda envía un mensaje platform.runtimeDone después de que la invocación de la función se complete correctamente o presente un error. La extensión puede utilizar este mensaje para detener toda la recopilación de telemetría para esta invocación de función.

La especificación OpenAPI para el tipo de evento de registro en la versión de esquema 2021-03-18 está disponible aquí: schema-2021-03-18.zip

Lambda genera el mensaje de registro platform.runtimeDone cuando el tiempo de ejecución envía una solicitud Next o Error de la API de tiempo de ejecución. El registro platform.runtimeDone informa a los consumidores de registros de la API que la invocación de función se completa. Las extensiones pueden utilizar esta información para decidir cuándo enviar toda la telemetría recopilada durante esa invocación.

Ejemplos

Lambda envía el mensaje platform.runtimeDone después de que el tiempo de ejecución envía la solicitud NEXT cuando se completa la invocación de la función. Los ejemplos siguientes muestran mensajes para cada uno de los valores de estado: éxito, error y tiempo de espera agotado.

ejemplo Ejemplo de mensaje de éxito
{
    "time": "2021-02-04T20:00:05.123Z",
    "type": "platform.runtimeDone",
    "record": {
       "requestId":"6f7f0961f83442118a7af6fe80b88",
       "status": "success"
    }
}
ejemplo Ejemplo de mensaje de error
{
   "time": "2021-02-04T20:00:05.123Z",
   "type": "platform.runtimeDone",
   "record": {
      "requestId":"6f7f0961f83442118a7af6fe80b88",
      "status": "failure"
   }
}
ejemplo Ejemplo de mensaje de tiempo de espera agotado 
{
   "time": "2021-02-04T20:00:05.123Z",
   "type": "platform.runtimeDone",
   "record": {
      "requestId":"6f7f0961f83442118a7af6fe80b88",
      "status": "timeout"
  }
}
ejemplo Plataforma de ejemplo. restoreRuntimeDone mensaje (solo tipo snap-start de inicialización)

La plataforma. restoreRuntimeDoneEl mensaje de registro muestra si la Restore fase se ha realizado correctamente o no. Lambda envía este mensaje cuando el tiempo de ejecución envía una solicitud de API restore/next de tiempo de ejecución. Hay tres estados posibles: éxito, error y tiempo de espera agotado. El siguiente ejemplo muestra una plataforma exitosa. restoreRuntimeDonemensaje de registro.

{
  "time":"2022-07-17T18:43:45.936Z",
  "type":"platform.restoreRuntimeDone",
  "record":{
      "status":"success"
  }
}