네이티브 쿼리 실행 자격 도구 실행

네이티브 쿼리 실행 (NQE)으로 더 빠른 런타임을 달성할 수 있는 일괄 워크로드를 식별하려면 자격 도구를 사용하면 됩니다. 이 도구는 Spark 이벤트 로그를 분석하여 잠재적인 런타임 절감액을 추정하고 NQE 엔진에서 지원하지 않는 작업을 식별합니다.

Google Cloud 는 자격 작업과 자격 스크립트라는 두 가지 자격 분석 실행 방법을 제공합니다. 대부분의 사용자에게 권장되는 방법은 일괄 워크로드의 검색 및 분석을 자동화하는 자격 작업입니다. 알려진 이벤트 로그 파일을 분석하는 특정 사용 사례에 대체 자격 스크립트를 사용할 수 있습니다. 사용 사례에 가장 적합한 방법을 선택하세요.

자격 작업 (권장): 기본적이고 권장되는 방법입니다. 하나 이상의 Google Cloud 프로젝트와 리전에서 최근 일괄 워크로드를 자동으로 검색하고 분석하는 PySpark 작업입니다. 개별 이벤트 로그 파일을 수동으로 찾을 필요 없이 광범위한 분석을 수행하려는 경우 이 방법을 사용하세요. 이 방법은 NQE 적합성을 대규모로 평가하는 데 적합합니다.
자격 스크립트 (대체): 고급 또는 특정 사용 사례를 위한 대체 방법입니다. 단일 Spark 이벤트 로그 파일 또는 특정 Cloud Storage 디렉터리 내의 모든 이벤트 로그를 분석하는 셸 스크립트입니다. 분석하려는 이벤트 로그의 Cloud Storage 경로가 있는 경우 이 방법을 사용하세요.

자격 작업

자격 작업은 Apache Spark용 서버리스 일괄 워크로드를 프로그래매틱 방식으로 검색하고 분산 분석 작업을 제출하여 대규모 분석을 간소화합니다. 이 도구는 조직 전체에서 작업을 평가하므로 이벤트 로그 경로를 수동으로 찾고 지정할 필요가 없습니다.

IAM 역할 부여

자격 작업이 일괄 워크로드 메타데이터에 액세스하고 Cloud Logging에서 Spark 이벤트 로그를 읽으려면 워크로드를 실행하는 서비스 계정에 분석할 모든 프로젝트에서 다음 IAM 역할이 부여되어야 합니다.

자격 작업 제출

gcloud CLI 도구를 사용하여 자격 작업을 제출합니다. 작업에는 퍼블릭 Cloud Storage 버킷에서 호스팅되는 PySpark 스크립트와 JAR 파일이 포함됩니다.

다음 실행 환경 중 하나에서 작업을 실행할 수 있습니다.

Apache Spark용 서버리스 일괄 워크로드로 실행합니다. 이는 간단한 독립형 작업 실행입니다.
Compute Engine 클러스터의 Dataproc에서 실행되는 작업으로 실행합니다. 이 방법은 작업을 워크플로에 통합하는 데 유용할 수 있습니다.

작업 인수

인수	설명	필수 여부	기본값
`--project-ids`	일괄 워크로드를 검사할 단일 프로젝트 ID 또는 쉼표로 구분된 Google Cloud 프로젝트 ID 목록입니다.	아니요	자격 작업이 실행되는 프로젝트입니다.
`--regions`	지정된 프로젝트 내에서 검사할 단일 리전 또는 쉼표로 구분된 리전 목록입니다.	아니요	지정된 프로젝트 내의 모든 리전입니다.
`--start-time`	배치를 필터링할 시작일입니다. 이 날짜 (형식: YYYY-MM-DD) 이후에 생성된 배치만 분석됩니다.	아니요	시작일 필터가 적용되지 않습니다.
`--end-time`	배치를 필터링할 종료일입니다. 이 날짜 (형식: YYYY-MM-DD) 이전에 생성된 배치만 분석됩니다.	아니요	종료일 필터가 적용되지 않습니다.
`--limit`	리전당 분석할 최대 배치 수입니다. 가장 최근 배치가 먼저 분석됩니다.	아니요	다른 필터 기준과 일치하는 모든 배치가 분석됩니다.
`--output-gcs-path`	결과 파일이 작성될 Cloud Storage 경로입니다 (예: `gs://your-bucket/output/`).	예	없음
`--input-file`	대량 분석을 위한 텍스트 파일의 Cloud Storage 경로입니다. 제공된 경우 이 인수는 다른 모든 범위 정의 인수 (`--project-ids`, `--regions`, `--start-time`, `--end-time`, `--limit`)를 재정의합니다.	아니요	없음

