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

# Alterações na publicação de métricas do SDK da versão 1 para a versão 2
<a name="migration-metrics"></a>

Este tópico detalha as mudanças na publicação de métricas do SDK do lado do cliente da versão 1.x (v1) para a versão 2.x (v2) do. AWS SDK para Java

## High-level mudanças
<a name="migration-metrics-high-level"></a>

### Mudanças na arquitetura
<a name="migration-metrics-architecture"></a>

Na v1, a coleta de métricas é uma JVM-wide configuração global que você ativa com uma propriedade do sistema. O SDK publica automaticamente todas as métricas coletadas em. CloudWatch Há apenas um destino de métricas.

Na v2, a coleta de métricas usa uma [MetricPublisher](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/metrics/MetricPublisher.html)interface conectável que você anexa a clientes ou solicitações de serviços individuais. O SDK fornece três implementações:
+ **[CloudWatchMetricPublisher](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/metrics/publishers/cloudwatch/CloudWatchMetricPublisher.html)**: agrega e carrega periodicamente métricas para. CloudWatch Mais adequado para aplicativos de longa duração.
+ **[EmfMetricLoggingPublisher](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/metrics/publishers/emf/EmfMetricLoggingPublisher.html)**: grava métricas como entradas de registro estruturadas no CloudWatch Embedded Metric Format (EMF). Mais adequado para funções Lambda e outros ambientes de curta duração.
+ **[LoggingMetricPublisher](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/metrics/LoggingMetricPublisher.html)**: envia métricas para o console por meio do registro SLF4J. Mais adequado para desenvolvimento e depuração locais.

### Mudanças no escopo
<a name="migration-metrics-scope"></a>

Na v1, habilitar métricas publica dados para todos os clientes de AWS serviço na JVM. Na v2, você controla as métricas no nível do cliente de serviço ou no nível da solicitação individual.

### Alterações no tipo de métrica
<a name="migration-metrics-types"></a>

A v1 coleta três categorias de métricas: métricas de AWS solicitação, métricas de AWS serviço e métricas de máquina (memória de pilha, contagem de threads, descritores de arquivos abertos).

A v2 se concentra nas métricas de solicitação e resposta do SDK, como duração da chamada de API, duração do empacotamento, duração da assinatura e contagem de novas tentativas. A v2 não coleta métricas da máquina, como memória de pilha, contagem de threads e descritores de arquivos abertos. Para continuar coletando métricas da JVM CloudWatch, você pode usar a coleção de métricas [CloudWatch Agent with JMX](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Agent-JMX-metrics.html).

## Mudanças nas dependências
<a name="migration-metrics-deps"></a>

A tabela a seguir mostra as mudanças na dependência e no nome do pacote do Maven entre v1 e v2.



| Alteração | v1 |  v2 da  | 
| --- | --- | --- | 
| Dependências do Maven |  <pre><dependencyManagement><br />    <dependencies><br />        <dependency><br />            <groupId>com.amazonaws</groupId><br />            <artifactId>aws-java-sdk-bom</artifactId><br />            <version>{{1.12.x1}}</version><br />            <type>pom</type><br />            <scope>import</scope><br />        </dependency><br />    </dependencies><br /></dependencyManagement><br /><dependencies><br />    <dependency><br />        <groupId>com.amazonaws</groupId><br />        <artifactId>aws-java-sdk-cloudwatchmetrics</artifactId><br />    </dependency><br /></dependencies></pre>  |  <pre><dependencyManagement><br />    <dependencies><br />        <dependency><br />            <groupId>software.amazon.awssdk</groupId><br />            <artifactId>bom</artifactId><br />            <version>{{2.x.x2}}</version><br />            <type>pom</type><br />            <scope>import</scope><br />        </dependency><br />    </dependencies><br /></dependencyManagement><br /><dependencies><br />    <dependency><br />        <groupId>software.amazon.awssdk</groupId><br />        <artifactId>cloudwatch-metric-publisher</artifactId><br />    </dependency><br /></dependencies></pre>  | 
| Nome do pacote | com.amazonaws.metrics | software.amazon.awssdk.metrics | 

