지원되는 시스템

Application Signals는 Amazon EKS, 네이티브 Kubernetes, Amazon ECS 및 Amazon EC2에서 지원 및 테스트됩니다. Amazon EC2에서 Application Signals를 활성화하는 지침은 CloudWatch 에이전트와 AWS Distro for OpenTelemetry를 지원하는 모든 플랫폼에서 유효해야 합니다.

Java 호환성

Application Signals는 Java 애플리케이션을 지원하며 AWS Distro for OpenTelemetry와 동일한 Java 라이브러리 및 프레임워크를 지원합니다. 자세한 내용은 지원되는 라이브러리, 프레임워크, 애플리케이션 서버 및 JVM을 참조하세요.

.NET 호환성

Application Signals는 AWS Distro for OpenTelemetry와 동일한 .NET 라이브러리 및 프레임워크를 지원합니다. 자세한 내용은 지원되는 계측을 참조하세요.

Application Signals에서는 x86-64 또는 ARM64 CPU에서 실행되는 .NET 애플리케이션을 지원하며 Linux x64, Linux ARM64, Microsoft Windows Server 2022 x64를 지원합니다.

PHP 호환성

Application Signals는 OpenTelemetry 제로 코드 계측을 통해 PHP 애플리케이션을 지원합니다. 이 용도로 사용할 수 있는 AWS Distro for Open Telemetry(ADOT) SDK가 없습니다. 트랜잭션 검색이 활성화된 표준 OpenTelemetry 계측 SDK를 사용해야 합니다. PHP에서 제로 코드 계측 사용을 시작하려면 OpenTelemetry PHP 계측 설명서, PHP zero-code instrumentation의 다음 단계를 수행합니다. 자동 계측은 일반적으로 사용되는 여러 PHP 라이브러리에 사용할 수 있습니다. 자세한 내용은 OpenTelemetry 레지스트리를 참조하세요.

Ruby 호환성

Application Signals는 OpenTelemetry 제로 코드 계측을 통해 Ruby 애플리케이션을 지원합니다. 이 용도로 사용할 수 있는 AWS Distro for Open Telemetry(ADOT) SDK가 없습니다. 트랜잭션 검색이 활성화된 표준 OpenTelemetry 계측 SDK를 사용해야 합니다. Ruby에서 제로 코드 계측 사용을 시작하려면 OpenTelemetry Ruby 계측 설명서, Ruby zero-code instrumentation의 다음 단계를 수행합니다. 릴리스된 계측 라이브러리 목록은 Registry를 참조하세요.

Python 호환성

Application Signals는 AWS Distro for OpenTelemetry와 동일한 라이브러리 및 프레임워크를 지원합니다. 자세한 내용은 opentelemetry-python-contrib에서 지원되는 패키지를 참조하세요.

Python 애플리케이션에서 Application Signals를 활성화하기 전에 다음 사항에 유의하세요.

Node.js 호환성

Application Signals는 AWS Distro for OpenTelemetry와 동일한 Node.js 라이브러리 및 프레임워크를 지원합니다. 자세한 내용은 지원되는 계측을 참조하세요.

ESM 사용 Node.js에 대해 알려진 제한 사항

AWS Distro for Opentelemetry Node.js는 ECMA 스크립트 모듈(ESM)과 CommonJS(CJS)라는 두 가지 모듈 시스템을 지원합니다. OpenTelemetry JavaScript의 ESM 지원은 실험작이고 작업이 진행 중이므로 Application Signals를 활성화하려면 CJS 모듈 형식을 사용하는 것이 좋습니다. 자세한 내용은 GitHub에서 ECMA 스크립트 모듈과 CommonJS 비교를 참조하세요.

애플리케이션이 ESM이 아닌 CJS를 사용하고 있는지 확인하려면 애플리케이션이 ESM 활성화 조건을 충족하지 않는지 확인하세요. 해당 조건들에 대한 자세한 내용은 Node.js 설명서의 활성화 부분을 참조하세요.

AWS Distro for Opentelemetry Node.js는 ESM에 대한 OpenTelemetry JavaScript의 실험 지원을 기반으로 ESM을 제한적으로 지원합니다. 이것이 의미하는 바는 다음과 같습니다.

Node.js ESM 모듈 형식으로 Application Signals를 활성화하기 위해 다음과 같은 다양한 플랫폼에 다양한 설정을 제공합니다.

GoLang 호환성

Application Signals는 OpenTelemetry 제로 코드 계측을 통해 GoLang 애플리케이션을 지원합니다. 이 용도로 사용할 수 있는 AWS Distro for Open Telemetry(ADOT) SDK가 없습니다. 트랜잭션 검색이 활성화된 표준 OpenTelemetry 계측 SDK를 사용해야 합니다. GoLang에서 제로 코드 계측 사용을 시작하려면 OpenTelemetry GoLang 계측 설명서, Getting Started with OpenTelemetry Go Automatic Instrumentation의 다음 단계를 수행합니다.

구현 고려 사항 GoLang 계측

GoLang 계측을 사용하기 위한 중요한 구현 세부 정보에 대해 알아봅니다. 이 지침에서는 GoLang 애플리케이션에서 명시적 컨텍스트 전파를 구현하고 Application Signals를 설정하는 방법을 설명합니다. GoLang 계측을 적절하게 구현하면 애플리케이션의 성능을 효과적으로 추적하고 분석할 수 있습니다.

AWS SDK 계측

Golang 자동 계측 라이브러리는 AWS SDK 계측을 바로 지원하지 않습니다. otelaws 라이브러리 계측을 자동 계측 에이전트와 함께 사용해야 합니다.

다음 예제에서는 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를 참조하세요.

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 직접 호출을 컨텍스트 인식에 상응하는 항목으로 바꿉니다.

이러한 메서드는 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
}

리소스 감지기

Go 자동 계측은 현재 런타임에서 리소스 감지기 구성을 지원하지 않습니다. OpenTelemetry 커뮤니티는 환경 변수를 사용하여 리소스 감지기를 구성하는 기능을 개발하고 있습니다. 향후 업데이트에서 이 기능을 확인해 보세요. 그 동안 자동 계측과 함께 CloudWatch 에이전트를 사용하여 호스트 리소스 속성을 자동으로 생성할 수 있습니다.

런타임 버전 지원 매트릭스

알려진 문제

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를 추가하여 런타임 지표 컬렉션을 비활성화합니다.