자격 작업 예

간단한 임시 분석을 수행하는 Apache Spark용 서버리스 일괄 작업입니다. 작업 인수는 -- 구분 기호 뒤에 나열됩니다.

gcloud dataproc batches submit pyspark gs://qualification-tool/performance-boost-qualification.py \
    --project=PROJECT_ID \
    --region=REGION \
    --jars=gs://qualification-tool/dataproc-perfboost-qualification-1.2.jar \
    -- \
    --project-ids=COMMA_SEPARATED_PROJECT_IDS \
    --regions=COMMA_SEPARATED_REGIONS \
    --limit=MAX_BATCHES \
    --output-gcs-path=gs://BUCKET

us-central1 리전의 sample_project에서 찾은 최대 50개의 최신 배치를 분석하는 Apache Spark용 서버리스 일괄 작업입니다. 결과는 Cloud Storage의 버킷에 작성됩니다. 작업 인수는 -- 구분 기호 뒤에 나열됩니다.

gcloud dataproc batches submit pyspark gs://qualification-tool/performance-boost-qualification.py \
    --project=PROJECT_ID \
    --region=US-CENTRAL1 \
    --jars=gs://qualification-tool/dataproc-perfboost-qualification-1.2.jar \
    -- \
    --project-ids=PROJECT_ID \
    --regions=US-CENTRAL1 \
    --limit=50 \
    --output-gcs-path=gs://BUCKET/

대규모, 반복 가능 또는 자동화된 분석 워크플로에서 대량 분석을 위해 Dataproc 클러스터에 제출된 Compute Engine 작업의 Dataproc입니다. 작업 인수는 INPUT_FILE에 업로드되는 BUCKET에 배치됩니다. Cloud Storage. 이 방법은 단일 실행에서 여러 프로젝트와 리전에 걸쳐 다양한 날짜 범위 또는 배치 한도를 검사하는 데 적합합니다.
```
gcloud dataproc jobs submit pyspark gs://qualification-tool/performance-boost-qualification.py \
    --cluster=CLUSTER_NAME \
    --region=REGION \
    --jars=gs://qualification-tool/dataproc-perfboost-qualification-1.2.jar \
    -- \
    --input-file=gs://INPUT_FILE \
    --output-gcs-path=gs://BUCKET
```
참고:

INPUT_FILE: 파일의 각 줄은 고유한 분석 요청을 나타내며 단일 문자 플래그와 그 값(예: -p PROJECT-ID -r REGION -s START_DATE -e END_DATE -l LIMITS) 형식을 사용합니다.

입력 파일 콘텐츠 예:
```
-p project1 -r us-central1 -s 2024-12-01 -e 2024-12-15 -l 100
-p project2 -r europe-west1 -s 2024-11-15 -l 50
```
이러한 인수는 도구가 다음 두 범위를 분석하도록 안내합니다.
- 2025년 12월 1일과 2025년 12월 15일 사이에 생성된 us-central1 리전의 project1에 있는 최대 100개의 배치입니다.
- 2025년 11월 15일 이후에 생성된 europe-west1 리전의 project2에 있는 최대 50개의 배치입니다.

자격 스크립트

