API di telemetria Lambda

L'API Telemetry consente alle estensioni di ricevere dati di telemetria direttamente da Lambda. Durante l'inizializzazione e l'invocazione, Lambda acquisisce in automatico i dati di telemetria, tra cui log, parametri della piattaforma e tracce della piattaforma. L'API Telemetry consente alle estensioni di accedere a tali dati di telemetria direttamente da Lambda quasi in tempo reale.

All'interno dell'ambiente di esecuzione Lambda, puoi abbonare le estensioni Lambda ai flussi di telemetria. Dopo l'abbonamento, Lambda invia automaticamente tutti i dati di telemetria alle estensioni. Dopodiché avrai la flessibilità di elaborare, filtrare e trasmettere i dati alla tua destinazione preferita, ad esempio un bucket Amazon Simple Storage Service (Amazon S3) o un fornitore di strumenti di osservabilità di terze parti.

Il diagramma seguente mostra come l'API Extensions e l'API Telemetry connettono le estensioni a Lambda dall'interno dell'ambiente di esecuzione. Inoltre L'API Runtime collega il runtime e la funzione a 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.

Le estensioni possono utilizzare l'API di telemetria per sottoscrivere i tre diversi flussi di telemetria.

• Telemetria della piattaforma: registri, metriche e tracce, che descrivono eventi ed errori relativi al ciclo di vita del runtime dell'ambiente di esecuzione, al ciclo di vita delle estensioni e alle chiamate delle funzioni.

• Log delle funzioni: log personalizzati generati dal codice della funzione Lambda.

• Log di estensione: i log personalizzati generati dal codice di estensione Lambda.

Nota

Lambda invia log e metriche e tracce a X-Ray (se hai attivato il tracciamento) CloudWatch, anche se un'estensione si abbona ai flussi di telemetria.

Sections

• Creazione di estensioni tramite l'API di telemetria
• Registrazione delle estensioni
• Creazione di un ascoltatore di telemetria
• Specifica di un protocollo di destinazione
• Configurazione dell'utilizzo della memoria e del buffering
• Invio di una richiesta di sottoscrizione all'API di telemetria
• Messaggi dell'API di telemetria in entrata
• Riferimento all'API di telemetria Lambda
• Riferimento allo schema Event dell'API di telemetria Lambda
• Conversione degli oggetti dell'API di Event telemetria Lambda in Spans OpenTelemetry
• API Logs di Lambda

Creazione di estensioni tramite l'API di telemetria

Le estensioni Lambda vengono eseguite come processi indipendenti nell'ambiente di esecuzione. L'esecuzione delle estensioni può proseguire dopo il completamento dell'invocazione della funzione. Poiché le estensioni vengono eseguite come processi separati, è possibile scriverle in un linguaggio diverso da quello del codice della funzione. Consigliamo di scrivere estensioni utilizzando un linguaggio compilato come Golang o Rust. In questo caso, l'estensione è un binario autonomo compatibile con qualsiasi runtime supportato.

Il diagramma seguente illustra un processo in quattro fasi per creare un'estensione che riceve ed elabora i dati di telemetria tramite l'API di telemetria.

Ecco ogni fase in modo più dettagliato:

1. Registra la tua estensione utilizzando l'API estensioni di Lambda. Questo ti fornisce un Lambda-Extension-Identifier, di cui avrai bisogno nei passaggi seguenti. Per ulteriori informazioni su come eseguire la registrazione dell'estensione, consulta Registrazione delle estensioni.

2. Crea un ascoltatore di telemetria. Può trattarsi di un server HTTP o TCP di base. Lambda utilizza l'URI del listener di telemetria per inviare dati di telemetria all'estensione. Per ulteriori informazioni, consulta Creazione di un ascoltatore di telemetria.

3. Utilizzando l'API Subscribe nell'API Telemetry, esegui l'abbonamento all'estensione ai flussi di telemetria desiderati. Avrai bisogno dell'URI del tuo ascoltatore di telemetria per questo passaggio. Per ulteriori informazioni, consulta Invio di una richiesta di sottoscrizione all'API di telemetria.

