Como usar a interface de linha de comando do Cloud Dataflow

Ao executar o pipeline usando o serviço gerenciado do Dataflow, é possível obter informações sobre o job do Dataflow usando a interface de linha de comando do Dataflow. Ela faz parte da ferramenta de linha de comando gcloud no SDK do Cloud.

Observação: se preferir visualizar e interagir com os jobs do Dataflow por meio da IU baseada na Web, use a interface de monitoramento do Dataflow.

Como instalar o componente da linha de comando do Cloud Dataflow

Para usar a interface de linha de comando do Dataflow, primeiro é necessário instalar a ferramenta gcloud.

Como executar os comandos disponíveis

Você interage com a interface de linha de comando do Dataflow executando os comandos disponíveis. Para executar um, digite o seguinte comando no shell ou no terminal:

  gcloud dataflow

A interface de linha de comando do Dataflow tem três subcomandos principais: jobs, logs e metrics.

Comandos jobs

O grupo de subcomandos jobs permite visualizar e interagir com os jobs do Dataflow no projeto do Google Cloud. Esses comandos são usados para visualizar uma lista dos jobs, cancelar um deles, exibir a descrição de um job específico etc. Por exemplo, para visualizar uma lista de todos os jobs do Dataflow, digite o seguinte comando no shell ou no terminal:

gcloud dataflow jobs list

A ferramenta gcloud retorna uma lista dos jobs atuais, da seguinte maneira:

  ID                                        NAME                                    TYPE   CREATION_TIME        STATE   REGION
  2015-06-03_16_39_22-4020553808241078833   wordcount-janedoe-0603233849            Batch  2015-06-03 16:39:22  Done    us-central1
  2015-06-03_16_38_28-4363652261786938862   wordcount-johndoe-0603233820            Batch  2015-06-03 16:38:28  Done    us-central1
  2015-05-21_16_24_11-17823098268333533078  bigquerytornadoes-johndoe-0521232402    Batch  2015-05-21 16:24:11  Done    europe-west1
  2015-05-21_13_38_06-16409850040969261121  bigquerytornadoes-johndoe-0521203801    Batch  2015-05-21 13:38:06  Done    us-central1
  2015-05-21_13_17_18-18349574013243942260  bigquerytornadoes-johndoe-0521201710    Batch  2015-05-21 13:17:18  Done    europe-west1
  2015-05-21_12_49_37-9791290545307959963   wordcount-johndoe-0521194928            Batch  2015-05-21 12:49:37  Done    us-central1
  2015-05-20_15_54_51-15905022415025455887  wordcount-johndoe-0520225444            Batch  2015-05-20 15:54:51  Failed  us-central1
  2015-05-20_15_47_02-14774624590029708464  wordcount-johndoe-0520224637            Batch  2015-05-20 15:47:02  Done    us-central1

Com o ID do job, é possível executar o comando describe para exibir mais informações sobre um job.

export JOBID=<X>
gcloud dataflow jobs describe $JOBID

Por exemplo, se você executar o comando para o ID do job 2015-02-09_11_39_40-15635991037808002875, a ferramenta gcloud retornará as seguintes informações:

createTime: '2015-02-09T19:39:41.140Z'
currentState: JOB_STATE_DONE
currentStateTime: '2015-02-09T19:56:39.510Z'
id: 2015-02-09_11_39_40-15635991037808002875
name: tfidf-bchambers-0209193926
projectId: google.com:clouddfe
type: JOB_TYPE_BATCH

É possível executar o comando com a opção --format=json para formatar o resultado em JSON.

gcloud --format=json dataflow jobs describe $JOBID

A ferramenta gcloud retorna as seguintes informações formatadas:

