기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다. # 에서 Step Functions 요청 데이터 추적 AWS X-Ray [AWS X-Ray](https://docs.aws.amazon.com/xray/latest/devguide/aws-xray.html)를 사용하여 상태 머신 구성 요소를 시각화하고 성능 병목 현상을 식별하며 오류가 발생한 요청 문제를 해결할 수 있습니다. 상태 머신은 트레이스 데이터를 X-Ray로 보내고 X-Ray는 데이터를 처리하여 서비스 맵과 검색 가능한 트레이스 요약을 생성합니다. 상태 시스템에 대해 X-Ray를 활성화하면 X-Ray를 사용할 수 있는 모든 AWS 리전의 Step Functions에서 실행되는 요청을 추적할 수 있습니다. 이를 통해 전체 Step Functions 요청에 대한 상세 개요를 확인할 수 있습니다. Step Functions는 업스트림 서비스에서 트레이스 ID를 전달하지 않은 경우에도 상태 머신 실행을 위해 트레이스를 X-Ray로 전송합니다. X-Ray 서비스 맵을 사용하여 X-Ray와 통합된 AWS 서비스를 포함하여 요청의 지연 시간을 볼 수 있습니다. 또한 샘플링 규칙을 구성하여 지정한 기준에 따라 어떤 요청을 어떤 샘플링 속도로 기록할지를 X-Ray에 지시할 수도 있습니다. 상태 머신에 X-Ray를 활성화하지 않고 업스트림 서비스에서 트레이스 ID를 전달하지 않으면 Step Functions는 상태 머신 실행을 위해 트레이스를 X-Ray에 전송하지 않습니다. 하지만 업스트림 서비스에서 트레이스 ID를 전달하는 경우 Step Functions는 상태 머신 실행을 위해 트레이스를 X-Ray로 전송합니다. 둘 다 지원되는 리전에서 Step Functions와 AWS X-Ray 함께를 사용할 수 있습니다. X-Ray 및 Step Functions의 리전 지원에 대한 자세한 내용은 [Step Functions](https://docs.aws.amazon.com/general/latest/gr/step-functions.html)와 [X-Ray](https://docs.aws.amazon.com/general/latest/gr/xray.html) 엔드포인트 및 할당량 페이지를 참조하세요. **X-Ray 및 Step Functions의 통합 할당량** 최대 7일 동안 데이터를 트레이스에 추가하고 X-Ray에서 트레이스 데이터를 저장하는 기간인 30일 이전의 트레이스 데이터를 쿼리할 수 있습니다. 트레이스에는 X-Ray 할당량이 적용됩니다. 다른 할당량 외에도 X-Ray는 Step Functions 상태 머신의 최소 보장 트레이스 크기인 100KiB를 제공합니다. 100KiB 이상의 트레이스 데이터가 X-Ray에 제공되면 트레이스가 정지될 수 있습니다. 다른 X-Ray 할당량에 대한 자세한 내용은 [X-Ray 엔드포인트 및 할당량](https://docs.aws.amazon.com/general/latest/gr/xray.html#limits_xray) 페이지의 서비스 할당량 섹션을 참조하세요. **중요** Step Functions는 [*Distributed Map 상태*](state-map-distributed.md)에서 시작된 하위 워크플로 실행의 X-Ray 트레이스를 지원하지 않습니다. 이러한 실행의 경우 [트레이스 문서 크기 한도](https://docs.aws.amazon.com/general/latest/gr/xray.html#limits_xray)를 초과하기 쉽기 때문입니다. **Topics** + [설정 및 구성](#xray-concept-create) + [개념](#xray-concepts) + [서비스 통합](#xray-concept-integrations) + [X-Ray 콘솔 보기](#xray-concept-tracing-details) + [Step Function에 대한 X-Ray 트레이싱 정보 보기](#concepts-xray-tracing-events) + [트레이스](#concepts-xray-traces) + [서비스 맵](#concepts-xray-tracing-overview) + [세그먼트 및 하위 세그먼트](#concepts-xray-tracing-segments) + [분석](#concepts-xray-tracing-analytics) + [구성](#concepts-xray-tracing-config) + [트레이스 맵 또는 서비스 맵에 데이터가 없으면 어떻게 되나요?](#concepts-xray-troubleshooting) ## 설정 및 구성 ### 상태 머신을 만들 때 X-Ray 트레이싱 활성화 **세부 정보 지정** 페이지에서 **X-Ray 추적 활성화**를 선택하여 새 상태 머신을 만들 때 X-Ray 트레이싱을 활성화할 수 있습니다. 1. [Step Functions 콘솔](https://console.aws.amazon.com/states/home)을 열고 **상태 머신 생성**을 선택합니다. 1. **작성 방법 선택** 페이지에서 적절한 옵션을 선택하여 상태 머신을 만듭니다. **샘플 프로젝트 실행**을 선택하면 상태 머신을 만드는 동안 X-Ray 트레이싱을 활성화할 수 없으며 상태 머신을 만든 후에 X-Ray 트레이싱을 활성화해야 합니다. 기존 상태 머신에서 X-Ray를 활성화하는 방법에 대한 자세한 내용은 [기존 상태 머신에서 X-Ray 활성화](#xray-concept-enable-existing) 섹션을 참조하세요. **다음**을 선택합니다. 1. **세부 정보 지정** 페이지에서 상태 머신을 구성합니다. 1. **X-Ray 추적 활성화**를 선택합니다. 이제 Step Functions 상태 머신에서 상태 머신 실행을 위해 트레이스를 X-Ray로 전송합니다. **참고** 기존 IAM 역할을 사용하는 경우 X-Ray 쓰기가 허용되는지 확인해야 합니다. 필요한 권한에 대한 자세한 내용은 다음 주제를 참조하세요. ### Step Functions AWS X-Ray 에서를 사용하는 IAM 정책 X-Ray 추적을 활성화하려면 추적을 허용할 수 있는 적절한 권한이 있는 IAM 정책이 필요합니다. 상태 머신에서 다른 통합 서비스를 사용하는 경우 추가 IAM 정책이 필요할 수 있습니다. 특정 서비스 통합에 대한 IAM 정책을 참조하세요. 기존 상태 머신에 X-Ray 추적을 활성화하는 경우 X-Ray 추적을 활성화할 수 있는 충분한 권한이 있는 정책을 추가해야 합니다. **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "xray:PutTraceSegments", "xray:PutTelemetryRecords", "xray:GetSamplingRules", "xray:GetSamplingTargets" ], "Resource": [ "*" ] } ] } ``` ### 기존 상태 머신에서 X-Ray 활성화 기존 상태 머신에서 X-Ray 활성화하기 1. [Step Functions 콘솔](https://console.aws.amazon.com/states/home)에서 트레이싱을 활성화하려는 상태 머신을 선택합니다. 1. **편집**을 선택합니다. 1. **X-Ray 추적 활성화**를 선택합니다. 추가적으로 변경해야 할 수도 있다는 알림이 표시됩니다. **참고** 기존 상태 머신에 X-Ray를 활성화할 때는 트레이스를 수행할 수 있도록 X-Ray에 충분한 권한을 부여하는 IAM 정책이 있는지 확인해야 합니다. 수동으로 추가하거나 생성할 수 있습니다. 자세한 내용은 [Step Functions AWS X-Ray 에서를 사용하는 IAM 정책](#xray-iam)에 대한 IAM 정책을 참조하세요. 1. (선택 사항) X-Ray 권한이 포함되도록 상태 머신의 새 역할을 자동 생성합니다. 1. **저장**을 선택합니다. ### Step Function에 대한 X-Ray 트레이싱 구성 X-Ray 추적이 활성화된 상태 시스템을 처음 실행하면 X-Ray 추적에 기본 구성 값을 사용합니다.는 애플리케이션으로 전송되는 모든 요청에 대해 데이터를 수집하지 AWS X-Ray 않습니다. 대신 통계적으로 유의미한 요청 수에 대한 데이터를 수집합니다. 기본 값은 매초 최초 요청과 추가 요청의 5% 기록입니다. 초당 하나의 요청은 *리저버*입니다. 이는 서비스가 요청을 처리 중인 동안 하나 이상의 트레이스가 매초 기록되도록 합니다. 5퍼센트는 리저버 크기를 넘는 추가 요청이 샘플링되는 *비율*입니다. 시작할 때 서비스 요금이 발생하지 않도록 하려는 경우 기본 샘플링 비율은 보수적입니다. 기본 샘플링 규칙을 수정하고 서비스 또는 요청의 속성에 따라 샘플링을 적용하는 추가 규칙을 구성하도록 X-Ray를 구성할 수 있습니다. 예를 들어 샘플링을 비활성화하고 상태를 수정하거나 또는 AWS 계정 트랜잭션을 처리하는 호출에 대한 모든 요청을 추적할 수 있습니다. 백그라운드 폴링, 상태 확인 또는 연결 유지 관리와 같은 대량 읽기 전용 직접 호출의 경우 낮은 비율로 샘플링하면서도 발생하는 문제를 관찰할 수 있을 만큼 충분한 데이터를 계속 확보할 수 있습니다. 상태 머신에 대한 샘플링 규칙 구성하기 1. [X-Ray 콘솔](https://console.aws.amazon.com/xray/home)로 이동합니다. 1. **샘플링**을 선택합니다. 1. **샘플링 규칙 생성**을 선택하여 규칙을 생성합니다. 규칙 이름을 선택하여 규칙을 편집합니다. 규칙을 선택하고 **작업**메뉴를 사용하여 규칙을 삭제합니다. 기존 샘플링 규칙의 일부(예: 이름 및 우선순위)를 변경할 수 없습니다. 대신 기존 규칙을 추가 또는 복제하고 원하는 대로 변경한 다음 새 규칙을 사용합니다. X-Ray 샘플링 규칙 및 다양한 파라미터를 구성하는 방법에 대한 자세한 내용은 [X-Ray 콘솔에서 샘플링 규칙 구성](https://docs.aws.amazon.com/xray/latest/devguide/xray-console-sampling.html)을 참조하세요. ### 업스트림 서비스 통합 Express, 동기 및 표준 워크플로와 같은 Step Functions 워크플로의 실행을 업스트림 서비스와 통합하려면 `traceHeader`를 설정해야 합니다. 이 작업은 API Gateway에서 HTTP API를 사용하는 경우 자동으로 수행됩니다. 하지만 Lambda 함수 또는 SDK를 사용하는 경우에는 [https://docs.aws.amazon.com/step-functions/latest/apireference/API_StartExecution.html](https://docs.aws.amazon.com/step-functions/latest/apireference/API_StartExecution.html) 또는 [https://docs.aws.amazon.com/step-functions/latest/apireference/API_StartSyncExecution.html](https://docs.aws.amazon.com/step-functions/latest/apireference/API_StartSyncExecution.html) API 직접 호출에서 직접 `traceHeader`를 설정해야 합니다. `traceHeader`를 `\p{ASCII}∗` 형식으로 지정해야 합니다. 또한 Step Functions에서 같은 트레이스 ID를 사용하도록 하려면 형식을 `Root={TRACE_ID};Sampled={1 or 0}`으로 지정해야 합니다. Lambda 함수를 사용하는 경우 `TRACE_ID`를 현재 세그먼트의 트레이스 ID로 바꾸고 샘플링 필드를 샘플링 모드가 true인 경우에는 `1`로, 샘플링 모드가 false인 경우에는 `0`으로 설정합니다. 트레이스 ID를 이 형식으로 제공하면 완전한 트레이스를 얻을 수 있습니다. 다음은 `traceHeader`를 지정하는 방법을 보여주기 위해 Python으로 작성된 예제입니다. ``` state_machine = config.get_string_paramter("STATE_MACHINE_ARN") if (xray_recorder.current_subsegment() is not None and xray_recorder.current_subsegment().sampled) : trace_id = "Root={};Sampled=1".format( xray_recorder.current_subsegment().trace_id ) else: trace_id = "Root=not enabled;Sampled=0" LOGGER.info("trace %s", trace_id) # execute it response = states.start_sync_execution( stateMachineArn=state_machine, input=event['body'], name=context.aws_request_id, traceHeader=trace_id ) LOGGER.info(response) ``` **X-Ray 헤더 또는 페이로드의 트레이스** X-Ray 추적의 경우 모든 AWS 서비스는 HTTP 요청의 `X-Amzn-Trace-Id` 헤더를 사용합니다. 헤더를 사용하는 것이 트레이스를 식별하는 데 선호되는 메커니즘입니다. `StartExecution` 및 `StartSyncExecution` API 작업은 요청 페이로드의 본문에서 `traceHeader`를 사용할 수도 있습니다. **두** 소스가 모두 제공된 경우는 요청 본문의 **값보다 헤더** 값(기본 설정)을 Step Functions 사용합니다. ## 개념 ### X-Ray 콘솔 AWS X-Ray 콘솔에서 상태 시스템에 X-Ray가 활성화된 경우 애플리케이션이 처리하는 요청에 대한 서비스 맵 및 추적을 볼 수 있습니다. 상태 머신 실행을 위해 X-Ray 콘솔에 액세스하는 방법은 [X-Ray 콘솔 보기](#xray-concept-tracing-details) 섹션을 참조하세요. X-Ray 콘솔에 대한 자세한 내용은 [X-Ray 콘솔 설명서](https://docs.aws.amazon.com/xray/latest/devguide/xray-console.html)를 참조하세요. ### 세그먼트, 하위 세그먼트 및 트레이스 **세그먼트**는 상태 머신에 대한 요청 정보를 기록합니다. 여기에는 상태 머신에서 수행하는 작업과 같은 정보가 포함되며 다운스트림 호출에 대한 정보가 포함된 **하위 세그먼트**도 포함될 수 있습니다. **트레이스**는 단일 요청에 의해 생성된 모든 세그먼트를 수집합니다. ### 샘플링 효율적인 트레이스를 보장하고 애플리케이션에서 처리하는 요청의 대표적 샘플을 제공하기 위해 X-Ray는 **샘플링** 알고리즘을 적용하여 트레이스되는 요청을 결정합니다. 샘플링 규칙을 편집하여 이를 변경할 수 있습니다. ### Metrics 상태 머신의 경우 X-Ray는 간접 호출 시간, 상태 전환 시간, Step Functions의 전체 실행 시간 및 이 실행 시간의 차이를 측정합니다. X-Ray 콘솔을 통해 이 정보에 액세스할 수 있습니다. ### 분석 AWS X-Ray 분석 콘솔은 추적 데이터를 해석하기 위한 대화형 도구입니다. 현재 트레이스 집합과 연결된 지표 및 필드의 그래프와 패널을 클릭하면 더욱 세부적인 필터로 활성 데이터세트를 구체화할 수 있습니다. 상태 머신이 수행되는 방식을 분석하여 성능 문제를 찾고 식별할 수 있습니다. X-Ray 분석에 대한 자세한 내용은 [AWS X-Ray Analytics 콘솔과 상호 작용을 참조하세요](https://docs.aws.amazon.com/xray/latest/devguide/xray-console-analytics.html). ## Step Functions 서비스 통합 및 X-Ray Step Functions와 통합되는 일부 AWS 서비스는 요청에 추적 헤더를 추가하거나, X-Ray 데몬을 실행하거나, 샘플링 결정을 내리고 추적 데이터를 X-Ray에 업로드 AWS X-Ray 하여와 통합합니다. 다른 항목은 AWS X-Ray SDK를 사용하여 계측해야 합니다. 몇몇 서비스는 아직 X-Ray 통합을 지원하지 않습니다. Step Functions와 서비스 통합을 사용할 때 완전한 트레이스 데이터를 제공하려면 X-Ray 통합이 필요합니다. ### 기본 X-Ray 지원 기본 X-Ray 지원과 서비스 통합에는 다음이 포함됩니다. + [ Amazon Simple Notification Service](https://docs.aws.amazon.com/xray/latest/devguide/xray-services-sns.html) + [Amazon Simple Queue Service](https://docs.aws.amazon.com/xray/latest/devguide/xray-services-sqs.html) + [AWS Lambda](https://docs.aws.amazon.com/xray/latest/devguide/xray-services-lambda.html) + AWS Step Functions ### 계측 필요 [X-Ray 기기](https://docs.aws.amazon.com/xray/latest/devguide/aws-xray.html)가 필요한 서비스 통합: + Amazon Elastic Container Service + AWS Batch + AWS Fargate ### 클라이언트 측 트레이스 전용 다른 서비스 통합은 X-Ray 트레이스를 지원하지 않습니다. 하지만 클라이언트 측 트레이스를 계속 수집할 수 있습니다. + Amazon DynamoDB + Amazon EMR + Amazon SageMaker AI + AWS CodeBuild + AWS Glue ## X-Ray 콘솔 보기 X-Ray는 서비스로부터 데이터를 세그먼트로 수신합니다. X-Ray는 공통 요청이 있는 세그먼트를 트레이스로 그룹화합니다. X-Ray는 트레이스를 처리하여 애플리케이션을 시각적으로 표현하는 서비스 그래프를 생성합니다. 상태 머신 실행을 시작한 후 실행 **세부 정보** 섹션에서 **X-Ray 트레이스 맵** 링크를 선택하면 X-Ray 트레이스를 볼 수 있습니다. 상태 머신에 X-Ray를 활성화한 후에는 X-Ray 콘솔에서 해당 실행에 대한 트레이싱 정보를 볼 수 있습니다. ## Step Function에 대한 X-Ray 트레이싱 정보 보기 다음 단계에서는 X-Ray를 활성화하고 실행을 실행한 후 콘솔에 표시되는 정보의 종류를 보여줍니다. [Amazon SQS, Amazon SNS, Lambda를 사용하여 콜백 패턴 예제 생성](callback-task-sample-sqs.md) 샘플 프로젝트의 X-Ray 트레이스가 표시됩니다. ## 트레이스 실행이 완료되면 X-Ray 콘솔로 이동합니다. 여기서 X-Ray **트레이스** 페이지가 표시됩니다. 이 페이지는 서비스 맵 개요뿐만 아니라 상태 머신의 트레이스 및 세그먼트 정보도 표시됩니다. ![상태 머신에 대한 X-Ray 트레이스의 예시 스크린샷입니다.](http://docs.aws.amazon.com/ko_kr/step-functions/latest/dg/images/xray-tracing-overview.png) ## 서비스 맵 X-Ray 콘솔의 서비스 맵을 사용하면 지연 시간이 긴 연결과 같은 오류가 발생한 서비스를 식별하고 실패한 요청의 트레이스를 확인할 수 있습니다. ![X-Ray 트레이스의 서비스 맵에 초점을 맞춘 예시 스크린샷입니다.](http://docs.aws.amazon.com/ko_kr/step-functions/latest/dg/images/xray-tracing-servicemap.png) 트레이스 맵에서 서비스 노드를 선택하여 해당 노드에 대한 요청을 보거나 두 노드 간의 엣지를 선택하여 해당 연결로 이동하는 요청을 볼 수 있습니다. 여기에서는 `WaitForCallBack` 노드가 선택되었으므로 해당 실행과 응답 상태에 대한 추가 정보를 볼 수 있습니다. ![X-Ray 추적 노드에 대한 세부 정보 예제입니다.](http://docs.aws.amazon.com/ko_kr/step-functions/latest/dg/images/xray-tracing-servicemap-detail.png) X-Ray 서비스 맵이 상태 머신과 상관 관계를 지정하는 방법을 확인할 수 있습니다. X-Ray를 지원하는 경우 Step Functions에서 직접적으로 호출하는 각 서비스 통합에 대한 서비스 맵 노드가 있습니다. ![추적 중인 상태 머신의 그래픽 표현 예제입니다.](http://docs.aws.amazon.com/ko_kr/step-functions/latest/dg/images/sample-callback-example.png) ## 세그먼트 및 하위 세그먼트 **트레이스**는 단일 요청에 의해 생성된 **세그먼트** 컬렉션입니다. 각 세그먼트는 리소스 이름, 요청의 세부 정보 및 완료된 작업의 세부 정보를 제공합니다. **트레이스** 페이지에서 세그먼트를 확인할 수 있으며 이 페이지를 확장하면 해당 하위 세그먼트도 확인할 수 있습니다. 세그먼트나 하위 세그먼트를 선택하여 해당 세그먼트에 대한 자세한 정보를 볼 수 있습니다. 서비스 맵에는 노드마다 다른 세그먼트가 있습니다. ![상태 머신에 대한 세그먼트 및 하위 세그먼트의 예제 스크린샷입니다.](http://docs.aws.amazon.com/ko_kr/step-functions/latest/dg/images/xray-tracing-segments.png) 세그먼트를 선택하면 리소스 이름, 요청의 세부 정보 및 완료된 작업의 세부 정보가 제공됩니다. 세그먼트는 완료된 작업에 대한 데이터를 하위 세그먼트로 구분할 수 있습니다. 하위 세그먼트를 선택하면 자세한 타이밍 정보와 세부 정보가 표시됩니다. 하위 세그먼트에는 AWS 서비스, 외부 HTTP API 또는 SQL 데이터베이스 호출에 대한 추가 세부 정보가 포함될 수 있습니다. ## 분석 AWS X-Ray **분석** 콘솔은 추적 데이터를 해석하기 위한 대화형 도구입니다. 이 콘솔을 사용하면 상태 머신이 수행되는 방식을 더욱 쉽게 이해할 수 있습니다. 대화형 응답 시간 및 시계열 그래프를 통해 트레이스를 탐색, 분석 및 시각화하여 성능 및 지연 시간 문제를 찾을 수 있습니다. 현재 트레이스 집합과 연결된 지표 및 필드의 그래프와 패널을 클릭하면 더욱 세부적인 필터로 활성 데이터세트를 구체화할 수 있습니다. ## 구성 X-Ray 콘솔에서 샘플링 및 암호화 옵션을 구성할 수 있습니다. + **샘플링**을 선택하여 샘플링 속도와 구성에 대한 세부 정보를 봅니다. 샘플링 규칙을 변경하여 기록할 데이터 양을 제어하고 특정 요구 사항에 맞게 샘플링 동작을 수정할 수 있습니다. + **암호화**를 선택하여 암호화 설정을 수정합니다. X-Ray에서 트레이스와 저장된 날짜를 암호화하는 기본 설정을 사용하거나 필요한 경우 KMS 키를 선택할 수 있습니다. 후자의 경우 표준 [AWS KMS](https://docs.aws.amazon.com/kms/latest/developerguide/) 요금이 적용됩니다. ## 트레이스 맵 또는 서비스 맵에 데이터가 없으면 어떻게 되나요? X-Ray를 활성화했지만 X-Ray 콘솔에 데이터가 표시되지 않으면 다음을 확인합니다. + IAM 역할은 X-Ray에 기록할 수 있도록 올바르게 설정되었습니다. + 샘플링 규칙에서 데이터 샘플링을 허용합니다. + 새로 생성되거나 수정된 IAM 역할이 적용되기까지 짧은 지연이 발생할 수 있으므로 몇 분 후에 트레이스 또는 서비스 맵을 다시 확인합니다. + X-Ray 추적 패널에 **데이터를 찾을 수 없음**이 표시되면 [ IAM 계정 설정을](https://console.aws.amazon.com/iam/home?#/account_settings) 확인하고 AWS Security Token Service 가 의도한 리전에 대해 활성화되어 있는지 확인합니다. 자세한 내용은 *IAM 사용 설명서*의 [AWS STS 에서 활성화 및 비활성화 AWS 리전](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_enable-regions.html#sts-regions-activate-deactivate)를 참조하세요.