Configurar o registro em log para uma API WebSocket

É possível habilitar o registro em log para gravar logs no CloudWatch Logs. Há dois tipos de registro de API em logs no CloudWatch: registro de execução e de acesso. No registro de execução, o API Gateway gerencia o CloudWatch Logs. O processo inclui a criação de grupos de log e fluxos de log, além de relatórios aos fluxos de log sobre solicitações e respostas de qualquer autor da chamada.

No registro de acessos, você, assim como um desenvolvedor de API, registra quem acessou sua API e como o autor da chamada acessou a API. Você pode criar seu próprio grupo de logs ou escolher um existente que possa ser gerenciado pelo API Gateway. Para especificar os detalhes de acesso, selecione variáveis $context (expressas em um formato de sua escolha) e selecione um grupo de logs como o destino.

Para obter instruções sobre como configurar o registro em log do CloudWatch, consulte Configurar o registro em log da API do CloudWatch usando o console do API Gateway.

Quando você especifica o Formato de registro, é possível escolher em quais variáveis de contexto se registrar. As seguintes variáveis são compatíveis.

Parâmetro	Descrição
$context.apiId	O identificador que o API Gateway atribui à sua API.
$context.authorize.error	A mensagem de erro de autorização.
$context.authorize.latency	A latência de autorização em ms.
$context.authorize.status	O código de status retornado de uma tentativa de autorização.
$context.authorizer.error	A mensagem de erro retornada de um autorizador.
$context.authorizer.integrationLatency	A latência do autorizador do Lambda em ms.
$context.authorizer.integrationStatus	O código de status retornado de um autorizador do Lambda.
$context.authorizer.latency	A latência de autorizador em ms.
$context.authorizer.requestId	O ID da solicitação do endpoint da AWS.
$context.authorizer.status	O código de status retornado de um autorizador.
$context.authorizer.principalId	A identificação do usuário principal associada ao token enviado pelo cliente e retornado de uma função do Lambda do autorizador do Lambda do API Gateway. (Anteriormente, um autorizador do Lambda era conhecido como um autorizador personalizado.)
$context.authorizer.property	O valor transformado em string do par de chave/valor especificado do mapa context retornado de uma função de autorizador do Lambda do API Gateway. Por exemplo, se o autorizador retornar o seguinte mapa context: "context" : { "key": "value", "numKey": 1, "boolKey": true } chamar $context.authorizer.key retornará a string "value", chamar $context.authorizer.numKey retornará a string "1" e chamar $context.authorizer.boolKey retornará a string "true".
$context.authenticate.error	A mensagem de erro retornada de uma tentativa de autenticação.
$context.authenticate.latency	A latência de autenticação em ms.
$context.authenticate.status	O código de status retornado de uma tentativa de autenticação.
$context.connectedAt	O tempo de conexão formatado em Epoch.
$context.connectionId	Um ID exclusivo para a conexão que pode ser utilizado para fazer uma chamada ao cliente.
$context.domainName	Um nome de domínio para a API WebSocket. Pode ser usado para fazer um retorno de chamada ao cliente (em vez de um valor codificado).
$context.error.message	Uma string que contém uma mensagem de erro do API Gateway.
$context.error.messageString	O valor citado de $context.error.message, ou seja, "$context.error.message".
$context.error.responseType	O tipo de resposta de erro.
$context.error.validationErrorString	Uma string que contém uma mensagem de erro de validação detalhada.
$context.eventType	O tipo de evento: CONNECT, MESSAGE ou DISCONNECT.
$context.extendedRequestId	Equivale a $context.requestId.
$context.identity.accountId	O ID da conta da AWS associado à solicitação.
$context.identity.apiKey	A chave do proprietário da API associada à solicitação de API habilitada por chave.
$context.identity.apiKeyId	O ID da chave da API associada à solicitação de API habilitada por chave
$context.identity.caller	O identificador da entidade do autor da chamada que assinou a solicitação. Compatível com rotas que usam a autorização do IAM.
$context.identity.cognitoAuthenticationProvider	Uma lista separada por vírgulas dos provedores de autenticação do Amazon Cognito usados pelo autor da chamada que faz a solicitação. Disponível somente se a solicitação foi assinada com credenciais do Amazon Cognito. Por exemplo, para uma identidade de um grupo de usuários do Amazon Cognito, cognito-idp. region.amazonaws.com/user_pool_id,cognito-idp.region.amazonaws.com/user_pool_id:CognitoSignIn:token subject claim Para obter informações, consulte Usar identidades federadas no Guia do desenvolvedor do Amazon Cognito.
$context.identity.cognitoAuthenticationType	O tipo de autenticação do Amazon Cognito do autor da chamada que faz a solicitação. Disponível somente se a solicitação foi assinada com credenciais do Amazon Cognito. Os valores possíveis incluem authenticated para identidades autenticadas e unauthenticated para identidades não autenticadas.
$context.identity.cognitoIdentityId	O ID de identidade do Amazon Cognito do autor da chamada que faz a solicitação. Disponível somente se a solicitação foi assinada com credenciais do Amazon Cognito.
$context.identity.cognitoIdentityPoolId	O ID do grupo de identidades do Amazon Cognito do autor da chamada que faz a solicitação. Disponível somente se a solicitação foi assinada com credenciais do Amazon Cognito.
$context.identity.principalOrgId	O ID da organização da AWS. Compatível com rotas que usam a autorização do IAM.
$context.identity.sourceIp	O endereço IP de origem da conexão TCP que está fazendo a solicitação para ao API Gateway.
$context.identity.user	O identificador da entidade do usuário que será autorizado contra o acesso a recursos. Compatível com rotas que usam a autorização do IAM.
$context.identity.userAgent	O agente de usuário do autor da chamada da API.
$context.identity.userArn	O Nome do Recurso Amazon (ARN) do usuário efetivo identificado após a autenticação.
$context.integration.error	A mensagem de erro retornada de uma integração.
$context.integration.integrationStatus	Para a integração de proxy do Lambda, o código de status retornado do AWS Lambda, não do código de função do Lambda de back-end.
$context.integration.latency	A latência de integração em ms. Equivale a $context.integrationLatency.
$context.integration.requestId	O ID da solicitação do endpoint da AWS. Equivale a $context.awsEndpointRequestId.
$context.integration.status	O código de status retornado de uma integração. Para integrações de proxy do Lambda, esse é o código de status que seu código de função do Lambda retorna. Equivale a $context.integrationStatus.
$context.integrationLatency	A latência de integração em ms, disponível somente para registro de log de acesso.
$context.messageId	Um ID exclusivo do servidor para uma mensagem. Disponível apenas quando o $context.eventType é MESSAGE.
$context.requestId	Igual a $context.extendedRequestId.
$context.requestTime	O horário da solicitação CLF formatado (dd/MMM/yyyy:HH:mm:ss +-hhmm).
$context.requestTimeEpoch	O tempo de solicitação formatado em Epoch, em milissegundos.
$context.routeKey	A chave de roteamento selecionada.
$context.stage	O estágio de implantação da chamada da API (por exemplo, beta ou prod).
$context.status	O status da resposta.
$context.waf.error	A mensagem de erro retornada pelo AWS WAF.
$context.waf.latency	A latência do AWS WAF em ms.
$context.waf.status	O código de status retornado pelo AWS WAF.

