Monitorar fluxos de trabalho

Nesta página, você encontra informações para monitorar as implantações e execuções do fluxo de trabalho.

Acessar a implantação e a exclusão de fluxos de trabalho

Acesse os registros de erros relacionados à implantação e à exclusão de um fluxo de trabalho no console do Google Cloud.

No console do Google Cloud, abra a página Workflows.

Acessar fluxos de trabalho
Clique no nome do fluxo de trabalho para exibir a página Detalhes do fluxo de trabalho.
Clique na guia Registros.
Para filtrar os registros por gravidade, selecione o tipo de registro a ser exibido na lista Padrão.

Acessar os resultados da execução do fluxo de trabalho

É possível acessar os resultados da execução do fluxo de trabalho no console do Google Cloud ou usando a CLI gcloud.

Console

No console do Google Cloud, abra a página Workflows.

Acessar fluxos de trabalho
Para acessar os resultados de execução de um fluxo de trabalho, clique no nome do fluxo de trabalho para acessar a página Detalhes do fluxo de trabalho.
Para detalhes sobre uma execução específica, na guia Execuções, clique no ID correspondente na lista para acessar a página Detalhes de execução.

Observação:para acessar a página Detalhes de execução, você precisa ter um papel que contenha as permissões workflows.workflows.get, workflows.executions.get e workflows.stepEntries.list. Para mais informações, consulte Papéis e permissões do Workflows e Gerenciar acesso.
Na guia Resumo, cada execução tem as seguintes informações:
- Estado de execução: indica o estado final do fluxo de trabalho, incluindo a etapa atual ou final do fluxo de trabalho.
- Início da execução: quando a execução começou.
- Fim da execução: quando a execução terminou.
- Duração da execução: tempo total decorrido. Isso pode ser uma indicação de erros de rede ou problemas de conectividade.
- Nome do fluxo de trabalho: o nome do fluxo de trabalho.
- Revisão do fluxo de trabalho: a revisão atual no momento da execução.
- Nível de registro de chamadas: o nível de registro de chamadas aplicado durante a execução. Neste documento, consulte Registro de chamadas.
- Entrada: os argumentos do ambiente de execução transmitidos para o fluxo de trabalho, se houver.
- Saída: a saída do fluxo de trabalho. Se a execução falhou, inclui a exceção que levou à falha. Neste documento, consulte Mensagens de erro de execução.
Para visualizar o histórico de execução do fluxo de trabalho como uma lista de entradas de etapa, clique na guia Etapas. Para mais informações, consulte Ver o histórico de etapas de execução.
Para visualizar os registros de uma execução de fluxo de trabalho, clique na guia Registros.
Para filtrar os registros de execução, use o campo Filtro na parte superior da tabela. Por exemplo, para exibir apenas tentativas de execução malsucedidas, insira failed no campo de texto do filtro.

gcloud

Para ver uma lista completa das execuções de um fluxo de trabalho, digite o seguinte comando:
```
gcloud workflows executions list WORKFLOW_NAME
```
Substitua WORKFLOW_NAME pelo nome do fluxo de trabalho. Copie o ID de execução do seu interesse.
Para ver os registros de execução de um fluxo de trabalho, digite o seguinte comando:
```
gcloud workflows executions describe \
    --workflow=WORKFLOW_NAME \
    EXECUTION_ID
```
Substitua:
- WORKFLOW_NAME: o nome do fluxo de trabalho
- EXECUTION_ID: o ID exclusivo da execução
Esse comando retorna um resultado semelhante a este:
```
argument: 'null'
endTime: '2022-07-19T12:40:07.070039707Z'
error:
 context: |-
    The argument of 'in' must be a dict or an array; got: null
    in step "checkSearchTermInInput", routine "main", line: 12
 payload: "{"message":"The argument of 'in' must be a dict or an array; got: null"

    ,"tags":["TypeError"]}"
 stackTrace:
    elements:
    - position:
       column: '26'
       length: '24'
       line: '12'
       routine: main
       step: checkSearchTermInInput
name: projects/1051295516635/locations/us-central1/workflows/myFirstWorkflow/executions/17ffc89c-0a27-4d2f-8356-e681d949a3d3
startTime: '2022-07-19T12:40:07.024823663Z'
state: FAILED
status:
 currentSteps:
 - routine: main
    step: checkSearchTermInInput
workflowRevisionId: 000001-ac2
```
A saída contém as informações a seguir:
- argument: os argumentos de ambiente de execução transmitidos para o fluxo de trabalho, se houver
- endTime: quando a execução foi finalizada
- error: a mensagem de erro gerada como parte da exceção que resultou na falha da execução
- name: o nome completo da execução, incluindo o nome do projeto, o local do fluxo de trabalho, o nome do fluxo de trabalho e o ID da execução
- startTime: quando a execução começou
- state: indica o estado final do fluxo de trabalho
- status: a etapa atual ou final do fluxo de trabalho da execução.
- workflowRevisionID: a revisão atual no momento da execução