1 [Versão mais recente](https://central.sonatype.com/artifact/com.amazonaws/aws-java-sdk-bom). 2 [Versão mais recente](https://central.sonatype.com/artifact/software.amazon.awssdk/bom).

O artefato v2 depende do caso de uso, conforme mostrado na tabela a seguir.



| Caso de uso | artifactId da v2 | Versão mínima do SDK | 
| --- | --- | --- | 
| Long-running aplicações | cloudwatch-metric-publisher | 2.14.0 | 
| funções do Lambda | emf-metric-logging-publisher | 2.30.3 | 
| Desenvolvimento e depuração | Nenhuma dependência adicional é necessária (LoggingMetricPublisherestá no núcleo do SDK) | 2.14.0 | 

## Alterações de API
<a name="migration-metrics-api"></a>

### Habilitar as métricas do
<a name="migration-metrics-enabling"></a>

A tabela a seguir compara como habilitar métricas na v1 e na v2 para diferentes casos de uso.



| Caso de uso | v1 |  v2 da  | 
| --- | --- | --- | 
| Habilite métricas globalmente | Adicione uma propriedade do sistema JVM:<pre>-Dcom.amazonaws.sdk.enableDefaultMetrics=credentialFile=/path/aws.properties</pre> | Sem compatibilidade. Anexe um MetricPublisher a cada cliente de serviço. | 
| Habilite métricas no Amazon EC2 sem arquivo de credenciais |  <pre>-Dcom.amazonaws.sdk.enableDefaultMetrics</pre>  | Não aplicável. A v2 usa sua resolução de credencial padrão. | 
| Habilitar métricas para um cliente de serviço | Sem compatibilidade. As métricas são globais ou desativadas. |  <pre>MetricPublisher metricsPub =<br />    CloudWatchMetricPublisher.create();<br /><br />DynamoDbClient ddb = DynamoDbClient.builder()<br />    .overrideConfiguration(c -> c<br />        .addMetricPublisher(metricsPub))<br />    .build();<br /><br />// ... use the client ...<br /><br />metricsPub.close();<br />ddb.close();</pre>  | 
| Habilite métricas para uma única solicitação | Sem compatibilidade. |  <pre>ddb.listTables(ListTablesRequest.builder()<br />    .overrideConfiguration(c -> c<br />        .addMetricPublisher(metricsPub))<br />    .build());</pre>  | 

### Configurando o destino CloudWatch
<a name="migration-metrics-cw-config"></a>

A tabela a seguir mostra como configurar o CloudWatch destino na v1 em comparação com a v2.



| Caso de uso | v1 |  v2 da  | 
| --- | --- | --- | 
| Definir CloudWatch região | Atributo de propriedade do sistema:<pre>-Dcom.amazonaws.sdk.enableDefaultMetrics=cloudwatchRegion={{us-west-2}}</pre> |  <pre>CloudWatchMetricPublisher.builder()<br />    .cloudWatchClient(<br />        CloudWatchAsyncClient.builder()<br />            .region(Region.US_WEST_2)<br />            .build())<br />    .build();</pre>  | 
| Definir frequência de carregamento | Não configurável. Carrega aproximadamente uma vez por minuto. |  <pre>CloudWatchMetricPublisher.builder()<br />    .uploadFrequency(Duration.ofMinutes(5))<br />    .build();</pre>  | 
| Definir CloudWatch namespace | Fixado emAWSSDK/Java. | O padrão é `AwsSdk/JavaSdk2`. Configurável via:<pre>CloudWatchMetricPublisher.builder()<br />    .namespace("MyApp/SDK")<br />    .build();</pre> Se você tiver CloudWatch painéis ou alarmes existentes referenciando o namespace `AWSSDK/Java` v1, defina para preservar a continuidade. `.namespace("AWSSDK/Java")`  | 
| Excluir métricas da máquina | Atributo de propriedade do sistema:<pre>-Dcom.amazonaws.sdk.enableDefaultMetrics=excludeMachineMetrics</pre> | Não aplicável. A v2 não coleta métricas da máquina. | 

### Métricas para funções Lambda
<a name="migration-metrics-lambda"></a>

A v1 não tem uma solução de Lambda-specific métricas. Na v2, use `EmfMetricLoggingPublisher` which grava métricas como entradas de registro estruturadas no CloudWatch Embedded Metric Format (EMF):

```
// v2 - Lambda-optimized metrics publishing
EmfMetricLoggingPublisher emfPublisher = EmfMetricLoggingPublisher.builder()
        .namespace("MyApp")
        .dimensions(CoreMetric.SERVICE_ID, CoreMetric.OPERATION_NAME)
        .build();

DynamoDbClient dynamoDb = DynamoDbClient.builder()
        .overrideConfiguration(c -> c.addMetricPublisher(emfPublisher))
        .build();
```

**nota**  
Em ambientes Lambda, o `logGroupName` é detectado automaticamente a partir da variável de ambiente. `AWS_LAMBDA_LOG_GROUP_NAME` Em ambientes não Lambda, como Amazon ECS ou Amazon EC2, você deve definir `logGroupName` explicitamente o construtor.

### Métricas para desenvolvimento e depuração
<a name="migration-metrics-debugging"></a>

A v1 não tem uma saída de métricas baseada em console. Na v2, use`LoggingMetricPublisher`:

```
// v2 - Console output for debugging
MetricPublisher loggingPublisher = LoggingMetricPublisher.create();

S3Client s3 = S3Client.builder()
        .overrideConfiguration(c -> c.addMetricPublisher(loggingPublisher))
        .build();
```

### Gerenciamento de ciclo de vida
<a name="migration-metrics-lifecycle"></a>

Na v1, a coleta de métricas é executada durante toda a vida útil da JVM depois que a propriedade do sistema é definida. Na v2, você deve gerenciar o ciclo de vida do: `MetricPublisher`

```
// v2 - Close the publisher when no longer needed
MetricPublisher metricsPub = CloudWatchMetricPublisher.create();
DynamoDbClient ddb = DynamoDbClient.builder()
        .overrideConfiguration(c -> c.addMetricPublisher(metricsPub))
        .build();

// ... use the client ...

metricsPub.close(); // Flushes remaining metrics to CloudWatch
ddb.close();
```

**Importante**  
Chame `close` a `MetricPublisher` instância quando ela não for mais necessária. Não fazer isso pode resultar em vazamentos de thread ou descritor de arquivo.

### Permissões obrigatórias
<a name="migration-metrics-permissions"></a>

A tabela a seguir lista as permissões do IAM necessárias para cada editor de métricas.



| Tipo de permissão | v1 | versão 2 () CloudWatchMetricPublisher | versão 2 () EmfMetricLoggingPublisher | 
| --- | --- | --- | --- | 
| Permissão do IAM | cloudwatch:PutMetricData | cloudwatch:PutMetricData | logs:PutLogEvents | 

## Limitações
<a name="migration-metrics-limitations"></a>

Atualmente, o [cliente AWS CRT-based S3](crt-based-s3-client.md) não oferece suporte à coleta de métricas do SDK na v2.

## Recursos adicionais do
<a name="migration-metrics-resources"></a>
+ [documentação de métricas v1](https://docs.aws.amazon.com/sdk-for-java/v1/developer-guide/generating-sdk-metrics.html)
+ [Publique métricas do SDK a partir do AWS SDK for Java 2.x](metrics.md)
+ [Publique métricas do SDK a partir de aplicativos de longa execução](metric-pub-impl-cwmp.md)
+ [Publique métricas do SDK para funções AWS Lambda](metric-pub-impl-emf.md)
+ [Envie métricas do SDK para o console](metric-pub-impl-logging.md)
+ [Referência abrangente de métricas](metrics-list.md)