Esta página foi traduzida pela API Cloud Translation.

Executar a ferramenta de qualificação de execução de consultas nativas

Para identificar cargas de trabalho em lote que podem alcançar tempos de execução mais rápidos com a execução de consultas nativas (NQE, na sigla em inglês), use a ferramenta de qualificação. A ferramenta analisa os registros de eventos do Spark para estimar possíveis economias de tempo de execução e identificar operações que não são compatíveis com o mecanismo NQE.

OGoogle Cloud oferece dois métodos para executar a análise de qualificação: job de qualificação e script de qualificação. A abordagem recomendada para a maioria dos usuários é o job de qualificação, que automatiza a descoberta e a análise de cargas de trabalho em lote. O script de qualificação alternativo está disponível para o caso de uso específico de análise de um arquivo de registro de eventos conhecido. Escolha o método que melhor se adapta ao seu caso de uso:

Vaga de qualificação (recomendado): esse é o método principal e recomendado. É um job do PySpark que descobre e analisa automaticamente as cargas de trabalho em lote recentes em um ou mais projetos e regiões do Google Cloud . Use esse método quando quiser fazer uma análise ampla sem precisar localizar manualmente arquivos de registro de eventos individuais. Essa abordagem é ideal para avaliação em grande escala da adequação do NQE.
Script de qualificação (alternativo): um método alternativo para casos de uso avançados ou específicos. É um script shell que analisa um único arquivo de registro de eventos do Spark ou todos os registros de eventos em um diretório específico do Cloud Storage. Use esse método se você tiver o caminho do Cloud Storage para os registros de eventos que quer analisar.

Job de qualificação

O job de qualificação simplifica a análise em grande escala ao verificar programaticamente as cargas de trabalho em lote do Serverless para Apache Spark e enviar um job de análise distribuída. A ferramenta avalia os jobs em toda a organização, eliminando a necessidade de encontrar e especificar manualmente os caminhos dos registros de eventos.

Conceder papéis do IAM

Para que o job de qualificação acesse os metadados da carga de trabalho em lote e leia os registros de eventos do Spark no Cloud Logging, a conta de serviço que executa a carga de trabalho precisa ter os seguintes papéis do IAM concedidos em todos os projetos a serem analisados:

Enviar o job de qualificação

Você envia o job de qualificação usando a ferramenta de CLI gcloud. O job inclui um script PySpark e um arquivo JAR hospedados em um bucket público do Cloud Storage.

É possível executar o job em um dos seguintes ambientes de execução:

Como uma carga de trabalho em lote do Serverless para Apache Spark. Essa é uma execução de job simples e independente.
Como um job executado em um cluster do Dataproc no Compute Engine. Essa abordagem pode ser útil para integrar o job a um fluxo de trabalho.

Argumentos de job

Argumento	Descrição	Obrigatório?	Valor padrão
`--project-ids`	Um único ID do projeto ou uma lista separada por vírgulas de IDs de projetos do Google Cloud para verificar cargas de trabalho em lote.	Não	O projeto em que o job de qualificação está sendo executado.
`--regions`	Uma única região ou uma lista separada por vírgulas de regiões para verificar nos projetos especificados.	Não	Todas as regiões nos projetos especificados.
`--start-time`	A data de início para filtrar lotes. Somente os lotes criados a partir dessa data (formato: AAAA-MM-DD) serão analisados.	Não	Nenhum filtro de data de início é aplicado.
`--end-time`	A data de término para filtrar lotes. Somente os lotes criados até essa data (formato: AAAA-MM-DD) serão analisados.	Não	Nenhum filtro de data de término é aplicado.
`--limit`	O número máximo de lotes a serem analisados por região. Os lotes mais recentes são analisados primeiro.	Não	Todos os lotes que correspondem aos outros critérios de filtro são analisados.
`--output-gcs-path`	O caminho do Cloud Storage (por exemplo, `gs://your-bucket/output/`) em que os arquivos de resultado serão gravados.	Sim	Nenhuma.
`--input-file`	O caminho do Cloud Storage para um arquivo de texto para análise em massa. Se fornecido, esse argumento vai substituir todos os outros argumentos que definem o escopo (`--project-ids`, `--regions`, `--start-time`, `--end-time`, `--limit`).	Não	Nenhuma.

