# Configurar o registro em log para APIs de WebSocket no API Gateway
<a name="websocket-api-logging"></a>

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

Para melhorar seu procedimento de segurança, recomendamos que você use o registro em log de execução no nível `ERROR` ou `INFO`. Você pode precisar fazer isso para cumprir vários requisitos de conformidade. Para ter mais informações, consulte [Amazon API Gateway controls](https://docs.aws.amazon.com/securityhub/latest/userguide/apigateway-controls.html) no *Guia do usuário do AWS Security Hub*.

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](set-up-logging.md#set-up-access-logging-using-console).

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`: <pre>"context" : {<br />                            "key": "value",<br />                            "numKey": 1,<br />                            "boolKey": true<br />                            }</pre><br />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](https://en.wikipedia.org/wiki/Unix_time). | 
| $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 de todos os 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. <br />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}}`<br />Consulte informações sobre os provedores de autenticação do Amazon Cognito disponível em [Using Federated Identities](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-identity.html) 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](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_org_details.html). 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 pelo AWS Lambda, e não pelo código de função do Lambda de backend. | 
| $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](https://httpd.apache.org/docs/current/logs.html#common) formatado (dd/MMM/yyyy:HH:mm:ss \+-hhmm). | 
| $context.requestTimeEpoch | O tempo de solicitação formatado em [Epoch](https://en.wikipedia.org/wiki/Unix_time), 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](https://httpd.apache.org/docs/current/logs.html#common)):

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