API Logs di Lambda

Importante

L'API di telemetria Lambda sostituisce l'API Lambda Logs. Sebbene l'API Logs rimanga completamente funzionante, in futuro consigliamo di utilizzare solo l'API di telemetria. Puoi iscrivere la tua estensione a un flusso di telemetria utilizzando l'API di telemetria o l'API Logs. Dopo la sottoscrizione tramite una di queste API, qualsiasi tentativo di sottoscrizione utilizzando l'altra API restituirà un errore.

Lambda acquisisce automaticamente i log di runtime e li trasmette ad Amazon. CloudWatch Questo flusso di registri contiene i log generati dal codice funzione e dalle estensioni e anche i log generati da Lambda nell'ambito del richiamo della funzione.

Le estensioni Lambda possono utilizzare l'API Logs del runtime di Lambda per eseguire la sottoscrizione ai flussi di log direttamente dall'interno dell'ambiente di esecuzione Lambda. Lambda trasmette i log all'estensione e l'estensione può quindi elaborare, filtrare e inviare i log a qualsiasi destinazione preferita.

L'API Logs consente alle estensioni di sottoscrivere tre flussi di log diversi:

• Log di funzioni che la funzione Lambda genera e scrive in stdout o stderr.

• Log di estensione generati dal codice di estensione.

• Log si piattaforma Lambda, che registrano eventi ed errori relativi a richiami ed estensioni.

Nota

Lambda invia tutti i log a CloudWatch, anche quando un'estensione sottoscrive uno o più flussi di log.

Sottoscrizione ai log di ricezione

Un'estensione Lambda può sottoscrivere i log di ricezione inviando una richiesta di sottoscrizione all'API Logs.

Per sottoscrivere i log di ricezione, è necessario l'identificatore di estensione (Lambda-Extension-Identifier). Innanzitutto registrare l'estensione per ricevere l'identificatore dell'estensione. Quindi sottoscrivere l'API Logs durante l'inizializzazione. Al termine della fase di inizializzazione, Lambda non elabora le richieste di sottoscrizione.

Nota

La sottoscrizione Logs API è idempotente. Le richieste di sottoscrizione duplicate non comportano sottoscrizioni duplicate.

Utilizzo della memoria

L'utilizzo della memoria aumenta linearmente man mano che aumenta il numero di abbonati. Le sottoscrizioni consumano risorse di memoria perché ogni sottoscrizione apre un nuovo buffer di memoria per archiviare i log. Per ottimizzare l'utilizzo della memoria, è possibile regolare la configurazione di buffering. L'utilizzo della memoria buffer conta per il consumo complessivo della memoria nell'ambiente di esecuzione.

Protocolli destinazione

È possibile scegliere uno dei seguenti protocolli per ricevere i log:

1. HTTP (consigliato) – Lambda consegna i log a un endpoint HTTP locale (http://sandbox.localdomain:${PORT}/${PATH}) come matrice di record in formato JSON. Il parametro $PATH è facoltativo. Si noti che è supportato solo HTTP, non HTTPS. Puoi scegliere di ricevere i log tramite PUT o POST.

2. TCP – Lambda consegna i log a una porta TCP in formato JSON delimitato da Newline (NDJSON).

Si consiglia di utilizzare HTTP anziché TCP. Con TCP, la piattaforma Lambda non può riconoscere che i log vengono consegnati al livello dell'applicazione. Pertanto, se l'estensione si blocca si potrebbero perdere i log. HTTP non condivide questa limitazione.

Si consiglia inoltre di impostare il listener HTTP locale o la porta TCP prima di sottoscrivere i log di ricezione. Durante l'installazione, tenere presente quanto segue:

• Lambda invia i log solo alle destinazioni che si trovano all'interno dell'ambiente di esecuzione.

• Lambda ritenta il tentativo di inviare i log (con backoff) se non c'è listener o se la richiesta POST o PUT genera errori. Se il sottoscrittore del log si blocca, continuerà a ricevere i log dopo che Lambda riavvia l'ambiente di esecuzione.

• Lambda riserva la porta 9001. Non ci sono altre restrizioni o raccomandazioni sul numero di porta.

Configurazione buffering

Lambda può tamponare i log e consegnarli al sottoscrittore. È possibile configurare questo comportamento nella richiesta di sottoscrizione specificando i seguenti campi facoltativi. Si noti che Lambda utilizza il valore predefinito per qualsiasi campo non specificato.

• timeoutMs – Il tempo massimo (in millisecondi) per il buffer di un batch. Valore predefinito: 1.000 Minimo: 25. Massimo: 30.000

• maxBytes – La dimensione massima (in byte) dei registri al buffer in memoria. Valore predefinito: 262.144. Minimo: 262.144. Massimo: 1.048.576.

• maxItems – Il numero massimo di eventi da memorizzare nel buffer. Valore predefinito: 10.000 Minimo: 1.000. Massimo: 10.000.

Durante la configurazione del buffering, prendere nota dei seguenti punti:

• Lambda svuota i log se uno qualsiasi dei flussi di input è chiuso, ad esempio, se il runtime si arresta in modo anomalo.

• Ogni sottoscrittore può specificare una configurazione di buffering diversa durante la richiesta di sottoscrizione.

• Considerare la dimensione del buffer necessaria per leggere i dati. Aspettarsi di ricevere payload grandi come 2*maxBytes+metadata, dove maxBytes è configurato nella richiesta di sottoscrizione. Ad esempio, Lambda aggiunge i byte di metadati seguenti a ciascun record:

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

• Se il server di sottoscrizione non è in grado di elaborare i log in ingresso abbastanza rapidamente, Lambda potrebbe eliminare i log per mantenere limitato l'utilizzo della memoria. Per indicare il numero di record eliminati, Lambda invia un log platform.logsDropped.

Esempio di sottoscrizione

L'esempio seguente mostra una richiesta di sottoscrizione ai log della piattaforma e delle funzioni.

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"
  }
}    