Exemplos de alguns formatos de log de acesso comumente usados são mostrados no console do API Gateway e estão listados a seguir.

• CLF (Formato de log comum):

  $context.identity.sourceIp $context.identity.caller \
  $context.identity.user [$context.requestTime] "$context.eventType $context.routeKey $context.connectionId" \
  $context.status $context.requestId

  Os caracteres de continuação (\) têm o objetivo de ajuda visual. O formato do log deve ser uma única linha. É possível adicionar um caractere de nova linha (\n) no final do formato de log para incluir uma nova linha no final de cada entrada de log.

• JSON:

  {
  "requestId":"$context.requestId", \
  "ip": "$context.identity.sourceIp", \
  "caller":"$context.identity.caller", \
  "user":"$context.identity.user", \
  "requestTime":"$context.requestTime", \
  "eventType":"$context.eventType", \
  "routeKey":"$context.routeKey", \
  "status":"$context.status", \
  "connectionId":"$context.connectionId"
  }

  Os caracteres de continuação (\) têm o objetivo de ajuda visual. O formato do log deve ser uma única linha. É possível adicionar um caractere de nova linha (\n) no final do formato de log para incluir uma nova linha no final de cada entrada de log.

• XML:

  <request id="$context.requestId"> \
   <ip>$context.identity.sourceIp</ip> \
   <caller>$context.identity.caller</caller> \
   <user>$context.identity.user</user> \
   <requestTime>$context.requestTime</requestTime> \
   <eventType>$context.eventType</eventType> \
   <routeKey>$context.routeKey</routeKey> \
   <status>$context.status</status> \
   <connectionId>$context.connectionId</connectionId> \
  </request>

  Os caracteres de continuação (\) têm o objetivo de ajuda visual. O formato do log deve ser uma única linha. É possível adicionar um caractere de nova linha (\n) no final do formato de log para incluir uma nova linha no final de cada entrada de log.

• CSV (valores separados por vírgula):

  $context.identity.sourceIp,$context.identity.caller, \
  $context.identity.user,$context.requestTime,$context.eventType, \
  $context.routeKey,$context.connectionId,$context.status, \
  $context.requestId

  Os caracteres de continuação (\) têm o objetivo de ajuda visual. O formato do log deve ser uma única linha. É possível adicionar um caractere de nova linha (\n) no final do formato de log para incluir uma nova linha no final de cada entrada de log.