As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá. # Publique métricas do SDK a partir do AWS SDK for Java 2.x Com isso, AWS SDK for Java 2.x você pode coletar métricas sobre os clientes de serviços e solicitações em seu aplicativo, analisar a saída no Amazon CloudWatch Logs e, em seguida, agir de acordo com ela. Por padrão, a coleta de métricas está desativada no SDK. Este tópico ajuda a habilitar e configurá-lo. ## Conceitos básicos das métricas de SDK Para habilitar a coleta de métricas na aplicação, escolha a implementação apropriada da interface `[MetricPublisher](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/metrics/MetricPublisher.html)` com base no seu caso de uso e siga as instruções detalhadas de configuração: **Para aplicações de longa execução:** + Usar o `[CloudWatchMetricPublisher](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/metrics/publishers/cloudwatch/CloudWatchMetricPublisher.html)` + Consulte instruções completas de configuração, exemplos de código e opções de configuração em [Publicar métricas do SDK de aplicações de longa execução](metric-pub-impl-cwmp.md). **Para AWS Lambda funções:** + Usar o `[EmfMetricLoggingPublisher](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/metrics/publishers/emf/EmfMetricLoggingPublisher.html)` + Consulte [Publicar métricas do SDK para AWS Lambda funções para](metric-pub-impl-emf.md) obter instruções completas de configuração, dependências e configurações específicas do Lambda. **Para solução de problemas e saída do console:** + Usar o `[LoggingMetricPublisher](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/metrics/LoggingMetricPublisher.html)` + Consulte instruções de configuração, opções de formatação e exemplos de desenvolvimento e solução de problemas locais em [Exibir métricas do SDK no console para desenvolvimento e depuração](metric-pub-impl-logging.md). ## Pré-visualização da implementação rápida Veja como é a ativação de métricas para cada caso de uso: **Aplicações de longa execução:** ``` MetricPublisher metricsPub = CloudWatchMetricPublisher.create(); DynamoDbClient ddb = DynamoDbClient.builder() .overrideConfiguration(c -> c.addMetricPublisher(metricsPub)) .build(); ``` **Funções do Lambda:** ``` EmfMetricLoggingPublisher emfPublisher = EmfMetricLoggingPublisher.builder() .namespace("MyApp") .build(); DynamoDbClient dynamoDb = DynamoDbClient.builder() .overrideConfiguration(c -> c.addMetricPublisher(emfPublisher)) .build(); ``` **Desenvolvimento e depuração:** ``` MetricPublisher loggingPublisher = LoggingMetricPublisher.create(); S3Client s3 = S3Client.builder() .overrideConfiguration(c -> c.addMetricPublisher(loggingPublisher)) .build(); ``` ## Limitação de métricas do cliente AWS S3 baseado em CRT Atualmente, o [Cliente do S3 baseado no AWS CRT](crt-based-s3-client.md) não permite a coleta de métricas do SDK. O construtor de uma instância de cliente S3 AWS baseada em CRT, [https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/s3/S3CrtAsyncClientBuilder.html](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/s3/S3CrtAsyncClientBuilder.html), não fornece métodos para configurar editores de métricas. ## Quando as métricas estão disponíveis? As métricas geralmente ficam disponíveis em 5 a 10 minutos após a emissão das métricas pelo SDK para Java. Para obter up-to-date métricas precisas, verifique o Cloudwatch pelo menos 10 minutos depois de emitir as métricas de seus aplicativos Java. ## Quais informações são coletadas? A coleção de métricas inclui o seguinte: + Número de solicitações de API, incluindo se foram bem-sucedidas ou se falharam + Informações sobre o Serviços da AWS que você chama em suas solicitações de API, incluindo exceções retornadas + A duração de várias operações, como marshalling, assinatura e solicitações HTTP + Métricas do cliente HTTP, como o número de conexões abertas, o número de solicitações pendentes e o nome do cliente HTTP usado **nota** As métricas disponíveis variam de acordo com o cliente HTTP. Para obter uma lista completa, consulte [Métricas de serviço do cliente](metrics-list.md). ## Como posso usar essas informações? Use as métricas que o SDK coleta para monitorar os clientes de serviço em sua aplicação. Você pode analisar as tendências gerais de uso, identificar anomalias, analisar as exceções retornadas pelos clientes de serviço ou obter mais informações para entender um problema específico. Usando o Amazon CloudWatch Logs, você também pode criar alarmes para notificá-lo assim que seu aplicativo atingir uma condição definida por você. Para obter mais informações, consulte Como [usar métricas do Amazon CloudWatch Logs](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/working_with_metrics.html) e [Usar alarmes do Amazon CloudWatch Logs](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/AlarmThatSendsEmail.html) no [Guia do usuário do Amazon CloudWatch Logs](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/). # Publique métricas do SDK de aplicativos de longa execução usando o AWS SDK for Java 2.x Como a `[CloudWatchMetricPublisher](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/metrics/publishers/cloudwatch/CloudWatchMetricPublisher.html)` implementação agrega e carrega periodicamente métricas para a Amazon CloudWatch com um atraso, seu uso é mais adequado para aplicativos de longa execução. As configurações padrão do editor de métricas têm como objetivo minimizar o uso e o CloudWatch custo da memória, ao mesmo tempo em que fornecem uma quantidade útil de informações sobre os dados métricos. ## Configuração Antes de ativar e usar as métricas usando `CloudWatchMetricPublisher`, siga as etapas a seguir. ### Etapa 1: adicionar dependência necessária Configure as dependências do seu projeto (por exemplo, no seu arquivo `pom.xml` ou `build.gradle`) para usar a versão `2.14.0` ou posterior do AWS SDK para Java. Inclua o artifactId `cloudwatch-metric-publisher` com o número da versão `2.14.0` ou posterior nas dependências do projeto. Por exemplo: ``` software.amazon.awssdk bom [2.30.11](https://central.sonatype.com/artifact/software.amazon.awssdk/bom) pom import software.amazon.awssdk cloudwatch-metric-publisher ``` ### Etapa 2: configurar as permissões necessárias Habilite as permissões `cloudwatch:PutMetricData` para a identidade do IAM usada pelo publicador de métricas para permitir que o SDK para Java escreva métricas. ## Habilitar métricas para uma solicitação específica A classe a seguir mostra como habilitar o editor de CloudWatch métricas para uma solicitação ao Amazon DynamoDB. Ele usa a configuração padrão do publicador de métricas. ``` import software.amazon.awssdk.metrics.MetricPublisher; import software.amazon.awssdk.metrics.publishers.cloudwatch.CloudWatchMetricPublisher; import software.amazon.awssdk.services.dynamodb.DynamoDbClient; import software.amazon.awssdk.services.dynamodb.model.ListTablesRequest; public class DefaultConfigForRequest { // Use one MetricPublisher for your application. It can be used with requests or service clients. static MetricPublisher metricsPub = CloudWatchMetricPublisher.create(); public static void main(String[] args) { DynamoDbClient ddb = DynamoDbClient.create(); // Publish metrics the for ListTables operation. ddb.listTables(ListTablesRequest.builder() .overrideConfiguration(c -> c.addMetricPublisher(metricsPub)) .build()); // Perform more work in your application. // A MetricsPublisher has its own lifecycle independent of any service client or request that uses it. // If you no longer need the publisher, close it to free up resources. metricsPub.close(); // All metrics stored in memory are flushed to CloudWatch. // Perform more work with the DynamoDbClient instance without publishing metrics. // Close the service client when you no longer need it. ddb.close(); } } ``` **Importante** A aplicação deve chamar `close` na instância `[MetricPublisher](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/metrics/MetricPublisher.html)` quando o cliente de serviço não estiver mais em uso. Não fazer isso pode causar vazamentos de threads ou descritores de arquivo. ## Habilitar métricas resumidas para um cliente de serviço específico O trecho de código a seguir mostra como habilitar um editor de CloudWatch métricas com configurações padrão para um cliente de serviço. ``` MetricPublisher metricsPub = CloudWatchMetricPublisher.create(); DynamoDbClient ddb = DynamoDbClient.builder() .overrideConfiguration(c -> c.addMetricPublisher(metricsPub)) .build(); ``` ## Personalize um editor de CloudWatch métricas A classe a seguir demonstra como definir uma configuração personalizada para o publicador de métricas de um cliente de serviço específico. As personalizações incluem carregar um perfil específico, especificar uma AWS região para a qual o editor de métricas envia solicitações e personalizar a frequência com que o editor envia métricas. CloudWatch ``` import software.amazon.awssdk.auth.credentials.ProfileCredentialsProvider; import software.amazon.awssdk.core.metrics.CoreMetric; import software.amazon.awssdk.metrics.MetricPublisher; import software.amazon.awssdk.metrics.publishers.cloudwatch.CloudWatchMetricPublisher; import software.amazon.awssdk.regions.Region; import software.amazon.awssdk.services.cloudwatch.CloudWatchAsyncClient; import software.amazon.awssdk.services.dynamodb.DynamoDbClient; import java.time.Duration; public class CustomConfigForDDBClient { // Use one MetricPublisher for your application. It can be used with requests or service clients. static MetricPublisher metricsPub = CloudWatchMetricPublisher.builder() .cloudWatchClient(CloudWatchAsyncClient.builder() .region(Region.US_WEST_2) .credentialsProvider(ProfileCredentialsProvider.create("cloudwatch")) .build()) .uploadFrequency(Duration.ofMinutes(5)) .maximumCallsPerUpload(100) .namespace("ExampleSDKV2Metrics") .detailedMetrics(CoreMetric.API_CALL_DURATION) .build(); public static void main(String[] args) { DynamoDbClient ddb = DynamoDbClient.builder() .overrideConfiguration(c -> c.addMetricPublisher(metricsPub)) .build(); // Publish metrics for DynamoDB operations. ddb.listTables(); ddb.describeEndpoints(); ddb.describeLimits(); // Perform more work in your application. // A MetricsPublisher has its own lifecycle independent of any service client or request that uses it. // If you no longer need the publisher, close it to free up resources. metricsPub.close(); // All metrics stored in memory are flushed to CloudWatch. // Perform more work with the DynamoDbClient instance without publishing metrics. // Close the service client when you no longer need it. ddb.close(); } } ``` As personalizações mostradas no trecho anterior têm os efeitos a seguir. + O `cloudWatchClient` método permite que você personalize o CloudWatch cliente usado para enviar métricas. Neste exemplo, usamos uma região diferente do padrão de *us-east-1* para onde o cliente envia métricas. Também usamos um perfil nomeado diferente, *cloudwatch*, cujas credenciais serão usadas para autenticar solicitações para. CloudWatch Essas credenciais devem ter permissões para `cloudwatch:PutMetricData`. + O `uploadFrequency` método permite que você especifique com que frequência o editor de métricas faz o upload das métricas. CloudWatch O padrão é uma vez por minuto. + O método `maximumCallsPerUpload` limita o número de chamadas feitas por upload. O valor padrão é ilimitado. + Por padrão, o SDK para Java 2.x publica métricas no namespace `AwsSdk/JavaSdk2`. Você pode usar o método `namespace` para especificar um valor diferente. + Por padrão, o SDK publica métricas resumidas. As métricas resumidas consistem em média, mínimo, máximo, soma e contagem de amostras. Ao especificar uma ou mais métricas do SDK no método `detailedMetrics`, o SDK publica dados adicionais para cada métrica. Esses dados adicionais permitem estatísticas percentuais, como p90 e p99, que você pode consultar. CloudWatch As métricas detalhadas são especialmente úteis para métricas de latência`APICallDuration`, como a que mede a end-to-end latência das solicitações de clientes do SDK. É possível usar os campos da classe `[CoreMetric](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/core/metrics/CoreMetric.html)` para especificar outras métricas comuns do SDK. **Próximas etapas:** Se você também estiver trabalhando com funções do Lambda, consulte [Publicar métricas do SDK para AWS Lambda funções para publicação de métricas baseadas](metric-pub-impl-emf.md) em EMF. # Publique métricas do SDK para AWS Lambda funções usando o AWS SDK for Java 2.x Como as funções do Lambda normalmente são executadas de milissegundos a minutos, qualquer atraso no envio das métricas, o que acontece com `CloudWatchMetricPublisher`, apresenta o risco de perda de dados. `[EmfMetricLoggingPublisher](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/metrics/publishers/emf/EmfMetricLoggingPublisher.html)`fornece uma abordagem mais adequada ao escrever imediatamente métricas como entradas de registro estruturadas em [CloudWatch Embedded Metric Format (EMF)](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Embedded_Metric_Format.html). `EmfMetricLoggingPublisher`funciona em ambientes de execução que têm integração integrada com o Amazon CloudWatch Logs, como AWS Lambda o Amazon Elastic Container Service. ## Configuração Antes de ativar e usar as métricas usando `EmfMetricLoggingPublisher`, siga as etapas a seguir. ### Etapa 1: adicionar dependência necessária Configure as dependências do seu projeto (por exemplo, no seu arquivo `pom.xml` ou `build.gradle`) para usar a versão `2.30.3` ou posterior do AWS SDK para Java. Inclua o artifactId `emf-metric-logging-publisher` com o número da versão `2.30.3` ou posterior nas dependências do projeto. Por exemplo: ``` software.amazon.awssdk bom [2.30.11](https://central.sonatype.com/artifact/software.amazon.awssdk/bom) pom import software.amazon.awssdk emf-metric-logging-publisher ``` ### Etapa 2: configurar as permissões necessárias Habilite as permissões `logs:PutLogEvents` para a identidade do IAM usada pelo publicador de métricas para permitir que o SDK para Java escreva logs formatados em EMF. ### Etapa 3: configurar logs Para garantir a coleta adequada de métricas, configure o envio dos logs ao console no nível de `INFO` ou inferior (como `DEBUG`). No arquivo `log4j2.xml`: ``` ``` Consulte mais informações sobre como configurar um arquivo `log4j2.xml` no [tópico de logs](logging-slf4j.md) deste guia. ## Configurar e usar `EmfMetricLoggingPublisher` A seguinte classe de função do Lambda primeiro cria e configura uma instância `EmfMetricLoggingPublisher` e depois a usa com um cliente de serviço do Amazon DynamoDB: ``` public class GameIdHandler implements RequestHandler, String> { private final EmfMetricLoggingPublisher emfPublisher; private final DynamoDbClient dynamoDb; public GameIdHandler() { // Build the publisher. this.emfPublisher = EmfMetricLoggingPublisher.builder() .namespace("namespace") .dimensions(CoreMetric.SERVICE_ID, CoreMetric.OPERATION_NAME) .build(); // Add the publisher to the client. this.dynamoDb = DynamoDbClient.builder() .overrideConfiguration(c -> c.addMetricPublisher(emfPublisher)) .region(Region.of(System.getenv("AWS_REGION"))) .build(); } @Override public String handleRequest(Map event, Context context) { Map gameItem = new HashMap<>(); gameItem.put("gameId", AttributeValue.builder().s(event.get("id")).build()); PutItemRequest putItemRequest = PutItemRequest.builder() .tableName("games") .item(gameItem) .build(); dynamoDb.putItem(putItemRequest); return "Request handled"; } } ``` Quando o cliente do DynamoDB executa `putItem` o método, ele publica automaticamente as métricas em CloudWatch um stream de log no formato EMF. ### Exemplo de um evento de logs em EMF Por exemplo, se você enviar o seguinte evento para a função GameHandler Lambda com o registro configurado conforme mostrado anteriormente: ``` { "id": "23456" } ``` Depois que a função processa o evento, você encontra dois eventos de log semelhantes ao exemplo a seguir. O objeto JSON no segundo evento contém os dados de métricas do Java SDK para a operação `PutItem` no DynamoDB. Quando CloudWatch recebe um evento de log no formato EMF, ele analisa automaticamente o JSON estruturado para extrair dados métricos. CloudWatch em seguida, cria métricas correspondentes enquanto armazena a entrada de registro original em CloudWatch Logs. ``` 2025-07-11 15:58:30 [main] INFO org.example.GameIdHandler:39 - Received map: {id=23456} 2025-07-11 15:58:34 [main] INFO software.amazon.awssdk.metrics.publishers.emf.EmfMetricLoggingPublisher:43 - { "_aws": { "Timestamp": 1752249513975, "LogGroupName": "/aws/lambda/GameId", "CloudWatchMetrics": [ { "Namespace": "namespace", "Dimensions": [ [ "OperationName", "ServiceId" ] ], "Metrics": [ { "Name": "AvailableConcurrency" }, { "Name": "PendingConcurrencyAcquires" }, { "Name": "ServiceCallDuration", "Unit": "Milliseconds" }, { "Name": "EndpointResolveDuration", "Unit": "Milliseconds" }, { "Name": "MaxConcurrency" }, { "Name": "BackoffDelayDuration", "Unit": "Milliseconds" }, { "Name": "MarshallingDuration", "Unit": "Milliseconds" }, { "Name": "LeasedConcurrency" }, { "Name": "SigningDuration", "Unit": "Milliseconds" }, { "Name": "ConcurrencyAcquireDuration", "Unit": "Milliseconds" }, { "Name": "ApiCallSuccessful" }, { "Name": "RetryCount" }, { "Name": "UnmarshallingDuration", "Unit": "Milliseconds" }, { "Name": "ApiCallDuration", "Unit": "Milliseconds" }, { "Name": "CredentialsFetchDuration", "Unit": "Milliseconds" } ] } ] }, "AvailableConcurrency": 0, "PendingConcurrencyAcquires": 0, "OperationName": "PutItem", "ServiceCallDuration": 1339, "EndpointResolveDuration": 81, "MaxConcurrency": 50, "BackoffDelayDuration": 0, "ServiceId": "DynamoDB", "MarshallingDuration": 181, "LeasedConcurrency": 1, "SigningDuration": 184, "ConcurrencyAcquireDuration": 83, "ApiCallSuccessful": 1, "RetryCount": 0, "UnmarshallingDuration": 85, "ApiCallDuration": 1880, "CredentialsFetchDuration": 138 } ``` A [documentação da API](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/metrics/publishers/emf/EmfMetricLoggingPublisher.Builder.html) referente a `EmfMetricLoggingPublisher.Builder` mostra as opções de configuração que você pode usar. Você também pode ativar o registro de métricas EMF para uma única solicitação, conforme [mostrado no CloudWatchMetricPublisher](metric-pub-impl-cwmp.md#enable-metrics-for-a-specific-request). **Próximas etapas:** Para aplicativos de longa execução, consulte [Publicar métricas do SDK de aplicativos de longa execução](metric-pub-impl-cwmp.md) para publicação de métricas CloudWatch baseadas. # Envie métricas do SDK para o console usando o AWS SDK for Java 2.x A implementação `[LoggingMetricPublisher](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/metrics/LoggingMetricPublisher.html)` gera métricas diretamente no console ou nos arquivos de log da aplicação. Essa abordagem é ideal para desenvolvimento, depuração e compreensão de quais métricas o SDK coleta sem exigir serviços externos, como a Amazon. CloudWatch Ao contrário de `CloudWatchMetricPublisher` e `EmfMetricLoggingPublisher`, `LoggingMetricPublisher` fornece uma saída imediata sem atrasos ou dependências externas. Isso o torna perfeito para cenários de desenvolvimento local e solução de problemas. ## Quando usar LoggingMetricPublisher Use `LoggingMetricPublisher` quando precisar: + Depurar a coleta de métricas durante o desenvolvimento + Entender quais métricas o SDK coleta para as operações + Solucionar problemas de desempenho localmente + Testar a coleta de métricas sem dependências de serviços externos + Visualizar as métricas imediatamente em seu console ou em arquivos de log **nota** `LoggingMetricPublisher` não é recomendado para ambientes de produção em que você precisa de recursos persistentes de armazenamento e análise de métricas. ## Configurar logs do console para métricas Para ver a saída `LoggingMetricPublisher`, configure o framework de logs para exibir mensagens de nível `INFO`. A configuração `log4j2.xml` a seguir garante que as métricas apareçam no console: ``` ``` Essa configuração orienta o SDK a gerar métricas para o console no nível `INFO`. A configuração do logger `LoggingMetricPublisher` garante que a saída métrica apareça mesmo se o logger raiz usar um nível mais alto, como `WARN` ou `ERROR`. ## Habilitar métricas de console para um cliente de serviço O exemplo a seguir mostra como criar um `LoggingMetricPublisher` e usá-lo com um cliente do Amazon Simple Storage Service: ``` import software.amazon.awssdk.metrics.LoggingMetricPublisher; import software.amazon.awssdk.metrics.MetricPublisher; import software.amazon.awssdk.regions.Region; import software.amazon.awssdk.services.s3.S3Client; // Create a LoggingMetricPublisher with default settings. MetricPublisher metricPublisher = LoggingMetricPublisher.create(); // Add the publisher to your service client. S3Client s3Client = S3Client.builder() .region(Region.US_EAST_1) .overrideConfiguration(config -> config.addMetricPublisher(metricPublisher)) .build(); // Make requests - metrics will appear in your console. s3Client.listBuckets(); // Clean up resources. metricPublisher.close(); s3Client.close(); ``` ## Escolher o formato de saída da métrica O `LoggingMetricPublisher` permite dois formatos de saída: + **Formato PLAIN (padrão):** gera métricas como entradas compactas de linha única + **Formato PRETTY:** gera métricas em um formato de várias linhas, legível para humanos O exemplo a seguir mostra como usar o formato PRETTY para facilitar a leitura durante o desenvolvimento: ``` import org.slf4j.event.Level; import software.amazon.awssdk.metrics.LoggingMetricPublisher; // Create a LoggingMetricPublisher with PRETTY format. MetricPublisher prettyMetricPublisher = LoggingMetricPublisher.create( Level.INFO, LoggingMetricPublisher.Format.PRETTY ); // Use with your service client. S3Client s3Client = S3Client.builder() .region(Region.US_EAST_1) .overrideConfiguration(config -> config.addMetricPublisher(prettyMetricPublisher)) .build(); ``` ## Exemplo completo O exemplo a seguir demonstra o uso de `LoggingMetricPublisher` de duas maneiras: + No nível de cliente de serviço + Para uma única solicitação ``` import org.slf4j.Logger; import org.slf4j.LoggerFactory; import org.slf4j.event.Level; import software.amazon.awssdk.metrics.LoggingMetricPublisher; import software.amazon.awssdk.metrics.MetricPublisher; import software.amazon.awssdk.regions.Region; import software.amazon.awssdk.services.s3.S3Client; import software.amazon.awssdk.services.s3.model.ListBucketsRequest; import software.amazon.awssdk.services.s3.model.ListBucketsResponse; /** * Demonstrates how to use LoggingMetricPublisher with AWS S3 SDK for Java 2.x. *