Se la richiesta ha esito positivo, il sottoscrittore riceve una risposta riuscita HTTP 200.

HTTP/1.1 200 OK
"OK"      

Codice di esempio per l'API Logs

Per un codice di esempio che illustra come inviare i log a una destinazione personalizzata, consulta Utilizzo delle estensioni AWS Lambda per inviare i log a una destinazione personalizzata nel blog Compute di AWS.

Per esempi di codice in Python e Go che mostrano come sviluppare un'estensione Lambda di base e sottoscrivere l'API Logs, consulta AWS LambdaExtensions on the Samples repository. AWS GitHub Per ulteriori informazioni sulla creazione di un'estensione Lambda, consultare Utilizzo dell'API Lambda Extensions per creare estensioni.

Riferimento dell'API Logs.

È possibile recuperare l'endpoint API Logs dallaAWS_LAMBDA_RUNTIME_API variabile di ambiente. Per inviare una richiesta API, utilizzare il prefisso 2020-08-15/ prima del percorso API. Per esempio:

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

La specifica OpenAPI per la versione Logs API 2020-08-15 è disponibile qui: .zip logs-api-request

Subscribe

Per sottoscrivere uno o più flussi di log disponibili nell'ambiente di esecuzione di Lambda, le estensioni inviano una richiesta API di sottoscrizione.

Percorso – /logs

Method – PUT

Parametri corpo

destination - Consultare Protocolli destinazione. Campo obbligatorio: sì Tipo: stringhe.

buffering - Consultare Configurazione buffering. Campo obbligatorio: no. Tipo: stringhe.

types – Un array dei tipi di log da ricevere. Campo obbligatorio: sì Tipo: array di stringhe Valori validi: «piattaforma», «funzione», «estensione».

schemaVersion – Obbligatorio: no. Valore di default: "2020-08-15". Impostare su "2021-03-18" per l'estensione in modo da ricevere messaggi platform.runtimeDone.

Parametri di risposta

Le specifiche OpenAPI per le risposte di sottoscrizione, versione 2020-08-15, sono disponibili per i protocolli HTTP e TCP:

• logs-api-http-responseHTTP: .zip

• TCP: .zip logs-api-tcp-response

Codice di risposta

• 200 – Richiesta completata con successo

• 202 – Richiesta accettata. Risposta ad una richiesta di sottoscrizione durante il test locale.

• 4XX – Richiesta non valida

• 500 – Errore servizio

Se la richiesta ha esito positivo, il sottoscrittore riceve una risposta riuscita HTTP 200.

HTTP/1.1 200 OK
"OK"      

Se la richiesta fallisce, il sottoscrittore riceve una risposta di errore. Ad esempio:

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

Messaggi di log

L'API Logs consente alle estensioni di sottoscrivere tre flussi di log diversi:

• Funzione – Log che la funzione Lambda genera e scrive in stdout o stderr.

• Estensione – Log generati dal codice di estensione.

• Piattaforma – Log generati dalla piattaforma runtime, che registrano eventi ed errori relativi a richiami ed estensioni.

Argomenti

• Log delle funzioni
• Log di estensioni
• Log di piattaforma

Log delle funzioni

La funzione Lambda e le estensioni interne generano log di funzioni e li scrivono in stdout o stderr.

L'esempio seguente mostra il formato di un messaggio di log di funzioni. { "time": "2020-08-20T12:31:32.123Z", "type": "function", "record": "ERROR encountered. Stack trace:\n\my-function (line 10)\n" }

Log di estensioni

Le estensioni possono generare log di estensioni. Il formato del log è uguale a quello di un log di funzioni.

Log di piattaforma

Lambda genera messaggi di log per eventi della piattaforma come platform.start, platform.end e platform.fault.

Facoltativamente, è possibile sottoscrivere la versione 2021-03-18 dello schema dell'API Log, che include il messaggio di log platform.runtimeDone.

Esempio di messaggi di log di piattaforma