Exemplos de tarefas de qualificação

Um job em lote do Serverless para Apache Spark para realizar análises simples e ad hoc. Os argumentos do job são listados após o separador --.

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

Um job em lote do Serverless para Apache Spark para analisar até 50 dos lotes mais recentes encontrados em sample_project na região us-central1. Os resultados são gravados em um bucket no Cloud Storage. Os argumentos do job são listados após o separador --.

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/

Um job do Dataproc no Compute Engine enviado a um cluster do Dataproc para análise em massa em um fluxo de trabalho de análise em grande escala, repetível ou automatizado. Os argumentos do job são colocados em um INPUT_FILE que é enviado para um BUCKET no Cloud Storage. Esse método é ideal para verificar diferentes períodos ou limites de lote em vários projetos e regiões em uma única execução.
```
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
```
Observações:

INPUT_FILE: cada linha do arquivo representa uma solicitação de análise distinta e usa um formato de flags de uma única letra seguidas pelos valores, como -p PROJECT-ID -r REGION -s START_DATE -e END_DATE -l LIMITS.

Exemplo de conteúdo do arquivo de entrada:
```
-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
```
Esses argumentos direcionam a ferramenta para analisar os dois escopos a seguir:
- Até 100 lotes no projeto1 na região us-central1 criados entre 1º e 15 de dezembro de 2025.
- Até 50 lotes no projeto2 na região europe-west1 criados a partir de 15 de novembro de 2025.

Script de qualificação

Use esse método se você tiver o caminho direto do Cloud Storage para um registro de eventos específico do Spark que quer analisar. Essa abordagem exige que você faça o download e execute um script shell, run_qualification_tool.sh, em uma máquina local ou em uma VM do Compute Engine configurada com acesso ao arquivo de registro de eventos no Cloud Storage.

Siga estas etapas para executar o script nos arquivos de eventos da carga de trabalho em lote do Serverless para Apache Spark.

1.Copie o run_qualification_tool.sh para um diretório local que contenha os arquivos de eventos do Spark a serem analisados.

Execute o script de qualificação para analisar um arquivo de evento ou um conjunto de arquivos de evento contidos no diretório do script.
```
./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
```
Flags e valores:

-f (obrigatório): consulte Locais dos arquivos de eventos do Spark para encontrar os arquivos de eventos da carga de trabalho do Spark.
- EVENT_FILE_PATH (obrigatório, a menos que EVENT_FILE_NAME seja especificado): caminho do arquivo de evento a ser analisado. Se não for fornecido, o caminho do arquivo de evento será considerado o diretório atual.
- EVENT_FILE_NAME (obrigatório, a menos que EVENT_FILE_PATH seja especificado): nome do arquivo de evento a ser analisado. Se não for fornecido, os arquivos de evento encontrados recursivamente no EVENT_FILE_PATH serão analisados.
-o(opcional): se não for fornecido, a ferramenta vai criar ou usar um diretório output no diretório atual para colocar os arquivos de saída.
- CUSTOM_OUTPUT_DIRECTORY_PATH: caminho do diretório de saída para arquivos de saída.
-k (opcional):
- SERVICE_ACCOUNT_KEY: a chave da conta de serviço no formato JSON, se necessário para acessar o EVENT_FILE_PATH.
-x (opcional):
- MEMORY_ALLOCATED: memória em gigabytes a ser alocada para a ferramenta. Por padrão, a ferramenta usa 80% da memória livre disponível no sistema e todos os núcleos de máquina disponíveis.
-t(opcional):
- PARALLEL_THREADS_TO_RUN: o número de linhas de execução paralelas que a ferramenta vai executar. Por padrão, a ferramenta executa todos os núcleos.
Exemplo de uso do comando:
```
./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
```
Neste exemplo, a ferramenta de qualificação percorre o diretório gs://dataproc-temp-us-east1-9779/spark-job-history e analisa os arquivos de eventos do Spark contidos nele e nos subdiretórios. O acesso ao diretório é fornecido pelo /keys/event-file-key. A ferramenta usa 34 GB memory para execução e executa 5 linhas de execução paralelas.