* This demo focuses on the S3 listBuckets operation to show how metrics are collected * and logged to the console for development and debugging purposes. *

* LoggingMetricPublisher is ideal for: * - Development and debugging * - Console output for troubleshooting * - Understanding what metrics are being collected * - Testing metric collection without external dependencies */ public class S3LoggingMetricPublisherDemo { private static final Logger logger = LoggerFactory.getLogger(S3LoggingMetricPublisherDemo.class); public static void main(String[] args) { S3LoggingMetricPublisherDemo demo = new S3LoggingMetricPublisherDemo(); demo.demonstrateUsage(); } /** * Demonstrates basic usage with S3Client and metrics enabled at the client level. */ private void demonstrateUsage() { // Create a LoggingMetricPublisher with default settings. The SDK logs metrics as text in a single line. // The default settings are equivalent to using `LoggingMetricPublisher.Format.PLAIN`. MetricPublisher metricPublisher = LoggingMetricPublisher.create(); // Create an S3 client with metrics enabled. try (S3Client s3Client = S3Client.builder() .region(Region.US_EAST_1) .overrideConfiguration(config -> config.addMetricPublisher(metricPublisher)) .build()) { // Make the listBuckets request - metrics will be logged to console. ListBucketsResponse response = s3Client.listBuckets(ListBucketsRequest.builder().build()); // The next block shows the using a different LoggingMetricPublisher with a `PRETTY` format. // Since the metric publisher is added to the request using the `overrideConfiguration`, this formatting // applies only to the one request. try { s3Client.listBuckets(ListBucketsRequest.builder() .overrideConfiguration(config -> config .addMetricPublisher(LoggingMetricPublisher.create( Level.INFO, LoggingMetricPublisher.Format.PRETTY))) .build()); } catch (Exception e) { logger.info("Request failed with metrics logged: {}", e.getMessage()); } logger.info("Found {} buckets in your AWS account.", response.buckets().size()); } catch (Exception e) { logger.error("Error during S3 operation: {}", e.getMessage()); logger.info("Note: This is expected if AWS credentials are not configured."); } // Close the metric publisher to flush any remaining metrics. metricPublisher.close(); } } ``` O código registra o seguinte no console: ``` INFO LoggingMetricPublisher - Metrics published: MetricCollection(name=ApiCall, metrics=[MetricRecord(metric=MarshallingDuration, value=PT0.005409792S), MetricRecord(metric=RetryCount, value=0), MetricRecord(metric=ApiCallSuccessful, value=true), MetricRecord(metric=OperationName, value=ListBuckets), MetricRecord(metric=EndpointResolveDuration, value=PT0.000068S), MetricRecord(metric=ApiCallDuration, value=PT0.163802958S), MetricRecord(metric=CredentialsFetchDuration, value=PT0.145686542S), MetricRecord(metric=ServiceEndpoint, value=https://s3.amazonaws.com), MetricRecord(metric=ServiceId, value=S3)], children=[MetricCollection(name=ApiCallAttempt, metrics=[MetricRecord(metric=TimeToFirstByte, value=PT0.138816S), MetricRecord(metric=SigningDuration, value=PT0.007803459S), MetricRecord(metric=ReadThroughput, value=165153.96002660287), MetricRecord(metric=ServiceCallDuration, value=PT0.138816S), MetricRecord(metric=AwsExtendedRequestId, value=e13Swj3uwn0qP1Oz+m7II5OGq7jf8xxT8H18iDfRBCQmDg+gU4ek91Xrsl8XxRLROlIzCAPQtsQF0DAAWOb8ntuKCzX2AJdj), MetricRecord(metric=HttpStatusCode, value=200), MetricRecord(metric=BackoffDelayDuration, value=PT0S), MetricRecord(metric=TimeToLastByte, value=PT0.148915667S), MetricRecord(metric=AwsRequestId, value=78AW9BM7SWR6YMGB)], children=[MetricCollection(name=HttpClient, metrics=[MetricRecord(metric=MaxConcurrency, value=50), MetricRecord(metric=AvailableConcurrency, value=0), MetricRecord(metric=LeasedConcurrency, value=1), MetricRecord(metric=ConcurrencyAcquireDuration, value=PT0.002623S), MetricRecord(metric=PendingConcurrencyAcquires, value=0), MetricRecord(metric=HttpClientName, value=Apache)], children=[])])]) INFO LoggingMetricPublisher - [4e6f2bb5] ApiCall INFO LoggingMetricPublisher - [4e6f2bb5] ┌──────────────────────────────────────────┐ INFO LoggingMetricPublisher - [4e6f2bb5] │ MarshallingDuration=PT0.000063S │ INFO LoggingMetricPublisher - [4e6f2bb5] │ RetryCount=0 │ INFO LoggingMetricPublisher - [4e6f2bb5] │ ApiCallSuccessful=true │ INFO LoggingMetricPublisher - [4e6f2bb5] │ OperationName=ListBuckets │ INFO LoggingMetricPublisher - [4e6f2bb5] │ EndpointResolveDuration=PT0.000024375S │ INFO LoggingMetricPublisher - [4e6f2bb5] │ ApiCallDuration=PT0.018463083S │ INFO LoggingMetricPublisher - [4e6f2bb5] │ CredentialsFetchDuration=PT0.000022334S │ INFO LoggingMetricPublisher - [4e6f2bb5] │ ServiceEndpoint=https://s3.amazonaws.com │ INFO LoggingMetricPublisher - [4e6f2bb5] │ ServiceId=S3 │ INFO LoggingMetricPublisher - [4e6f2bb5] └──────────────────────────────────────────┘ INFO LoggingMetricPublisher - [4e6f2bb5] ApiCallAttempt INFO LoggingMetricPublisher - [4e6f2bb5] ┌───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ INFO LoggingMetricPublisher - [4e6f2bb5] │ TimeToFirstByte=PT0.0165575S │ INFO LoggingMetricPublisher - [4e6f2bb5] │ SigningDuration=PT0.000301125S │ INFO LoggingMetricPublisher - [4e6f2bb5] │ ReadThroughput=1195591.792850103 │ INFO LoggingMetricPublisher - [4e6f2bb5] │ ServiceCallDuration=PT0.0165575S │ INFO LoggingMetricPublisher - [4e6f2bb5] │ AwsExtendedRequestId=3QI1eenRuokdszWqZBmBMDUmko6FlSmHkM+CUMNMeLor7gJml4D4lv6QXUZ1zWoTgG+tHbr6yo2vHdz4h1P8PDovvtMFRCeB │ INFO LoggingMetricPublisher - [4e6f2bb5] │ HttpStatusCode=200 │ INFO LoggingMetricPublisher - [4e6f2bb5] │ BackoffDelayDuration=PT0S │ INFO LoggingMetricPublisher - [4e6f2bb5] │ TimeToLastByte=PT0.017952625S │ INFO LoggingMetricPublisher - [4e6f2bb5] │ AwsRequestId=78AVFAF795AAWAXH │ INFO LoggingMetricPublisher - [4e6f2bb5] └───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ INFO LoggingMetricPublisher - [4e6f2bb5] HttpClient INFO LoggingMetricPublisher - [4e6f2bb5] ┌───────────────────────────────────────┐ INFO LoggingMetricPublisher - [4e6f2bb5] │ MaxConcurrency=50 │ INFO LoggingMetricPublisher - [4e6f2bb5] │ AvailableConcurrency=0 │ INFO LoggingMetricPublisher - [4e6f2bb5] │ LeasedConcurrency=1 │ INFO LoggingMetricPublisher - [4e6f2bb5] │ ConcurrencyAcquireDuration=PT0.00004S │ INFO LoggingMetricPublisher - [4e6f2bb5] │ PendingConcurrencyAcquires=0 │ INFO LoggingMetricPublisher - [4e6f2bb5] │ HttpClientName=Apache │ INFO LoggingMetricPublisher - [4e6f2bb5] └───────────────────────────────────────┘ INFO S3LoggingMetricPublisherDemo - Found 6 buckets in your AWS account. ``` ### Artefatos adicionais para o exemplo Arquivo `pom.xml` do Maven ``` 4.0.0 com.example s3-logging-metric-publisher-demo 1.0.0 jar AWS S3 LoggingMetricPublisher Demo Demonstrates how to use LoggingMetricPublisher with AWS S3 SDK for Java 2.x 17 17 UTF-8 2.31.66 2.24.3 software.amazon.awssdk bom ${aws.java.sdk.version} pom import org.apache.logging.log4j log4j-bom ${log4j.version} pom import software.amazon.awssdk s3 org.apache.logging.log4j log4j-slf4j2-impl org.apache.logging.log4j log4j-core org.apache.maven.plugins maven-compiler-plugin 3.13.0 17 17 ``` Arquivo de configuração `Log4j2.xml` ``` ``` As métricas incluem informações de tempo, detalhes do serviço, nomes das operações e códigos de status HTTP que ajudam você a entender os padrões de uso da AWS API do seu aplicativo. ## Próximas etapas Depois de usar `LoggingMetricPublisher` para desenvolvimento e depuração, considere estas opções para ambientes de produção: + Para aplicativos de longa duração, use [CloudWatchMetricPublisher](metric-pub-impl-cwmp.md)para enviar métricas à Amazon CloudWatch para análise e alertas + Para AWS Lambda funções, use [EmfMetricLoggingPublisher](metric-pub-impl-emf.md)para publicar métricas no formato métrico CloudWatch incorporado # AWS SDK for Java 2.x: referência abrangente de métricas Com o AWS SDK for Java 2.x, você pode coletar métricas dos clientes de serviço em seu aplicativo e depois publicar (gerar) essas métricas [na Amazon CloudWatch](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/WhatIsCloudWatch.html). Essas tabelas listam as métricas que é possível coletar e os requisitos de uso do cliente HTTP. Para obter mais informações sobre como habilitar e configurar métricas para o SDK, consulte [Como habilitar métricas do SDK](metrics.md). ## Métricas coletadas com cada solicitação | Nome da métrica | Description | Tipo | | --- | --- | --- | | ApiCallDuration | A duração da chamada de API. Isso inclui todas as tentativas de chamada feitas. | Duração\$1 | | ApiCallSuccessful | Verdadeiro se a chamada de API foi bem-sucedida, falso se não foi. | Booleano | | CredentialsFetchDuration | O tempo necessário para obter as credenciais de assinatura para a chamada de API. | Duração\$1 | | EndpointResolveDuration | A duração do tempo para resolver o endpoint usado na chamada de API. | Duração\$1 | | MarshallingDuration | O tempo necessário para converter a solicitação de SDK em uma solicitação HTTP. | Duração\$1 | | OperationName | O nome da operação de serviço que está sendo invocada. | String | | RetryCount | O número de novas tentativas que o SDK realizou na execução da solicitação. 0 indica que a solicitação funcionou na primeira vez e que nenhuma tentativa foi feita. Consulte mais informações sobre como configurar a retenção de dados em [Estratégias de novas tentativas](retry-strategy.md#retry-strategies). | Inteiro | | ServiceId | O ID exclusivo para o serviço. | String | | ServiceEndpoint | O endpoint para o serviço. | URI | | TokenFetchDuration | O tempo necessário para obter as credenciais de assinatura para a chamada de API. | Duração\$1 | \$1[java.time.Duration](https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/time/Duration.html). ## Métricas coletadas para cada tentativa de solicitação Cada chamada de API pode exigir várias tentativas antes de receber uma resposta. Essas métricas são coletadas para cada tentativa. ### Métricas principais | Nome da métrica | Description | Tipo | | --- | --- | --- | | AwsExtendedRequestId | O ID da solicitação estendida da solicitação de serviço. | String | | AwsRequestId | O ID da solicitação de serviço. | String | | BackoffDelayDuration | O tempo que o SDK esperou antes dessa tentativa de chamada de API. O valor é baseado no conjunto `[https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/retries/api/BackoffStrategy.html](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/retries/api/BackoffStrategy.html)` do cliente. Veja mais informações na seção [Estratégias de novas tentativas](retry-strategy.md#retry-strategies) a seguir deste guia. | Duração\$1 | | ErrorType | O tipo de erro que ocorreu em uma tentativa de chamada. Os valores possíveis são: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/sdk-for-java/latest/developer-guide/metrics-list.html) | String | | ReadThroughput | O throughput de leitura do cliente, definido como `NumberOfResponseBytesRead / (TTLB - TTFB)`. Esse valor está em bytes por segundo. Observe que essa métrica mede apenas os bytes lidos de dentro do `ResponseTransformer` ou `AsyncResponseTransformer`. Os dados lidos fora do transformador, por exemplo, quando o fluxo de resposta é retornado como resultado do transformador, não são incluídos no cálculo. | Duplo | | WriteThroughput | A taxa de transferência de gravação do cliente, definida como`RequestBytesWritten / (LastByteWrittenTime - FirstByteWrittenTime)`. Esse valor está em bytes por segundo. Essa métrica mede a taxa na qual o SDK fornece o corpo da solicitação ao cliente HTTP. Isso exclui a configuração da conexão, o tempo de handshake TLS e o tempo de processamento do servidor. Essa métrica só é relatada para solicitações que têm um corpo de streaming, como o S3 PutObject. Observe que essa métrica não leva em conta o buffer na camada do cliente HTTP. A taxa real de transmissão da rede pode ser menor se o cliente HTTP armazenar dados em buffer antes do envio. Essa métrica representa um limite superior da taxa de transferência da rede. | Duplo | | ServiceCallDuration | O tempo necessário para se conectar ao serviço (ou adquirir uma conexão do pool de conexões), enviar a solicitação serializada e receber a resposta inicial (por exemplo, código de status e cabeçalhos HTTP). Isso NÃO inclui o tempo para ler toda a resposta do serviço. | Duração\$1 | | SigningDuration | O tempo necessário para assinar a solicitação HTTP. | Duração\$1 | | TimeToFirstByte | O tempo necessário do envio da solicitação HTTP (incluindo a aquisição de uma conexão) até o serviço e o recebimento do primeiro byte dos cabeçalhos na resposta. | Duração\$1 | | TimeToLastByte | O tempo necessário do envio da solicitação HTTP (incluindo a aquisição de uma conexão) até o serviço e o recebimento do último byte da resposta. Observe que, para APIs essas respostas de streaming de retorno, essa métrica abrange o tempo até a `AsyncResponseTransformer` conclusão do `ResponseTransformer` ou. | Duração\$1 | | UnmarshallingDuration | O tempo necessário para desvincular uma resposta HTTP de uma resposta do SDK. Observação: para operações de streaming, isso não inclui o tempo de leitura da carga útil da resposta. | Duração\$1 | \$1[java.time.Duration](https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/time/Duration.html). ### Métricas HTTP | Nome da métrica | Description | Tipo | Um cliente HTTP é necessário\$1 | | --- | --- | --- | --- | | AvailableConcurrency | O número de solicitações simultâneas adicionais que o cliente HTTP suporta sem estabelecer novas conexões com o servidor de destino. Para operações HTTP/1, isso é igual ao número de conexões TCP ociosas estabelecidas com o serviço. Para operações HTTP/2, isso é igual ao número de fluxos ociosos. Observação: esse valor varia de acordo com a implementação do cliente HTTP: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/sdk-for-java/latest/developer-guide/metrics-list.html) O valor tem como escopo uma instância individual do cliente HTTP e exclui a simultaneidade de outros clientes HTTP na mesma JVM. | Inteiro | Apache, Netty, CRT | | ConcurrencyAcquireDuration | O tempo necessário para adquirir um canal do grupo de conexões. Para operações HTTP/1, um canal é igual a uma conexão TCP. Para operações HTTP/2, um canal é igual a um canal de fluxo HTTP/2. A aquisição de um novo canal pode incluir tempo para: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/sdk-for-java/latest/developer-guide/metrics-list.html) | Duração\$1 | Apache, Netty, CRT | | HttpClientName | O nome do HTTP usado para a solicitação. | String | Apache, Netty, CRT | | HttpStatusCode | O código de status da resposta HTTP. | Inteiro | Any | | LeasedConcurrency | O número de solicitações que estão sendo executadas atualmente pelo cliente HTTP. Para operações HTTP/1, isso é igual ao número de conexões TCP ativas estabelecidas com o serviço (excluindo conexões ociosas). Para operações HTTP/2, isso é igual ao número de fluxos HTTP ativos com o serviço (excluindo a capacidade de fluxo ocioso). Observação: esse valor varia de acordo com a implementação do cliente HTTP: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/sdk-for-java/latest/developer-guide/metrics-list.html) O valor tem como escopo uma instância individual do cliente HTTP e exclui a simultaneidade de outros clientes HTTP na mesma JVM. | Inteiro | Apache, Netty, CRT | | LocalStreamWindowSize | O tamanho da janela HTTP/2 local em bytes para o fluxo que executa essa solicitação. | Inteiro | Netty | | MaxConcurrency | O número máximo de solicitações simultâneas que o cliente HTTP suporta. Para operações HTTP/1, isso é igual ao número máximo de conexões TCP que o cliente HTTP pode agrupar. Para operações HTTP/2, isso é igual ao número máximo de fluxos que o cliente HTTP pode agrupar. Observação: esse valor varia de acordo com a implementação do cliente HTTP: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/sdk-for-java/latest/developer-guide/metrics-list.html) O valor tem como escopo uma instância individual do cliente HTTP e exclui a simultaneidade de outros clientes HTTP na mesma JVM. | Inteiro | Apache, Netty, CRT | | PendingConcurrencyAcquires | O número de solicitações que aguardam a simultaneidade do cliente HTTP. Para operações HTTP/1, isso é igual ao número de solicitações que aguardam o estabelecimento ou o retorno de uma conexão TCP do pool de conexões. Para operações HTTP/2, isso é igual ao número de solicitações que aguardam um novo fluxo (e, possivelmente, uma nova conexão HTTP/2) do grupo de conexões. Observação: esse valor varia de acordo com a implementação do cliente HTTP: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/sdk-for-java/latest/developer-guide/metrics-list.html) O valor tem como escopo uma instância individual do cliente HTTP e exclui a simultaneidade de outros clientes HTTP na mesma JVM. | Inteiro | Apache, Netty, CRT | | RemoteStreamWindowSize | O tamanho da janela HTTP/2 remota em bytes para o fluxo que executa essa solicitação. | Inteiro | Netty | \$1[java.time.Duration](https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/time/Duration.html). Os termos usados na coluna significam: + Apache: o cliente HTTP baseado no Apache (`[ApacheHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/apache/ApacheHttpClient.html)`) + Netty: o cliente HTTP baseado em Netty (`[NettyNioAsyncHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/nio/netty/NettyNioAsyncHttpClient.html)`) + CRT: o cliente HTTP AWS baseado em CRT () `[AwsCrtAsyncHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/crt/AwsCrtAsyncHttpClient.html)` + Qualquer: a coleta de dados métricos não depende do cliente HTTP; isso inclui o cliente HTTP URLConnection baseado (`[UrlConnectionHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/urlconnection/UrlConnectionHttpClient.html)`)