Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà. # Pubblica le metriche SDK da AWS SDK for Java 2.x Con il AWS SDK for Java 2.x puoi raccogliere metriche sui client di servizio e sulle richieste nella tua applicazione, analizzare l'output in Amazon CloudWatch Logs e quindi agire di conseguenza. Per impostazione predefinita, la raccolta delle metriche è disabilitata nell'SDK. Questo argomento ti aiuta ad abilitarlo e configurarlo. ## Guida introduttiva alle metriche SDK Per abilitare la raccolta delle metriche nella tua applicazione, scegli l'implementazione appropriata dell'`[MetricPublisher](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/metrics/MetricPublisher.html)`interfaccia in base al tuo caso d'uso e segui le istruzioni di configurazione dettagliate: **Per applicazioni a lunga durata:** + Utilizzare `[CloudWatchMetricPublisher](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/metrics/publishers/cloudwatch/CloudWatchMetricPublisher.html)` + Per istruzioni di configurazione complete, esempi di codice e opzioni di configurazione, consulta [Pubblicare metriche SDK da applicazioni a esecuzione prolungata](metric-pub-impl-cwmp.md). **Per le funzioni: AWS Lambda ** + Utilizzare `[EmfMetricLoggingPublisher](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/metrics/publishers/emf/EmfMetricLoggingPublisher.html)` + Consulta [Publish SDK metrics for AWS Lambda functions per](metric-pub-impl-emf.md) istruzioni di configurazione complete, dipendenze e configurazioni specifiche per Lambda. **Per la risoluzione dei problemi e l'output della console:** + Utilizzare `[LoggingMetricPublisher](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/metrics/LoggingMetricPublisher.html)` + Consulta [Output SDK Metrics to console per lo sviluppo e il debug](metric-pub-impl-logging.md) per istruzioni di configurazione, opzioni di formattazione ed esempi per lo sviluppo locale e la risoluzione dei problemi. ## Anteprima rapida dell'implementazione Ecco come si presentano le metriche di abilitazione per ogni caso d'uso: **Applicazioni a lunga durata:** ``` MetricPublisher metricsPub = CloudWatchMetricPublisher.create(); DynamoDbClient ddb = DynamoDbClient.builder() .overrideConfiguration(c -> c.addMetricPublisher(metricsPub)) .build(); ``` **Funzioni Lambda:** ``` EmfMetricLoggingPublisher emfPublisher = EmfMetricLoggingPublisher.builder() .namespace("MyApp") .build(); DynamoDbClient dynamoDb = DynamoDbClient.builder() .overrideConfiguration(c -> c.addMetricPublisher(emfPublisher)) .build(); ``` **Sviluppo e debug:** ``` MetricPublisher loggingPublisher = LoggingMetricPublisher.create(); S3Client s3 = S3Client.builder() .overrideConfiguration(c -> c.addMetricPublisher(loggingPublisher)) .build(); ``` ## Limitazione delle metriche del client S3 basato su CRT AWS Il [client S3 AWS basato su CRT attualmente](crt-based-s3-client.md) non supporta la raccolta di metriche SDK. Il builder per un'istanza client S3 AWS basata su CRT non fornisce metodi per configurare gli editori di [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)metriche. ## Quando sono disponibili le metriche? Le metriche sono generalmente disponibili entro 5-10 minuti dall'emissione da parte dell'SDK for Java. Per informazioni accurate e up-to-date metriche, controlla Cloudwatch almeno 10 minuti dopo aver emesso le metriche delle tue applicazioni Java. ## Quali informazioni vengono raccolte? La raccolta di metriche include quanto segue: + Numero di richieste API, incluso l'esito positivo o negativo + Informazioni Servizi AWS sulla chiamata nelle richieste API, incluse le eccezioni restituite + La durata di varie operazioni come Marshalling, Signing e richieste HTTP + Metriche del client HTTP, come il numero di connessioni aperte, il numero di richieste in sospeso e il nome del client HTTP utilizzato **Nota** Le metriche disponibili variano in base al client HTTP. Per un elenco completo, consulta le [metriche del client di servizio](metrics-list.md). ## Come posso usare queste informazioni? Puoi utilizzare le metriche raccolte dall'SDK per monitorare i client di servizio nella tua applicazione. Puoi esaminare le tendenze generali di utilizzo, identificare anomalie, esaminare le eccezioni restituite dai client di servizio o approfondire per comprendere un problema particolare. Utilizzando Amazon CloudWatch Logs, puoi anche creare allarmi per avvisarti non appena l'applicazione raggiunge una condizione da te definita. [Per ulteriori informazioni, consulta [Using Amazon CloudWatch Logs Metrics](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/working_with_metrics.html) e Using [Amazon CloudWatch Logs Alarms nella Amazon Logs](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/AlarmThatSendsEmail.html) User Guide. CloudWatch ](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/) # Pubblica i parametri SDK di applicazioni a lunga esecuzione utilizzando il AWS SDK for Java 2.x Poiché l'`[CloudWatchMetricPublisher](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/metrics/publishers/cloudwatch/CloudWatchMetricPublisher.html)`implementazione aggrega e carica periodicamente le metriche su Amazon CloudWatch con un certo ritardo, il suo utilizzo è più adatto per applicazioni a lunga durata. Le impostazioni predefinite dell'editore delle metriche hanno lo scopo di ridurre al minimo l'utilizzo e i CloudWatch costi della memoria, fornendo al contempo un'utile quantità di informazioni sui dati metrici. ## Configurazione Prima di poter abilitare e utilizzare le metriche utilizzando`CloudWatchMetricPublisher`, completa i seguenti passaggi. ### Passaggio 1: aggiungere la dipendenza richiesta Configura le dipendenze del progetto (ad esempio, nel tuo `build.gradle` file `pom.xml` o) per utilizzare la versione `2.14.0` o successiva di. AWS SDK per Java Includi l'`cloudwatch-metric-publisher`ArtifactID con il `2.14.0` numero di versione o successivo nelle dipendenze del progetto. Esempio: ``` software.amazon.awssdk bom [2.30.11](https://central.sonatype.com/artifact/software.amazon.awssdk/bom) pom import software.amazon.awssdk cloudwatch-metric-publisher ``` ### Passaggio 2: configura le autorizzazioni richieste Abilita `cloudwatch:PutMetricData` le autorizzazioni per l'identità IAM utilizzata dall'editore delle metriche per consentire all'SDK for Java di scrivere metriche. ## Abilita le metriche per una richiesta specifica La classe seguente mostra come abilitare l'editore di CloudWatch metriche per una richiesta ad Amazon DynamoDB. Utilizza la configurazione predefinita di Metrics Publisher. ``` 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** Assicurati che l'applicazione richiami `close` l'`[MetricPublisher](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/metrics/MetricPublisher.html)`istanza quando il client del servizio non è più in uso. In caso contrario, potrebbero verificarsi fughe di thread o descrittori di file. ## Abilita le metriche di riepilogo per un client di servizio specifico Il seguente frammento di codice mostra come abilitare un editore di CloudWatch metriche con impostazioni predefinite per un client di servizio. ``` MetricPublisher metricsPub = CloudWatchMetricPublisher.create(); DynamoDbClient ddb = DynamoDbClient.builder() .overrideConfiguration(c -> c.addMetricPublisher(metricsPub)) .build(); ``` ## Personalizza un editore di metriche CloudWatch La seguente classe dimostra come impostare una configurazione personalizzata per l'editore delle metriche per uno specifico client di servizio. Le personalizzazioni includono il caricamento di un profilo specifico, la specificazione di una AWS regione in cui l'editore delle metriche invia le richieste e la personalizzazione della frequenza a cui l'editore invia le metriche. 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(); } } ``` Le personalizzazioni mostrate nello snippet precedente hanno i seguenti effetti. + Il `cloudWatchClient` metodo consente di personalizzare il CloudWatch client utilizzato per inviare le metriche. In questo esempio, utilizziamo una regione diversa da quella predefinita di *us-east-1* in cui il client invia le metriche. Utilizziamo anche un profilo con nome diverso, *cloudwatch*, le cui credenziali verranno utilizzate per autenticare le richieste. CloudWatch Tali credenziali devono avere le autorizzazioni per. `cloudwatch:PutMetricData` + Il `uploadFrequency` metodo consente di specificare la frequenza con cui l'editore di metriche carica le metriche. CloudWatch L'impostazione predefinita è una volta al minuto. + Il `maximumCallsPerUpload` metodo limita il numero di chiamate effettuate per ogni caricamento. Il valore predefinito è illimitato. + Per impostazione predefinita, l'SDK for Java 2.x pubblica le metriche nello spazio dei nomi. `AwsSdk/JavaSdk2` È possibile utilizzare il `namespace` metodo per specificare un valore diverso. + Per impostazione predefinita, l'SDK pubblica metriche di riepilogo. Le metriche di riepilogo sono costituite da media, minima, massima, somma e numero di campioni. Specificando una o più metriche SDK nel `detailedMetrics` metodo, l'SDK pubblica dati aggiuntivi per ogni metrica. Questi dati aggiuntivi consentono statistiche percentili come p90 e p99 su cui è possibile eseguire interrogazioni. CloudWatch Le metriche dettagliate sono particolarmente utili per le metriche di latenza come`APICallDuration`, che misura la latenza per le richieste dei end-to-end client SDK. Puoi utilizzare i campi della `[CoreMetric](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/core/metrics/CoreMetric.html)` classe per specificare altre metriche SDK comuni. **Passaggi successivi:** se utilizzi anche le funzioni Lambda, consulta [Pubblicare metriche SDK per le AWS Lambda funzioni per la pubblicazione di metriche basate](metric-pub-impl-emf.md) su EMF. # Pubblica le metriche SDK per le funzioni utilizzando il AWS Lambda AWS SDK for Java 2.x Poiché le funzioni Lambda vengono in genere eseguite da millisecondi a minuti, qualsiasi ritardo nell'invio delle metriche, che si verifica con il, rischia la `CloudWatchMetricPublisher` perdita di dati. `[EmfMetricLoggingPublisher](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/metrics/publishers/emf/EmfMetricLoggingPublisher.html)`fornisce un approccio più adatto scrivendo immediatamente le metriche come voci di registro strutturate in [CloudWatch Embedded](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Embedded_Metric_Format.html) Metric Format (EMF). `EmfMetricLoggingPublisher`funziona in ambienti di esecuzione dotati di integrazione integrata con Amazon CloudWatch Logs come AWS Lambda Amazon Elastic Container Service. ## Configurazione Prima di poter abilitare e utilizzare le metriche utilizzando`EmfMetricLoggingPublisher`, completa i seguenti passaggi. ### Passaggio 1: aggiungere la dipendenza richiesta Configura le dipendenze del progetto (ad esempio, nel tuo `build.gradle` file `pom.xml` o) per utilizzare la versione `2.30.3` o successiva di. AWS SDK per Java Includi l'`emf-metric-logging-publisher`ArtifactID con il `2.30.3` numero di versione o successivo nelle dipendenze del progetto. Esempio: ``` 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 ``` ### Passaggio 2: configura le autorizzazioni richieste Abilita `logs:PutLogEvents` le autorizzazioni per l'identità IAM utilizzata dall'editore delle metriche per consentire all'SDK for Java di scrivere log in formato EMF. ### Fase 3: Configurazione della registrazione Per garantire una corretta raccolta delle metriche, configura la registrazione in modo che venga inviata alla console a un `INFO` livello o inferiore (ad esempio). `DEBUG` Nel tuo `log4j2.xml` file: ``` ``` Per ulteriori informazioni su come configurare un `log4j2.xml` file, consulta l'[argomento relativo alla registrazione](logging-slf4j.md) in questa guida. ## Configurazione e utilizzo `EmfMetricLoggingPublisher` La seguente classe di funzioni Lambda crea e configura prima un'`EmfMetricLoggingPublisher`istanza e poi la utilizza con un client di servizio 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 il client DynamoDB esegue il metodo, pubblica automaticamente `putItem` le metriche in un flusso di log in formato EMF. CloudWatch ### Esempio di evento di registro EMF Ad esempio, se invii il seguente evento alla funzione GameHandler Lambda con la registrazione configurata come mostrato in precedenza: ``` { "id": "23456" } ``` Dopo che la funzione ha elaborato l'evento, trovate due eventi di registro simili all'esempio seguente. L'oggetto JSON nel secondo evento contiene i dati metrici Java SDK per l'`PutItem`operazione su DynamoDB. Quando CloudWatch riceve un evento di registro in formato EMF, analizza automaticamente il codice JSON strutturato per estrarre i dati metrici. CloudWatch quindi crea le metriche corrispondenti durante l'archiviazione della voce di registro originale in Logs. CloudWatch ``` 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 } ``` La [documentazione dell'API](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/metrics/publishers/emf/EmfMetricLoggingPublisher.Builder.html) `EmfMetricLoggingPublisher.Builder` mostra le opzioni di configurazione che è possibile utilizzare. È inoltre possibile abilitare la registrazione delle metriche EMF per una singola richiesta, come [mostrato](metric-pub-impl-cwmp.md#enable-metrics-for-a-specific-request) per. CloudWatchMetricPublisher **Passaggi successivi:** per le applicazioni a esecuzione prolungata, consulta [Pubblicazione delle metriche SDK da applicazioni a esecuzione prolungata per la pubblicazione di metriche](metric-pub-impl-cwmp.md) basate su metriche. CloudWatch # Invia le metriche SDK alla console utilizzando il AWS SDK for Java 2.x L'`[LoggingMetricPublisher](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/metrics/LoggingMetricPublisher.html)`implementazione invia le metriche direttamente nella console o nei file di registro dell'applicazione. Questo approccio è ideale per lo sviluppo, il debug e la comprensione dei parametri raccolti dall'SDK senza richiedere servizi esterni come Amazon. CloudWatch A differenza di `CloudWatchMetricPublisher` and`EmfMetricLoggingPublisher`, `LoggingMetricPublisher` fornisce un output immediato senza ritardi o dipendenze esterne. Ciò lo rende perfetto per lo sviluppo locale e gli scenari di risoluzione dei problemi. ## Quando usare LoggingMetricPublisher Usa `LoggingMetricPublisher` quando devi: + Raccolta di metriche di debug durante lo sviluppo + Scopri quali metriche raccoglie l'SDK per le tue operazioni + Risolvi i problemi di prestazioni a livello locale + Testa la raccolta di metriche senza dipendenze da servizi esterni + Visualizza immediatamente le metriche nella console o nei file di registro **Nota** `LoggingMetricPublisher`non è consigliato per ambienti di produzione in cui sono necessarie funzionalità persistenti di analisi e archiviazione delle metriche. ## Configura la registrazione da console per le metriche Per visualizzare l'`LoggingMetricPublisher`output, configura il framework di registrazione per visualizzare `INFO` i messaggi di livello. La seguente `log4j2.xml` configurazione assicura che le metriche vengano visualizzate nella console: ``` ``` Questa configurazione indirizza l'SDK a inviare le metriche alla console a livello. `INFO` La configurazione del `LoggingMetricPublisher` logger garantisce che l'output metrico venga visualizzato anche se il logger root utilizza un livello superiore come o. `WARN` `ERROR` ## Abilita le metriche della console per un client di servizio L'esempio seguente mostra come creare `LoggingMetricPublisher` e utilizzare un client 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(); ``` ## Scegli il formato di output metrico `LoggingMetricPublisher`supporta due formati di output: + **Formato PLAIN (predefinito):** restituisce le metriche come voci compatte a riga singola + **Formato PRETTY:** emette le metriche in un formato multilinea leggibile dall'uomo L'esempio seguente mostra come utilizzare il formato PRETTY per facilitare la lettura durante lo sviluppo: ``` 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(); ``` ## Esempio completo L'esempio seguente dimostra l'utilizzo `LoggingMetricPublisher` in due modi: + A livello di cliente del servizio + Per una singola richiesta ``` 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(); } } ``` Il codice registra quanto segue nella 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. ``` ### Artefatti aggiuntivi per l'esempio File Maven `pom.xml` ``` 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 ``` File di configurazione `Log4j2.xml` ``` ``` Le metriche includono informazioni sulla tempistica, dettagli del servizio, nomi delle operazioni e codici di stato HTTP che aiutano a comprendere i modelli di utilizzo delle API dell' AWS applicazione. ## Fasi successive Dopo l'utilizzo `LoggingMetricPublisher` per lo sviluppo e il debug, considera queste opzioni per gli ambienti di produzione: + Per le applicazioni a lunga durata, utilizzalo [CloudWatchMetricPublisher](metric-pub-impl-cwmp.md)per inviare metriche ad Amazon CloudWatch per analisi e avvisi + Per quanto riguarda AWS Lambda le funzioni, utilizza per [EmfMetricLoggingPublisher](metric-pub-impl-emf.md)pubblicare le metriche in formato Embedded Metric CloudWatch # AWS SDK for Java 2.x: Riferimento completo alle metriche [Con AWS SDK for Java 2.x, puoi raccogliere metriche dai client di servizio nella tua applicazione e quindi pubblicarle (emettere) tali metriche su Amazon. CloudWatch](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/WhatIsCloudWatch.html) Queste tabelle elencano le metriche che puoi raccogliere e qualsiasi requisito di utilizzo del client HTTP. [Per ulteriori informazioni sull'abilitazione e la configurazione delle metriche per l'SDK, consulta Abilitazione delle metriche SDK.](metrics.md) ## Metriche raccolte con ogni richiesta | Nome parametro | Description | Tipo | | --- | --- | --- | | ApiCallDuration | La durata della chiamata API. Sono inclusi tutti i tentativi di chiamata effettuati. | Durata\$1 | | ApiCallSuccessful | Vero se la chiamata API è riuscita, falso in caso contrario. | Booleano | | CredentialsFetchDuration | Il periodo di tempo necessario per recuperare le credenziali di firma per la chiamata API. | Durata\$1 | | EndpointResolveDuration | Il periodo di tempo necessario per risolvere l'endpoint utilizzato per la chiamata API. | Durata\$1 | | MarshallingDuration | Il periodo di tempo necessario per adattare la richiesta SDK a una richiesta HTTP. | Durata\$1 | | OperationName | Il nome dell'operazione di servizio richiamata. | Stringa | | RetryCount | Il numero di tentativi eseguiti dall'SDK nell'esecuzione della richiesta. 0 implica che la richiesta ha funzionato la prima volta e che non è stato effettuato alcun tentativo. Per ulteriori informazioni sulla configurazione del comportamento dei nuovi tentativi, consulta. [Strategie di nuovo tentativo](retry-strategy.md#retry-strategies) | Numero intero | | ServiceId | L'ID univoco del servizio. | Stringa | | ServiceEndpoint | L'endpoint del servizio. | URI | | TokenFetchDuration | Il periodo di tempo necessario per recuperare le credenziali di firma per la chiamata API. | Durata\$1 | [\$1 java.time.Duration.](https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/time/Duration.html) ## Metriche raccolte per ogni tentativo di richiesta Ogni chiamata API potrebbe richiedere più tentativi prima di ricevere una risposta. Queste metriche vengono raccolte per ogni tentativo. ### Metriche principali | Nome parametro | Description | Tipo | | --- | --- | --- | | AwsExtendedRequestId | L'ID della richiesta estesa della richiesta di servizio. | Stringa | | AwsRequestId | L'ID della richiesta di servizio. | Stringa | | BackoffDelayDuration | Il periodo di attesa dell'SDK prima di questo tentativo di chiamata API. Il valore si basa sul `[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)` set sul client. Per ulteriori informazioni, consulta la [Strategie di nuovo tentativo](retry-strategy.md#retry-strategies) sezione di questa guida. | Durata\$1 | | ErrorType | Il tipo di errore che si è verificato durante un tentativo di chiamata. I seguenti sono i valori possibili: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/it_it/sdk-for-java/latest/developer-guide/metrics-list.html) | Stringa | | ReadThroughput | La velocità effettiva di lettura del client, definita come. `NumberOfResponseBytesRead / (TTLB - TTFB)` Questo valore è espresso in byte al secondo. Nota che questa metrica misura solo i byte letti dall'interno di o. `ResponseTransformer` `AsyncResponseTransformer` I dati letti all'esterno del trasformatore, ad esempio quando il flusso di risposta viene restituito come risultato del trasformatore, non sono inclusi nel calcolo. | Double | | WriteThroughput | La velocità effettiva di scrittura del client, definita come. `RequestBytesWritten / (LastByteWrittenTime - FirstByteWrittenTime)` Questo valore è espresso in byte al secondo. Questa metrica misura la velocità con cui l'SDK fornisce il corpo della richiesta al client HTTP. Sono esclusi la configurazione della connessione, il tempo di handshake TLS e il tempo di elaborazione del server. Questa metrica viene riportata solo per le richieste che hanno un corpo di streaming come S3. PutObject Tieni presente che questa metrica non tiene conto del buffering nel livello client HTTP. La velocità di trasmissione effettiva della rete potrebbe essere inferiore se il client HTTP memorizza i dati nel buffer prima dell'invio. Questa metrica rappresenta il limite superiore del throughput di rete. | Double | | ServiceCallDuration | Il periodo di tempo necessario per connettersi al servizio (o acquisire una connessione dal pool di connessioni), inviare la richiesta serializzata e ricevere la risposta iniziale (ad esempio il codice di stato HTTP e le intestazioni). Ciò NON include il tempo necessario per leggere l'intera risposta dal servizio. | Durata\$1 | | SigningDuration | Il periodo di tempo necessario per firmare la richiesta HTTP. | Durata\$1 | | TimeToFirstByte | Periodo di tempo compreso tra l'invio della richiesta HTTP (inclusa l'acquisizione di una connessione) al servizio e la ricezione del primo byte delle intestazioni della risposta. | Durata\$1 | | TimeToLastByte | Periodo di tempo compreso tra l'invio della richiesta HTTP (inclusa l'acquisizione di una connessione) al servizio e la ricezione dell'ultimo byte della risposta. Tieni presente APIs che per le risposte in streaming di ritorno, questa metrica copre il tempo fino al completamento dell'o. `ResponseTransformer` `AsyncResponseTransformer` | Durata\$1 | | UnmarshallingDuration | Il periodo di tempo necessario per annullare il marshall della risposta HTTP a una risposta SDK. Nota: per le operazioni di streaming, questo non include il tempo necessario per leggere il payload di risposta. | Durata\$1 | [\$1 java.time.Duration.](https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/time/Duration.html) ### Metriche HTTP | Nome parametro | Description | Tipo | Client HTTP richiesto\$1 | | --- | --- | --- | --- | | AvailableConcurrency | Il numero di richieste simultanee aggiuntive supportate dal client HTTP senza stabilire nuove connessioni al server di destinazione. Per le operazioni HTTP/1, questo è uguale al numero di connessioni TCP inattive stabilite con il servizio. Per le operazioni HTTP/2, questo è uguale al numero di flussi inattivi. Nota: questo valore varia in base all'implementazione del client HTTP: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/it_it/sdk-for-java/latest/developer-guide/metrics-list.html) Il valore è limitato a una singola istanza del client HTTP ed esclude la concorrenza di altri client HTTP nella stessa JVM. | Numero intero | Apache, Netty, CRT | | ConcurrencyAcquireDuration | Il periodo di tempo necessario per acquisire un canale dal pool di connessioni. Per le operazioni HTTP/1, un canale equivale a una connessione TCP. Per le operazioni HTTP/2, un canale è uguale a un canale di flusso HTTP/2. L'acquisizione di un nuovo canale può includere del tempo per: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/it_it/sdk-for-java/latest/developer-guide/metrics-list.html) | Durata\$1 | Apache, Netty, CRT | | HttpClientName | Il nome dell'HTTP utilizzato per la richiesta. | Stringa | Apache, Netty, CRT | | HttpStatusCode | Il codice di stato della risposta HTTP. | Numero intero | Qualsiasi | | LeasedConcurrency | Il numero di richieste attualmente eseguite dal client HTTP. Per le operazioni HTTP/1, questo è uguale al numero di connessioni TCP attive con il servizio (escluse le connessioni inattive). Per le operazioni HTTP/2, questo è uguale al numero di flussi HTTP attivi con il servizio (esclusa la capacità del flusso inattivo). Nota: questo valore varia in base all'implementazione del client HTTP: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/it_it/sdk-for-java/latest/developer-guide/metrics-list.html) Il valore è limitato a una singola istanza del client HTTP ed esclude la concorrenza di altri client HTTP nella stessa JVM. | Numero intero | Apache, Netty, CRT | | LocalStreamWindowSize | La dimensione della finestra HTTP/2 locale in byte per il flusso che esegue questa richiesta. | Numero intero | Netty | | MaxConcurrency | Il numero massimo di richieste simultanee supportate dal client HTTP. Per le operazioni HTTP/1, questo è uguale al numero massimo di connessioni TCP che il client HTTP può raggruppare. Per le operazioni HTTP/2, questo è uguale al numero massimo di flussi che il client HTTP può raggruppare. Nota: questo valore varia in base all'implementazione del client HTTP: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/it_it/sdk-for-java/latest/developer-guide/metrics-list.html) Il valore è limitato a una singola istanza del client HTTP ed esclude la concorrenza di altri client HTTP nella stessa JVM. | Numero intero | Apache, Netty, CRT | | PendingConcurrencyAcquires | Il numero di richieste che attendono la concorrenza dal client HTTP. Per le operazioni HTTP/1, questo è uguale al numero di richieste in attesa che venga stabilita o restituita una connessione TCP dal pool di connessioni. Per le operazioni HTTP/2, questo è uguale al numero di richieste in attesa di un nuovo flusso (e possibilmente di una nuova connessione HTTP/2) dal pool di connessioni. Nota: questo valore varia in base all'implementazione del client HTTP: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/it_it/sdk-for-java/latest/developer-guide/metrics-list.html) Il valore è limitato a una singola istanza del client HTTP ed esclude la concorrenza di altri client HTTP nella stessa JVM. | Numero intero | Apache, Netty, CRT | | RemoteStreamWindowSize | La dimensione della finestra HTTP/2 remota in byte per il flusso che esegue questa richiesta. | Numero intero | Netty | \$1 [java.time.Duration](https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/time/Duration.html). I termini usati nella colonna significano: + Apache: il client HTTP basato su Apache () `[ApacheHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/apache/ApacheHttpClient.html)` + Netty: il client HTTP basato su Netty () `[NettyNioAsyncHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/nio/netty/NettyNioAsyncHttpClient.html)` + CRT: il client HTTP basato su AWS CRT () `[AwsCrtAsyncHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/crt/AwsCrtAsyncHttpClient.html)` + Qualsiasi: la raccolta di dati metrici non dipende dal client HTTP, incluso il client HTTP URLConnection basato () `[UrlConnectionHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/urlconnection/UrlConnectionHttpClient.html)`