Locais dos arquivos de eventos do Spark

Siga uma destas etapas para encontrar os arquivos de eventos do Spark para cargas de trabalho em lote do Serverless para Apache Spark:

No Cloud Storage, encontre e faça o download do spark.eventLog.dir da carga de trabalho.
1. Se você não encontrar o spark.eventLog.dir, defina o spark.eventLog.dir como um local do Cloud Storage, execute a carga de trabalho novamente e faça o download do spark.eventLog.dir.
Se você tiver configurado o servidor de histórico do Spark para o job em lote:
1. Acesse o servidor de histórico do Spark e selecione a carga de trabalho.
2. Clique em Download na coluna Registro de eventos.

Arquivos de saída da ferramenta de qualificação

Quando o job de qualificação ou a análise de script for concluída, a ferramenta de qualificação colocará os seguintes arquivos de saída em um diretório perfboost-output no diretório atual:

AppsRecommendedForBoost.tsv: uma lista separada por tabulação de aplicativos recomendados para uso com a execução de consultas nativas.
UnsupportedOperators.tsv: uma lista separada por tabulação de aplicativos não recomendados para uso com a execução de consultas nativas.

Arquivo de saída `AppsRecommendedForBoost.tsv`

A tabela a seguir mostra o conteúdo de um exemplo de arquivo de saída AppsRecommendedForBoost.tsv. Ela contém uma linha para cada aplicativo analisado.

Exemplo de arquivo de saída 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%	0%	548924253	548924253	100%	TRUE	30%
app-2024081/batches/60381cab738021457-000	projects/example.com:dev/locations/us-central1 474113a1462b426bf b3aeb	0%	0%	514401703	514401703	100%	TRUE	30%

Descrições de colunas:

applicationId: o ApplicationID do aplicativo Spark. Use isso para identificar a carga de trabalho em lote correspondente.
applicationName: o nome do aplicativo Spark.
rddPercentage: a porcentagem de operações de RDD no aplicativo. As operações de RDD não são compatíveis com a execução de consultas nativas.
unsupportedSqlPercentage: Porcentagem de operações SQL não compatíveis com a execução de consultas nativas.
totalTaskTime: tempo cumulativo de todas as tarefas executadas durante a execução do aplicativo.
supportedTaskTime: o tempo total de tarefa compatível com a execução de consultas nativas.

As colunas a seguir fornecem informações importantes para ajudar você a determinar se a execução de consultas nativas pode beneficiar sua carga de trabalho em lote:

supportedSqlPercentage:a porcentagem de operações SQL compatíveis com a execução de consultas nativas. Quanto maior a porcentagem, maior a redução no tempo de execução que pode ser alcançada ao executar o aplicativo com a execução de consultas nativas.
recommendedForBoost:se TRUE, recomendamos executar o aplicativo com a execução de consultas nativas. Se recommendedForBoost for FALSE, não use a execução de consultas nativas na carga de trabalho em lote.
expectedRuntimeReduction:a porcentagem esperada de redução no tempo de execução do aplicativo ao executar o aplicativo com a execução de consultas nativas.

Arquivo de saída `UnsupportedOperators.tsv`.

O arquivo de saída UnsupportedOperators.tsv contém uma lista de operadores usados em aplicativos de carga de trabalho que não são compatíveis com a execução de consultas nativas. Cada linha no arquivo de saída lista um operador sem suporte.