API de Telemetria do Lambda - AWS Lambda

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 APIs de extensões, telemetria e runtime que conectam o Lambda aos processos no ambiente de execução.
Importante

A API de telemetria do Lambda substitui a API de logs do Lambda. Embora a API de logs permaneça totalmente funcional, recomendamos usar apenas a API de telemetria daqui para frente. É possível inscrever sua extensão em um fluxo de telemetria usando a API de telemetria ou a API de logs. Após se inscrever usando uma dessas APIs, qualquer tentativa de se inscrever usando a outra API retornará um erro.

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

  • Telemetria de plataforma: logs, métricas e rastreamentos que descrevem eventos e erros relacionados ao ciclo de vida de runtime do ambiente de execução, ao ciclo de vida de extensão e às invocações de função.

  • Logs de função: logs personalizados gerados pelo código da função do Lambda.

  • Logs de extensão: logs personalizados gerados pelo código de extensão do Lambda.

nota

O Lambda envia registros CloudWatch, métricas e rastreamentos para o X-Ray (se você tiver ativado o rastreamento), mesmo que uma extensão assine fluxos de telemetria.

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.

Registre a extensão, crie um receptor, realize a assinatura em um fluxo e, em seguida, obtenha a telemetria.

Veja a seguir cada etapa com mais detalhes:

  1. Registre sua extensão usando a API Extensions do Lambda. Isso fornece um Lambda-Extension-Identifier, que você precisará para as etapas a seguir. Para obter mais informações sobre como registrar sua extensão, consulte Como registrar sua extensão.

  2. Crie um receptor de telemetria. Pode ser um servidor HTTP ou TCP comum. O Lambda usa o URI do receptor de telemetria para enviar dados de telemetria para a extensão. Para ter mais informações, consulte Como criar um receptor de telemetria.

  3. Use a API de inscrição na API de telemetria para inscrever a extensão nos fluxos de telemetria desejados. Você precisará do URI do receptor de telemetria para esta etapa. Para ter mais informações, consulte Como enviar uma solicitação de assinatura para a API de telemetria.

  4. Obtenha os dados de telemetria do Lambda por meio do receptor de telemetria. É possível fazer qualquer processamento personalizado desses dados, como enviar os dados para o Amazon S3 ou para um serviço de observabilidade externo.

nota

O ambiente de execução de uma função do Lambda pode ser iniciado e interrompido diversas vezes como parte de seu ciclo de vida. Em geral, o código de extensão é executado durante as invocações de função e também por até dois segundos durante a fase de desligamento. Recomendamos processar a telemetria em lotes à medida que ela chegar ao receptor. Em seguida, use os eventos de ciclo de vida Invoke e Shutdown para enviar cada lote aos destinos desejados.

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:

  • HTTP (recomendado): o Lambda fornece telemetria para um endpoint HTTP local (http://sandbox.localdomain:${PORT}/${PATH}) como uma matriz de registros no formato JSON. O parâmetro $PATH é opcional. O Lambda oferece suporte somente para HTTP, não para HTTPS. O Lambda fornece telemetria por meio de solicitações POST.

  • TCP: o Lambda fornece telemetria para uma porta TCP no formato Newline delimited JSON (NDJSON).

nota

Recomendamos fortemente o uso de HTTP em vez de TCP. Com o TCP, a plataforma do Lambda não reconhece que a telemetria é entregue à camada da aplicação. Portanto, se sua extensão falhar, você poderá perder a telemetria. O HTTP não tem essa limitação.

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

  • O Lambda envia telemetria somente para destinos que estão dentro do ambiente de execução.

  • O Lambda tenta novamente enviar telemetria (com recuo) na ausência de um receptor ou se a solicitação POST encontrar algum erro. Se o receptor de telemetria apresentar falhas, ele continuará a receber telemetria depois que o Lambda reiniciar o ambiente de execução.

  • Lambda reserva porto 9001. Não há outras restrições ou recomendações de número de porta.

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 } }
Definições de configuração de armazenamento em buffer
Parâmetro Descrição Padrões e limites

maxBytes

O volume máximo de telemetria (em bytes) para armazenar em buffer na memória.

Padrão: 262.144

Mínimo: 262.144

Máximo: 1.048.576

maxItems

O número máximo de eventos para armazenar em buffer na memória.

Padrão: 10.000

Mínimo: 1.000

Máximo: 10.000.

timeoutMs

O tempo máximo (em milissegundos) para armazenar em buffer um lote.

Padrão: 1.000

Mínimo: 25

Máximo: 30.000

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

  • Se algum dos fluxos de entrada estiver fechado, o Lambda liberará os logs. Por exemplo, isso pode acontecer se o runtime apresentar falhas.

  • Cada assinante pode personalizar a configuração de buffer durante a solicitação de assinatura.

  • Ao determinar o tamanho do buffer para ler os dados, preveja o recebimento de cargas úteis tão grandes quanto 2 * maxBytes + metadataBytes, em que maxBytes é um componente da configuração de buffer. Para avaliar a quantidade de metadataBytes a ser considerada, analise os metadados a seguir. O Lambda anexa metadados semelhantes a este para cada registro:

    { "time": "2022-08-20T12:31:32.123Z", "type": "function", "record": "Hello World" }
  • Se o assinante não puder processar a telemetria de entrada com rapidez suficiente ou se o código da sua função gerar um volume de log muito alto, o Lambda poderá descartar registros para manter a utilização da memória limitada. Quando isso ocorre, o Lambda envia um evento platform.logsDropped.

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 propriedade time define quando a plataforma do Lambda gerou o evento. Isso é diferente de quando o evento realmente ocorreu. O valor da string time é um carimbo de data/hora no formato ISO 8601.

  • A propriedade type define o tipo de evento. A tabela a seguir descreve todos os valores possíveis.

  • A propriedade record define um objeto JSON que contém os dados de telemetria. O esquema desse objeto JSON depende do arquivo type.

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.

Tipos de mensagem da API de telemetria
Categoria Tipo de evento Descrição Esquema de registro de evento

Evento de plataforma

platform.initStart

A inicialização da função foi iniciada.

Esquema platform.initStart

Evento de plataforma

platform.initRuntimeDone

A inicialização da função foi concluída.

Esquema platform.initRuntimeDone

Evento de plataforma

platform.initReport

Um relatório sobre a inicialização da função.

Esquema platform.initReport

Evento de plataforma

platform.start

A invocação da função foi iniciada.

Esquema platform.start

Evento de plataforma

platform.runtimeDone

O runtime concluiu o processamento de um evento com sucesso ou com falha.

Esquema platform.runtimeDone

Evento de plataforma

platform.report

Um relatório sobre a invocação de função.

Esquema platform.report

Evento de plataforma

platform.restoreStart

A restauração do runtime foi iniciada.

Esquema platform.restoreStart

Evento de plataforma

platform.restoreRuntimeDone

A restauração do runtime foi concluída.

Esquema platform.restoreRuntimeDone

Evento de plataforma

platform.restoreReport

Relatório de restauração do runtime.

Esquema platform.restoreReport

Evento de plataforma

platform.telemetrySubscription

A extensão foi inscrita na API de telemetria.

Esquema platform.telemetrySubscription

Evento de plataforma

platform.logsDropped

O Lambda descartou entradas de log.

Esquema platform.logsDropped

Registros de função

function

Uma linha de log do código da função.

Esquema function

Logs de extensões

extension

Uma linha de log do código de extensão.

Esquema extension