Mapas de erros de execução

Quando um fluxo de trabalho gera um erro durante a execução que não é detectado em um bloco try/except, a execução falha e um mapa de erros (um dicionário JSON) descrevendo o erro é retornado.

Os erros gerados durante a execução do fluxo de trabalho contêm tags para ajudar a identificar o que causou o erro. Por exemplo, o erro retornado de um conector pode ter duas chaves (tags e message) semelhantes ao seguinte:

{'tags': ['SystemError'], 'message': 'an error has occurred'}

Pode haver mais de uma tag. Para verificar a presença de uma tag específica, você pode usar uma expressão. Exemplo:

${'SystemError' in e.tags}

Acessar dados de erro retornados como uma string

Alguns conectores e APIs HTTP serializam erros como strings antes de os retornar. Use as funções padrão da biblioteca para restaurar um payload no erro original. Por exemplo, para converter uma string de erro em um mapa, use as funções json.decode e text.encode:

json.decode(text.encode(ERROR_FROM_API))

Tags de erro

A tabela a seguir descreve o significado de diferentes tags de erro.

Tag	Descrição
AuthError	Surge ao gerar credenciais para uma solicitação HTTP.
ConnectionError	Gerado quando uma conexão é estabelecida com o endpoint, mas há um problema com a conexão durante a transferência de dados. A conexão é encerrada antes que uma resposta completa seja recebida e uma mensagem pode não ter sido entregue ao endpoint. As novas tentativas podem não ser idempotentes.
ConnectionFailedError	Gerado quando uma conexão não é estabelecida com o endpoint de API. Por exemplo, devido a um nome de domínio incorreto, problemas de resolução de DNS ou outros problemas de rede. As novas tentativas são idempotentes.
HttpError	Gerado quando uma solicitação HTTP falha com um status de erro HTTP. Quando essa exceção é gerada, a resposta é um mapa com os seguintes elementos: `tags`: lista com a string `HttpError` `message`: mensagem de erro legível `code`: código de status de resposta HTTP `headers`: cabeçalhos de resposta `body`: corpo da resposta
IndexError	Surge quando um subscrito de sequência é um número inteiro fora do intervalo.
KeyError	Surge quando uma chave de mapa não é encontrada no conjunto de chaves atuais.
OperationError	Gerado quando uma operação de longa duração é concluída com falha.
ParallelNestingError	Gerado quando a profundidade máxima em que as etapas paralelas podem ser aninhadas é excedida.
RecursionError	Gerado quando o intérprete detecta que a profundidade máxima da pilha de chamadas foi excedida.
ResourceLimitError	Surge quando algum limite de recurso é esgotado. Quando gerado internamente, esse tipo de erro não pode ser capturado e causa falha de execução imediata.
ResponseTypeError	Gerada quando uma operação de longa duração retorna uma resposta do tipo errado.
SystemError	Surge quando o intérprete encontra um erro interno.
TimeoutError	Surge quando uma função do sistema atinge o tempo limite no nível do sistema.
TypeError	Surge quando uma operação ou função é aplicada a um objeto de tipo incompatível. O valor associado é uma string que fornece detalhes sobre a incompatibilidade de tipos.
UnhandledBranchError	Gerado quando uma ou mais ramificações ou iterações encontram um erro de tempo de execução não processado até um número máximo.
ValueError	Surge quando uma operação ou função recebe um argumento que tem o tipo correto, mas um valor incorreto, e a situação não é descrita por uma exceção mais precisa, como um `IndexError`.
ZeroDivisionError	Surge quando o segundo argumento de uma divisão ou operação de módulo é zero. O valor associado é uma string que indica o tipo dos operandos e a operação.

