Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

Accesso ai dati di telemetria in tempo reale per le estensioni tramite l'API Telemetry

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.

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

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:

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 listener di telemetria

L'estensione Lambda deve disporre di un listener che gestisca le richieste in entrata dall'API di telemetria. Il codice seguente mostra un esempio di implementazione dell'listener 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:

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

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

Quando configuri il buffering, tieni presente i seguenti punti:

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 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.