# 지원되는 시스템
Application Signals는 Amazon EKS, 네이티브 Kubernetes, Amazon ECS 및 Amazon EC2에서 지원 및 테스트됩니다. Amazon EC2에서 Application Signals를 활성화하는 지침은 CloudWatch 에이전트와 AWS Distro for OpenTelemetry를 지원하는 모든 플랫폼에서 유효해야 합니다.
**Topics**
+ [Java 호환성](#CloudWatch-Application-Signals-supportmatrix-java)
+ [.NET 호환성](#CloudWatch-Application-Signals-supportmatrix-dotnet)
+ [PHP 호환성](#php-compatibility)
+ [Ruby 호환성](#ruby-compatibility)
+ [Python 호환성](#CloudWatch-Application-Signals-supportmatrix-python)
+ [Node.js 호환성](#CloudWatch-Application-Signals-supportmatrix-node)
+ [GoLang 호환성](#golang-compatibility)
+ [런타임 버전 지원 매트릭스](#rumtime-version-matix)
+ [알려진 문제](#AppSignals-Issues)
## Java 호환성
Application Signals는 Java 애플리케이션을 지원하며 AWS Distro for OpenTelemetry와 동일한 Java 라이브러리 및 프레임워크를 지원합니다. 자세한 내용은 [지원되는 라이브러리, 프레임워크, 애플리케이션 서버 및 JVM](https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/main/docs/supported-libraries.md)을 참조하세요.
## .NET 호환성
Application Signals는 AWS Distro for OpenTelemetry와 동일한 .NET 라이브러리 및 프레임워크를 지원합니다. 자세한 내용은 [지원되는 계측](https://github.com/open-telemetry/opentelemetry-dotnet-instrumentation/blob/main/docs/internal/instrumentation-libraries.md)을 참조하세요.
Application Signals에서는 x86-64 또는 ARM64 CPU에서 실행되는 .NET 애플리케이션을 지원하며 Linux x64, Linux ARM64, Microsoft Windows Server 2022 x64를 지원합니다.
**참고**
AWS Distro for Open Telemetry(ADOT) SDK for .NET에서는 AWS SDK for .NET V4를 지원하지 않습니다. 전체 Application Signals 지원을 받으려면 AWS SDK .NET V3를 사용하세요.
## PHP 호환성
Application Signals는 OpenTelemetry 제로 코드 계측을 통해 PHP 애플리케이션을 지원합니다. 이 용도로 사용할 수 있는 AWS Distro for Open Telemetry(ADOT) SDK가 없습니다. [트랜잭션 검색](AmazonCloudWatch/latest/monitoring/CloudWatch-Transaction-Search.html)이 활성화된 표준 OpenTelemetry 계측 SDK를 사용해야 합니다. PHP에서 제로 코드 계측 사용을 시작하려면 OpenTelemetry PHP 계측 설명서, [PHP zero-code instrumentation](https://opentelemetry.io/docs/zero-code/php/)의 다음 단계를 수행합니다. 자동 계측은 일반적으로 사용되는 여러 PHP 라이브러리에 사용할 수 있습니다. 자세한 내용은 [OpenTelemetry 레지스트리](https://packagist.org/search/?query=open-telemetry%3Dinstrumentation)를 참조하세요.
## Ruby 호환성
Application Signals는 OpenTelemetry 제로 코드 계측을 통해 Ruby 애플리케이션을 지원합니다. 이 용도로 사용할 수 있는 AWS Distro for Open Telemetry(ADOT) SDK가 없습니다. [트랜잭션 검색](AmazonCloudWatch/latest/monitoring/CloudWatch-Transaction-Search.html)이 활성화된 표준 OpenTelemetry 계측 SDK를 사용해야 합니다. Ruby에서 제로 코드 계측 사용을 시작하려면 OpenTelemetry Ruby 계측 설명서, [Ruby zero-code instrumentation](https://opentelemetry.io/docs/languages/ruby/getting-started/#instrumentation)의 다음 단계를 수행합니다. 릴리스된 계측 라이브러리 목록은 [Registry](https://opentelemetry.io/ecosystem/registry/?language=rubycomponent=instrumentation)를 참조하세요.
## Python 호환성
Application Signals는 AWS Distro for OpenTelemetry와 동일한 라이브러리 및 프레임워크를 지원합니다. 자세한 내용은 [opentelemetry-python-contrib](https://github.com/open-telemetry/opentelemetry-python-contrib/blob/main/instrumentation/README.md)에서 **지원되는 패키지**를 참조하세요.
Python 애플리케이션에서 Application Signals를 활성화하기 전에 다음 사항에 유의하세요.
+ 일부 컨테이너화된 애플리케이션에서는 `PYTHONPATH` 환경 변수가 누락되면 애플리케이션이 시작되지 않을 수 있습니다. 이 문제를 해결하려면 `PYTHONPATH` 환경 변수를 애플리케이션의 작업 디렉터리 위치로 설정해야 합니다. 이는 OpenTelemetry 자동 계측과 관련하여 알려진 문제 때문입니다. 이 문제에 대한 자세한 내용은 [Python autoinstrumentation setting of PYTHONPATH is not compliant](https://github.com/open-telemetry/opentelemetry-operator/issues/2302)를 참조하세요.
+ Django 애플리케이션의 경우 추가 필수 구성이 있으며, [OpenTelemetry Python 설명서](https://opentelemetry-python.readthedocs.io/en/latest/examples/django/README.html)에서 설명합니다.
+ `--noreload` 플래그를 사용하여 자동 재로드를 방지합니다.
+ `DJANGO_SETTINGS_MODULE` 환경 변수를 Django 애플리케이션 `settings.py` 파일의 위치로 설정합니다. 이렇게 하면 OpenTelemetry가 올바르게 액세스하여 Django 설정에 통합할 수 있습니다.
## Node.js 호환성
Application Signals는 AWS Distro for OpenTelemetry와 동일한 Node.js 라이브러리 및 프레임워크를 지원합니다. 자세한 내용은 [지원되는 계측](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main)을 참조하세요.
### ESM 사용 Node.js에 대해 알려진 제한 사항
AWS Distro for Opentelemetry Node.js는 ECMA 스크립트 모듈(ESM)과 CommonJS(CJS)라는 두 가지 모듈 시스템을 지원합니다. OpenTelemetry JavaScript의 ESM 지원은 실험작이고 작업이 진행 중이므로 Application Signals를 활성화하려면 CJS 모듈 형식을 사용하는 것이 좋습니다. 자세한 내용은 GitHub에서 [ECMA 스크립트 모듈과 CommonJS 비교](https://github.com/open-telemetry/opentelemetry-js/blob/eb3ca4fb07ee31c62093f5fcec56575573c902ce/doc/esm-support.md)를 참조하세요.
애플리케이션이 ESM이 아닌 CJS를 사용하고 있는지 확인하려면 애플리케이션이 ESM 활성화 조건을 충족하지 않는지 확인하세요. 해당 조건들에 대한 자세한 내용은 Node.js 설명서의 [활성화](https://nodejs.org/api/esm.html#enabling) 부분을 참조하세요.
AWS Distro for Opentelemetry Node.js는 ESM에 대한 OpenTelemetry JavaScript의 실험 지원을 기반으로 ESM을 제한적으로 지원합니다. 이것이 의미하는 바는 다음과 같습니다.
+ Node.js버전은 18.19.0 이상이어야 합니다.
+ 계측하려는 Node.js 애플리케이션에는 종속성으로 `@aws/aws-distro-opentelemetry-node-autoinstrumentation`과 `@opentelemetry/instrumentation`이 포함되어야 합니다.
+ 계측하려는 Node.js 애플리케이션이 다음 노드 옵션으로 시작해야 합니다.
```
NODE_OPTIONS=' --import @aws/aws-distro-opentelemetry-node-autoinstrumentation/register --experimental-loader=@opentelemetry/instrumentation/hook.mjs'
```
Node.js ESM 모듈 형식으로 Application Signals를 활성화하기 위해 다음과 같은 다양한 플랫폼에 다양한 설정을 제공합니다.
+ **Amazon EKS** – [ESM 모듈 형식으로 Node.js 애플리케이션 설정](CloudWatch-Application-Signals-Enable-EKS.md#EKS-NodeJs-ESM)
+ **사이드카 전략을 사용하는 Amazon ECS** – [Setting up a Node.js application with the ESM module format](CloudWatch-Application-Signals-ECS-Sidecar.md#ECS-NodeJs-ESM)
+ **대몬 전략을 사용하는 Amazon ECS** – [Setting up a Node.js application with the ESM module format](CloudWatch-Application-Signals-ECS-Daemon.md#ECSDaemon-NodeJs-ESM)
+ **AWS CDK를 사용하는 Amazon ECS**
+ **Amazon EC2** – [Setting up a Node.js application with the ESM module format](CloudWatch-Application-Signals-Enable-EC2Main.md#EC2-NodeJs-ESM)
+ **Kubernetes** – [ESM 모듈 형식으로 Node.js 애플리케이션 설정](CloudWatch-Application-Signals-Enable-KubernetesMain.md#Kubernetes-NodeJs-ESM)
## GoLang 호환성
Application Signals는 OpenTelemetry 제로 코드 계측을 통해 GoLang 애플리케이션을 지원합니다. 이 용도로 사용할 수 있는 AWS Distro for Open Telemetry(ADOT) SDK가 없습니다. [트랜잭션 검색](AmazonCloudWatch/latest/monitoring/CloudWatch-Transaction-Search.html)이 활성화된 표준 OpenTelemetry 계측 SDK를 사용해야 합니다. GoLang에서 제로 코드 계측 사용을 시작하려면 OpenTelemetry GoLang 계측 설명서, [Getting Started with OpenTelemetry Go Automatic Instrumentation](https://github.com/open-telemetry/opentelemetry-go-instrumentation/blob/main/docs/getting-started.md)의 다음 단계를 수행합니다.
### 구현 고려 사항 GoLang 계측
GoLang 계측을 사용하기 위한 중요한 구현 세부 정보에 대해 알아봅니다. 이 지침에서는 GoLang 애플리케이션에서 명시적 컨텍스트 전파를 구현하고 Application Signals를 설정하는 방법을 설명합니다. GoLang 계측을 적절하게 구현하면 애플리케이션의 성능을 효과적으로 추적하고 분석할 수 있습니다.
#### AWS SDK 계측
Golang 자동 계측 라이브러리는 AWS SDK 계측을 바로 지원하지 않습니다. `otelaws` 라이브러리 계측을 자동 계측 에이전트와 함께 사용해야 합니다.
1. 필요한 종속 항목을 설치하세요.
```
go get go.opentelemetry.io/contrib/instrumentation/github.com/aws/aws-sdk-go-v2/otelaws
```
1. 애플리케이션에 다음 줄을 추가하세요.
```
otelaws.AppendMiddlewares(&cfg.APIOptions)
```
1. 이전 `aws.Config` 객체를 사용하여 후속 AWS 클라이언트를 생성하세요.
```
s3Client := s3.NewFromConfig(cfg)
```
다음 예제에서는 AWS 직접 호출에 대한 스팬을 생성하고 자동 계측과 통합합니다.
```
func handleRequest(ctx context.Context) error {
cfg, err := config.LoadDefaultConfig(ctx)
if err != nil {
return err
}
// Add OpenTelemetry instrumentation middleware to the AWS config
otelaws.AppendMiddlewares(&cfg.APIOptions)
// Create S3 client with the instrumented config
s3Client := s3.NewFromConfig(cfg)
// Now any operations with this client will be traced
// with the context from the upstream call
_, err = s3Client.ListBuckets(ctx, &s3.ListBucketsInput{})
return err
}
```
자동 계측 실행 파일 구성에 대한 자세한 내용은 [Configuration methods](https://github.com/open-telemetry/opentelemetry-go-instrumentation/blob/main/docs/configuration.md)를 참조하세요.
#### HTTP 직접 호출 계측
HTTP 직접 호출은 요청 간에 컨텍스트가 전달되지 않을 때 추적을 분할할 수 있습니다. 다운스트림 서비스가 동일한 컨텍스트를 사용하도록 하려면 HTTP 클라이언트가 `NewRequest()` 대신 `NewRequestWithContext()`를 사용해야 합니다. 두 서비스 모두에 계측 에이전트가 있는 경우 스팬은 동일한 추적 ID로 연결되어 포괄적인 가시성을 제공합니다.
```
func makeDownstreamCall(ctx context.Context, url string) ([]byte, error) {
client := &http.Client{}
// Create request with context from the upstream call
req, err := http.NewRequestWithContext(ctx, http.MethodGet, url, nil)
if err != nil {
return nil, err
}
// Execute the request
resp, err := client.Do(req)
if err != nil {
return nil, err
}
defer resp.Body.Close()
}
```
#### SQL 직접 호출 계측
SQL 스팬이 상위 스팬과 연결 해제될 수 있으며 이 경우 클라이언트 직접 호출을 서버 스팬으로 추론할 수 있습니다. 이는 SQL 직접 호출이 업스트림 핸들러로부터 컨텍스트를 수신하지 않을 때 나타납니다. 표준 SQL 직접 호출(예: `Query` 및 `Exec`)은 기본적으로 업스트림 직접 호출자의 컨텍스트가 아닌 `context.Background()`를 사용합니다. 표준 SQL 직접 호출을 컨텍스트 인식에 상응하는 항목으로 바꿉니다.
+ `Query` 대신 `QueryContext` 사용
+ `Exec` 대신 `ExecContext` 사용
이러한 메서드는 DB 직접 호출에 업스트림 요청 컨텍스트를 전달하여 적절한 추적 연속성을 유지합니다.
```
func queryDatabase(ctx context.Context, db *sql.DB, userID string) (*sql.Rows, error) {
// This breaks the trace context
// row := db.Query("SELECT name FROM users WHERE id = $1", userID)
// This passes the context from the upstream call for trace continuity
rows, err := db.QueryContext(ctx, "SELECT name FROM users WHERE id = $1", userID)
return rows, error
}
```
**참고**
`db.system` 속성은 현재 SQL 직접 호출에서 지원되지 않습니다. 이 제한 사항은 데이터베이스 클라이언트를 정확하게 식별하는 CloudWatch의 기능에 영향을 줍니다. 따라서 종속성은 쿼리를 수행하는 DB 클라이언트 이름 대신 **UnknownRemoteService**를 표시합니다.
#### 리소스 감지기
Go 자동 계측은 현재 런타임에서 리소스 감지기 구성을 지원하지 않습니다. OpenTelemetry 커뮤니티는 환경 변수를 사용하여 리소스 감지기를 구성하는 기능을 개발하고 있습니다. 향후 업데이트에서 이 기능을 확인해 보세요. 그 동안 자동 계측과 함께 CloudWatch 에이전트를 사용하여 호스트 리소스 속성을 자동으로 생성할 수 있습니다.
## 런타임 버전 지원 매트릭스
| 언어 | 실행 시간 버전 |
| --- | --- |
| Java | JVM 버전 8, 11, 17, 21, 23 |
| Python | Python 버전 3.9 이상이 지원됨 |
| .NET | 릴리스 1.6.0 이하에서는 .NET 6 및 8과 .NET Framework 4.6.2 이상을 지원함
릴리스 1.7.0 이상에서는 .NET 8 및 9와 .NET Framework 4.6.2 이상을 지원함 |
| Node.js | Node.js 버전 14, 16, 18, 20, 22 |
| PHP | PHP 버전 8.0 이상 |
| Ruby | CRuby 3.1 이상, JRuby 9.3.2.0 이상 또는 TruffleRuby 22.1 이상 |
| Golang | Golang 버전 1.18 이상 |
## 알려진 문제
Java SDK 릴리스 v1.32.5의 런타임 지표 수집은 JBoss Wildfly를 사용하는 애플리케이션에서는 작동하지 않는 것으로 알려져 있습니다. 이 문제는 Amazon CloudWatch Observability EKS 추가 기능으로 확장되므로, `2.3.0-eksbuild.1`\~`2.6.0-eksbuild.1` 버전에 영향을 미칩니다. Java SDK 릴리스 `v1.32.6` 및 Amazon CloudWatch Observability EKS 추가 기능 버전 `v3.0.0-eksbuild.1`에서 문제가 수정되었습니다.
영향을 받은 경우 Java SDK 버전을 업그레이드하거나 애플리케이션에 환경 변수 `OTEL_AWS_APPLICATION_SIGNALS_RUNTIME_ENABLED=false`를 추가하여 런타임 지표 컬렉션을 비활성화합니다.