기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다. # 에서 SDK 지표 게시 AWS SDK for Java 2.x 를 사용하면 애플리케이션의 서비스 클라이언트 및 요청에 대한 지표를 수집하고 Amazon CloudWatch Logs의 출력을 분석한 다음 조치를 취할 AWS SDK for Java 2.x 수 있습니다. 기본적으로 SDK에서 지표 수집은 비활성화되어 있습니다. 이 항목은 활성화하고 구성하는 데 도움이 됩니다. ## SDK 지표 사용 시작하기 애플리케이션에서 지표 수집을 사용하려면 사용 사례에 따라 `[MetricPublisher](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/metrics/MetricPublisher.html)` 인터페이스의 적절한 구현을 선택하고 자세한 설정 안내를 따릅니다. **장기 실행 애플리케이션의 경우:** + `[CloudWatchMetricPublisher](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/metrics/publishers/cloudwatch/CloudWatchMetricPublisher.html)` 사용 + 전체 설정 안내, 코드 예제 및 구성 옵션은 [장기 실행 애플리케이션의 SDK 지표 게시](metric-pub-impl-cwmp.md)를 참조하세요. ** AWS Lambda 함수의 경우:** + `[EmfMetricLoggingPublisher](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/metrics/publishers/emf/EmfMetricLoggingPublisher.html)` 사용 + 전체 설정 지침, 종속성 및 Lambda별 구성은 [AWS Lambda 함수에 대한 SDK 지표 게시](metric-pub-impl-emf.md)를 참조하세요. **문제 해결 및 콘솔 출력의 경우:** + `[LoggingMetricPublisher](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/metrics/LoggingMetricPublisher.html)` 사용 + 설정 안내, 형식 지정 옵션, 로컬 개발 및 문제 해결을 위한 예제는 [개발 및 디버깅용 콘솔에 대한 SDK 지표 출력](metric-pub-impl-logging.md)을 참조하세요. ## 빠른 구현 미리 보기 각 사용 사례에 대한 지표 사용 설정은 다음과 같습니다. **장기 실행 애플리케이션:** ``` MetricPublisher metricsPub = CloudWatchMetricPublisher.create(); DynamoDbClient ddb = DynamoDbClient.builder() .overrideConfiguration(c -> c.addMetricPublisher(metricsPub)) .build(); ``` **Lambda 함수:** ``` EmfMetricLoggingPublisher emfPublisher = EmfMetricLoggingPublisher.builder() .namespace("MyApp") .build(); DynamoDbClient dynamoDb = DynamoDbClient.builder() .overrideConfiguration(c -> c.addMetricPublisher(emfPublisher)) .build(); ``` **개발 및 디버깅:** ``` MetricPublisher loggingPublisher = LoggingMetricPublisher.create(); S3Client s3 = S3Client.builder() .overrideConfiguration(c -> c.addMetricPublisher(loggingPublisher)) .build(); ``` ## AWS CRT 기반 S3 클라이언트의 지표 제한 [AWS CRT 기반 S3 클라이언트](crt-based-s3-client.md)는 현재 SDK 지표 수집을 지원하지 않습니다. AWS CRT 기반 S3 클라이언트 인스턴스의 빌더는 지표 게시자를 구성하는 방법을 제공하지 [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)않습니다. ## 지표는 언제 사용할 수 있나요? 지표는 일반적으로 Java용 SDK가 지표를 생성한 후 5\$110분 이내에 사용할 수 있습니다. 정확한 최신 지표를 확인하려면 Java 애플리케이션에서 지표를 전송한 후 최소 10분 후에 Cloudwatch를 확인하세요. ## 어떤 정보가 수집되나요? 지표 수집에는 다음이 포함됩니다. + 성공 또는 실패 여부를 포함한 API 요청 수 + 반환된 예외를 포함하여 API 요청에서 호출 AWS 서비스 하는에 대한 정보 + 마샬링, 서명, HTTP 요청과 같은 다양한 작업에 소요되는 기간 + 열린 연결 수, 보류 중인 요청 수, 사용된 HTTP 클라이언트 이름과 같은 HTTP 클라이언트 측정항목 **참고** 사용 가능한 지표는 HTTP 클라이언트마다 다릅니다. 전체 목록은 [서비스 클라이언트 메트릭](metrics-list.md)을 참조하세요. ## 이 정보를 어떻게 사용할 수 있나요? SDK가 수집하는 측정항목을 사용하여 애플리케이션의 서비스 클라이언트를 모니터링할 수 있습니다. 전반적인 사용 추세를 살펴보고, 이상 현상을 식별하고, 반환된 서비스 클라이언트 예외를 검토하거나, 특정 문제를 이해하기 위해 자세히 알아볼 수 있습니다. Amazon CloudWatch Logs를 사용하면 애플리케이션이 정의한 조건에 도달하는 즉시 알림을 보내는 경보를 만들 수도 있습니다. 자세한 내용은 [Amazon CloudWatch Logs 사용 설명서](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/)에서 [Amazon CloudWatch 지표 사용](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/working_with_metrics.html) 및 [Amazon CloudWatch 경보 사용](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/AlarmThatSendsEmail.html)을 참조하세요. # 를 사용하여 장기 실행 애플리케이션의 SDK 지표 게시 AWS SDK for Java 2.x `[CloudWatchMetricPublisher](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/metrics/publishers/cloudwatch/CloudWatchMetricPublisher.html)` 구현은 지연과 지표를 집계하고 지연되어 Amazon CloudWatch에 주기적으로 업로드하기 때문에 장기 실행 애플리케이션에 가장 적합합니다. 지표 게시자의 기본 설정은 메모리 사용량과 CloudWatch 비용을 최소화하면서 지표 데이터에 대한 유용한 인사이트를 제공하기 위한 것입니다. ## 설정 `CloudWatchMetricPublisher`를 통해 지표를 사용 설정하고 사용하려면 먼저 다음 단계를 완료해야 합니다. ### 1단계: 필수 종속성 추가 AWS SDK for Java버전 `2.14.0` 또는 그 이상의 버전을 사용하도록 프로젝트 종속성(예: `pom.xml` 또는 `build.gradle` 파일)을 구성하세요. 프로젝트 종속 항목에 버전 번호 `2.14.0` 이상의 `cloudwatch-metric-publisher` artifactId를 포함해야 합니다. 예제: ``` software.amazon.awssdk bom [2.30.11](https://central.sonatype.com/artifact/software.amazon.awssdk/bom) pom import software.amazon.awssdk cloudwatch-metric-publisher ``` ### 2단계: 필수 권한 구성 SDK for Java에서 지표 게시자를 사용하여 IAM ID에 대한 `cloudwatch:PutMetricData` 권한을 사용합니다. ## 특정 요청에 대한 지표 활성화 다음 클래스는 Amazon DynamoDB에 대한 요청에서 CloudWatch 지표 게시자를 사용하는 방법을 보여줍니다. 기본 메트릭 게시자 구성을 사용합니다. ``` 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(); } } ``` **중요** 서비스 클라이언트가 더 이상 사용되지 않을 때 애플리케이션이 `[MetricPublisher](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/metrics/MetricPublisher.html)` 인스턴스에서 `close`를 직접적으로 호출하는지 확인합니다. 이렇게 하지 않으면 스레드 또는 파일 설명자 누수가 발생할 수 있습니다. ## 특정 서비스 클라이언트에 대한 요약 지표 사용 다음 코드 조각은 서비스 클라이언트의 기본 설정으로 CloudWatch 지표 게시자를 사용하는 방법을 보여줍니다. ``` MetricPublisher metricsPub = CloudWatchMetricPublisher.create(); DynamoDbClient ddb = DynamoDbClient.builder() .overrideConfiguration(c -> c.addMetricPublisher(metricsPub)) .build(); ``` ## CloudWatch 지표 게시자 사용자 지정 다음 클래스는 특정 서비스 클라이언트의 지표 게시자에 대한 사용자 지정 구성을 사용하는 방법을 보여줍니다. 사용자 지정에는 특정 프로필 로드, 지표 게시자가 요청을 보내는 AWS 리전 지정, 게시자가 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(); } } ``` 이전 코드 조각에 표시된 사용자 지정은 다음과 같은 효과가 있습니다. + `cloudWatchClient` 메서드를 사용하면 지표를 전송하는 데 사용되는 CloudWatch 클라이언트를 사용자 지정할 수 있습니다. 이 예제에서는 클라이언트가 지표를 보내는 *us-east-1* 기본값과 다른 리전을 사용합니다. 또한 CloudWatch에 대한 요청을 인증하는 데 사용되는 자격 증명인 *cloudwatch*라는 다른 이름의 프로필을 사용합니다. 이러한 자격 증명에는 `cloudwatch:PutMetricData` 작업에 대한 권한이 있어야 합니다. + `uploadFrequency` 메서드를 사용하면 지표 게시자가 CloudWatch에 지표를 업로드하는 빈도를 지정할 수 있습니다. 기본값은 분당 1회입니다. + `maximumCallsPerUpload` 메서드는 업로드당 발생하는 직접 호출 수를 제한합니다. 기본값은 무제한입니다. + 기본적으로 SDK for Java 2.x는 네임스페이스(`AwsSdk/JavaSdk2`) 아래에 지표를 게시합니다. `namespace` 메서드를 사용하여 다른 값을 지정할 수 있습니다. + 기본적으로 SDK는 요약 지표를 게시합니다. 요약 지표는 평균, 최소, 최대, 합계 및 샘플 수로 구성됩니다. SDK는 `detailedMetrics` 메서드에 하나 이상의 SDK 지표를 지정하여 각 지표에 대한 추가 데이터를 게시합니다. 이 추가 데이터는 CloudWatch에서 쿼리할 수 있는 p90 및 p99와 같은 백분위수 통계를 사용합니다. 세부 지표는 SDK 클라이언트 요청의 종단간 지연 시간을 측정하는 `APICallDuration`과 같은 지연 시간 지표에 특히 유용합니다. `[CoreMetric](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/core/metrics/CoreMetric.html)` 클래스의 필드를 사용하여 다른 일반적인 SDK 지표를 지정할 수 있습니다. **다음 단계:** Lambda 함수로도 작업하는 경우 EMF 기반 [지표 게시를 위한 AWS Lambda 함수에 대한 SDK](metric-pub-impl-emf.md) 지표 게시를 참조하세요. # 를 사용하여 AWS Lambda 함수에 대한 SDK 지표 게시 AWS SDK for Java 2.x Lambda 함수는 일반적으로 밀리초에서 분 단위 동안 실행되므로 `CloudWatchMetricPublisher`에서 발생하는 지표 전송 지연으로 인해 데이터가 손실될 위험이 있습니다. `[EmfMetricLoggingPublisher](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/metrics/publishers/emf/EmfMetricLoggingPublisher.html)`는 지표를 [CloudWatch Embedded Metric Format(EMF)](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Embedded_Metric_Format.html)의 정형화된 로그 항목으로 즉시 작성하여 보다 적합한 접근 방식을 제공합니다. `EmfMetricLoggingPublisher`는 AWS Lambda 및 Amazon Elastic Container Service등 Amazon CloudWatch Logs와의 통합이 내장된 실행 환경에서 작동합니다. ## 설정 `EmfMetricLoggingPublisher`를 통해 지표를 사용 설정하고 사용하려면 먼저 다음 단계를 완료해야 합니다. ### 1단계: 필수 종속성 추가 AWS SDK for Java버전 `2.30.3` 또는 그 이상의 버전을 사용하도록 프로젝트 종속성(예: `pom.xml` 또는 `build.gradle` 파일)을 구성하세요. 프로젝트 종속 항목에 버전 번호 `2.30.3` 이상의 `emf-metric-logging-publisher` artifactId를 포함해야 합니다. 예제: ``` 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 ``` ### 2단계: 필수 권한 구성 SDK for Java에서 지표 게시자를 사용하여 IAM ID에 대한 `logs:PutLogEvents` 권한을 사용 설정해 EMF 형식 로그를 작성합니다. ### 3단계: 로깅 설정 적절한 지표 수집을 확보하려면 `INFO` 수준 이하(예: `DEBUG`)에서 콘솔에 출력하도록 로깅을 구성합니다. `log4j2.xml` 파일의 경우: ``` ``` `log4j2.xml` 파일 설정 방법에 대한 자세한 내용은 이 가이드의 [로깅 주제](logging-slf4j.md)를 참조하세요. ## `EmfMetricLoggingPublisher` 구성 및 사용 다음 Lambda 함수 클래스는 먼저 `EmfMetricLoggingPublisher` 인스턴스를 만들고 구성한 다음 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"; } } ``` DynamoDB 클라이언트는 `putItem` 메서드를 실행할 경우 지표를 EMF 형식의 CloudWatch 로그 스트림에 자동으로 게시합니다. ### EMF 로그 이벤트의 예제 예를 들어 다음과 같이 구성된 로깅을 사용하여 GameHandler Lambda 함수에 다음 이벤트를 전송하는 경우입니다. ``` { "id": "23456" } ``` 함수에서 이벤트를 처리한 후 다음 예제와 유사한 2개의 로그 이벤트를 찾습니다. 두 번째 이벤트의 JSON 객체에는 DynamoDB에 대한 `PutItem` 작업의 Java SDK 지표 데이터가 포함됩니다. CloudWatch는 EMF 형식의 로그 이벤트를 수신하면 정형화된 JSON을 자동으로 구문 분석하여 지표 데이터를 추출합니다. 그런 다음 CloudWatch는 원본 로그 항목을 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 } ``` `EmfMetricLoggingPublisher.Builder`의 [API 설명서](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/metrics/publishers/emf/EmfMetricLoggingPublisher.Builder.html)에는 사용할 수 있는 구성 옵션이 나와 있습니다. 또한 [CloudWatchMetricPublisher에 표시된 대로](metric-pub-impl-cwmp.md#enable-metrics-for-a-specific-request) 단일 요청에 대해 EMF 지표 로깅을 사용할 수 있습니다. **다음 단계:** 장기 실행 애플리케이션의 경우 CloudWatch 기반 지표 게시를 위해 [장기 실행 애플리케이션의 SDK 지표 게시](metric-pub-impl-cwmp.md)를 참조하세요. # 를 사용하여 SDK 지표를 콘솔로 출력 AWS SDK for Java 2.x `[LoggingMetricPublisher](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/metrics/LoggingMetricPublisher.html)` 구현은 지표를 애플리케이션의 콘솔 또는 로그 파일에 직접 출력합니다. 이 접근 방식은 Amazon CloudWatch와 같은 외부 서비스 없이 SDK가 수집하는 지표를 개발, 디버깅 및 이해하는 데 적합합니다. `CloudWatchMetricPublisher` 및 `EmfMetricLoggingPublisher`와 달리 `LoggingMetricPublisher`는 지연이나 외부 종속성 없이 즉각적인 출력을 제공합니다. 따라서 로컬 개발 및 문제 해결 시나리오에 적합합니다. ## LoggingMetricPublisher를 사용해야 하는 경우 다음 작업 시 `LoggingMetricPublisher`를 사용합니다. + 개발 중 지표 수집 디버그 + SDK가 작업에 대해 수집하는 지표 이해 + 로컬 방식으로 성능 문제 해결 + 외부 서비스 종속성 없이 지표 수집 테스트 + 콘솔 또는 로그 파일에서 지표 즉시 보기 **참고** `LoggingMetricPublisher`는 영구 지표 스토리지 및 분석 기능이 필요한 프로덕션 환경에는 권장되지 않습니다. ## 지표용 콘솔 로깅 설정 `LoggingMetricPublisher` 출력을 보려면 `INFO` 레벨 메시지를 표시하도록 로깅 프레임워크를 구성합니다. 다음 `log4j2.xml` 구성을 사용하면 지표가 콘솔에 표시됩니다. ``` ``` 이 구성은 SDK가 `INFO` 레벨의 콘솔에 지표를 출력하도록 지시합니다. `LoggingMetricPublisher` 로거 구성을 사용하면 루트 로거가 `WARN` 또는 `ERROR` 등의 상위 수준을 사용하더라도 지표 출력이 나타납니다. ## 서비스 클라이언트에 대한 콘솔 지표 사용 다음 예제에서는 `LoggingMetricPublisher`를 만들고 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(); ``` ## 지표 출력 형식 선택 `LoggingMetricPublisher`에서 지원되는 2가지 출력 형식: + **PLAIN 형식(기본값):** 지표를 압축된 한 줄 항목으로 출력합니다. + **PRETTY 형식:** 사람이 읽을 수 있는 여러 줄 형식으로 지표를 출력합니다. 다음 예제에서는 개발 중에 읽기 쉽도록 PRETTY 형식을 사용하는 방법을 보여줍니다. ``` 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(); ``` ## 전체 예제 다음의 예제는 2가지 방식으로 `LoggingMetricPublisher`를 사용하는 쿼리를 보여줍니다. + 서비스 클라이언트 수준인 경우 + 단일 요청인 경우 ``` 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(); } } ``` 코드는 콘솔에 다음을 로그합니다. ``` 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. ``` ### 예제용 추가 아티팩트 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 ``` `Log4j2.xml` 구성 파일 ``` ``` 지표에는 애플리케이션의 AWS API 사용 패턴을 이해하는 데 도움이 되는 타이밍 정보, 서비스 세부 정보, 작업 이름 및 HTTP 상태 코드가 포함됩니다. ## 다음 단계 개발 및 디버깅에 `LoggingMetricPublisher`를 사용한 후 프로덕션 환경에 대해 다음 옵션을 고려합니다. + 장기 실행 애플리케이션의 경우 [CloudWatchMetricPublisher](metric-pub-impl-cwmp.md)를 사용하여 분석 및 알림용으로 Amazon CloudWatch에 지표를 전송합니다. + AWS Lambda 함수의 경우 [EmfMetricLoggingPublisher](metric-pub-impl-emf.md)를 사용하여 CloudWatch 임베디드 지표 형식으로 지표 게시 # AWS SDK for Java 2.x: 포괄적인 지표 참조 를 사용하면 애플리케이션의 서비스 클라이언트에서 지표를 수집한 다음 해당 지표를 [Amazon CloudWatch](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/WhatIsCloudWatch.html)에 게시(출력)할 AWS SDK for Java 2.x수 있습니다. 다음 표에는 수집할 수 있는 지표와 HTTP 클라이언트 사용 요구 사항이 나열되어 있습니다. SDK 지표를 활성화 및 구성하는 자세한 내용은 [SDK 지표 활성화](metrics.md)를 참조하세요. ## 각 요청에서 수집된 지표 | 지표 이름 | 설명 | 형식 | | --- | --- | --- | | ApiCallDuration | API 직접 호출 지속 시간입니다. 여기에는 모든 직접 호출 시도가 포함됩니다. | 지속 시간\$1 | | ApiCallSuccessful | API 직접 호출이 성공하면 true이고, 그렇지 않으면 false입니다. | 부울 | | CredentialsFetchDuration | API 직접 호출용 서명 자격 증명을 가져오는 지속 시간입니다. | 지속 시간\$1 | | EndpointResolveDuration | API 직접 호출에 사용되는 엔드포인트를 해결하는 데 걸리는 시간입니다. | 지속 시간\$1 | | MarshallingDuration | SDK 요청을 HTTP 요청으로 마샬하는 데 걸리는 시간입니다. | 지속 시간\$1 | | OperationName | 간접 호출 중인 서비스 작업의 이름입니다. | 문자열 | | RetryCount | SDK가 요청 실행 시 수행한 재시도 횟수입니다. 0은 요청이 처음 작동했고 재시도가 시도되지 않았음을 의미합니다. 재시도 동작 구성에 대한 자세한 내용은 [재시도 전략](retry-strategy.md#retry-strategies) 섹션을 참조하세요. | Integer | | ServiceId | 서비스의 고유 ID입니다. | 문자열 | | ServiceEndpoint | 서비스의 엔드포인트입니다. | URI | | TokenFetchDuration | API 직접 호출용 서명 자격 증명을 가져오는 지속 시간입니다. | 지속 시간\$1 | \$1[java.time.Duration](https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/time/Duration.html). ## 각 요청 시도에 대해 수집된 지표 응답을 수신하려면 각 API 호출에 여러 번 시도해야 할 수 있습니다. 이 지표는 각 요청 시도에 대해 수집됩니다. ### 주요 지표 | 지표 이름 | 설명 | 형식 | | --- | --- | --- | | AwsExtendedRequestId | 서비스 요청의 확장 요청 ID입니다. | 문자열 | | AwsRequestId | 서비스 요청의 요청 ID입니다. | 문자열 | | BackoffDelayDuration | 이 API 직접 호출을 시도하기 전에 SDK가 대기한 지속 시간입니다. 값은 클라이언트에 설정된 `[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)`를 기반으로 합니다. 자세한 내용은 이 가이드의 [재시도 전략](retry-strategy.md#retry-strategies) 섹션을 참조하세요. | 지속 시간\$1 | | ErrorType | 직접 호출 시도에서 발생한 오류 유형입니다. 유효한 값은 다음과 같습니다. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/sdk-for-java/latest/developer-guide/metrics-list.html) | 문자열 | | ReadThroughput | `NumberOfResponseBytesRead / (TTLB - TTFB)`로 정의된 클라이언트의 읽기 처리량입니다. 이 값은 초당 바이트 단위입니다. 이 지표는 `ResponseTransformer` 또는 `AsyncResponseTransformer` 내에서 읽은 바이트만 측정합니다. 응답 스트림이 변환기의 결과로 반환되는 경우와 같이 변환기 외부에서 읽는 데이터는 계산에 포함되지 않습니다. | 배정밀도 실수 | | WriteThroughput | 로 정의된 클라이언트의 쓰기 처리량입니다`RequestBytesWritten / (LastByteWrittenTime - FirstByteWrittenTime)`. 이 값은 초당 바이트 단위입니다. 이 지표는 SDK가 HTTP 클라이언트에 요청 본문을 제공하는 속도를 측정합니다. 연결 설정, TLS 핸드셰이크 시간 및 서버 처리 시간은 제외됩니다. 이 지표는 S3 PutObject와 같은 스트리밍 본문이 있는 요청에 대해서만 보고됩니다. 이 지표는 HTTP 클라이언트 계층의 버퍼링을 고려하지 않습니다. HTTP 클라이언트가 전송하기 전에 데이터를 버퍼링하면 실제 네트워크 전송 속도가 낮아질 수 있습니다. 이 지표는 네트워크 처리량의 상한을 나타냅니다. | 배정밀도 실수 | | ServiceCallDuration | 서비스에 연결하고(또는 연결 풀에서 연결을 획득하고), 직렬화된 요청을 보내고, 초기 응답(예: HTTP 상태 코드 및 헤더)을 수신하는 지속 시간입니다. 여기에는 서비스의 전체 응답을 읽는 시간은 포함되지 않습니다. | 지속 시간\$1 | | SigningDuration | HTTP 요청에 서명하는 지속 시간입니다. | 지속 시간\$1 | | TimeToFirstByte | 서비스에 HTTP 요청(연결 획득 포함)을 보내고 응답에서 헤더의 첫 번째 바이트를 수신하는 지속 시간입니다. | 지속 시간\$1 | | TimeToLastByte | 서비스에 HTTP 요청(연결 획득 포함)을 보내고 응답에서 마지막 바이트를 수신하는 지속 시간입니다. 스트리밍 응답을 반환하는 API의 경우 이 지표는 `ResponseTransformer` 또는 `AsyncResponseTransformer`가 완료될 때까지의 시간에 걸쳐 있습니다. | 지속 시간\$1 | | UnmarshallingDuration | SDK 응답에 대한 HTTP 응답을 언마샬하는 데 걸리는 지속 시간입니다. 참고: 스트리밍 작업의 경우 응답 페이로드를 읽는 데 걸리는 시간은 포함되지 않습니다. | 지속 시간\$1 | \$1[java.time.Duration](https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/time/Duration.html). ### HTTP 지표 | 지표 이름 | 설명 | 형식 | HTTP 클라이언트 필요\$1 | | --- | --- | --- | --- | | AvailableConcurrency | 대상 서버에 대한 새 연결을 설정하지 않고 HTTP 클라이언트가 지원하는 추가 동시 요청 수입니다. HTTP/1 작업의 경우 서비스에 설정된 유휴 TCP 연결 수와 같습니다. HTTP/2 작업의 경우 유휴 스트림 수와 같습니다. 참고: 이 값은 HTTP 클라이언트 구현에 따라 다릅니다. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/sdk-for-java/latest/developer-guide/metrics-list.html) 값은 개별 HTTP 클라이언트 인스턴스로 범위가 지정되며 동일한 JVM의 다른 HTTP 클라이언트에서 동시성을 제외합니다. | Integer | Apache, Netty, CRT | | ConcurrencyAcquireDuration | 연결 풀에서 채널을 획득하는 데 걸린 지속 시간입니다. HTTP/1 작업의 경우 채널은 TCP 연결과 같습니다. HTTP/2 작업의 경우 채널은 HTTP/2 스트림 채널과 같습니다. 새 채널을 획득하는 데 다음과 같은 시간이 포함될 수 있습니다. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/sdk-for-java/latest/developer-guide/metrics-list.html) | 지속 시간\$1 | Apache, Netty, CRT | | HttpClientName | 요청에 사용 중인 HTTP의 이름입니다. | 문자열 | Apache, Netty, CRT | | HttpStatusCode | HTTP 응답의 상태 코드입니다. | Integer | 임의 | | LeasedConcurrency | HTTP 클라이언트에서 실행하는 요청 수입니다. HTTP/1 작업의 경우 서비스와의 활성 TCP 연결 수와 같습니다(유휴 연결 제외). HTTP/2 작업의 경우 서비스가 포함된 활성 HTTP 스트림 수와 같습니다(유휴 스트림 용량 제외). 참고: 이 값은 HTTP 클라이언트 구현에 따라 다릅니다. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/sdk-for-java/latest/developer-guide/metrics-list.html) 값은 개별 HTTP 클라이언트 인스턴스로 범위가 지정되며 동일한 JVM의 다른 HTTP 클라이언트에서 동시성을 제외합니다. | Integer | Apache, Netty, CRT | | LocalStreamWindowSize | 이 요청이 실행되는 스트림의 로컬 HTTP/2 창 크기(바이트)입니다. | Integer | Netty | | MaxConcurrency | HTTP 클라이언트가 지원하는 최대 동시 요청 수입니다. HTTP/1 작업의 경우 HTTP 클라이언트가 풀링할 수 있는 최대 TCP 연결 수와 같습니다. HTTP/2 작업의 경우 HTTP 클라이언트가 풀링할 수 있는 최대 스트림 수와 같습니다. 참고: 이 값은 HTTP 클라이언트 구현에 따라 다릅니다. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/sdk-for-java/latest/developer-guide/metrics-list.html) 값은 개별 HTTP 클라이언트 인스턴스로 범위가 지정되며 동일한 JVM의 다른 HTTP 클라이언트에서 동시성을 제외합니다. | Integer | Apache, Netty, CRT | | PendingConcurrencyAcquires | HTTP 클라이언트의 동시성을 기다리는 요청 수입니다. HTTP/1 작업의 경우 TCP 연결이 연결 풀에서 설정되거나 반환될 때까지 대기하는 요청 수와 같습니다. HTTP/2 작업의 경우 연결 풀에서 새 스트림(및 가능한 경우 새 HTTP/2 연결)을 기다리는 요청 수와 같습니다. 참고: 이 값은 HTTP 클라이언트 구현에 따라 다릅니다. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/sdk-for-java/latest/developer-guide/metrics-list.html) 값은 개별 HTTP 클라이언트 인스턴스로 범위가 지정되며 동일한 JVM의 다른 HTTP 클라이언트에서 동시성을 제외합니다. | Integer | Apache, Netty, CRT | | RemoteStreamWindowSize | 이 요청이 실행되는 스트림의 원격 HTTP/2 창 크기(바이트)입니다. | Integer | Netty | \$1[java.time.Duration](https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/time/Duration.html). 열에 사용된 용어의 의미는 다음과 같습니다. + Apache: Apache 기반 HTTP 클라이언트(`[ApacheHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/apache/ApacheHttpClient.html)`) + Netty: Netty 기반 HTTP 클라이언트(`[NettyNioAsyncHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/nio/netty/NettyNioAsyncHttpClient.html)`) + CRT: AWS CRT 기반 HTTP 클라이언트(`[AwsCrtAsyncHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/crt/AwsCrtAsyncHttpClient.html)`) + 임의: 지표 데이터 수집은 HTTP 클라이언트에 종속되지 않습니다. 여기에는 URLConnection 기반 HTTP 클라이언트(`[UrlConnectionHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/urlconnection/UrlConnectionHttpClient.html)`)가 포함됨