O AWS SDK para Java 1.x entrou no modo de manutenção em 31 de julho de 2024 e o fim do suporte está previsto para 31 de dezembro de 2025. Recomendamos que você migre para o AWS SDK for Java 2.x para continuar recebendo novos recursos, melhorias de disponibilidade e atualizações de segurança.

Registrar em log as chamadas a AWS SDK para Java

O AWS SDK para Java é instrumentalizado com o Apache Commons Logging, que é uma camada de abstração que permite o uso de qualquer um dos diversos sistemas de registro em log em tempo de execução.

Entre os sistemas de registro em log compatíveis estão o Java Logging Framework e o Apache Log4j, entre outros. Este tópico mostra como usar o Log4j. Você pode usar a funcionalidade de registro em log do SDK sem fazer alterações no código do aplicativo.

Para saber mais sobre o Log4j, consulte o site do Apache.

Fazer download do Log4J JAR

Para usar o Log4j com o SDK, você precisa fazer download do Log4j JAR no site do Apache. O SDK não inclui o JAR. Copie o arquivo JAR para um local no classpath.

O Log4j usa um arquivo de configuração, log4j.properties. Os arquivos de configuração de exemplo são mostrados abaixo. Copie esse arquivo de configuração para um diretório no classpath. O Log4j JAR e o arquivo log4j.properties não precisam estar no mesmo diretório.

O arquivo de configuração log4j.properties especifica propriedades como nível de registro em log, em que a saída do registro em log é enviada (por exemplo, para um arquivo ou para o console) e o formato da saída. O nível de registro em log é a granularidade de saída gerada pelo registrador em log. O Log4j dá suporte ao conceito de várias hierarquias de registro em log. O nível de registro em log é definido de maneira independente para cada hierarquia. As duas seguintes hierarquias de registro em log estão disponíveis no AWS SDK para Java:

Definir o classpath

O Log4j JAR e o arquivo log4j.properties devem estar no classpath. Se você estiver usando o Apache Ant, defina o classpath no elemento path do arquivo Ant. O exemplo a seguir mostra um elemento de caminho do arquivo Ant para o exemplo do Amazon S3 incluído no SDK.

<path id="aws.java.sdk.classpath">
  <fileset dir="../../third-party" includes="**/*.jar"/>
  <fileset dir="../../lib" includes="**/*.jar"/>
  <pathelement location="."/>
</path>

Se estiver usando o IDE do Eclipse, você poderá definir o classpath abrindo o menu e navegando até Project (Projeto) | Properties (Propriedades) | Java Build Path.

Erros e avisos específicos do serviço

Recomendamos sempre deixar a hierarquia do registrador em log "com.amazonaws" definida como "WARN" para interceptar todas as mensagens importantes das bibliotecas de cliente. Por exemplo, se o cliente do Amazon S3 detectar que o aplicativo não fechou corretamente um InputStream e possa estar vazando recursos, o cliente do S3 informará isso por meio de uma mensagem de aviso para os logs. Isso também garante que as mensagens serão registradas em log se o cliente enfrentar algum problema ao processar requisições ou respostas.

O arquivo log4j.properties a seguir define o rootLogger como WARN, o que faz mensagens de erro e aviso de todos os registradores em log na hierarquia "com.amazonaws" serem incluídas. Você também pode definir explicitamente o registrador em log com.amazonaws como WARN.

log4j.rootLogger=WARN, A1
log4j.appender.A1=org.apache.log4j.ConsoleAppender
log4j.appender.A1.layout=org.apache.log4j.PatternLayout
log4j.appender.A1.layout.ConversionPattern=%d [%t] %-5p %c -  %m%n
# Or you can explicitly enable WARN and ERROR messages for the {AWS} Java clients
log4j.logger.com.amazonaws=WARN

Registro em log do resumo de requisição/resposta

Cada solicitação a um AWS service (Serviço da AWS) gera um ID de solicitação exclusivo da AWS que é útil se você tiver problemas com a forma como um AWS service (Serviço da AWS) está lidando com uma solicitação. Os IDs de solicitação da AWS podem ser acessados programaticamente por meio de objetos de exceção no SDK para qualquer chamada de serviço com falha e também podem ser relatados por meio do nível de log DEBUG no logger “com.amazonaws.request”.

O arquivo log4j.properties a seguir permite um resumo de requisições e respostas, inclusive IDs de requisição da AWS.

log4j.rootLogger=WARN, A1
log4j.appender.A1=org.apache.log4j.ConsoleAppender
log4j.appender.A1.layout=org.apache.log4j.PatternLayout
log4j.appender.A1.layout.ConversionPattern=%d [%t] %-5p %c -  %m%n
# Turn on DEBUG logging in com.amazonaws.request to log
# a summary of requests/responses with {AWS} request IDs
log4j.logger.com.amazonaws.request=DEBUG

