기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.

# 관찰성
<a name="observability"></a>

관찰성은 시스템의 현재 상태를 내보내는 데이터에서 추론할 수 있는 범위입니다. 방출되는 데이터를 일반적으로 원격 측정이라고 합니다.

는 지표, 추적 및 로그라는 세 가지 공통 원격 측정 신호를 모두 제공할 AWS SDK for Kotlin 수 있습니다. [https://docs.aws.amazon.com/smithy-kotlin/api/latest/telemetry-api/aws.smithy.kotlin.runtime.telemetry/-telemetry-provider/index.html](https://docs.aws.amazon.com/smithy-kotlin/api/latest/telemetry-api/aws.smithy.kotlin.runtime.telemetry/-telemetry-provider/index.html)를 연결하여 원격 측정 데이터를 관찰성 백엔드(예: [AWS X-Ray](https://docs.aws.amazon.com/xray/?icmpid=docs_homepage_devtools) 또는 [Amazon CloudWatch](https://docs.aws.amazon.com/cloudwatch/?icmpid=docs_homepage_mgmtgov))로 전송한 다음 조치를 취할 수 있습니다.

SDK에서는 기본적으로 로깅만 활성화되고 다른 원격 측정 신호는 비활성화됩니다. 이 주제에서는 원격 측정 출력을 활성화하고 구성하는 방법을 설명합니다.

**중요**  
`TelemetryProvider`는 현재 사용하기 위해 옵트인해야 하는 실험 API입니다.

## `TelemetryProvider` 구성
<a name="observability-conf-telemetry-provider"></a>

애플리케이션에서 모든 서비스 클라이언트 또는 개별 클라이언트`TelemetryProvider`에 대해 전역적으로를 구성할 수 있습니다. 다음 예제에서는 가상 함수를 사용하여 `TelemetryProvider` API 작업을 `getConfiguredProvider()` 보여줍니다. 이 [원격 측정 공급자](observability-telemetry-providers.md) 섹션에서는 SDK에서 제공하는 구현에 대한 정보를 설명합니다. 공급자가 지원되지 않는 경우 자체 지원을 구현하거나 [ GitHub에서 기능 요청을 열](https://github.com/awslabs/aws-sdk-kotlin/issues/new/choose) 수 있습니다.

### 기본 글로벌 원격 측정 공급자 구성
<a name="observability-conf-telemetry-provider-global"></a>

기본적으로 모든 서비스 클라이언트는 전역적으로 사용 가능한 원격 측정 공급자를 사용하려고 시도합니다. 이렇게 하면 공급자를 한 번 설정할 수 있으며, 모든 클라이언트가 공급자를 사용합니다. 이 작업은 서비스 클라이언트를 인스턴스화하기 전에 한 번만 수행해야 합니다.

글로벌 원격 측정 공급자를 사용하려면 먼저 다음 Gradle 코드 조각과 같이 프로젝트 종속성을 업데이트하여 원격 측정 기본 모듈을 추가합니다.

(*X.Y.Z* 링크로 이동하여 사용 가능한 최신 버전을 볼 수 있습니다.)

```
dependencies {
    implementation(platform("aws.smithy.kotlin:bom:[https://github.com/smithy-lang/smithy-kotlin/releases/latest](https://github.com/smithy-lang/smithy-kotlin/releases/latest)"))
    implementation("aws.smithy.kotlin:telemetry-defaults")
    ...
}
```

그런 다음 다음 코드와 같이 서비스 클라이언트를 생성하기 전에 글로벌 원격 측정 공급자를 설정합니다.

```
import aws.sdk.kotlin.services.s3.S3Client
import aws.smithy.kotlin.runtime.telemetry.GlobalTelemetryProvider
import kotlinx.coroutines.runBlocking

fun main() = runBlocking {
    val myTelemetryProvider = getConfiguredProvider()
    GlobalTelemetryProvider.set(myTelemetryProvider)

    S3Client.fromEnvironment().use { s3 ->
        …
    }     
}

fun getConfiguredProvider(): TelemetryProvider {
    TODO("TODO - configure a provider")
}
```

### 특정 서비스 클라이언트에 대한 원격 측정 공급자 구성
<a name="observability-conf-telemetry-provider-client"></a>

특정 원격 측정 공급자(글로벌 공급자 제외)를 사용하여 개별 서비스 클라이언트를 구성할 수 있습니다. 방법은 다음 예제와 같습니다.

```
import aws.sdk.kotlin.services.s3.S3Client
import kotlinx.coroutines.runBlocking

fun main() = runBlocking {
    S3Client.fromEnvironment{
        telemetryProvider = getConfiguredProvider()
    }.use { s3 ->
        ...
    }
}

fun getConfiguredProvider(): TelemetryProvider {
    TODO("TODO - configure a provider")
}
```

# Metrics
<a name="observability-telemetry-metrics"></a>

다음 표에는 SDK가 내보내는 원격 측정 지표가 나열되어 있습니다. 지표를 관찰할 수 있도록 [원격 측정 공급자를 구성](observability.md#observability-conf-telemetry-provider)합니다.


**어떤 지표가 내보내집니까?**  

| 지표 이름 | 단위 | Type | 속성 | 설명 | 
| --- | --- | --- | --- | --- | 
| smithy.client.call.duration | s | 히스토그램(Histogram) | rpc.service, rpc.method | 전체 통화 기간(재시도 포함) | 
| smithy.client.call.attempts | \$1attempt\$1 | MonotonicCounter | rpc.service, rpc.method | 개별 작업에 대한 시도 횟수 | 
| smithy.client.call.errors | \$1error\$1 | MonotonicCounter | rpc.service, rpc.method, exception.type | 작업의 오류 수 | 
| smithy.client.call.attempt\$1duration | s | 히스토그램(Histogram) | rpc.service, rpc.method | 서비스에 연결하고, 요청을 보내고, HTTP 상태 코드 및 헤더를 다시 가져오는 데 걸리는 시간(전송 대기 시간 포함) | 
| smithy.client.call.resolve\$1endpoint\$1duration | s | 히스토그램(Histogram) | rpc.service, rpc.method | 요청에 대한 엔드포인트(DNS가 아닌 엔드포인트 해석기)를 해결하는 데 걸리는 시간 | 
| smithy.client.call.serialization\$1duration | s | 히스토그램(Histogram) | rpc.service, rpc.method | 메시지 본문을 직렬화하는 데 걸리는 시간 | 
| smithy.client.call.deserialization\$1duration | s | 히스토그램(Histogram) | rpc.service, rpc.method | 메시지 본문을 역직렬화하는 데 걸리는 시간 | 
| smithy.client.call.auth.signing\$1duration | s | 히스토그램(Histogram) | rpc.service, rpc.method, auth.scheme\$1id | 요청에 서명하는 데 걸리는 시간 | 
| smithy.client.call.auth.resolve\$1identity\$1duration | s | 히스토그램(Histogram) | rpc.service, rpc.method, auth.scheme\$1id | 자격 증명 공급자로부터 자격 증명(예: AWS 자격 증명 또는 보유자 토큰)을 획득하는 데 걸리는 시간 | 
| smithy.client.http.connections.acquire\$1duration | s | 히스토그램(Histogram) |  | 요청을 통해 연결을 획득하는 데 걸리는 시간 | 
| smithy.client.http.connections.limit | \$1connection\$1 | [비동기]UpDownCounter |  | HTTP 클라이언트에 대해 허용/구성된 최대 열린 연결 수 | 
| smithy.client.http.connections.usage | \$1connection\$1 | [비동기]UpDownCounter | 상태: 유휴 \$1 획득 | 연결 풀의 현재 상태 | 
| smithy.client.http.connections.uptime | s | 히스토그램(Histogram) |  | 연결이 열린 시간 | 
| smithy.client.http.requests.usage | \$1요청\$1 | [비동기]UpDownCounter | 상태: 대기 중 \$1 진행 중 | HTTP 클라이언트 요청 동시성의 현재 상태 | 
| smithy.client.http.requests.queued\$1duration | s | 히스토그램(Histogram) |  | HTTP 클라이언트가 요청을 대기열에 넣고 실행을 기다리는 데 소요된 시간입니다. | 
| smithy.client.http.bytes\$1sent | 방법 | MonotonicCounter | server.address | HTTP 클라이언트가 전송한 총 바이트 수 | 
| smithy.client.http.bytes\$1received | 방법 | MonotonicCounter | server.address | HTTP 클라이언트가 수신한 총 바이트 수입니다. | 

다음은 열 설명입니다.
+ **지표 이름** - 내보낸 지표의 이름입니다.
+ **단위** - 지표의 측정 단위입니다. 단위는 [UCUM](https://unitsofmeasure.org/ucum) 대/소문자를 구분하는(‘c/s’) 표기법으로 제공됩니다.
+ **유형** - 지표를 캡처하는 데 사용되는 계측의 유형입니다.
+ **설명** - 지표가 측정하는 항목에 대한 설명입니다.
+ **속성** - 지표와 함께 내보내지는 속성(차원) 세트입니다.

# 로깅
<a name="logging"></a>

는 [SLF4J](https://www.slf4j.org/manual.html) 호환 로거를 원격 측정 공급자`LoggerProvider`의 기본값으로 AWS SDK for Kotlin 구성합니다. 추상화 계층인 SLF4J를 사용하면 런타임 시 여러 로깅 시스템 중 하나를 사용할 수 있습니다. 지원되는 로깅 시스템에는 [Java 로깅 APIs](https://docs.oracle.com/javase/8/docs/technotes/guides/logging/). [Log4j ](https://logging.apache.org/log4j/2.x/) [https://logback.qos.ch/](https://logback.qos.ch/)

**주의**  
디버깅에는 유선 로깅만 사용하는 것이 좋습니다. (유선 로깅은 아래에 설명되어 있습니다.) 이메일 주소, 보안 토큰, API 키, 암호 및 AWS Secrets Manager 보안 암호와 같은 민감한 데이터를 로깅할 수 있으므로 프로덕션 환경에서 끕니다. 와이어 로깅은 HTTPS 호출의 경우에도 암호화 없이 전체 요청 또는 응답을 로깅합니다.  
대규모 요청(예: Amazon S3에 파일 업로드) 또는 응답의 경우 자세한 유선 로깅도 애플리케이션의 성능에 상당한 영향을 미칠 수 있습니다.

## Log4j 2 로깅 구성 예제
<a name="log4j2-example"></a>

 `SLF4J`호환 로그 라이브러리를 사용할 수 있지만이 예제에서는 Log4j 2를 사용하여 JVM 프로그램의 SDK에서 로그 출력을 활성화합니다.

**Gradle 종속성**

(*X.Y.Z* 링크로 이동하여 사용 가능한 최신 버전을 볼 수 있습니다.)

```
implementation("org.apache.logging.log4j:log4j-slf4j2-impl:[https://search.maven.org/#search|gav|1|g:org.apache.logging.log4j%20AND%20a:log4j-slf4j2-impl](https://search.maven.org/#search|gav|1|g:org.apache.logging.log4j%20AND%20a:log4j-slf4j2-impl)")
```

**Log4j 2 구성 파일**

`resources` 디렉터리`log4j2.xml`에 라는 파일을 생성합니다(예: `<project-dir>/src/main/resources`). 파일에 다음 XML 구성을 추가합니다.

```
<Configuration status="ERROR">
    <Appenders>
        <Console name="Out">
            <PatternLayout pattern="%d{YYYY-MM-dd HH:mm:ss} %-5p %c:%L %X - %encode{%m}{CRLF}%n"/>
        </Console>
    </Appenders>
    <Loggers>
        <Root level="info">
            <AppenderRef ref="Out"/>
        </Root>
    </Loggers>
</Configuration>
```

이 구성에는 MDC(매핑된 진단 컨텍스트) 로깅을 활성화하는 `pattern` 속성의 `%X` 지정자가 포함됩니다.

SDK는 각 작업에 대해 다음과 같은 MDC 요소를 추가합니다.

**rpc**  
호출된 RPC의 이름입니다. 예: `S3.GetObject`.

**sdkInvocationId**  
작업에 대해 서비스 클라이언트가 할당한 고유 ID입니다. ID는 단일 작업의 호출과 관련된 모든 로깅 이벤트를 상호 연관시킵니다.

## 유선 수준 메시지에 대한 로그 모드 지정
<a name="sdk-log-mode"></a>

기본적으로는 API 요청 및 응답의 민감한 데이터를 포함할 수 있으므로 유선 수준 메시지를 로깅하지 AWS SDK for Kotlin 않습니다. 그러나 디버깅을 위해 이러한 수준의 세부 정보가 필요한 경우가 있습니다.

Kotlin SDK를 사용하면 코드에서 로그 모드를 설정하거나 환경 설정을 사용하여 다음에 대한 디버그 메시징을 활성화할 수 있습니다.
+ HTTP 요청
+ HTTP 응답

로그 모드는 각 비트가 플래그(모드)이고 값이 추가되는 비트 필드로 지원됩니다. 하나의 요청 모드와 하나의 응답 모드를 결합할 수 있습니다.

### 코드에서 로그 모드 설정
<a name="set-log-mode-programmatically"></a>

추가 로깅을 옵트인하려면 서비스 클라이언트를 구성할 때 `logMode` 속성을 설정합니다.

다음 예제에서는 요청(본문 포함) 및 응답(본문 제외)의 로깅을 활성화하는 방법을 보여줍니다.

```
import aws.smithy.kotlin.runtime.client.LogMode

// ...

val client = DynamoDbClient {
    // ...
    logMode = LogMode.LogRequestWithBody + LogMode.LogResponse
}
```

서비스 클라이언트 구성 중에 설정된 로그 모드 값은 환경에서 설정된 모든 로그 모드 값을 재정의합니다.

### 환경에서 로그 모드 설정
<a name="set-log-mode-from-enviironment"></a>

코드에서 명시적으로 구성되지 않은 모든 서비스 클라이언트에 대해 전역적으로 로그 모드를 설정하려면 다음 중 하나를 사용합니다.
+ JVM 시스템 속성: `sdk.logMode`
+ 환경 변수: `SDK_LOG_MODE`

다음과 같은 대/소문자를 구분하지 않는 값을 사용할 수 있습니다.
+ `LogRequest`
+ `LogRequestWithBody`
+ `LogResponse`
+ `LogResponseWithBody`

환경의 설정을 사용하여 결합된 로그 모드를 생성하려면 값을 파이프(`|`) 기호로 구분합니다.

예를 들어 다음 예제에서는 이전 예제와 동일한 로그 모드를 설정합니다.

```
# Environment variable.
export SDK_LOG_MODE=LogRequestWithBody|LogResponse
```

```
# JVM system property.
java -Dsdk.logMode=LogRequestWithBody|LogResponse ...
```

**참고**  
또한 호환되는 SLF4J 로거를 구성하고 로깅 수준을 DEBUG로 설정하여 유선 수준 로깅을 활성화해야 합니다.

# 원격 측정 공급자
<a name="observability-telemetry-providers"></a>

SDK는 현재 [OpenTelemetry](https://opentelemetry.io/)(OTel)를 공급자로 지원합니다. SDK는 향후 추가 원격 측정 공급자를 제공할 수 있습니다.

**Topics**
+ [OpenTelemetry 기반 원격 측정 공급자 구성](observability-telemetry-providers-otel.md)

# OpenTelemetry 기반 원격 측정 공급자 구성
<a name="observability-telemetry-providers-otel"></a>

SDK for Kotlin은 OpenTelemetry에서 지원하는 `TelemetryProvider` 인터페이스의 구현을 제공합니다.

## 사전 조건
<a name="observability-telemetry-providers-otel-prereqs"></a>

다음 Gradle 코드 조각과 같이 프로젝트 종속성을 업데이트하여 OpenTelemetry 공급자를 추가합니다. *X.Y.Z* 링크로 이동하여 사용 가능한 최신 버전을 볼 수 있습니다.

```
dependencies {
    implementation(platform("aws.smithy.kotlin:bom:[https://github.com/smithy-lang/smithy-kotlin/releases/latest](https://github.com/smithy-lang/smithy-kotlin/releases/latest)"))
    implementation(platform("io.opentelemetry.instrumentation:opentelemetry-instrumentation-bom:[https://search.maven.org/#search|gav|1|g:io.opentelemetry.instrumentation%20AND%20a:opentelemetry-instrumentation-bom](https://search.maven.org/#search|gav|1|g:io.opentelemetry.instrumentation%20AND%20a:opentelemetry-instrumentation-bom)"))
    implementation("aws.smithy.kotlin:telemetry-provider-otel")

    // OPTIONAL: If you use log4j, the following entry enables the ability to export logs through OTel.
    runtimeOnly("io.opentelemetry.instrumentation:opentelemetry-log4j-appender-2.17")
}
```

## SDK 구성
<a name="observability-telemetry-providers-otel-conf"></a>

다음 코드는 OpenTelemetry 원격 측정 공급자를 사용하여 서비스 클라이언트를 구성합니다.

```
import aws.sdk.kotlin.services.s3.S3Client
import aws.smithy.kotlin.runtime.telemetry.otel.OpenTelemetryProvider
import io.opentelemetry.api.GlobalOpenTelemetry
import kotlinx.coroutines.runBlocking

fun main() = runBlocking {
    val otelProvider = OpenTelemetryProvider(GlobalOpenTelemetry.get())

    S3Client.fromEnvironment().use { s3 ->
        telemetryProvider = otelProvider
        …
    }
}
```

**참고**  
OpenTelemetry SDK를 구성하는 방법에 대한 설명은이 가이드의 범위를 벗어납니다. [OpenTelemetry Java 설명서에](https://opentelemetry.io/docs/instrumentation/java/)는 [수동](https://opentelemetry.io/docs/instrumentation/java/manual/), [ Java 에이전트](https://opentelemetry.io/docs/instrumentation/java/automatic/)를 통한 자동 또는 (선택 사항) [수집기](https://opentelemetry.io/docs/collector/) 등 다양한 접근 방식에 대한 구성 정보가 포함되어 있습니다.

## 리소스
<a name="observability-telemetry-providers-otel-res"></a>

OpenTelemetry를 시작하는 데 도움이 되는 다음 리소스를 사용할 수 있습니다.
+ [AWS Distro for OpenTelemetry](https://aws-otel.github.io/docs/introduction) - AWS OTeL Distro 홈페이지
+ [aws-otel-java-instrumentation](https://github.com/aws-observability/aws-otel-java-instrumentation) - AWS Distro for OpenTelemetry Java Instrumentation Library
+ [aws-otel-lambda](https://github.com/aws-observability/aws-otel-lambda) AWS 관리형 OpenTelemetry Lambda 계층
+ [aws-otel-collector](https://github.com/aws-observability/aws-otel-collector) -OpenTelemetry Collector용 AWS 배포
+ [AWS 관찰성 모범 사례](https://aws-observability.github.io/observability-best-practices/) - 관련 관찰성에 대한 일반 모범 사례 AWS