4. Ottieni dati di telemetria da Lambda tramite l'ascoltatore di telemetria. Puoi eseguire qualsiasi elaborazione personalizzata di questi dati, ad esempio inviandoli ad Amazon S3 o a un servizio di osservabilità esterno.

Nota

L'ambiente di esecuzione di una funzione Lambda può avviarsi e interrompersi più volte nell'ambito del suo ciclo di vita. In generale, il codice dell'estensione viene eseguito durante le chiamate delle funzioni e anche fino a 2 secondi durante la fase di spegnimento. Consigliamo di raggruppare i dati di telemetria non appena arrivano all'ascoltatore. Quindi, utilizza gli eventi del ciclo di vita Invoke e Shutdown per inviare ogni batch alle destinazioni desiderate.

Registrazione delle estensioni

Prima di poter eseguire l'abbonamento ai dati di telemetria, devi registrare l'estensione Lambda. La registrazione avviene durante la fase di inizializzazione dell'estensione. L'esempio seguente mostra una richiesta HTTP per la registrazione di un'estensione.

POST http://${AWS_LAMBDA_RUNTIME_API}/2020-01-01/extension/register
 Lambda-Extension-Name: lambda_extension_name
{
    'events': [ 'INVOKE', 'SHUTDOWN']
}

Se la richiesta ha esito positivo, il sottoscrittore riceve una risposta riuscita HTTP 200. L'intestazione della risposta contiene l'Lambda-Extension-Identifier. Il corpo della risposta contiene altre proprietà della funzione.

HTTP/1.1 200 OK
Lambda-Extension-Identifier: a1b2c3d4-5678-90ab-cdef-EXAMPLE11111
{
    "functionName": "lambda_function",
    "functionVersion": "$LATEST",
    "handler": "lambda_handler",
    "accountId": "123456789012"
}

Per ulteriori informazioni, consulta Riferimento all'API delle estensioni.

Creazione di un ascoltatore di telemetria

L'estensione Lambda deve disporre di un ascoltatore che gestisca le richieste in entrata dall'API di telemetria. Il codice seguente mostra un esempio di implementazione dell'ascoltatore di telemetria in Golang:

// Starts the server in a goroutine where the log events will be sent
func (s *TelemetryApiListener) Start() (string, error) {
	address := listenOnAddress()
	l.Info("[listener:Start] Starting on address", address)
	s.httpServer = &http.Server{Addr: address}
	http.HandleFunc("/", s.http_handler)
	go func() {
		err := s.httpServer.ListenAndServe()
		if err != http.ErrServerClosed {
			l.Error("[listener:goroutine] Unexpected stop on Http Server:", err)
			s.Shutdown()
		} else {
			l.Info("[listener:goroutine] Http Server closed:", err)
		}
	}()
	return fmt.Sprintf("http://%s/", address), nil
}

// http_handler handles the requests coming from the Telemetry API.
// Everytime Telemetry API sends log events, this function will read them from the response body
// and put into a synchronous queue to be dispatched later.
// Logging or printing besides the error cases below is not recommended if you have subscribed to
// receive extension logs. Otherwise, logging here will cause Telemetry API to send new logs for
// the printed lines which may create an infinite loop.
func (s *TelemetryApiListener) http_handler(w http.ResponseWriter, r *http.Request) {
	body, err := ioutil.ReadAll(r.Body)
	if err != nil {
		l.Error("[listener:http_handler] Error reading body:", err)
		return
	}

	// Parse and put the log messages into the queue
	var slice []interface{}
	_ = json.Unmarshal(body, &slice)

	for _, el := range slice {
		s.LogEventsQueue.Put(el)
	}

	l.Info("[listener:http_handler] logEvents received:", len(slice), " LogEventsQueue length:", s.LogEventsQueue.Len())
	slice = nil
}

Specifica di un protocollo di destinazione