Nell'esempio seguente vengono illustrati i log di inizio e di fine della piattaforma. Questi log indicano l'ora di inizio e l'ora di fine chiamata per la chiamata specificata da 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 piattaforma. initRuntimeDoneil messaggio di registro mostra lo stato della Runtime init sottofase, che fa parte della fase del ciclo di vita di Init. In caso di riuscita di Runtime init, il runtime invia una richiesta API /next di runtime (per i tipi di inizializzazione on-demand e provisioned-concurrency) o restore/next (per il tipo di inizializzazione snap-start). L'esempio seguente mostra una piattaforma di successo. initRuntimeDonemessaggio di registro per il tipo di snap-start inizializzazione.

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

Il messaggio di log platform.initReport mostra quanto è durata la fase Init e quanti millisecondi sono stati fatturati durante questa fase. Quando il tipo di inizializzazione è provisioned-concurrency, Lambda invia questo messaggio durante la chiamata. Quando il tipo di inizializzazione è snap-start, Lambda invia questo messaggio dopo aver ripristinato lo snapshot. L'esempio seguente mostra un messaggio di log platform.initReport riuscito per il tipo di inizializzazione snap-start.

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

Il log dei report della piattaforma include parametri sulla chiamata specificata da requestId. Il campo initDurationMs è incluso nel log solo se la chiamata include un avvio a freddo. Se la traccia AWS X-Ray è attiva, il log include i metadati X-Ray. Nell'esempio seguente viene illustrato un log di rapporto della piattaforma per una chiamata che includeva un avvio a freddo.

{     
    "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
        }
    }
} 

Il log della piattaforma acquisisce errori di runtime o dell'ambiente di esecuzione. L'esempio seguente mostra un messaggio di log di errore della piattaforma.

{     
    "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 log di estensioni della piattaforma quando un'estensione si registra con l'API delle estensioni. L'esempio seguente mostra un messaggio dell'estensione della piattaforma.

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

Lambda genera un log di sottoscrizione al log della piattaforma quando un'estensione sottoscrive l'API Log. Nell'esempio seguente viene illustrato un messaggio di sottoscrizione log.

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

Lambda genera un log eliminato dei log di piattaforma quando un'estensione non è in grado di elaborare il numero di log che sta ricevendo. Nell'esempio seguente viene mostrato unplatform.logsDropped messaggio di log.

{     
    "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
    }
}

Il messaggio di log platform.restoreStart mostra l'ora di inizio della fase Restore (solo per il tipo di inizializzazione snap-start). Esempio:

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

Il messaggio di log platform.restoreReport mostra quanto è durata la fase Restore e quanti millisecondi sono stati fatturati durante questa fase (solo per il tipo di inizializzazione snap-start). Esempio:

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

Messaggi runtimeDone della piattaforma

Se si imposta la versione dello schema su "2021-03-18" nella richiesta di sottoscrizione, Lambda invia un messaggio platform.runtimeDone dopo il completamento della chiamata della funzione o con un errore. L'estensione può utilizzare questo messaggio per arrestare tutta la raccolta di dati di telemetria per questa chiamata di funzione.

La specifica OpenAPI per il tipo di evento Log nella versione dello schema 2021-03-18 è disponibile qui: schema-2021-03-18.zip

Lambda genera il messaggio di log platform.runtimeDone quando il runtime invia una richiesta API di runtime Next o Error. Il log platform.runtimeDone informa i consumatori dell'API Log che la chiamata di funzione è stata completata. Le estensioni possono utilizzare queste informazioni per decidere quando inviare tutti i dati di telemetria raccolti durante tale chiamata.

Esempi

Lambda invia il messaggio platform.runtimeDone dopo che il runtime invia la richiesta NEXT al completamento della chiamata della funzione. Negli esempi seguenti vengono illustrati i messaggi relativi a ciascuno dei valori di stato: riuscita, errore e timeout.

Esempio di messaggio di riuscita

{
    "time": "2021-02-04T20:00:05.123Z",
    "type": "platform.runtimeDone",
    "record": {
       "requestId":"6f7f0961f83442118a7af6fe80b88",
       "status": "success"
    }
}         

Esempio di messaggio di errore

{
   "time": "2021-02-04T20:00:05.123Z",
   "type": "platform.runtimeDone",
   "record": {
      "requestId":"6f7f0961f83442118a7af6fe80b88",
      "status": "failure"
   }
}        

Esempio di messaggio di timeout

{
   "time": "2021-02-04T20:00:05.123Z",
   "type": "platform.runtimeDone",
   "record": {
      "requestId":"6f7f0961f83442118a7af6fe80b88",
      "status": "timeout"
  }
}

Esempio Piattaforma di esempio. restoreRuntimeDone messaggio (solo tipo di snap-start inizializzazione)

La piattaforma. restoreRuntimeDoneil messaggio di registro mostra se la Restore fase ha avuto successo o meno. Lambda genera questo messaggio quando il runtime invia una richiesta API di runtime restore/next. Ci sono tre stati possibili: riuscito, errore e timeout. L'esempio seguente mostra una piattaforma di successo. restoreRuntimeDonemessaggio di registro.

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