Aqui está um exemplo da saída do log.

2009-12-17 09:53:04,269 [main] DEBUG com.amazonaws.request - Sending
Request: POST https://rds.amazonaws.com / Parameters: (MaxRecords: 20,
Action: DescribeEngineDefaultParameters, SignatureMethod: HmacSHA256,
AWSAccessKeyId: ACCESSKEYID, Version: 2009-10-16, SignatureVersion: 2,
Engine: mysql5.1, Timestamp: 2009-12-17T17:53:04.267Z, Signature:
q963XH63Lcovl5Rr71APlzlye99rmWwT9DfuQaNznkD, ) 2009-12-17 09:53:04,464
[main] DEBUG com.amazonaws.request - Received successful response: 200, {AWS}
Request ID: 694d1242-cee0-c85e-f31f-5dab1ea18bc6 2009-12-17 09:53:04,469
[main] DEBUG com.amazonaws.request - Sending Request: POST
https://rds.amazonaws.com / Parameters: (ResetAllParameters: true, Action:
ResetDBParameterGroup, SignatureMethod: HmacSHA256, DBParameterGroupName:
java-integ-test-param-group-0000000000000, AWSAccessKeyId: ACCESSKEYID,
Version: 2009-10-16, SignatureVersion: 2, Timestamp:
2009-12-17T17:53:04.467Z, Signature:
9WcgfPwTobvLVcpyhbrdN7P7l3uH0oviYQ4yZ+TQjsQ=, )

2009-12-17 09:53:04,646 [main] DEBUG com.amazonaws.request - Received
successful response: 200, {AWS} Request ID:
694d1242-cee0-c85e-f31f-5dab1ea18bc6

Registro em log detalhado

Em alguns casos, pode ser útil ver as requisições e as respostas exatas enviadas e recebidas pelo AWS SDK para Java. Você não deve permitir esse registro em log em sistemas de produção, porque gravar solicitações (por exemplo, o upload de um arquivo para o Amazon S3) ou respostas grandes pode atrasar significativamente um aplicativo. Se realmente precisar de acesso a essas informações, você poderá habilitá-lo temporariamente por meio do registrador em log do Apache HttpClient 4. Habilitar o nível DEBUG no registrador em log org.apache.http.wire permite o registro em log de todos os dados de requisição e resposta.

O arquivo log4j.properties a seguir ativa o registro em log completo no Apache HttpClient 4 e somente deve ser ativado temporariamente porque pode ter um impacto significativo sobre o desempenho do aplicativo.

log4j.rootLogger=WARN, A1
log4j.appender.A1=org.apache.log4j.ConsoleAppender
log4j.appender.A1.layout=org.apache.log4j.PatternLayout
log4j.appender.A1.layout.ConversionPattern=%d [%t] %-5p %c -  %m%n
# Log all HTTP content (headers, parameters, content, etc)  for
# all requests and responses. Use caution with this since it can
# be very expensive to log such verbose data!
log4j.logger.org.apache.http.wire=DEBUG

Registro de métricas de latência

Se você estiver solucionando problemas e desejar ver métricas, como qual processo está consumindo mais tempo ou se o lado do servidor ou do cliente têm mais latência, o registrador de latência será útil. Defina o registrador com.amazonaws.latency como DEBUG para habilitá-lo.

log4j.rootLogger=WARN, A1
log4j.appender.A1=org.apache.log4j.ConsoleAppender
log4j.appender.A1.layout=org.apache.log4j.PatternLayout
log4j.appender.A1.layout.ConversionPattern=%d [%t] %-5p %c -  %m%n
log4j.logger.com.amazonaws.latency=DEBUG

Aqui está um exemplo da saída do log.

com.amazonaws.latency - ServiceName=[{S3}], StatusCode=[200],
ServiceEndpoint=[https://list-objects-integ-test-test.s3.amazonaws.com],
RequestType=[ListObjectsV2Request], AWSRequestID=[REQUESTID], HttpClientPoolPendingCount=0,
RetryCapacityConsumed=0, HttpClientPoolAvailableCount=0, RequestCount=1,
HttpClientPoolLeasedCount=0, ResponseProcessingTime=[52.154], ClientExecuteTime=[487.041],
HttpClientSendRequestTime=[192.931], HttpRequestTime=[431.652], RequestSigningTime=[0.357],
CredentialsRequestTime=[0.011, 0.001], HttpClientReceiveResponseTime=[146.272]