TELEMETRIA

O que é e para que serve?

Na célula de RPA do Grupo Águia Branca, os produtos principais que são confeccionados por nós, desenvolvedores, são as automações (também chamados de trabalhadores virtuais, ou ainda, robôs) responsáveis por realizar uma tarefa, de modo a gerar valor através do cumprimento de certos objetivos. A telemetria são dados gerados a cada execução do robô que refletem o funcionamento daquele robô na execução específica.

A telemetria gera dados que demonstram como o robô funciona em cada uma de suas execuções, contendo dados como quais os passos que foram realizados naquela execução, que objetivos ele conseguiu identificar, e se esses objetivos foram cumpridos com sucesso ou não. Esses dados podem então ser consultados no nosso portal RPA System e serem usados para decisões estratégicas, diagnósticos, etc.

Atualmente, a telemetria utilizada obtém dados e os separa de acordo com as seguinte estrutura:

Ciclo (Cycle):

Um ciclo representa a execução de um robô. Se um robô é executado diariamente, então todos os dias a telemetria irá gerar um ciclo representando aquela execução.

Cada ciclo possui as seguintes propriedades:

• Data de Início: Data de início da execução do Ciclo
• Data de Fim: Data de fim da execução do Ciclo
• Status: Estado de execução do Ciclo, podendo ser:
  • 0: Não concluído
  • 1: Concluído com sucesso
  • 2: Concluído com erro
• Descrição: Texto que descreve a natureza da execução atual deste robô. Geralmente é (mas não está restrito a):
  • “Rodada de testes”
  • “Rodada programada” (independente de ser manual ou automática)

Geralmente um ciclo é iniciado quando o robô inicia, e é finalizado quando o robô terminar sua execução, porém, em alguns casos especiais, esse relacionamento nem sempre é de 1 para 1. Existem casos onde execuções não geram ciclo algum, e casos onde uma única execução pode gerar 2 ou mais ciclos. Porém, esses casos não são a regra e devem ser consultados e discutidos com a equipe para validar a necessidade dessa exceção.

Saída (Output):

Todo robô existe para cumprir um certo objetivo, objetivo este que é o artefato gerador de valor do robô. Se um robô não possui um objetivo, ele não gera valor, portanto, é obsoleto. Este objetivo é algo vital para entendermos o que é a Saída de um ciclo.

Uma Saída representa a entrega principal de um robô, ou seja, quais objetivos aquele robô cumpriu durante sua execução. De maneira resumida, pode-se entender como saída:

• Um e-mail enviado
• Um registro adicionado em um banco de dados
• Um arquivo baixado/produzido
• O processamento de alguma entidade (ex: cadastro em um portal, recebimento de MD, lançamento em nbs ou sap, etc.)

Para entender um pouco melhor o que representa uma saída, abaixo seguem alguns exemplos:

Robô: Envio de notificação de aniversário Descrição: Envia emails para todos os funcionários da holding informando o aniversariante do dia Saída: Todo dia que possui aniversariantes gera uma saída (como o email é o mesmo para todos, considera-se que foi produzida apenas uma saída).

Robô: Cobrança de inadimplência Descrição: Envia emails para agências que estão com pagamento atrasado Saída: Cada email enviado para as agências é uma saída (como os emails são diferentes para cada agência, e cada um precisa de um processamento específico, cada email é uma saída).

Robô: Download operadora Amil Descrição: Baixa documentos de faturas Amil das empresas em uma pasta de rede Saída: Cada arquivo baixado é uma saída.

Robô: Recebimento de MD Descrição: Percorre todas as empresas do portal Prisma e lança uma movimentação no site para abater as diferenças registradas no dia. Saída: Cada movimentação lançada é uma saída.

Robô: Extrai dados portal trend Descrição: Acessa o portal da Trend e registra em um banco de dados todas as vendas que ocorreram no dia. Saída: Cada venda registrada no banco de dados é uma saída.

Vale lembrar que, considera-se como saída apenas os artefatos citados acima que são o objetivo principal do robô. Se o robô gera outros artefatos que não são necessariamente o objetivo dele, esses artefatos não são considerados saídas. Alguns exemplos seguem:

Robô: Recebimento de MD Saída: Cada movimentação lançada no portal é uma saída. Não são saídas: O robô baixa 2 arquivos para poder entender quais são as empresas que ele precisa percorrer, e também manda emails de notificação de sucesso e erro. Nenhum destes artefatos são considerados saídas, visto que eles não são seu objetivo principal.

Robô: Registro de peças e recalls Saída: Cada movimentação de peça lançada no NBS é uma saída. Não são saídas: O robô baixa vários arquivos de recall para poder identificar quais são os recalls que precisam ter as peças registradas no NBS, e depois disponibiliza esses arquivos em uma pasta de rede. Esses arquivos não são considerados saídas, visto que são não o seu objetivo principal (são apenas um bônus, algo a mais).

Cada saída possui as seguintes propriedades:

• Status: Indica se o processamento da saída foi concluído. Podendo ser:
  • 0: Não concluído
  • 1: Concluído

O status vai permanecer 0 se o arquivo começou seu processamento mas não o finalizou. Quando uma saída termina de ser processada (independente de erros), ela passa de Não concluído para Concluído.

• Sucesso: Indica se a saída foi gerada com êxito. Podendo ser:

  • 0: Erro no processamento
  • 1: Gerada com sucesso

• Nome: Nome conciso da saída em questão

• Descrição: Descrição detalhada da composição e/ou propósito da saída, podendo conter dados adicionais.

• Data de Início: Data de início do processamento da Saída

• Data de Fim: Data de fim do processamento da Saída

• Código: Identificador de 5 caracteres em caixa alta que descrevem a natureza da saída, podendo ser:

  • UPPNL: Upload de planilha para sistema ou portal
  • DWPNL: Download de planilha para pasta de rede
  • GRPNL: Geração de planilha, que pode posteriormente ser salva em uma pasta de rede
  • UPARQ: Upload de arquivo para sistema ou portal
  • DWARQ: Download de arquivo para pasta de rede
  • GRARQ: Geração de arquivo, que pode posteriormente ser salva em uma pasta de rede
  • EMAIL: Envio de email
  • ATZDB: Adição, atualização ou remoção de registro em um banco de dados
  • PRSAP: Processamento de entidade no sistema SAP
  • PRNBS: Processamento de entidade no sistema NBS
  • PRWEB: Processamento de entidade em algum site ou portal, seja ele interno ou externo
  • OUTRO: Saída que não se enquadra em nenhum outro tipo

Logs (Logs):

Os Logs são a unidade mais básica de registro da telemetria, representando passos durante a execução de um Ciclo. Basicamente, um log vai documentar exatamente qual passo o robô está. Por exemplo, para o robô de Download Operadora Amil, um conjunto de Logs de um Ciclo em específico pode ser visto abaixo:

Iniciando processo para matriz: empresas 224781A02 Realizando login da matriz: empresas 224781A02 Decodificando token da matriz: empresas 224781A02 Obtendo contratos da matriz: empresas 224781A02 Iniciando processo para contrato: 224781000 Iniciando processo para fatura: 1611629736 Realizando download de Demonstrativo Realizando download de RelFat Realizando download de TsFat

Esses logs documentam passo a passo o que está acontecendo com a execução do robô. Cada log possui as seguintes propriedades:

• Nome do arquivo: Indica o nome do arquivo que gerou aquele log.
• Linha: Indica a linha do arquivo que gerou o log.
• Descrição: Descrição do passo que está sendo registrado pelo log.
• Data do Log: Data e hora em que o log foi gerado.

Cada Log está vinculado a um Ciclo, e, além disso, opcionalmente, cada log pode estar vinculado também à uma Saída. Isso se dá quando queremos documentar os passos que estão acontecendo durante o processamento de uma Saída (dessa forma, se uma Saída for processada com erro, podemos verificar nos Logs daquela Saída o que exatamente aconteceu que causou o problema).

Composição geral:

Abaixo podemos ver um exemplo da composição geral de um ciclo:

A biblioteca telemetria-rpa

Para registrar a telemetria nos robôs, dentro dos projetos python utilizamos uma biblioteca de uso interno chamada de telemetria-rpa. Essa biblioteca visa fornecer uma interface amigável e de fácil uso e aprendizagem para os desenvolvedores preencherem corretamente os itens da telemetria em cada robô desenvolvido.

Instalação:

Como a biblioteca de telemetria é de uso interno, seu código está armazenado no nosso gitlab do grupo águia branca sob o repositório abaixo:

gitlab-gab.aguiabranca.com.br/dti-gab/gab/rpa/biblioteca/telemetria-rpa

Podemos instalar essa biblioteca de dois modos:

1° método: Instalação via requirements.txt (recomendado)

Para instalar a biblioteca, basta adicionar a seguinte linha no seu arquivo requirements.txt do projeto:

E depois instalar as bibliotecas presentes no arquivo requirements.txt

2° método: Instalação via python packages

Com o seu projeto aberto no PyCharm, no canto inferior direito, clique em Python Packages

Em seguida, clique em Add Package, e então From Version Control Cole a seguinte linha e clique em OK.

Com isso feito, podemos então finalmente ver como usar a biblioteca de telemetria para registrar cada uma de suas estruturas.

Ciclo (Cycle):

A importação do Ciclo pela biblioteca é feita da seguinte forma:

Para iniciar um ciclo (no início do seu código) basta usar a seguinte sintaxe:

Quando a execução do processo tiver sido finalizada, no fim do seu código, adicione a seguinte sintaxe para encerrar o ciclo:

OBS: Tudo relacionado a telemetria deve estar contido entre um start_cycle e um end_cycle. Tentar fazer qualquer outra coisa, como por exemplo, registrar um log, fora desse intervalo, irá gerar um erro no código.

OBS: É muito importante lembrar de encerrar o ciclo

Saída (Output):

A importação da Saída pela biblioteca é feita da seguinte forma:

Para iniciar o processamento de uma saída, registramos a mesma da seguinte forma:

Vale lembrar que o tipo de saída deverá ser do tipo OutputCodes, veja um exemplo:

Uma vez que o processamento da saída tenha sido finalizado com sucesso, basta registrar a finalização da mesma da seguinte forma:

Ou, se a saída tiver sido processada com erro, finalize-a desse modo:

Logs (Logs):

A importação dos Logs pela biblioteca é feita da seguinte forma:

Outra opção que temos é registrar o um log de erro. O log de erro funciona da mesma forma que o log normal, porém, no código ele vai disparar um erro, que devemos futuramente capturá-lo com um try ... except.

Vale lembrar que a ordem dos fatores altera o resultado. Todos os logs devem estar entre o início e fim de um Ciclo:

Outro ponto interessante é que, todo log que estiver entre o início e o fim de uma Saída, será automaticamente vinculado àquela saída.

Caso não seja desejável atribuir o Log à saída por algum motivo (ex: você está dentro do processamento de uma saída, mas o log que deseja lançar não é relacionado ao processamento daquela saída), você poderá ignorar esse comportamento utilizando um parâmetro None após a mensagem de log_info. O mesmo pode ser feito dentro de raise_error:

Por fim, caso queira ter um controle mais explícito sobre múltiplas saídas (útil quando se tem o processamento de várias saídas de maneiras concorrentes), você poderá instanciar várias saídas, vincular logs a cada uma delas (ou a nenhuma) e finalizar cada uma das saídas de maneira individual (com o método finalize_output_inst):

O método finalize_output_inst funciona de maneira idêntica ao método finalize_output, mas o mesmo é preparado para ser executado em cima de uma saída específica, enquanto finalize_output é executado em cima da última saída gerada apenas.

Exemplo de uso da biblioteca

A seguir podemos ver um código que usa a biblioteca de telemetria-rpa no robô 17:

O mesmo código pode ser encontrado em: gitlab-gab.aguiabranca.com.br/dti-gab/gab/rpa/biblioteca/telemetria-rpa/blob/release/test.py