기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다. # Amazon EMR용 Apache Spark 문제 해결 에이전트란? ## 소개 Amazon EMR용 Apache Spark 문제 해결 에이전트는 Amazon EMR, AWS Glue 및 Amazon SageMaker 노트북에서 Apache Spark 애플리케이션의 문제 해결을 간소화하는 대화형 AI 기능입니다. 기존 Spark 문제 해결에서는 로그, 성능 지표 및 오류 패턴을 광범위하게 수동으로 분석하여 근본 원인과 코드 수정을 식별해야 합니다. 에이전트는 자연어 프롬프트, 자동화된 워크로드 분석 및 지능형 코드 권장 사항을 통해이 프로세스를 간소화합니다. 에이전트를 사용하여 PySpark 및 Scala 애플리케이션 실패 문제를 해결할 수 있습니다. 에이전트는 실패한 작업을 분석하고, 성능 병목 현상을 식별하고, 실행 가능한 권장 사항 및 코드 수정을 제공하는 동시에 구현 결정을 완벽하게 제어할 수 있습니다. **참고** Apache Spark 문제 해결 에이전트는 Amazon EMR의 일부로 추가 비용 없이 사용할 수 있습니다. 에이전트는 분석 및 권장 사항만 제공합니다. 권장 수정 사항을 검증하기 위해 애플리케이션을 실행할 때 사용하는 Amazon EMR 리소스에 대해서만 비용을 지불합니다. ## 아키텍처 개요 문제 해결 에이전트에는 상호 작용을 위한 개발 환경의 MCP 호환 AI 도우미, 클라이언트와 AWS 서비스 간의 보안 통신 및 인증을 처리하는 [용 MCP 프록시 AWS](https://github.com/aws/mcp-proxy-for-aws), Amazon EMR, Glue 및 Amazon SageMaker 노트북을 위한 특수 Spark 문제 해결 도구를 `(preview)` 제공하는 Amazon SageMaker Unified Studio 원격 MCP 서버의 세 가지 주요 구성 요소가 있습니다. AWS 이 다이어그램은 AI 도우미를 통해 Amazon SageMaker Unified Studio 원격 MCP 서버와 상호 작용하는 방법을 보여줍니다. ![\[Spark 에이전트 아키텍처 문제 해결.\]](http://docs.aws.amazon.com/ko_kr/emr/latest/ReleaseGuide/images/spark-troubleshooting-agent-architecture.png) AI 어시스턴트는 다음 단계에 따라 MCP 서버에서 제공하는 특수 도구를 사용하여 문제 해결을 오케스트레이션합니다. + **특성 추출 및 컨텍스트 구축:** 에이전트는 Spark 기록 서버 로그, 구성 설정 및 오류 추적을 포함하여 Spark 애플리케이션에서 원격 측정 데이터를 자동으로 수집하고 분석합니다. 주요 성능 지표, 리소스 사용률 패턴 및 장애 서명을 추출하여 지능형 문제 해결을 위한 포괄적인 컨텍스트 프로파일을 구축합니다. + **GenAI 근본 원인 분석기 및 권장 엔진:** 에이전트는 AI 모델과 Spark 지식 기반을 활용하여 추출된 기능을 상호 연관시키고 성능 문제 또는 장애의 근본 원인을 식별합니다. Spark 애플리케이션 실행에서 무엇이 잘못되었는지에 대한 진단 인사이트와 분석을 제공합니다. + **GenAI Spark 코드 권장 사항:** 이전 단계의 근본 원인 분석을 기반으로 에이전트는 기존 코드 패턴을 분석하고 애플리케이션 장애에 대한 코드 수정이 필요한 비효율적인 작업을 식별합니다. 구체적인 예제를 통해 특정 코드 수정, 구성 조정 및 아키텍처 개선 등 실행 가능한 권장 사항을 제공합니다. **Topics** + [소개](#spark-troubleshooting-agent-intro) + [아키텍처 개요](#spark-troubleshooting-agent-architecture) + [에이전트 문제 해결을 위한 설정](spark-troubleshooting-agent-setup.md) + [문제 해결 에이전트 사용](spark-troubleshooting-using-troubleshooting-agent.md) + [기능 및 기능](spark-troubleshooting-features.md) + [문제 해결 및 Q&A](spark-troubleshooting-agent-troubleshooting.md) + [세부 정보의 Spark 에이전트 워크플로 문제 해결](spark-troubleshooting-agent-workflow.md) + [프롬프트 예제](spark-troubleshooting-agent-prompt-examples.md) + [IAM 역할 설정](spark-troubleshooting-agent-iam-setup.md) + [Spark 문제 해결 도구 사용](spark-troubleshooting-agent-using-tools.md) + [Amazon SageMaker Unified Studio MCP에 대한 인터페이스 VPC 엔드포인트 구성](spark-troubleshooting-agent-vpc-endpoints.md) + [Apache Spark 문제 해결 에이전트의 리전 간 처리](spark-troubleshooting-cross-region-processing.md) + [를 사용하여 Amazon SageMaker Unified Studio MCP 호출 로깅 AWS CloudTrail](spark-troubleshooting-cloudtrail-integration.md) + [Apache Spark 에이전트의 서비스 개선 사항](spark-agents-service-improvements.md) # 에이전트 문제 해결을 위한 설정 **참고** Apache Spark 문제 해결 에이전트는 리전 간 추론을 사용하여 자연어 요청을 처리하고 응답을 생성합니다. 자세한 내용은 단원을 참조하십시오[Apache Spark 문제 해결 에이전트의 리전 간 처리](spark-troubleshooting-cross-region-processing.md). Amazon SageMaker Unified Studio MCP 서버는 미리 보기 중이며 변경될 수 있습니다. ## 사전 조건 Kiro CLI와의 통합을 위한 설정 프로세스를 시작하기 전에 워크스테이션에 다음이 설치되어 있는지 확인합니다. + [AWS CLI 설치 ](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) + [ Python 3.10 이상 설치 ](https://www.python.org/downloads/release/python-3100/) + [ 용 MCP 프록시용 `uv` 패키지 관리자 설치 ](https://docs.astral.sh/uv/getting-started/installation/) [AWS](https://github.com/aws/mcp-proxy-for-aws?tab=readme-ov-file) + [ Kiro CLI 설치 ](https://kiro.dev/docs/cli/) + AWS 구성된 로컬 자격 증명([AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-configure.html), 환경 변수 또는 IAM 역할을 통해) - EMR 검증 작업 실행을 위해 업그레이드된 작업 아티팩트 업로드와 같은 로컬 작업에 사용됩니다. ## 리소스 설정 AWS CloudFormation 템플릿을 사용하여 MCP 서버의 리소스를 설정할 수 있습니다. 이 템플릿은 요구 사항에 맞게 수정해야 하는 샘플입니다. 템플릿은 문제 해결 프로세스를 위해 다음 리소스를 생성합니다. 1. MCP Server를 호출할 수 있는 권한과 선택한 플랫폼의 문제 해결 프로세스에 필요한 권한이 있는 IAM 역할입니다. 다음 표에서 **스택 시작** 버튼 중 하나를 선택하십시오. 그러면 해당 리전의 AWS CloudFormation 콘솔에서 스택이 시작됩니다. | 리전 | 시작 | | --- | --- | | 미국 동부(오하이오) | [https://console.aws.amazon.com/cloudformation/home?region=us-east-2#/stacks/new?templateURL=https%3A%2F%2Fsmus-mcp-cfn-template-prod-us-east-2.s3.us-east-2.amazonaws.com%2Fcloudformation%2Fspark-troubleshooting-mcp-setup.yaml&stackName=spark-troubleshooting-mcp-setup](https://console.aws.amazon.com/cloudformation/home?region=us-east-2#/stacks/new?templateURL=https%3A%2F%2Fsmus-mcp-cfn-template-prod-us-east-2.s3.us-east-2.amazonaws.com%2Fcloudformation%2Fspark-troubleshooting-mcp-setup.yaml&stackName=spark-troubleshooting-mcp-setup) | | 미국 동부(버지니아 북부) | [https://console.aws.amazon.com/cloudformation/home?region=us-east-1#/stacks/new?templateURL=https%3A%2F%2Fsmus-mcp-cfn-template-prod-us-east-1.s3.us-east-1.amazonaws.com%2Fcloudformation%2Fspark-troubleshooting-mcp-setup.yaml&stackName=spark-troubleshooting-mcp-setup](https://console.aws.amazon.com/cloudformation/home?region=us-east-1#/stacks/new?templateURL=https%3A%2F%2Fsmus-mcp-cfn-template-prod-us-east-1.s3.us-east-1.amazonaws.com%2Fcloudformation%2Fspark-troubleshooting-mcp-setup.yaml&stackName=spark-troubleshooting-mcp-setup) | | 미국 서부(오레곤) | [https://console.aws.amazon.com/cloudformation/home?region=us-west-2#/stacks/new?templateURL=https%3A%2F%2Fsmus-mcp-cfn-template-prod-us-west-2.s3.us-west-2.amazonaws.com%2Fcloudformation%2Fspark-troubleshooting-mcp-setup.yaml&stackName=spark-troubleshooting-mcp-setup](https://console.aws.amazon.com/cloudformation/home?region=us-west-2#/stacks/new?templateURL=https%3A%2F%2Fsmus-mcp-cfn-template-prod-us-west-2.s3.us-west-2.amazonaws.com%2Fcloudformation%2Fspark-troubleshooting-mcp-setup.yaml&stackName=spark-troubleshooting-mcp-setup) | | 아시아 태평양(도쿄) | [https://console.aws.amazon.com/cloudformation/home?region=ap-northeast-1#/stacks/new?templateURL=https%3A%2F%2Fsmus-mcp-cfn-template-prod-ap-northeast-1.s3.ap-northeast-1.amazonaws.com%2Fcloudformation%2Fspark-troubleshooting-mcp-setup.yaml&stackName=spark-troubleshooting-mcp-setup](https://console.aws.amazon.com/cloudformation/home?region=ap-northeast-1#/stacks/new?templateURL=https%3A%2F%2Fsmus-mcp-cfn-template-prod-ap-northeast-1.s3.ap-northeast-1.amazonaws.com%2Fcloudformation%2Fspark-troubleshooting-mcp-setup.yaml&stackName=spark-troubleshooting-mcp-setup) | | 유럽(아일랜드) | [https://console.aws.amazon.com/cloudformation/home?region=eu-west-1#/stacks/new?templateURL=https%3A%2F%2Fsmus-mcp-cfn-template-prod-eu-west-1.s3.eu-west-1.amazonaws.com%2Fcloudformation%2Fspark-troubleshooting-mcp-setup.yaml&stackName=spark-troubleshooting-mcp-setup](https://console.aws.amazon.com/cloudformation/home?region=eu-west-1#/stacks/new?templateURL=https%3A%2F%2Fsmus-mcp-cfn-template-prod-eu-west-1.s3.eu-west-1.amazonaws.com%2Fcloudformation%2Fspark-troubleshooting-mcp-setup.yaml&stackName=spark-troubleshooting-mcp-setup) | | 아시아 태평양(싱가포르) | [https://console.aws.amazon.com/cloudformation/home?region=ap-southeast-1#/stacks/new?templateURL=https%3A%2F%2Fsmus-mcp-cfn-template-prod-ap-southeast-1.s3.ap-southeast-1.amazonaws.com%2Fcloudformation%2Fspark-troubleshooting-mcp-setup.yaml&stackName=spark-troubleshooting-mcp-setup](https://console.aws.amazon.com/cloudformation/home?region=ap-southeast-1#/stacks/new?templateURL=https%3A%2F%2Fsmus-mcp-cfn-template-prod-ap-southeast-1.s3.ap-southeast-1.amazonaws.com%2Fcloudformation%2Fspark-troubleshooting-mcp-setup.yaml&stackName=spark-troubleshooting-mcp-setup) | | 아시아 태평양(시드니) | [https://console.aws.amazon.com/cloudformation/home?region=ap-southeast-2#/stacks/new?templateURL=https%3A%2F%2Fsmus-mcp-cfn-template-prod-ap-southeast-2.s3.ap-southeast-2.amazonaws.com%2Fcloudformation%2Fspark-troubleshooting-mcp-setup.yaml&stackName=spark-troubleshooting-mcp-setup](https://console.aws.amazon.com/cloudformation/home?region=ap-southeast-2#/stacks/new?templateURL=https%3A%2F%2Fsmus-mcp-cfn-template-prod-ap-southeast-2.s3.ap-southeast-2.amazonaws.com%2Fcloudformation%2Fspark-troubleshooting-mcp-setup.yaml&stackName=spark-troubleshooting-mcp-setup) | | 캐나다(중부) | [https://console.aws.amazon.com/cloudformation/home?region=ca-central-1#/stacks/new?templateURL=https%3A%2F%2Fsmus-mcp-cfn-template-prod-ca-central-1.s3.ca-central-1.amazonaws.com%2Fcloudformation%2Fspark-troubleshooting-mcp-setup.yaml&stackName=spark-troubleshooting-mcp-setup](https://console.aws.amazon.com/cloudformation/home?region=ca-central-1#/stacks/new?templateURL=https%3A%2F%2Fsmus-mcp-cfn-template-prod-ca-central-1.s3.ca-central-1.amazonaws.com%2Fcloudformation%2Fspark-troubleshooting-mcp-setup.yaml&stackName=spark-troubleshooting-mcp-setup) | | 남아메리카(상파울루) | [https://console.aws.amazon.com/cloudformation/home?region=sa-east-1#/stacks/new?templateURL=https%3A%2F%2Fsmus-mcp-cfn-template-prod-sa-east-1.s3.sa-east-1.amazonaws.com%2Fcloudformation%2Fspark-troubleshooting-mcp-setup.yaml&stackName=spark-troubleshooting-mcp-setup](https://console.aws.amazon.com/cloudformation/home?region=sa-east-1#/stacks/new?templateURL=https%3A%2F%2Fsmus-mcp-cfn-template-prod-sa-east-1.s3.sa-east-1.amazonaws.com%2Fcloudformation%2Fspark-troubleshooting-mcp-setup.yaml&stackName=spark-troubleshooting-mcp-setup) | | 유럽(프랑크푸르트) | [https://console.aws.amazon.com/cloudformation/home?region=eu-central-1#/stacks/new?templateURL=https%3A%2F%2Fsmus-mcp-cfn-template-prod-eu-central-1.s3.eu-central-1.amazonaws.com%2Fcloudformation%2Fspark-troubleshooting-mcp-setup.yaml&stackName=spark-troubleshooting-mcp-setup](https://console.aws.amazon.com/cloudformation/home?region=eu-central-1#/stacks/new?templateURL=https%3A%2F%2Fsmus-mcp-cfn-template-prod-eu-central-1.s3.eu-central-1.amazonaws.com%2Fcloudformation%2Fspark-troubleshooting-mcp-setup.yaml&stackName=spark-troubleshooting-mcp-setup) | | 유럽(스톡홀름) | [https://console.aws.amazon.com/cloudformation/home?region=eu-north-1#/stacks/new?templateURL=https%3A%2F%2Fsmus-mcp-cfn-template-prod-eu-north-1.s3.eu-north-1.amazonaws.com%2Fcloudformation%2Fspark-troubleshooting-mcp-setup.yaml&stackName=spark-troubleshooting-mcp-setup](https://console.aws.amazon.com/cloudformation/home?region=eu-north-1#/stacks/new?templateURL=https%3A%2F%2Fsmus-mcp-cfn-template-prod-eu-north-1.s3.eu-north-1.amazonaws.com%2Fcloudformation%2Fspark-troubleshooting-mcp-setup.yaml&stackName=spark-troubleshooting-mcp-setup) | | 유럽(런던) | [https://console.aws.amazon.com/cloudformation/home?region=eu-west-2#/stacks/new?templateURL=https%3A%2F%2Fsmus-mcp-cfn-template-prod-eu-west-2.s3.eu-west-2.amazonaws.com%2Fcloudformation%2Fspark-troubleshooting-mcp-setup.yaml&stackName=spark-troubleshooting-mcp-setup](https://console.aws.amazon.com/cloudformation/home?region=eu-west-2#/stacks/new?templateURL=https%3A%2F%2Fsmus-mcp-cfn-template-prod-eu-west-2.s3.eu-west-2.amazonaws.com%2Fcloudformation%2Fspark-troubleshooting-mcp-setup.yaml&stackName=spark-troubleshooting-mcp-setup) | | 유럽(파리) | [https://console.aws.amazon.com/cloudformation/home?region=eu-west-3#/stacks/new?templateURL=https%3A%2F%2Fsmus-mcp-cfn-template-prod-eu-west-3.s3.eu-west-3.amazonaws.com%2Fcloudformation%2Fspark-troubleshooting-mcp-setup.yaml&stackName=spark-troubleshooting-mcp-setup](https://console.aws.amazon.com/cloudformation/home?region=eu-west-3#/stacks/new?templateURL=https%3A%2F%2Fsmus-mcp-cfn-template-prod-eu-west-3.s3.eu-west-3.amazonaws.com%2Fcloudformation%2Fspark-troubleshooting-mcp-setup.yaml&stackName=spark-troubleshooting-mcp-setup) | | 아시아 태평양(서울) | [https://console.aws.amazon.com/cloudformation/home?region=ap-northeast-2#/stacks/new?templateURL=https%3A%2F%2Fsmus-mcp-cfn-template-prod-ap-northeast-2.s3.ap-northeast-2.amazonaws.com%2Fcloudformation%2Fspark-troubleshooting-mcp-setup.yaml&stackName=spark-troubleshooting-mcp-setup](https://console.aws.amazon.com/cloudformation/home?region=ap-northeast-2#/stacks/new?templateURL=https%3A%2F%2Fsmus-mcp-cfn-template-prod-ap-northeast-2.s3.ap-northeast-2.amazonaws.com%2Fcloudformation%2Fspark-troubleshooting-mcp-setup.yaml&stackName=spark-troubleshooting-mcp-setup) | | 아시아 태평양(뭄바이) | [https://console.aws.amazon.com/cloudformation/home?region=ap-south-1#/stacks/new?templateURL=https%3A%2F%2Fsmus-mcp-cfn-template-prod-ap-south-1.s3.ap-south-1.amazonaws.com%2Fcloudformation%2Fspark-troubleshooting-mcp-setup.yaml&stackName=spark-troubleshooting-mcp-setup](https://console.aws.amazon.com/cloudformation/home?region=ap-south-1#/stacks/new?templateURL=https%3A%2F%2Fsmus-mcp-cfn-template-prod-ap-south-1.s3.ap-south-1.amazonaws.com%2Fcloudformation%2Fspark-troubleshooting-mcp-setup.yaml&stackName=spark-troubleshooting-mcp-setup) | **스택 세부 정보 지정** 페이지로 이동하여 **스택 이름을** 입력합니다. **파라미터(Parameters)** 아래에 추가 정보를 입력합니다. 다음 정보를 제공하고 스택 생성을 진행합니다. + **TroubleshootingRoleName** - 문제 해결 작업을 위해 생성할 IAM 역할의 이름입니다. + **EnableEMREC2** - EMR-EC2 문제 해결 권한 활성화(기본값: true) + **EnableEMRServerless** - EMR-Serverless 문제 해결 권한 활성화(기본값: true) + **EnableGlue** - Glue 문제 해결 권한 활성화(기본값: true) + **CloudWatchKmsKeyArn** - (선택 사항) CloudWatch Logs 암호화를 위한 기존 KMS 키의 ARN(EMR Serverless만 해당, 기본 암호화를 위해 비워둠) [CloudFormation 템플릿을](https://github.com/aws-samples/aws-emr-utilities/blob/03c20fece616de23ec0ea5389f0113a5bc65fc3a/utilities/apache-spark-agents/spark-troubleshooting-agent-cloudformation/spark-troubleshooting-mcp-setup.yaml) 다운로드 및 검토하고, 위의 옵션을 지정하고, CloudFormation CLI 명령을 사용하여 템플릿을 직접 시작할 수도 있습니다. 아래 예제를 참조하세요. ``` # deploy the stack with CloudFormation CLI commands aws cloudformation deploy \ --template-file spark-troubleshooting-mcp-setup.yaml \ --stack-name spark-troubleshooting-mcp-setup \ --region \ --capabilities CAPABILITY_NAMED_IAM \ --parameter-overrides \ TroubleshootingRoleName=spark-troubleshooting-role # retrieve the 1-line instruction to set the local environment variables, which will be used for the following MCP server configuration aws cloudformation describe-stacks \ --stack-name spark-troubleshooting-mcp-setup \ --region \ --query "Stacks[0].Outputs[?OutputKey=='ExportCommand'].OutputValue" \ --output text ``` 출력 탭을 열고(또는 위의 CloudFormation describe-stacks CLI 명령에서 검색) CloudFormation 출력에서 1줄 명령을 복사하여 환경 변수를 설정한 다음 로컬 환경에서 실행합니다. 1줄 지침의 예: ``` export SMUS_MCP_REGION= && export IAM_ROLE=arn:aws:iam::111122223333:role/spark-troubleshooting-role-xxxxxx ``` 그런 다음 로컬에서 다음 명령을 실행하여 IAM 프로파일 및 MCP 서버 구성을 설정합니다. ``` # Step 1: Configure AWS CLI Profile aws configure set profile.smus-mcp-profile.role_arn ${IAM_ROLE} aws configure set profile.smus-mcp-profile.source_profile aws configure set profile.smus-mcp-profile.region ${SMUS_MCP_REGION} # Step 2: if you are using kiro CLI, use the following command to add the MCP configuration # Add Spark Troubleshooting MCP Server kiro-cli-chat mcp add \ --name "sagemaker-unified-studio-mcp-troubleshooting" \ --command "uvx" \ --args "[\"mcp-proxy-for-aws@latest\",\"https://sagemaker-unified-studio-mcp.${SMUS_MCP_REGION}.api.aws/spark-troubleshooting/mcp\", \"--service\", \"sagemaker-unified-studio-mcp\", \"--profile\", \"smus-mcp-profile\", \"--region\", \"${SMUS_MCP_REGION}\", \"--read-timeout\", \"180\"]" \ --timeout 180000 \ --scope global # Add Spark Code Recommendation MCP Server kiro-cli-chat mcp add \ --name "sagemaker-unified-studio-mcp-code-rec" \ --command "uvx" \ --args "[\"mcp-proxy-for-aws@latest\",\"https://sagemaker-unified-studio-mcp.${SMUS_MCP_REGION}.api.aws/spark-code-recommendation/mcp\", \"--service\", \"sagemaker-unified-studio-mcp\", \"--profile\", \"smus-mcp-profile\", \"--region\", \"${SMUS_MCP_REGION}\", \"--read-timeout\", \"180\"]" \ --timeout 180000 \ --scope global ``` MCP 서버 구성을 `~/.kiro/settings/mcp.json` 포함하도록 아래와 같이 업데이트해야 합니다. ``` { "mcpServers": { "sagemaker-unified-studio-mcp-troubleshooting": { "type": "stdio", "command": "uvx", "args": [ "mcp-proxy-for-aws@latest", "https://sagemaker-unified-studio-mcp.us-east-1.api.aws/spark-troubleshooting/mcp", "--service", "sagemaker-unified-studio-mcp", "--profile", "smus-mcp-profile", "--region", "us-east-1", "--read-timeout", "180" ], "timeout": 180000, "disabled": false }, "sagemaker-unified-studio-mcp-code-rec": { "type": "stdio", "command": "uvx", "args": [ "mcp-proxy-for-aws@latest", "https://sagemaker-unified-studio-mcp.us-east-1.api.aws/spark-code-recommendation/mcp", "--service", "sagemaker-unified-studio-mcp", "--profile", "smus-mcp-profile", "--region", "us-east-1", "--read-timeout", "180" ], "timeout": 180000, "disabled": false } } } ``` Kiro, Cline 및 GitHub CoPilot과 같은 다양한 MCP 클라이언트에 대한 구성 지침은 섹션을 참조[지원되는 인터페이스](spark-troubleshooting-using-troubleshooting-agent.md#supported-interfaces)하세요. # 문제 해결 에이전트 사용 ## 지원되는 배포 모드 Amazon EMR용 Apache Spark 문제 해결 에이전트는 자동화된 오류 진단, 성능 병목 현상 식별, 코드 권장 사항 및 다음 Spark 배포 모드의 향상된 애플리케이션 성능을 위한 실행 가능한 제안 등 장애가 발생한 Spark 워크로드에 대한 포괄적인 분석 기능을 지원합니다. + EMR on EC2 + EMR Serverless + AWS Glue 자세한 기능, 용량 및 제한 사항을 알아보려면 [기능 및 기능](spark-troubleshooting-features.md) 섹션을 참조하세요. ## 지원되는 인터페이스 ### Amazon SageMaker 노트북 내 셀 문제 해결 Amazon SageMaker Notebooks의 문제 해결 경험에 대한 데모입니다. 노트북 셀 장애의 경우 `Fix with AI` 버튼을 클릭하여 Amazon SageMaker Notebook Agent에 분석 요청 실패 문제를 해결하고 코드에서 오류가 발생한 경우 가능한 코드 수정을 요청할 수 있습니다. [![AWS Videos](http://img.youtube.com/vi/https://www.youtube.com/embed/btW8hwio0tE/0.jpg)](http://www.youtube.com/watch?v=https://www.youtube.com/embed/btW8hwio0tE) ### Kiro CLI를 사용한 Glue 및 EMR Spark 애플리케이션 문제 해결 Kiro CLI 또는 AI Assistant를 시작하고 문제 해결 프로세스를 위해 로드된 도구를 확인합니다. ``` ... sagemaker-unified-studio-mcp-code-rec (MCP) - spark_code_recommendation not trusted sagemaker-unified-studio-mcp-troubleshooting (MCP) - analyze_spark_workload not trusted ... ``` 이제 Spark 문제 해결 에이전트 워크플로를 시작할 준비가 되었습니다. Kiro CLI의 문제 해결 경험에 대한 데모입니다. 다음 프롬프트를 사용하여 문제 해결 프로세스를 시작할 수 있습니다. ``` Analyze my Glue job. The job name is "xxx" and the job run id is "xxx" ``` [![AWS Videos](http://img.youtube.com/vi/https://www.youtube.com/embed/YLwV_EenJXY/0.jpg)](http://www.youtube.com/watch?v=https://www.youtube.com/embed/YLwV_EenJXY) ### 다른 MCP 클라이언트와 통합 에 설명된 구성은 다른 MCP 클라이언트 및 IDEs 데 사용할 [에이전트 문제 해결을 위한 설정](spark-troubleshooting-agent-setup.md) 수 있습니다. + **Cline과 통합** - MCP 서버를 Cline과 함께 사용하려면를 수정`cline_mcp_settings.json`하고 위의 구성을 추가합니다. MCP 구성을 관리하는 방법에 대한 자세한 내용은 [Cline의 설명서를](https://docs.cline.bot/mcp/configuring-mcp-servers) 참조하세요. + **Claude 코드와 통합** Claude 코드와 함께 MCP 서버를 사용하려면 MCP 구성을 포함하도록 구성 파일을 수정합니다. 파일 경로는 운영 체제에 따라 다릅니다. 자세한 설정은 [ https://code.claude.com/docs/en/mcp](https://code.claude.com/docs/en/mcp) 참조하십시오. + **GitHub Copilot과의 통합** - GitHub Copilot과 함께 MCP 서버를 사용하려면 [ https://docs.github.com/en/copilot/how-tos/provide-context/use-mcp/extend-copilot-chat-with-mcp](https://docs.github.com/en/copilot/how-tos/provide-context/use-mcp/extend-copilot-chat-with-mcp) 지침에 따라 해당 구성 파일을 수정하고 각 IDE의 지침에 따라 설정을 활성화합니다. # 기능 및 기능 ## 지원되는 플랫폼 + **언어**: Python 및 Scala Spark 애플리케이션 + **대상 플랫폼**: Amazon EMR, EMR Serverless 및 AWS Glue ## 작동 방식 Spark 애플리케이션에 장애가 발생하면 문제 해결 에이전트를 사용하여 무엇이 잘못되었는지 자동으로 조사할 수 있습니다. Spark 이벤트 로그, 오류 메시지 및 리소스 사용량을 분석하여 메모리 부족, 구성 오류 또는 코드 버그와 같은 정확한 문제를 정확히 찾아냅니다. 자연어 프롬프트에 Spark 워크로드를 분석하도록 요청하면 에이전트는 플랫폼의 리소스에 연결하고 기능(Spark 이벤트 로그, 쿼리 계획, 실행기 타임라인, 로그 추적, 구성 및 지표 포함)을 추출합니다. + EMR-EC2: 클러스터의 [EMR 영구 UI](https://docs.aws.amazon.com/emr/latest/ManagementGuide/app-history-spark-UI.html)에 연결 + Glue: 작업에 대한 Glue Studio의 [Spark UI](https://docs.aws.amazon.com/glue/latest/dg/monitor-spark-ui-jobs.html)에서 컨텍스트를 빌드합니다. + EMR-Serverless: 작업을 위해 EMR-Serverless [Spark 기록 서버에](https://docs.aws.amazon.com/emr-serverless/latest/APIReference/API_GetDashboardForJobRun.html) 연결 + 또한 에이전트는 오류 스택 추적 및 구성 세부 정보를 분석하여 실행 가능한 인사이트를 제공합니다. 실패한 워크로드의 경우 명확한 근본 원인 설명과 이를 해결하기 위한 특정 단계를 얻을 수 있습니다. 에이전트가 코드 관련 문제를 감지하면 코드에서 변경해야 할 사항을 정확히 보여주는 코드 권장 사항을 자동으로 제공합니다. 전체 분석 없이 언제든지 코드 수준 제안을 직접 요청할 수도 있습니다. ## 사용 가능한 리전 Spark 문제 해결 에이전트는 다음 리전에서 사용할 수 있습니다. + **아시아 태평양**: 도쿄(ap-northeast-1), 서울(ap-northeast-2), 싱가포르(ap-southeast-1), 시드니(ap-southeast-2), 뭄바이(ap-south-1) + **북미**: 캐나다(ca-central-1) + **유럽**: 스톡홀름(eu-north-1), 아일랜드(eu-west-1), 런던(eu-west-2), 파리(eu-west-3), 프랑크푸르트(eu-central-1) + **남아메리카**: 상파울루(sa-east-1) + **미국**: 버지니아 북부(us-east-1), 오하이오(us-east-2), 오리건(us-west-2) ## Spark 문제 해결 범위 및 사용자 요구 사항 + **지원되는 Spark 워크로드 상태**: 도구는 실패한 Spark 워크로드에 대한 응답만 지원합니다. + **EMR 영구 UI:** Amazon EMR-EC2 워크로드를 분석할 때 분석 도구는 EMR 영구 UI에 연결하여 주요 Spark 정보를 검색하려고 시도합니다. EMR 영구 UI 고려 사항은 [ 여기에](https://docs.aws.amazon.com/emr/latest/ManagementGuide/app-history-spark-UI.html#app-history-spark-UI-limitations) 설명되어 있습니다. + **Glue Studio Spark UI**: Glue 워크로드를 분석할 AWS 때 분석 도구는 Amazon S3에서 사용자의 Spark 이벤트 로그를 구문 분석하여 주요 Spark 정보를 검색하려고 시도합니다. 허용되는 최대 Spark 이벤트 로그 크기는 여기에 설명되어 [ 있습니다](https://docs.aws.amazon.com/glue/latest/dg/monitor-spark-ui-jobs.html). 롤링 로그의 경우 512MB 및 2GB입니다. + **코드 권장 사항:** PySpark 워크로드용 Amazon EMR-EC2 및 AWS Glue 워크로드에만 지원됨 + **리전 리소스:** Spark 문제 해결 에이전트는 리전별이며 문제 해결 프로세스에 해당 리전의 기본 EMR 리소스를 사용합니다. 리전 간 문제 해결은 지원되지 않습니다. # 문제 해결 및 Q&A ## 문제 해결 Spark 문제 해결 에이전트의 오류 메시지는 다양한 MCP 클라이언트에서 다양한 방식으로 사용할 수 있습니다. 이 페이지에서는 Amazon EMR용 Apache Spark 문제 해결 에이전트를 사용하여 발생할 수 있는 일반적인 문제에 대한 몇 가지 일반적인 지침을 나열합니다. 주제 + [오류: MCP 서버 로드 실패](#mcp-server-failed-to-load) + [관찰: 느린 도구 로드](#slow-tool-loading) + [오류: 제한 오류와 함께 도구 호출 실패](#throttling-error) + [오류: 도구가 사용자 오류로 응답](#user-error) + [오류: 도구가 내부 오류로 응답](#internal-error) ### 오류: MCP 서버 로드 실패 + MCP 구성이 올바르게 구성되었는지 확인합니다. + **JSON 구문 검증**: + 구문 오류 없이 JSON이 유효한지 확인 + 누락된 쉼표, 따옴표 또는 대괄호 확인 + 로컬 AWS 자격 증명을 확인하고 MCP IAM 역할에 대한 정책이 올바르게 구성되었는지 확인합니다. + /mcp를 실행하여 `Kiro-CLI` 사례에 대한 MCP 서버 가용성 확인 ### 관찰: 느린 도구 로드 + 서버를 처음 시작할 때 도구를 로드하는 데 몇 초 정도 걸릴 수 있습니다. + 도구가 표시되지 않으면 채팅을 다시 시작해 보세요. + `/tools` 명령을 실행하여 도구 가용성을 확인합니다. + 서버가 오류 없이 시작`/mcp`되면를 실행합니다. ### 오류: 제한 오류와 함께 도구 호출 실패 + 서비스 한도에 도달한 경우 제한 예외가 표시되면 몇 초 정도 기다렸다가 도구 호출을 실행하십시오. ### 오류: 도구가 사용자 오류로 응답 + AccessDeniedException - 오류 메시지를 확인하고 권한 문제를 수정합니다. + InvalidInputException - 오류 메시지를 확인하고 도구 입력 파라미터를 수정합니다. + ResourceNotFoundException - 오류 메시지를 확인하고 리소스 참조를 위해 입력 파라미터를 수정합니다. ### 오류: 도구가 내부 오류로 응답 + 표시되는 경우 몇 초 후에 도구 호출을 다시 시도`The service is handling high-volume requests`하세요. + 분석 ID, 도구 이름, mcp 로그 또는 도구 응답에서 사용할 수 있는 오류 메시지, 선택적으로 삭제된 대화 기록을 문서화하고 AWS 지원 팀에 문의`INTERNAL SERVICE EXCEPTION`하세요. ## Q&A ### 1. 도구에 대해 기본적으로 "신뢰" 설정을 활성화해야 합니까? 처음에는 모든 도구 호출에 대해 기본적으로 "신뢰" 설정을 켜지 말고 코드 권장 사항을 수락할 때 git 버전 빌드 환경에서 작동하세요. 각 도구 실행을 검토하여 변경 사항을 이해합니다. ### 2. 문제 해결 도구를 활용하기 위한 일반적인 예제 프롬프트는 무엇입니까? 문제 해결 도구 활용에 대한 프롬프트 예제[프롬프트 예제](spark-troubleshooting-agent-prompt-examples.md)는 섹션을 참조하세요. ### 3. LLM으로 전송되는 데이터는 무엇이며 어떻게 처리됩니까? 고객 데이터 및 파일은 선택한 AWS 리전 내에 유지되며 리전 간에 전송되지 않습니다. 에이전트가 Amazon Bedrock의 글로벌 리전 간 추론을 사용하는 리전에서 작동하는 경우 서비스는 수요에 따라 사용 가능한 용량이 있는 가장 가까운 리전으로 요청을 라우팅할 수 있습니다. 이러한 경우 고객 로그에서 추출한 메타데이터와 처리된 추론 결과만 전송되며 기본 고객 데이터나 파일은 전송되지 않습니다. 추론이 동일한 리전 내에서 발생하든 다른 리전으로 라우팅하든 모든 데이터는 처리를 위해 LLM으로 전송되기 전에 PII 마스킹 처리됩니다. 교차 리전 추론의 작동 방식과 영향을 받는 리전에 대한 자세한 내용은 섹션을 참조하세요[Apache Spark 문제 해결 에이전트의 리전 간 처리](spark-troubleshooting-cross-region-processing.md). # 세부 정보의 Spark 에이전트 워크플로 문제 해결 문제 해결 프로세스를 시작하려면 지원되는 플랫폼(EMR-EC2, EMR Serverless, AWS Glue 또는 Amazon SageMaker Data Notebooks)에서 실행 중인 실패한 Spark 애플리케이션 식별자에 액세스해야 합니다. 애플리케이션에는 액세스 가능한 로그, Spark 기록 서버 및 구성 세부 정보가 있어야 합니다. 플랫폼 리소스 및 애플리케이션 메타데이터에 액세스하는 데 필요한 권한이 있는지 확인합니다. 이러한 요구 사항이 설정되면 다음과 같은 프롬프트를 제출하여 문제 해결 워크플로를 시작할 수 있습니다. ``` Analyze my EMR step execution failure, EMR id with cluster id ``` 이 시점에서 에이전트는 특수 도구를 사용하여 문제 해결을 오케스트레이션합니다. 워크플로는 다음 단계를 따릅니다. 1. **특성 추출 및 컨텍스트 구축**: 에이전트는 기록 서버 로그, 구성 설정 및 오류 추적을 포함하여 Spark 애플리케이션에서 원격 측정 데이터를 자동으로 수집하고 분석합니다. 성능 지표, 리소스 사용률 패턴 및 장애 서명에 대한 정보를 수집하는 도구가 표시됩니다. 1. **분석 및 근본 원인 식별**: 에이전트는 AI 모델과 Spark 지식 기반을 활용하여 추출된 기능을 상호 연관시키고 성능 문제 또는 장애의 근본 원인을 식별합니다. 다음을 받게 됩니다. + **분석 인사이트**: 에이전트가 검색하고 분석한 내용에 대한 기술 세부 정보입니다. + **근본 원인**: 무엇이 왜 잘못되었는지에 대한 명확한 설명입니다. + **초기 평가**: 문제가 코드 관련이든 구성 관련이든 리소스 관련이든 완화를 위한 몇 가지 일반 지침 및 분석이 제공됩니다. 1. **코드 권장 사항**(해당하는 경우): 분석에서 오류 분류를 기반으로 코드 관련 문제를 식별하는 경우 에이전트는 코드 권장 도구를 활용하여 제안된 대체와 함께 정확한 전/후 코드로 권장 코드 수정을 구현하기 위한 특정 권장 사항을 제공하도록 제안할 수 있습니다. 문제 해결 프로세스는 반복적입니다. 대화를 계속 진행하여 특정 문제를 자세히 살펴볼 수 있습니다. 로컬 Spark 코드 개발에서 대화형으로 도구를 사용하여 코드 버그를 해결하거나 코드를 지속적으로 개선할 수도 있습니다. # 프롬프트 예제 다음은 문제 해결 경험에 사용할 수 있는 프롬프트 예제 목록입니다. ## 1. Spark 작업 실행 실패 문제 해결 EC2의 EMR 문제 해결: ``` Troubleshoot my EMR-EC2 step with id s-xxxxxxxxxxxx on cluster j-xxxxxxxxxxxxx ``` Glue 작업 문제 해결: ``` Troubleshoot my Glue job with job run id jr_xxxxxxxxxxxxxxxxxxxxxxxxxxxx and job name test_job ``` EMR Serverless 문제 해결: ``` Troubleshoot my EMR-Serverless job run with application id 00xxxxxxxx and job run id 00xxxxxxxx ``` ## 2. 코드 수정 권장 사항 요청 EC2 작업의 EMR에 대한 코드 수정 권장 사항 요청: ``` Recommend code fix for my EMR-EC2 step with id s-STEP_ID on cluster j-CLUSTER_ID ``` Glue 작업에 대한 코드 수정 권장 사항 요청: ``` Recommend code fix for my Glue job with job run id jr_JOB_RUN_ID and job name test_job ``` # IAM 역할 설정 설정 지침의 CloudFormation 스택은 IAM 역할 설정을 자동화합니다. 수동으로 실행하려면 아래 지침을 따르세요. ## MCP 서버에 대한 IAM 역할 설정 SMUS 관리형 MCP 서버에 액세스하려면 다음 인라인 정책에 따라 IAM 역할이 필요합니다. ``` { "Version": "2012-10-17", "Statement": [ { "Sid": "AllowUseSagemakerUnifiedStudioMcpServer", "Effect": "Allow", "Action": [ "sagemaker-unified-studio-mcp:InvokeMcp", "sagemaker-unified-studio-mcp:CallReadOnlyTool", "sagemaker-unified-studio-mcp:CallPrivilegedTool" ], "Resource": [ "*" ] } ] } ``` 다음 단계에서는이 역할에 대한 프로필을 생성합니다. 자격 증명을 얻기 위해이 역할을 수임하는 계정은 수임 역할 정책에 추가해야 합니다. ``` { "Version": "2012-10-17", "Statement": [ { "Sid": "AllowAccountToAssumeRole", "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam:::root" }, "Action": "sts:AssumeRole" } ] } ``` ## 배포 모드별 추가 권한(EMR-EC2/EMR-S/Glue) ### EMR-EC2 애플리케이션 ``` { "Version": "2012-10-17", "Statement": [ { "Sid": "EMREC2ReadAccess", "Effect": "Allow", "Action": [ "elasticmapreduce:DescribeCluster", "elasticmapreduce:DescribeStep", "elasticmapreduce:ListSteps", "elasticmapreduce:ListClusters", "elasticmapreduce:DescribeJobFlows" ], "Resource": [ "*" ] }, { "Sid": "EMRS3LogAccess", "Effect": "Allow", "Action": [ "s3:GetObject", "s3:ListBucket" ], "Resource": "*" }, { "Sid": "EMRPersistentApp", "Effect": "Allow", "Action": [ "elasticmapreduce:CreatePersistentAppUI", "elasticmapreduce:DescribePersistentAppUI", "elasticmapreduce:GetPersistentAppUIPresignedURL" ], "Resource": [ "*" ] } ] } ``` ### Glue 작업 ``` { "Version": "2012-10-17", "Statement": [ { "Sid": "GlueReadAccess", "Effect": "Allow", "Action": [ "glue:GetJob", "glue:GetJobRun", "glue:GetJobRuns", "glue:GetJobs", "glue:BatchGetJobs" ], "Resource": [ "arn:aws:glue:*::job/*" ] }, { "Sid": "GlueCloudWatchLogsAccess", "Effect": "Allow", "Action": [ "logs:GetLogEvents", "logs:FilterLogEvents" ], "Resource": [ "arn:aws:logs:*::log-group:/aws/glue/*" ] }, { "Sid": "GlueSparkWebUI", "Effect": "Allow", "Action": [ "glue:RequestLogParsing", "glue:GetLogParsingStatus", "glue:GetEnvironment", "glue:GetStage", "glue:GetStages", "glue:GetStageFiles", "glue:BatchGetStageFiles", "glue:GetStageAttempt", "glue:GetStageAttemptTaskList", "glue:GetStageAttemptTaskSummary", "glue:GetExecutors", "glue:GetExecutorsThreads", "glue:GetStorage", "glue:GetStorageUnit", "glue:GetQueries", "glue:GetQuery", "glue:GetDashboardUrl" ], "Resource": [ "arn:aws:glue:*::job/*" ] }, { "Sid": "GluePassRoleAccess", "Effect": "Allow", "Action": "iam:PassRole", "Resource": "*", "Condition": { "StringLike": { "iam:PassedToService": "glue.amazonaws.com" } } } ] } ``` ### EMR Serverless 애플리케이션 ``` { "Version": "2012-10-17", "Statement": [ { "Sid": "EMRServerlessReadAccess", "Effect": "Allow", "Action": [ "emr-serverless:GetJobRun", "emr-serverless:GetApplication", "emr-serverless:ListApplications", "emr-serverless:ListJobRuns", "emr-serverless:ListJobRunAttempts", "emr-serverless:GetDashboardForJobRun", "emr-serverless:ListTagsForResource" ], "Resource": [ "*" ] }, { "Sid": "EMRServerlessCloudWatchLogsAccess", "Effect": "Allow", "Action": [ "logs:GetLogEvents", "logs:FilterLogEvents" ], "Resource": [ "arn:aws:logs:*::log-group:/aws/emr-serverless/*" ] }, { "Sid": "EMRServerlessS3LogsAccess", "Effect": "Allow", "Action": [ "s3:GetObject", "s3:ListBucket" ], "Resource": "*" } ] } ``` ### KMS 권한 - CloudWatch Logs CloudWatch Logs가 CMK로 암호화된 경우 서비스가 EMR-Serverless 애플리케이션 로그를 읽을 수 있도록 다음 정책을 추가합니다. ``` { "Effect": "Allow", "Action": [ "kms:Decrypt", "kms:DescribeKey" ], "Resource": "arn:aws:kms:::key/" } ``` # Spark 문제 해결 도구 사용 ## 사용 가능한 문제 해결 도구 MCP 서비스는 Spark 문제 해결 에이전트를 위한 다양한 도구를 제공합니다. 주요 도구는 다음과 같습니다. | 도구 이름 | 도구 범주 | 설명 | | --- | --- | --- | | analyze\$1spark\$1워크로드 | 근본 원인 분석 | 실패한 Apache Spark 워크로드에 대한 자세한 문제 해결 제공 | | spark\$1code\$1recommendation | 코드 수정 권장 사항 | 실패한 작업에 대한 Apache Spark 코드 권장 사항을 제공합니다. | # Amazon SageMaker Unified Studio MCP에 대한 인터페이스 VPC 엔드포인트 구성 *인터페이스 VPC 엔드포인트*를 생성하여 VPC와 Amazon SageMaker Unified Studio MCP 서비스 간에 프라이빗 연결을 설정할 수 있습니다. 인터페이스 엔드포인트는 [Amazon VPC](https://aws.amazon.com/vpc/)로 구동되므로 인터넷 게이트웨이, NAT 디바이스, VPN 연결 또는 연결 없이 VPC의 MCP 서버에 비공개로 액세스할 수 있습니다. VPC의 인스턴스는 MCP 서비스와 통신하는 데 퍼블릭 IP 주소가 필요하지 않으며 VPC와 MCP 서비스 간의 트래픽은 Amazon 네트워크를 벗어나지 않습니다. 각 인터페이스 엔드포인트는 VPC 서브넷에서 하나 이상의 [탄력적 네트워크 인터페이스](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-eni.html)로 표시됩니다. 자세한 내용은 *Amazon* [VPC 사용 설명서의 인터페이스 VPC 엔드포인트](https://docs.aws.amazon.com/vpc/latest/userguide/vpce-interface.html)를 참조하세요. ## 1단계: Amazon SageMaker Unified Studio MCP용 인터페이스 VPC 엔드포인트 생성 Amazon VPC 콘솔 또는를 사용하여 Amazon SageMaker Unified Studio MCP 서비스에 대한 VPC 엔드포인트를 생성할 수 있습니다 AWS CLI. 자세한 내용은 *Amazon VPC 사용 설명서*의 [인터페이스 엔드포인트 생성](https://docs.aws.amazon.com/vpc/latest/userguide/vpce-interface.html#create-interface-endpoint)을 참조하세요. 다음 서비스 이름을 사용하여 Amazon SageMaker Unified Studio MCP용 VPC 엔드포인트를 생성합니다. + com.amazonaws.**.sagemaker-unified-studio-mcp 엔드포인트에 대해 프라이빗 DNS를 활성화하는 경우 리전의 기본 DNS 이름을 사용하여 Amazon SageMaker Unified Studio MCP에 API 요청을 할 수 있습니다. 예를 들면 다음과 같습니다. `sagemaker-unified-studio-mcp.us-east-1.api.aws` 자세한 내용은 *Amazon VPC 사용 설명서*의 [인터페이스 엔드포인트를 통해 서비스 액세스](https://docs.aws.amazon.com/vpc/latest/userguide/vpce-interface.html#access-service-though-endpoint)를 참조하세요. ## 2단계: Amazon SageMaker Unified Studio MCP에 대한 VPC 엔드포인트 정책 생성 Amazon SageMaker Unified Studio MCP에 대한 액세스를 제어하는 엔드포인트 정책을 VPC 엔드포인트에 연결할 수 있습니다. 이 정책은 다음 정보를 지정합니다. + 작업을 수행할 수 있는 위탁자. + 수행할 수 있는 작업. + 작업을 수행할 수 있는 리소스. 자세한 내용은 *Amazon VPC 사용 설명서*의 [VPC 엔드포인트를 통해 서비스에 대한 액세스 제어](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-endpoints-access.html)를 참조하세요. ### 예: 특정 IAM 역할에 대한 MCP 액세스를 허용하는 VPC 엔드포인트 정책 다음은 Amazon SageMaker Unified Studio MCP 액세스를 위한 엔드포인트 정책의 예입니다. 엔드포인트에 연결되면이 정책은 모든 리소스의 특정 IAM 역할 보안 주체에 대해 나열된 Amazon SageMaker Unified Studio MCP 작업에 대한 액세스 권한을 부여합니다. ``` { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::ACCOUNT-ID:role/YourRoleName" }, "Action": [ "sagemaker-unified-studio-mcp:InvokeMcp", "sagemaker-unified-studio-mcp:CallReadOnlyTool", "sagemaker-unified-studio-mcp:CallPrivilegedTool" ], "Resource": "*" } ] } ``` ## 3단계: VPC 테스트 이 `curl` 명령은 HTTP/HTTPS 요청을 통해 VPC 네트워크(EC2)에서 VPC 엔드포인트로의 end-to-end 네트워크 연결을 검증합니다. MCP 서버에서 메시지를 다시 수신하는 curl 응답은 전체 네트워크 경로가 작동하는지 확인합니다. ### 방법 1: 프라이빗 DNS가 활성화된 경우(권장) ``` curl https://sagemaker-unified-studio-mcp.us-east-1.api.aws/spark-troubleshooting/mcp ``` ### 방법 2: 프라이빗 DNS가 활성화되지 않은 경우 ``` curl -k https://vpce-0069xxxx-ejwhxxx.sagemaker-unified-studio-mcp.us-east-1.vpce.amazonaws.com/spark-troubleshooting/mcp ``` **참고** `-k` 플래그는 VPC 엔드포인트 DNS 이름과 인증서의 일반 이름(CN) 간의 호스트 이름 불일치로 인해 SSL 인증서 확인을 우회합니다. 두 경우 모두 curl 명령은 응답을 반환합니다`{"Message":"...."}`. 메시지와 함께를 반환하면 MCP 서비스의 VPC 엔드포인트에 대한 네트워크 경로 연결이 성공했는지 확인합니다. ## 4단계: MCP VPC 엔드포인트 사용 시작 연결을 확인한 후에는 단계에 따라에서 MCP를 구성할 수 있습니다[에이전트 문제 해결을 위한 설정](spark-troubleshooting-agent-setup.md). MCP 구성에서 프라이빗 VPC 엔드포인트를 사용하기만 하면 됩니다. # Apache Spark 문제 해결 에이전트의 리전 간 처리 Apache Spark 문제 해결 에이전트는 리전 간 추론을 사용하여 자연어 요청을 처리하고 응답을 생성합니다. 교차 리전 추론을 통해 에이전트는 추론 요청을 자동으로 라우팅하여 성능을 최적화하고 사용 가능한 컴퓨팅 리소스와 모델 가용성을 극대화하며 최상의 고객 경험을 제공합니다. 사용되는 교차 리전 추론 유형은 Apache Spark 문제 해결 에이전트를 실행하는 리전에 따라 다릅니다. 대부분의 리전에서 에이전트는 추론 요청을 처리할 리전 내에서 최적의 리전을 선택합니다. 그러나 일부 리전에서는 에이전트가 수행한 추론 요청이 모든 글로벌 상용 AWS 리전에서 사용 가능한 모든 컴퓨팅 리소스로 안전하게 라우팅됩니다. ## 교차 리전 추론 Apache Spark 문제 해결 에이전트는 Amazon Bedrock으로 구동되며 교차 리전 추론을 사용하여 여러 AWS 리전에 트래픽을 분산하여 대규모 언어 모델(LLM) 추론 성능과 신뢰성을 개선합니다. Spark 애플리케이션 또는 문제 해결 환경이 호스팅되거나 데이터가 저장되는 리전 간 추론은 변경되지 않지만, 추론 처리를 위해 입력 프롬프트와 출력 결과가 다른 리전으로 전송될 수 있습니다. 모든 데이터는 Amazon의 보안 네트워크를 통해 암호화되어 전송됩니다. 교차 리전 추론을 사용하는 데 드는 추가 비용은 없습니다. ## 교차 리전 추론에 지원되는 리전 **지리적 리전 간 추론을 사용하는 리전** 대부분의 리전에서 교차 리전 추론 요청은 Apache Spark 문제 해결 에이전트를 실행하는 동일한 리전의 일부인 AWS 리전 내에 보관됩니다. 예를 들어 미국 동부(버지니아 북부) 리전의 에이전트로부터 이루어진 요청은 미국 리전 내의 AWS 리전으로만 라우팅됩니다. 다음 표에서는 요청이 시작된 리전에 따라 요청이 라우팅될 수 있는 리전을 설명합니다. | 지원되는 지역 | 추론 리전 | | --- | --- | | 미국 | 미국 동부(버지니아 북부)(us-east-1), 미국 서부(오레곤)(us-west-2), 미국 동부(오하이오)(us-east-2), 미국 서부(캘리포니아 북부)(us-west-1) | | 유럽 | 유럽(프랑크푸르트)(eu-central-1), 유럽(아일랜드)(eu-west-1), 유럽(파리)(eu-west-3), 유럽(스톡홀름)(eu-north-1), 유럽(런던)(eu-west-2) | | 아시아 태평양 | 아시아 태평양(도쿄)(ap-northeast-1), 아시아 태평양(서울)(ap-northeast-2), 아시아 태평양(뭄바이)(ap-south-1) | ### 글로벌 리전 간 추론을 사용하는 리전 **중요** 다음 AWS 리전은 글로벌 리전 간 추론을 사용합니다. 이러한 리전에서 Apache Spark 문제 해결 에이전트를 사용하는 경우 성능 및 가용성을 최적화하기 위해 추론 처리를 위해 요청이 다른 AWS 리전으로 전역적으로 전송될 수 있습니다. 남아메리카(상파울루) (sa-east-1) 아시아 태평양(싱가포르)(ap-southeast-1) 아시아 태평양(시드니)(ap-southeast-2) 캐나다(중부)(ca-central-1) # 를 사용하여 Amazon SageMaker Unified Studio MCP 호출 로깅 AWS CloudTrail Amazon SageMaker Unified Studio MCP Server는 Amazon SageMaker Unified Studio MCP Server에서 사용자, 역할 또는 서비스가 수행한 작업에 대한 레코드를 AWS CloudTrail제공하는 AWS 서비스와 통합됩니다. CloudTrail은 Amazon SageMaker Unified Studio MCP Server에 대한 모든 API 호출을 이벤트로 캡처합니다. 캡처되는 호출에는 Amazon SageMaker Unified Studio MCP Server에 대한 호출과 SageMaker Unified Studio MCP Server에서 도구를 실행하는 동안 다른 AWS 작업에 대한 코드 호출이 포함됩니다. 추적을 생성하면 Amazon SageMaker Unified Studio MCP Server에 대한 이벤트를 포함하여 CloudTrail 이벤트를 지속적으로 Amazon S3 버킷에 배포할 수 있습니다. Amazon S3 Amazon SageMaker 추적을 구성하지 않은 경우에도 **이벤트 기록**에서 CloudTrail 콘솔의 최신 이벤트를 볼 수 있습니다. CloudTrail에서 수집한 정보를 사용하여 Amazon SageMaker Unified Studio MCP 서버에 수행된 요청, 요청이 수행된 IP 주소, 요청을 수행한 사람, 요청이 수행된 시간 및 추가 세부 정보를 확인할 수 있습니다. CloudTrail에 대한 자세한 내용은 [AWS CloudTrail 사용 설명서](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/)를 참조하세요. ## CloudTrail의 Amazon SageMaker Unified Studio MCP Server 정보 AWS 계정을 생성할 때 계정에서 CloudTrail이 활성화됩니다. Amazon SageMaker Unified Studio MCP 서버에서 활동이 발생하면 해당 활동은 **이벤트 기록**의 다른 AWS 서비스 이벤트와 함께 CloudTrail 이벤트에 기록됩니다. AWS 계정에서 최근 이벤트를 보고 검색하고 다운로드할 수 있습니다. 자세한 내용은 [CloudTrail 이벤트 기록을 사용하여 이벤트 보기](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/view-cloudtrail-events.html)를 참조하세요. SageMaker Unified Studio MCP Server에 대한 이벤트를 포함하여 AWS 계정에 이벤트를 지속적으로 기록하려면 추적을 생성합니다. CloudTrail은 추적을 사용하여 Amazon S3 버킷으로 로그 파일을 전송할 수 있습니다. 기본적으로 콘솔에서 추적을 생성하면 추적이 모든 AWS 리전에 적용됩니다. 추적은 AWS 파티션의 모든 리전에서 이벤트를 로깅하고 지정한 Amazon S3 버킷으로 로그 파일을 전송합니다. 또한 CloudTrail 로그에서 수집된 이벤트 데이터를 추가로 분석하고 조치를 취하도록 다른 AWS 서비스를 구성할 수 있습니다. 자세한 내용은 다음 자료를 참조하세요. + [추적 생성 개요](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-create-and-update-a-trail.html) + [CloudTrail 지원 서비스 및 통합](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-aws-service-specific-topics.html) + [CloudTrail에 대한 Amazon SNS 알림 구성](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/configure-sns-notifications-for-cloudtrail.html) + [여러 리전에서 CloudTrail 로그 파일 받기](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/receive-cloudtrail-log-files-from-multiple-regions.html) 및 [여러 계정에서 CloudTrail 로그 파일 받기](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-receive-logs-from-multiple-accounts.html) 도구 실행 중에 AWS 서비스에 대한 모든 SageMaker Unified Studio MCP Server 도구 호출 및 API 호출은 CloudTrail에서 로깅됩니다. 예를 들어 다양한 도구에 대한 호출과 도구에서 수행된 AWS 서비스 호출은 CloudTrail 로그 파일에 항목을 생성합니다. 모든 이벤트 또는 로그 항목에는 요청을 생성했던 사용자에 관한 정보가 포함됩니다. ID 정보를 이용하면 다음을 쉽게 판단할 수 있습니다. + 요청을 루트로 했는지 아니면 IAM 사용자 자격 증명 정보로 했는지 여부. + 역할 또는 페더레이션 사용자의 임시 자격 증명을 사용하여 요청이 생성되었는지 여부. + 요청이 다른 AWS 서비스에 의해 이루어졌는지 여부입니다. 자세한 내용은 [CloudTrail userIdentity 요소](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-event-reference-user-identity.html)를 참조하세요. ## Amazon SageMaker Unified Studio MCP Server 로그 파일 항목 이해 트레일이란 지정한 S3 버킷에 이벤트를 로그 파일로 입력할 수 있게 하는 구성입니다. CloudTrail 로그 파일에는 하나 이상의 로그 항목이 포함될 수 있습니다. 이벤트는 모든 소스로부터의 단일 요청을 나타내며 요청 작업, 작업 날짜와 시간, 요청 파라미터 등에 대한 정보가 들어 있습니다. CloudTrail 로그 파일은 퍼블릭 API 직접 호출의 주문 스택 트레이스가 아니므로 특정 순서로 표시되지 않습니다. 다음 예제는 `CallTool` 작업을 보여주는 CloudTrail 로그 항목이 나타냅니다. ``` { "eventVersion": "1.09", "userIdentity": { ... }, "eventTime": "...", "eventSource": "sagemaker-unified-studio-mcp.amazonaws.com", "eventName": "CallPrivilegedTool", "awsRegion": "us-east-1", "sourceIPAddress": "...", "userAgent": "...", "requestParameters": { "id": 1, "method": "tools/call", "params": { "name": "generate_spark_upgrade_plan", "arguments": "***", "_meta": { "progressToken": 1 } }, "jsonrpc": "2.0" }, "responseElements": { "result": { "content": "***", "structuredContent": "***", "isError": false }, "id": 1, "jsonrpc": "2.0" }, "requestID": "12345678-1234-1234-1234-123456789012", "eventID": "87654321-4321-4321-4321-210987654321", "readOnly": false, "eventType": "AwsMcpEvent", "managementEvent": true, "recipientAccountId": "123456789012", "eventCategory": "Management" } ``` 다음 예제는 업그레이드 도구 호출 중에 Amazon SageMaker Unified Studio MCP의 `AddJobFlowSteps` 작업을 보여주는 CloudTrail 로그 항목을 보여줍니다. ``` { "eventVersion": "1.11", "userIdentity": { "type": "AssumedRole", "principalId": "...", "arn": "...", "accountId": "123456789012", "accessKeyId": "...", "sessionContext": { ... }, "invokedBy": "sagemaker-unified-studio-mcp.amazonaws.com" }, "eventTime": "...", "eventSource": "elasticmapreduce.amazonaws.com", "eventName": "AddJobFlowSteps", "awsRegion": "us-east-1", "sourceIPAddress": "sagemaker-unified-studio-mcp.amazonaws.com", "userAgent": "sagemaker-unified-studio-mcp.amazonaws.com", "requestParameters": { "jobFlowId": "j-2PY4KXXXXXX63", "steps": [ ... ] }, "responseElements": { "stepIds": [ ... ] }, "requestID": "12345678-1234-1234-1234-123456789013", "eventID": "87654321-4321-4321-4321-210987654322", "readOnly": false, "eventType": "AwsApiCall", "managementEvent": true, "recipientAccountId": "123456789012", "sharedEventID": "12345678-1234-1234-1234-123456789012", "vpcEndpointId": "sagemaker-unified-studio-mcp.amazonaws.com", "vpcEndpointAccountId": "sagemaker-unified-studio-mcp.amazonaws.com", "eventCategory": "Management" } ``` # Apache Spark 에이전트의 서비스 개선 사항 Amazon EMR용 Apache Spark 에이전트는 예를 들어 에이전트가 일반적인 질문에 더 나은 응답을 제공하거나 운영 문제를 해결하거나 디버깅하는 데 도움이 되는 콘텐츠를 사용할 수 있습니다. ## 가 서비스 개선에 사용할 AWS 수 있는 콘텐츠 + Amazon EMR, AWS Glue 및 Amazon SageMaker Notebooks에 대한 Apache Spark 에이전트의 자연어 프롬프트 및 생성된 응답 ## 서비스 개선에를 사용하지 AWS 않는 콘텐츠 + Spark 애플리케이션을 위해 직접 작성하는 코드 + SageMaker 노트북 컨텍스트 및 메타데이터 + AWS Glue 데이터 카탈로그 또는 기타 데이터 소스의 데이터 Amazon 직원만 데이터에 액세스할 수 있습니다. 사용자의 신뢰, 프라이버시 및 고객 콘텐츠 보안을 최우선으로 생각하며, 약속한 대로 데이터를 사용하도록 할 것입니다. 자세한 내용은 데이터 프라이버시 FAQ를 참조하세요. ## 옵트아웃 방법 Apache Spark 에이전트의 데이터 수집을 옵트아웃하려면 AWS Organizations for Amazon SageMaker Unified Studio MCP Service에서 AI 서비스 옵트아웃 정책을 구성합니다. 자세한 내용은 *AWS 조직 사용 설명서*의 [AI 서비스 옵트아웃 정책](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_policies_ai-opt-out.html)을 참조하세요. AI 서비스 옵트아웃 정책을 구성하면 다음과 같은 효과가 있습니다. + AWS 는 옵트아웃 전에 서비스 개선을 위해 수집 및 저장된 데이터를 삭제합니다(있는 경우). + 옵트아웃한 후에는 AWS 가 더 이상이 데이터를 수집하거나 저장하지 않습니다. + AWS 는 더 이상 서비스 개선에 콘텐츠를 사용하지 않습니다.