Também é possível gerar erros personalizados usando a sintaxe raise.

Verificar o status das execuções

Há vários comandos para ajudar você a verificar o status de uma execução de fluxo de trabalho.

Para recuperar uma lista das tentativas de execução de um fluxo de trabalho e os respectivos IDs, digite o seguinte comando:
```
gcloud workflows executions list WORKFLOW_NAME
```
Substitua WORKFLOW_NAME pelo nome do fluxo de trabalho.

O comando retorna um valor NAME semelhante ao seguinte:

projects/PROJECT_NUMBER/locations/REGION/workflows/WORKFLOW_NAME/executions/EXECUTION_ID

Copie o ID de execução para usar no próximo comando.
Para verificar o status de uma tentativa de execução e aguardar ela ser concluída, digite o seguinte comando:
```
gcloud workflows executions wait EXECUTION_ID
```
Substitua EXECUTION_ID pelo ID da tentativa de execução.

O comando aguarda a conclusão da tentativa de execução e, em seguida, retorna os resultados.
Para aguardar até que a última execução seja concluída e, em seguida, retornar o resultado dela, insira o seguinte comando:
```
gcloud workflows executions wait-last
```
Se você fez uma tentativa de execução anterior na mesma sessão gcloud, o comando aguardará a conclusão da tentativa de execução anterior e retornará os resultados da execução concluída. Se não houver nenhuma tentativa anterior, gcloud retornará o seguinte erro:
```
ERROR: (gcloud.workflows.executions.wait-last) [NOT FOUND] There are no cached executions available.
```
Para receber o status da última execução, digite o seguinte comando:
```
gcloud workflows executions describe-last
```
Se você tiver feito uma tentativa de execução anterior na mesma sessão gcloud, o comando retornará os resultados da última execução, mesmo que ela esteja em execução. Se não houver nenhuma tentativa anterior, o gcloud retornará o seguinte erro:
```
ERROR: (gcloud.beta.workflows.executions.describe-last) [NOT FOUND] There are no cached executions available.
```

Enviar registros para o Cloud Logging

O Workflows gera registros de execução no Cloud Logging automaticamente.

Também é possível ativar o registro de chamadas. Ou, ainda, criar registros personalizados que usam a função sys.log na origem. O registro de chamadas e os registros personalizados permitem controlar quando os registros são enviados para o Logging durante uma execução de fluxo de trabalho e podem ser particularmente úteis para depurar seu fluxo de trabalho.

Para detalhes, incluindo os arquivos proto de geração de registros engine_call e executions_system, consulte este repositório do GitHub.

Registros de execução

Cada execução de fluxo de trabalho aciona automaticamente pelo menos dois registros: um no início da execução e outro no final.

Para mais informações sobre os registros da plataforma do Workflows disponíveis no Logging, consulte Registros do Google Cloud Platform.

Registro de chamadas

É possível definir uma sinalização para que cada etapa de chamada durante a execução do fluxo de trabalho seja registrada, assim como os nomes de etapas, nomes de funções, argumentos de função e respostas de chamada. Ou então, você pode registrar todas as exceções detectadas ou que interrompem uma chamada.