Quando esegui la sottoscrizione per ricevere la telemetria tramite l'API di telemetria, puoi specificare un protocollo di destinazione in aggiunta all'URI di destinazione:

{
    "destination": {
        "protocol": "HTTP",
        "URI": "http://sandbox.localdomain:8080"
    }
}

Lambda accetta due protocolli per la ricezione della telemetria:

• HTTP (consigliato): Lambda consegna la telemetria a un endpoint HTTP locale (http://sandbox.localdomain:${PORT}/${PATH}) come matrice di record in formato JSON. Il parametro $PATH è facoltativo. Lambda supporta solo HTTP, non HTTPS. Lambda fornisce la telemetria tramite richieste POST.

• TCP: Lambda consegna la telemetria a una porta TCP in formato JSON delimitato da Newline (NDJSON).

Nota

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

Prima di eseguire l'abbonamento per i ricevere i dati di telemetria, definisci l'ascoltatore HTTP locale o la porta TCP. Durante l'installazione, tenere presente quanto segue:

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

• Lambda riprova a inviare i dati di telemetria (con backoff) in assenza di un ascoltatore o se la richiesta POST subisce un errore. Se riporta un arresto anomalo, l'ascoltatore di telemetria continuerà a riceverla dopo che Lambda avrà riavviato l'ambiente di esecuzione.

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

Configurazione dell'utilizzo della memoria e del buffering

L'utilizzo della memoria in un ambiente di esecuzione aumenta linearmente con il numero di abbonati. Gli abbonamenti consumano risorse di memoria, perché ognuno apre un nuovo buffer di memoria per archiviare i dati di telemetria. L'utilizzo della memoria buffer contribuisce al consumo di memoria complessivo nell'ambiente di esecuzione.

Quando effettui l'abbonamento per ricevere la telemetria attraverso l'API Telemetry, hai la possibilità di eseguire il buffer dei dati di telemetria e consegnarli agli abbonati in batch. Per ottimizzare l'utilizzo della memoria, puoi specificare una configurazione di buffering:

{
    "buffering": {
        "maxBytes": 256*1024,
        "maxItems": 1000,
        "timeoutMs": 100
    }
}

Impostazioni di configurazione del buffering
Parametro	Descrizione	Valori predefiniti e limiti
maxBytes	Il volume massimo di dati di telemetria (in byte) da memorizzare nel buffer della memoria.	Predefinito: 262.144. Minimo: 262.144. Massimo: 1.048.576.
maxItems	Il numero massimo di eventi da memorizzare nel buffer.	Predefinito: 10.000 Minimo: 1.000 Massimo: 10.000.
timeoutMs	Il tempo massimo (in millisecondi) per memorizzare nel buffer un batch.	Predefinito: 1.000 Minimo: 25 Massimo: 30.000

Quando configuri il buffering, tieni presente i seguenti punti:

• Se uno qualsiasi dei flussi di input è chiuso, Lambda svuota i log. Ad esempio, ciò si può verificare quando il runtime subisce un arresto anomalo.

• Ogni abbonato può personalizzare la configurazione di buffering nella richiesta di abbonamento.

• Al momento di determinare la dimensione di buffer per la lettura dei dati, prevedi di ricevere payload di dimensioni pari a 2 * maxBytes + metadataBytes, dove maxBytes è un componente della configurazione di buffering. Per valutare la quantità di metadataBytes da considerare, esamina i seguenti metadati. Lambda allega metadati simili a questi a ogni record:

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

• Se il sottoscrittore non è in grado di elaborare la telemetria in ingresso abbastanza rapidamente o se il codice di funzione genera un volume di log molto elevato, Lambda potrebbe eliminare i registri per mantenere limitato l'utilizzo della memoria. Quando ciò si verifica, Lambda invia un evento platform.logsDropped.

Invio di una richiesta di sottoscrizione all'API di telemetria

Un'estensione Lambda può eseguire la sottoscrizione per ricevere i dati di telemetria inviando una richiesta di sottoscrizione all'API di telemetria. La richiesta di sottoscrizione deve contenere informazioni sui tipi di eventi a cui si desidera che l'estensione si iscriva. Inoltre, la richiesta può contenere informazioni sulla destinazione della consegna e una configurazione del buffering.

Prima di inviare una richiesta di sottoscrizione, è necessario disporre di un ID di estensione (Lambda-Extension-Identifier). Quando registri l'estensione con l'API delle estensioni, ottieni un ID di estensione dalla risposta dell'API.

La registrazione avviene durante la fase di inizializzazione dell'estensione. L'esempio seguente mostra una richiesta HTTP di sottoscrizione a tutti e tre i flussi di telemetria: telemetria della piattaforma, log delle funzioni e log delle estensioni.

PUT http://${AWS_LAMBDA_RUNTIME_API}/2022-07-01/telemetry HTTP/1.1
{
   "schemaVersion": "2022-12-13",
   "types": [
        "platform",
        "function",
        "extension"
   ],
   "buffering": {
        "maxItems": 1000,
        "maxBytes": 256*1024,
        "timeoutMs": 100
   },
   "destination": {
        "protocol": "HTTP",
        "URI": "http://sandbox.localdomain:8080"
   }
}

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

HTTP/1.1 200 OK
"OK"

Messaggi dell'API di telemetria in entrata

Dopo l'abbonamento con l'API Telemetry, un'estensione comincia in automatico a ricevere i dati di telemetria da Lambda attraverso richieste POST. Ogni corpo di richiesta POST contiene una serie di oggetti Event. Ogni Event presenta il seguente schema:

{
   time: String,
   type: String,
   record: Object
}

• La proprietà time definisce il momento in cui la piattaforma Lambda ha generato l'evento. Si tratta di un valore diverso da quando l'evento si è verificato effettivamente. Il valore della stringa di time è un timestamp nel formato ISO 8601.

• La proprietà type definisce il tipo di evento. La seguente tabella riporta tutti i valori possibili.

• La proprietà record definisce un oggetto JSON che contiene i dati di telemetria. Lo schema di questo oggetto JSON dipende dal type.

La tabella seguente riassume tutti i tipi di oggetti Event e i collegamenti al riferimento dello schema Event dell'API di telemetria per ogni tipo di evento.

Tipi di messaggi dell'API di telemetria
Categoria	Tipo di evento	Descrizione	Schema dei registri di eventi
Evento della piattaforma	platform.initStart	Inizializzazione della funzione avviata.	Schema platform.initStart
Evento della piattaforma	platform.initRuntimeDone	Inizializzazione della funzione completata.	Schema platform.initRuntimeDone
Evento della piattaforma	platform.initReport	Un rapporto sull'inizializzazione della funzione.	Schema platform.initReport
Evento della piattaforma	platform.start	L'invocazione della funzione è stata avviata.	Schema platform.start
Evento della piattaforma	platform.runtimeDone	Il runtime ha terminato l'elaborazione di un evento con esito positivo o negativo.	Schema platform.runtimeDone
Evento della piattaforma	platform.report	Un rapporto sull'invocazione di una funzione.	Schema platform.report
Evento della piattaforma	platform.restoreStart	Il ripristino del runtime è iniziato.	Schema platform.restoreStart
Evento della piattaforma	platform.restoreRuntimeDone	Il ripristino del runtime è stato completato.	Schema platform.restoreRuntimeDone
Evento della piattaforma	platform.restoreReport	Rapporto di ripristino del runtime.	Schema platform.restoreReport
Evento della piattaforma	platform.telemetrySubscription	L'estensione che ha eseguito la sottoscrizione all'API di telemetria.	Schema platform.telemetrySubscription
Evento della piattaforma	platform.logsDropped	Lambda ha eliminato le voci del log.	Schema platform.logsDropped
Log delle funzioni	function	Una riga del log dal codice della funzione.	Schema function
Log di estensioni	extension	Una riga di log dal codice dell'estensione.	Schema extension