분석하려는 특정 Spark 이벤트 로그의 직접 Cloud Storage 경로가 있는 경우 이 방법을 사용하세요. 이 방법을 사용하려면 Cloud Storage의 이벤트 로그 파일에 대한 액세스 권한이 구성된 로컬 머신 또는 Compute Engine VM에서 셸 스크립트 run_qualification_tool.sh를 다운로드하고 실행해야 합니다.

Apache Spark용 서버리스 일괄 워크로드 이벤트 파일에 대해 스크립트를 실행하려면 다음 단계를 따르세요.

1.분석할 Spark 이벤트 파일이 포함된 로컬 디렉터리에 run_qualification_tool.sh 를 복사합니다.

자격 스크립트를 실행하여 이벤트 파일 하나 또는 스크립트 디렉터리에 포함된 이벤트 파일 집합 을 분석합니다.
```
./run_qualification_tool.sh -f EVENT_FILE_PATH/EVENT_FILE_NAME \
    -o CUSTOM_OUTPUT_DIRECTORY_PATH \
    -k SERVICE_ACCOUNT_KEY  \
    -x MEMORY_ALLOCATEDg  \
    -t PARALLEL_THREADS_TO_RUN
```
플래그 및 값:

-f (필수): Spark 워크로드 이벤트 파일을 찾으려면 Spark 이벤트 파일 위치 를 참고하세요.
- EVENT_FILE_PATH (EVENT_FILE_NAME이 지정되지 않은 경우 필수): 분석할 이벤트 파일의 경로입니다. 제공되지 않으면 이벤트 파일 경로는 현재 디렉터리로 간주됩니다.
- EVENT_FILE_NAME (EVENT_FILE_PATH가 지정되지 않은 경우 필수): 분석할 이벤트 파일의 이름입니다. 제공되지 않으면 EVENT_FILE_PATH에서 재귀적으로 발견된 이벤트 파일이 분석됩니다.
-o(선택 사항): 제공되지 않으면 도구는 현재 디렉터리 아래에 output 디렉터리를 만들거나 기존 디렉터리를 사용하여 출력 파일을 배치합니다.
- CUSTOM_OUTPUT_DIRECTORY_PATH: 출력 파일의 출력 디렉터리 경로입니다.
-k (선택사항):
- SERVICE_ACCOUNT_KEY: 서비스 계정 키입니다. EVENT_FILE_PATH에 액세스하는 데 필요한 경우 JSON 형식입니다.
-x (선택사항):
- MEMORY_ALLOCATED: 도구에 할당할 메모리(기가바이트)입니다. 기본적으로 도구는 시스템에서 사용 가능한 여유 메모리의 80% 와 사용 가능한 모든 머신 코어를 사용합니다.
-t(선택사항):
- PARALLEL_THREADS_TO_RUN: 도구가 실행할 병렬 스레드 수입니다. 기본적으로 도구는 모든 코어를 실행합니다.
명령어 사용 예:
```
./run_qualification_tool.sh -f gs://dataproc-temp-us-east1-9779/spark-job-history \
    -o perfboost-output -k /keys/event-file-key -x 34g -t 5
```
이 예에서 자격 도구는 gs://dataproc-temp-us-east1-9779/spark-job-history 디렉터리를 순회하고 이 디렉터리와 하위 디렉터리에 포함된 Spark 이벤트 파일을 분석합니다. 디렉터리에 대한 액세스 권한은 /keys/event-file-key에 제공됩니다. 이 도구는 실행에 34 GB memory 를 사용하고 5개의 병렬 스레드를 실행합니다.

Spark 이벤트 파일 위치

다음 단계 중 하나를 수행하여 Apache Spark용 서버리스 일괄 워크로드의 Spark 이벤트 파일을 찾으세요.