Somente as etapas explícitas da chamada são registradas, como chamadas para subfluxos de trabalho ou funções de biblioteca. Chamadas de expressões ou dentro de funções de biblioteca padrão (por exemplo, http.post em sys.log) e conectores internos não são registrados.

Os cabeçalhos da solicitação HTTP Authorization são editados nos registros de chamadas HTTP.

Ao aplicar a geração de registros de chamadas a uma definição de fluxo de trabalho ou à execução de um fluxo de trabalho, é possível especificar o nível necessário de geração de registros. O nível de registro de execução tem precedência sobre qualquer nível de registro de fluxo de trabalho, a menos que o nível de registro de execução não seja especificado (o padrão). Nesse caso, o nível de registro do fluxo de trabalho se aplica.

Observe que o limite de tamanho da entrada de registro definido pelo Cloud Logging também se aplica à geração de registros de chamadas.

Registros personalizados

Para criar uma entrada de registro no Logging durante uma execução de fluxo de trabalho, defina uma etapa no fluxo que faz uma chamada para a função sys.log padrão da biblioteca:

YAML

  - step1:
      assign:
          - varA: "Hello"
          - varB: "World"
  - logStep:
      call: sys.log
      args:
          text: TEXT
          severity: SEVERITY 
  - step2:
      return: ${varA + " " + varB}

JSON

    [
      {
        "step1": {
          "assign": [
            {
              "varA": "Hello"
            },
            {
              "varB": "World"
            }
          ]
        }
      },
      {
        "logStep": {
          "call": "sys.log",
          "args": {
            "text": "TEXT",
            "severity": "SEVERITY"
          }
        }
      },
      {
        "step2": {
          "return": "${varA + " " + varB}"
        }
      }
    ]

Ao criar uma entrada de registro, defina:

TEXT: obrigatório. O texto a ser registrado. Se você precisar registrar os valores de um mapa, use ${json.encode_to_string(myMap)}.
SEVERITY: opcional. O nível de gravidade da entrada de registro. Por exemplo, INFO, WARNING ou CRITICAL.

Para mais informações, consulte a função de referência sys.log.

Permissões necessárias

Para aplicar o registro de chamadas ou enviar registros personalizados ao Logging, um fluxo de trabalho precisa estar associado a uma conta de serviço que inclua a permissão logging.logEntries.create, por exemplo, o papel roles/logging.logWriter. Se você precisar alterar a conta de serviço atualizada com seu fluxo de trabalho, consulte Atualizar um fluxo de trabalho. Para saber mais sobre como criar contas de serviço e atribuir papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Ver registros do fluxo de trabalho

É possível ver os registros no Workflows ou no Logging. Para ver os registros de um único fluxo de trabalho, use a guia Registros do Workflows. Para ter uma visualização agregada dos registros de todos os fluxos de trabalho, use a página Explorador de registros do Logging.

Ver registros no Workflows

Para ver os registros de um fluxo de trabalho no Workflows, faça o seguinte:

No console do Google Cloud, acesse a página Fluxos de trabalho.

Acessar fluxos de trabalho
Para acessar os registros de um fluxo de trabalho, clique no nome dele para acessar a página Detalhes.
Para visualizar os registros, clique em Registros.
Para filtrar os registros por gravidade, selecione o tipo de registro a ser exibido na lista Padrão. Por padrão, os registros de todos os níveis de gravidade são exibidos.

A guia Registros na página Detalhes de um fluxo de trabalho exibe os seguintes tipos de registros:

Registros enviados para o Logging
Registros de auditoria de qualquer operação realizada no fluxo de trabalho, como atualizações na definição do fluxo de trabalho

Ver registros no Logging

Para ver os registros no Logging, faça o seguinte:

No console do Google Cloud, acesse a página Análise de registros:

Acessar o Explorador de registros
No Criador de consultas, clique em Recurso e digite workflow. Selecione Cloud Workflow na lista e clique em Adicionar.
Clique em Run query.

Para saber mais sobre como visualizar registros no Logging, consulte Usar o Explorador de registros.