API de Telemetria do Lambda

A API de Telemetria permite que as extensões recebam dados de telemetria diretamente do Lambda. Durante a inicialização e a invocação da função, o Lambda captura automaticamente a telemetria, incluindo logs, métricas de plataforma e rastreamentos de plataforma. A API de telemetria permite que as extensões acessem esses dados de telemetria diretamente no Lambda e quase em tempo real.

No ambiente de execução do Lambda, você pode inscrever as extensões do Lambda em fluxos de telemetria. Após a inscrição, o Lambda transmite automaticamente todos os dados de telemetria para as extensões. Em seguida, é possível processar, filtrar e entregar esses dados para o destino de preferência, como um bucket do Amazon Simple Storage Service (Amazon S3) ou um provedor externo de ferramentas de observabilidade.

O diagrama a seguir mostra como a API de extensões e a API de telemetria conectam extensões ao Lambda no ambiente de execução. Além disso, a API de runtime conecta o seu runtime e a função ao Lambda.

As extensões podem usar a API de telemetria para se inscrever em três fluxos de telemetria diferentes:

Criação de extensões usando a API de telemetria

As extensões do Lambda são executadas como processos independentes no ambiente de execução. As extensões podem continuar sendo executadas após a conclusão da invocação da função. Como as extensões são processos separados, é possível escrevê-las em uma linguagem diferente do código da função. Recomendamos a gravação de extensões usando uma linguagem compilada, como Golang ou Rust. Dessa forma, a extensão corresponde a um binário independente que pode ser compatível com qualquer runtime com suporte.

O diagrama a seguir ilustra um processo de quatro etapas para a criação de uma extensão que recebe e processa dados de telemetria usando a API de telemetria.

Veja a seguir cada etapa com mais detalhes:

Como registrar sua extensão

Antes de se inscrever em dados de telemetria, você deve registrar a extensão do Lambda. O registro ocorre durante a fase de inicialização da extensão. O exemplo a seguir mostra uma solicitação HTTP para registrar uma extensão.

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

Se o pedido for bem-sucedido, o assinante receberá uma resposta de sucesso HTTP 200. O cabeçalho de resposta contém o Lambda-Extension-Identifier. O corpo de resposta contém outras propriedades da função.

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

Para obter mais informações, consulte Referência de API de extensões.

Como criar um receptor de telemetria

Sua extensão do Lambda deve ter um receptor que processe as solicitações recebidas da API de telemetria. O código a seguir mostra um exemplo de implementação de receptor de telemetria em 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
}

Como especificar um protocolo de destino

Ao se inscrever para receber telemetria usando a API de telemetria, é possível especificar um protocolo de destino além do URI de destino:

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

O Lambda aceita dois protocolos para o recebimento de telemetria:

Antes de se inscrever para receber telemetria, estabeleça o receptor HTTP ou a porta TCP local. Durante a configuração, observe o seguinte:

Como configurar o uso de memória e o armazenamento em buffer

O uso de memória em um ambiente de execução cresce linearmente com o número de assinantes. As assinaturas consomem recursos de memória porque cada assinatura abre um novo buffer de memória para armazenar dados de telemetria. O uso da memória buffer contribui para o consumo geral de memória no ambiente de execução.

Ao se inscrever para receber telemetria usando a API de telemetria, você tem a opção de armazenar em buffer os dados de telemetria e entregá-los aos assinantes em lotes. Para otimizar o uso da memória, é possível especificar uma configuração de armazenamento em buffer:

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

Ao configurar o buffer, lembre-se dos seguintes pontos:

Como enviar uma solicitação de assinatura para a API de telemetria

As extensões do Lambda podem se inscrever para receber dados de telemetria enviando uma solicitação de assinatura para a API de telemetria. A solicitação de assinatura deve conter informações sobre os tipos de eventos que você deseja que a extensão assine. Além disso, a solicitação pode conter informações do destino de entrega e uma configuração de armazenamento em buffer.

Antes de enviar uma solicitação de assinatura, você deve ter um ID de extensão (Lambda-Extension-Identifier). Ao registrar sua extensão na API de extensões, você obtém um ID de extensão a partir da resposta da API.

A assinatura ocorre durante a fase de inicialização da extensão. O exemplo a seguir mostra uma solicitação HTTP para assinar todos os três fluxos de telemetria: telemetria de plataforma, logs de função e logs de extensão.

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 a solicitação tiver êxito, o assinante receberá uma resposta de sucesso HTTP 200.

HTTP/1.1 200 OK
"OK"

Mensagens da API de telemetria de entrada

Depois de se inscrever usando a API de telemetria, uma extensão começa automaticamente a receber telemetria do Lambda por meio de solicitações POST. Cada corpo de solicitação POST contém uma matriz de objetos Event. Cada Event tem o seguinte esquema:

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

A tabela a seguir resume todos os tipos de objetos Event e apresenta links para a referência de esquema Event da API de telemetria para cada tipo de evento.