Cloud Storage에서 워크로드의 spark.eventLog.dir을 찾은 후 다운로드합니다.
1. spark.eventLog.dir을 찾을 수 없는 경우 spark.eventLog.dir을 Cloud Storage 위치로 설정한 후 워크로드를 다시 실행하고 spark.eventLog.dir을 다운로드합니다.
일괄 작업에 Spark 기록 서버 를 구성한 경우 다음 단계를 따르세요.
1. Spark 기록 서버로 이동한 후 워크로드를 선택합니다.
2. **이벤트 로그** 열에서 **다운로드** 를 클릭합니다.

자격 도구 출력 파일

자격 작업 또는 스크립트 분석이 완료되면 자격 도구 는 현재 디렉터리의 perfboost-output 디렉터리에 다음 출력 파일을 배치합니다.

AppsRecommendedForBoost.tsv: 네이티브 쿼리 실행과 함께 사용하도록 권장되는 애플리케이션의 탭으로 구분된 목록입니다.
UnsupportedOperators.tsv: 네이티브 쿼리 실행과 함께 사용하지 않는 것이 좋은 애플리케이션의 탭으로 구분된 목록입니다.

`AppsRecommendedForBoost.tsv` 출력 파일

다음 표는 샘플 AppsRecommendedForBoost.tsv 출력 파일의 콘텐츠를 보여줍니다. 분석된 각 애플리케이션의 행이 포함되어 있습니다.

샘플 AppsRecommendedForBoost.tsv 출력 파일:

applicationId	applicationName	rddPercentage	unsupportedSqlPercentage	totalTaskTime	supportedTaskTime	supportedSqlPercentage	recommendedForBoost	expectedRuntimeReduction
app-2024081/batches/083f6196248043938-000	projects/example.com:dev/locations/us-central1 6b4d6cae140f883c0 11c8e	0.00%	0.00%	548924253	548924253	100.00%	TRUE	30.00%
app-2024081/batches/60381cab738021457-000	projects/example.com:dev/locations/us-central1 474113a1462b426bf b3aeb	0.00%	0.00%	514401703	514401703	100.00%	TRUE	30.00%

열 설명:

applicationId: Spark 애플리케이션의 ApplicationID입니다. 상응하는 일괄 워크로드를 식별하는 데 사용합니다.
applicationName: Spark 애플리케이션의 이름입니다.
rddPercentage: 애플리케이션의 RDD 작업 비율입니다. RDD 작업은 네이티브 쿼리 실행에서 지원되지 않습니다.
unsupportedSqlPercentage: 네이티브 쿼리 실행에서 지원되지 않는 SQL 작업의 비율입니다.
totalTaskTime: 애플리케이션 실행 중에 실행된 모든 작업의 누적 작업 시간입니다.
supportedTaskTime: 네이티브 쿼리 실행에서 지원되는 총 작업 시간입니다.

다음 열은 네이티브 쿼리 실행이 일괄 워크로드에 도움이 되는지 판단하는 데 도움이 되는 중요한 정보를 제공합니다.

supportedSqlPercentage: 네이티브 쿼리 실행에서 지원되는 SQL 작업의 비율입니다. 비율이 높을수록 네이티브 쿼리 실행으로 애플리케이션을 실행하여 달성할 수 있는 런타임 감소가 커집니다.
recommendedForBoost: TRUE인 경우 네이티브 쿼리 실행으로 애플리케이션을 실행하는 것이 좋습니다. recommendedForBoost이 FALSE인 경우 일괄 워크로드에서 네이티브 쿼리 실행을 사용하지 마세요.
expectedRuntimeReduction: 네이티브 쿼리 실행으로 애플리케이션을 실행할 때 애플리케이션 런타임의 예상 감소 비율입니다.

`UnsupportedOperators.tsv` 출력 파일.

UnsupportedOperators.tsv 출력 파일에는 네이티브 쿼리 실행에서 지원되지 않는 워크로드 애플리케이션에 사용되는 연산자 목록이 포함되어 있습니다. 출력 파일의 각 행에는 지원되지 않는 연산자가 나열됩니다.