Monitorar fluxos de trabalho

Esta página contém informações para ajudar você a monitorar implantações e execuções de fluxos de trabalho.

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

É possível acessar registros de erros relacionados à implantação e exclusão de um fluxo de trabalho no console do Google Cloud.

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

    Acessar fluxos de trabalho

  2. Clique no nome do fluxo de trabalho para abrir a página Detalhes do fluxo de trabalho.

  3. Clique na guia Registros.

  4. 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

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

    Acessar fluxos de trabalho

  2. Para acessar os resultados da execução de um fluxo de trabalho, clique no nome dele para acessar a página Detalhes do fluxo de trabalho.

  3. Para detalhes sobre uma execução específica, na guia Executions, clique no ID da execução na lista para acessar a página Execution details.

  4. Na guia Resumo, cada execução tem as seguintes informações:

    • Estado de execução: indica o estado final do fluxo de trabalho, incluindo o 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. Consulte Registro de chamadas neste documento.
    • Entrada: os argumentos do ambiente de execução transmitidos ao 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.
  5. Para conferir o histórico de execução do fluxo de trabalho como uma lista de entradas de etapas, clique na guia Etapas. Para mais informações, consulte Consultar o histórico das etapas de execução.

  6. Para visualizar os registros de uma execução de fluxo de trabalho, clique na guia Registros.

  7. 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

  1. 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.

  2. 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 é capturado em um bloco try/except, a execução falha e um mapa de erros (um dicionário JSON) que descreve 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 às seguintes:

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

Pode haver mais de uma tag. Para verificar se há uma tag específica, você pode usar um expression. Exemplo:

${'SystemError' in e.tags}

Acessar dados de erro retornados como uma string

Alguns conectores e APIs HTTP serializam erros como strings antes de retornar os erros. É possível usar funções de biblioteca padrão para restaurar um payload ao erro original. Por exemplo, para converter uma string de erro em um mapa, você pode usar 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. 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 idempotente.
ConnectionFailedError Gerado quando uma conexão não é estabelecida com o endpoint de API. para 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 Surge quando uma solicitação HTTP falha com um status de erro HTTP. Quando essa exceção é gerada, o é 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 sem sucesso.
ParallelNestingError Surge quando a profundidade máxima em que as etapas paralelas podem ser aninhadas é excedida.
RecursionError Gerado quando o intérprete detecta que o a profundidade máxima da pilha de chamadas for 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 É gerada quando uma ou mais ramificações ou iterações encontram um erro de execução não tratado 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 a conclusão da última execução e retornar o resultado dela, digite o seguinte comando:

    gcloud workflows executions wait-last

    Se você fez uma tentativa de execução anterior na mesma sessão do gcloud, o comando aguarda a conclusão da tentativa de execução anterior e, em seguida, retorna os resultados da execução concluída. Se não houver nenhuma tentativa anterior, gcloud vai retornar o seguinte erro:

    ERROR: (gcloud.workflows.executions.wait-last) [NOT FOUND] There are no cached executions available.
    
  • Para conferir o status da última execução, digite o seguinte comando:

    gcloud workflows executions describe-last

    Se você fez uma tentativa de execução anterior na mesma sessão de gcloud, o comando retorna 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.
    

Execuções de filtro

É possível aplicar filtros à lista de execuções de fluxo de trabalho retornadas pelo método workflows.executions.list.

É possível filtrar pelos seguintes campos:

  • createTime
  • disableOverflowBuffering
  • duration
  • endTime
  • executionId
  • label
  • startTime
  • state
  • stepName
  • workflowRevisionId

Por exemplo, para filtrar um rótulo (labels."fruit":"apple"), faça uma solicitação de API semelhante a esta:

GET https://workflowexecutions.googleapis.com/v1/projects/MY_PROJECT/locations/MY_LOCATION/workflows/MY_WORKFLOW/executions?view=full&filter=labels.%22fruit%22%3A%22apple%22"

Em que:

  • view=full especifica uma visualização que define quais campos precisam ser preenchidos na execuções retornadas nesse caso, todos os dados
  • labels.%22fruit%22%3A%22apple%22 é a sintaxe do filtro codificado pelo URL

Para mais informações, consulte Filtragem AIP-160.

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 você pode registrar qualquer exceções que são capturadas 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 de solicitação HTTP Authorization são editados nos registros de chamadas HTTP.

Ao aplicar o registro de chamadas definição do fluxo de trabalho ou ao execução de um fluxo de trabalho, especifique o nível de geração de registros necessário. O nível de registro de execução leva 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 será aplicado.

O limite de tamanho de entrada de registro definido pelo Cloud Logging também se aplica ao registro 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:

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

    Acessar fluxos de trabalho

  2. Para acessar os registros de um fluxo de trabalho, clique no nome dele para acessar a página Detalhes.

  3. Para visualizar os registros, clique em Registros.

  4. 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:

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

    Acessar o Explorador de registros

  2. No Criador de consultas, clique em Recurso e digite workflow. Selecione Cloud Workflow na lista e clique em Adicionar.

    Geração de registros de fluxo de trabalho

  3. Clique em Run query.

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

A seguir