{
  "createTime": "2015-02-09T19:39:41.140Z",
  "currentState": "JOB_STATE_DONE",
  "currentStateTime": "2015-02-09T19:56:39.510Z",
  "id": "2015-02-09_11_39_40-15635991037808002875",
  "name": "tfidf-bchambers-0209193926",
  "projectId": "google.com:clouddfe",
  "type": "JOB_TYPE_BATCH"
}

Para acessar uma lista completa dos comandos jobs, consulte o comando gcloud dataflow jobs na documentação do SDK do Cloud.

Comandos logs

Os comandos logs exibem entradas de registro para jobs executados no Serviço do Dataflow.

O comando list, por exemplo, é usado para imprimir os registros que informam sobre o que o job está fazendo.

export JOBID=<X>
gcloud dataflow logs list $JOBID

Para o ID do job 2015-02-09_11_39_40-15635991037808002875, a ferramenta gcloud retorna:

Listed 0 items.

Neste exemplo, nenhum registro foi exibido na gravidade padrão (Warning). É possível incluir os registros BASIC executando o comando list com a opção --importance=detailed.

gcloud dataflow logs list $JOBID --importance=detailed

A ferramenta gcloud imprime os seguintes registros:

d 2016-08-29T09:33:28 2015-02-09_11_39_40-15635991037808002875_00000156d72606f7 (39b2a31f5e883423): Starting worker pool synchronously
d 2016-08-29T09:33:28 2015-02-09_11_39_40-15635991037808002875_00000156d7260871 (39b2a31f5e883ce9): Worker pool is running
d 2016-08-29T09:33:28 2015-02-09_11_39_40-15635991037808002875_00000156d7260874 (39b2a31f5e883b77): Executing operation Count.PerElement/Sum.PerKey/GroupByKey/GroupByKeyOnly…
...

Para acessar uma lista completa dos comandos logs, consulte o comando gcloud dataflow logs na documentação do SDK do Cloud.

Comandos metrics

Os comandos metrics permitem visualizar as métricas de um determinado job do Dataflow.

Observação: os nomes dos comandos metric estão sujeitos a alterações, e algumas métricas estão sujeitas à exclusão.

O comando list é usado para acessar informações sobre as etapas do job.

gcloud dataflow metrics list $JOBID

Para esse comando, a ferramenta gcloud retorna:

---
name:
  name: s09-s14-start-msecs
  origin: dataflow/v1b3
scalar: 137
updateTime: '2016-08-29T16:35:50.007Z'
---
name:
  context:
    output_user_name: WordCount.CountWords/Count.PerElement/Init-out0
  name: ElementCount
  origin: dataflow/v1b3
scalar: 26181
updateTime: '2016-08-29T16:35:50.007Z'
---
name:
  context:
    step: s2
  name: emptyLines
  origin: user
scalar: 1080
updateTime: '2016-08-29T16:35:50.007Z'
...

O comando gcloud dataflow metrics list é usado para obter métricas preliminares enquanto o job estiver em execução ou logo após a conclusão. Para visualizar métricas preliminares, execute o comando com a sinalização --tentative. Uma métrica marcada como tentative é atualizada com frequência à medida que as instâncias de worker processam os dados do pipeline. Ela poderá diminuir se houver um erro no worker. As métricas tentative se tornam valores committed à medida que o worker conclui o trabalho e confirma os resultados.

Para acessar uma lista completa dos comandos metrics, consulte o comando gcloud dataflow metrics na documentação do SDK do Cloud.

Como usar comandos com endpoints regionais

A interface de linha de comando do Dataflow é compatível com endpoints regionais desde a versão 176 da ferramenta gcloud. Use a opção --region com qualquer comando para especificar o endpoint regional que gerencia o job.

Por exemplo, gcloud dataflow jobs list listará os jobs de todas as regiões, mas gcloud dataflow jobs list --region=europe-west1 listará apenas os gerenciados de europe-west1.

Observação: a opção --region é necessária para obter informações de um job de um endpoint regional. Se você não especificar um endpoint regional, us-central1 será usado como padrão.