Pular para conteúdo

GeoProcess Consumer-Dash-Basic

Introdução

O módulo Consumer-Dash-Basic é uma estrutura básica pronta para auxiliar no processo de construção de consumidores de dashboards interativos. Ele oferece um modelo simples e adaptável, projetado para ser copiado e ajustado conforme as necessidades específicas do usuário na plataforma GeoProcess.

Quando desejamos desenvolver um dashboard devemos pensar em algumas questões como: Quantos gráficos são necessários? Quais as dependências desses gráficos? Quais as entradas desses gráficos? Quais as bases de dados utilizadas na construção desses gráficos? Quais tipos de gráficos melhor se ajustam ao meu objetivo? A partir dessas informações podemos começar a implementação do consumidor de dashboard. O exemplo mostrado a seguir é apenas uma aplicação "hello world" que mostra como criar um primeiro dashboard utilizando o mínimo de recursos possíveis.

Um Dashboard é um conjunto de gráficos e de entradas, em que cada gráfico pode ter múltiplas entradas. Os Dashboards são recursos úteis para realizar análises exploratórias nos dados. Pode-se construir dashboards com quantos gráficos e entradas se desejar. Os Dashboards dentro da plataforma GeoProcess não tem relação com os consumidores do tipo Perguntas e Resposta nem com os Alertas.

A seguir será descrita uma visão geral do módulo Consumer-Dash-Basic.

Visão Geral

A estrutura com as pastas e arquivos principais do projeto Consumer-Dash-Basic está destacada a seguir.

Estrutura de Pastas Consumidor Dash Básico

Na raiz do projeto, estão os principais componentes do CONSUMER-DASH-BASIC, incluindo:

  • main.py: Módulo principal em Python e ponto de entrada da aplicação consumidora.

  • consumer_dash/: Pasta em que fica localizado o módulo consumidor, nesse exemplo o módulo service.py na pasta basic.

  • conf_samples/ Pasta em que temos o arquivo de configuração env.conf que deverá ser copiado para a raiz do projeto.

  • graph_output/: Armazena os arquivos de resposta com os gráficos que serão utilizados na construção do dashboard.

  • logs/: Armazena os logs gerados pelo consumidor, facilitando o acompanhamento de sua execução.

  • tests/: Pasta dedicada aos testes de software.

  • dashboards/: Pasta que contém arquivos de configuração importante em formato JSON. Esses arquivos definem uma série de configurações sobre o consumidor de dashboard.

A seguir será detalhado alguns dos principais arquivos, módulos e diretórios destacados acima do consumidor dash básico.

Módulo Service

No módulo service.py na pasta consumer_dash/basic/ temos o código do consumidor de dashboard em uma aplicação de exemplo básica (hello world). Neste módulo, temos a declaração de uma classe chamada Service que herda de DashWorker (definida na biblioteca PGST-LIB). Essa classe contém o esqueleto básico de um consumidor para dashboard que deve ser adaptado para um propósito específico.

A seguir, apresentamos uma visão geral dos métodos da classe Service.

class Service(DashWorker):

    def random(self, qtd, vmin, vmax):
        ...

    @dashProcess(componentId="graph_1")
    def process1(self, input)
        ...

    @dashProcess(componentId="graph_2")
    def process2(self, input)
        ...

O método random é utilizado para gerar uma lista de valores aleatórios que serão utilizados pelo process1 e process2.

A seguir vemos a implementação do método process1. Este método é responsável pelo processamento do primeiro gráfico (acessado através do componentId que é igual a graph_1) do dashboard.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
@dashProcess(componentId="graph_1")
def process1(self, input):
    print("Processando graph_1", input)
    answer = dict({
            "data": [
                {
                    "fill": "tonexty",
                    "line": {
                        "color": "rgba(255, 153, 51, 1.0)",
                    },
                    "mode": "lines",
                    "name": "Série A",
                    "type": "scatter",
                    "x": [ 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 ],
                    "y": self.random(10,0,2),
                    "fillcolor": "rgba(255, 153, 51, 0.3)"
                },
                {
                    "fill": "tonexty",
                    "line": {
                        "color": "rgba(55, 128, 191, 1.0)",
                    },
                    "mode": "lines",
                    "name": "Série B",
                    "type": "scatter",
                    "x": [ 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 ],
                    "y": self.random(10,0,1),
                    "fillcolor": "rgba(55, 128, 191, 0.3)"
                },
                {
                    "fill": "tonexty",
                    "line": {
                        "color": "rgba(50, 171, 96, 1.0)",
                    },
                    "mode": "lines",
                    "name": "Série C",
                    "type": "scatter",
                    "x": [ 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 ],
                    "y": self.random(10,1,2),
                    "fillcolor": "rgba(50, 171, 96, 0.3)"
                }
            ],
            "layout": {
                "title": "Gráfico de Linhas",
                "legend": {
                    "font": {
                        "color": "#4D5663"
                    },
                    "bgcolor": "#F5F6F9"
                },
                "xaxis1": {
                    "title": "Eixo X",
                    "tickfont": {
                        "color": "#4D5663"
                    },
                    "gridcolor": "#E1E5ED",
                    "titlefont": {
                        "color": "#4D5663"
                    },
                    "zerolinecolor": "#E1E5ED"
                },
                "yaxis1": {
                    "title": "Eixo Y",
                    "tickfont": {
                        "color": "#4D5663"
                    },
                    "zeroline": False,
                    "gridcolor": "#E1E5ED",
                    "titlefont": {
                        "color": "#4D5663"
                    },
                    "zerolinecolor": "#E1E5ED"
                },
                "plot_bgcolor": "#F5F6F9",
                "paper_bgcolor": "#F5F6F9"
            },
            "frames": []
        })
    return answer

Informação

Repare que, por ser uma aplicação de exemplo, os dados estão injetados diretamente no código. Em uma aplicação real, esses dados são carregados de algum banco de dados.

Nessa implementação temos a modelagem do primeiro gráficos do dashboard. Esse método (process1) possui um decorador @dashProcess com o parâmetro componentId (linha 1). Este método recebe apenas um parâmetro com nome input que é uma lista contendo as informações de entrada do método (linha 2). A primeira ação do método é imprimir na tela uma informação (linha 3). Repare que esse método basicamente definiu um dicionário com as informações necessárias para plotagem de um gráfico e o retornou. Esse dicionário define um gráfico de linhas com áreas preenchidas usando a biblioteca Plotly em Python. Este exemplo mostra a configuração para plotar três séries de dados em um gráfico, cada uma com um estilo visual próprio. Vamos destrinchar cada parte para entender o que cada campo representa:

  • Estrutura Geral
  • data: Lista de dicionários, onde cada dicionário representa um conjunto de dados que será plotado como uma linha no gráfico.
  • layout: Define as configurações de layout do gráfico, incluindo estilização dos eixos, legendas, cores de fundo, entre outros.
  • frames: Utilizado para animações, mas está vazio neste exemplo, indicando que não há animações.
  • Detalhes dos Dicionários em data
  • fill: tonexty indica que a área sob a linha será preenchida até a próxima linha no gráfico. Isso é usado para criar efeitos de camadas de preenchimento entre linhas.
  • line: Configurações da linha, incluindo cor e opacidade.
  • mode: lines indica que os pontos serão conectados por linhas, sem marcadores nos pontos.
  • name: Nome da série, que aparece na legenda.
  • type: scatter é um tipo de gráfico no Plotly que pode ser usado para criar gráficos de linha, bolha, entre outros.
  • x e y: Coordenadas dos pontos no gráfico. x é uma lista de valores de 0 a 9, e y é gerada por uma função que parece criar valores aleatórios. O método self.random(10, 0, 2) parece gerar 10 valores aleatórios entre 0 e 2, por exemplo.
  • fillcolor: Cor do preenchimento sob a linha, com opacidade definida (o valor de alpha é 0.3 para transparência).
  • Detalhes do Dicionário em layout
  • title: Título do gráfico.
  • legend: Configurações da legenda, incluindo cor da fonte e cor de fundo.
  • xaxis1 e yaxis1:
    • title: Título dos eixos X e Y.
    • tickfont: Estilo da fonte usada nos marcadores dos eixos.
    • gridcolor: Cor das linhas da grade do gráfico.
    • titlefont: Estilo da fonte do título do eixo.
    • zerolinecolor: Cor da linha que marca o valor zero no gráfico.
    • zeroline: Especifica se a linha zero deve ser exibida no eixo Y.
  • plot_bgcolor e paper_bgcolor: Cores de fundo do gráfico e do papel (área ao redor do gráfico), respectivamente.

Após executar a aplicação consumidora (python3 main.py CONTRACT_TEST 001), um arquivo HTML é gerado na pasta graph_outpout para ser posteriormente exibido no dashboard do GeoProcess. A imagem a seguir mostra a resposta no frontend do sistema.

Resposta Consumer Dash Básico 1

A seguir vemos a implementação do método process2. Este método representa o processamento do segundo gráfico (acessado através do componentId que é igual a graph_2) do dashboard.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
@dashProcess(componentId="graph_2")
def process2(self, input):
    print("Processando graph_2", input)
    answer = dict({
            "data": [
                {
                    "hole": 0.1,
                    "name": "GraficoPizza",
                    "pull": 0,
                    "type": "pie",
                    "domain": {
                        "x": [ 0, 1 ],
                        "y": [ 0, 1 ]
                    },
                    "marker": {
                        "colors": [
                            "#7fc97f", "#beaed4","#fdc086", "#ffff99", "#386cb0"
                        ]
                    },
                    "textinfo": "label+value",
                    "hoverinfo": "all",
                    "labels": [
                        "Classe A", "Classe B", "Classe C", "Classe D", "Classe E",
                    ],
                    "values": self.random(6,10,30),
                    "showlegend": False
                }
            ],
            "layout": {
                "title": "Gráfico de Pizza",
                "autosize": True
            },
            "frames": []
        })
    return answer

Nessa implementação temos a modelagem do segundo gráfico do dashboard. Esse método (process2) possui um decorador @dashProcess com o parâmetro componentId (linha 1). Este método recebe apenas um parâmetro com nome input que é uma lista contendo as informações de entrada do método (linha 2). A primeira ação do método é imprimir na tela uma informação (linha 3). Repare que esse método basicamente definiu um dicionário com as informações necessárias para plotagem de um gráfico e o retornou. Esse dicionário define um gráfico de pizza (pie chart) usando a biblioteca Plotly em Python. Vamos analisar cada componente para entender melhor o que cada parte faz:

  • Estrutura Geral
  • data: Lista de dicionários, onde cada dicionário representa um conjunto de dados que será plotado como uma linha no gráfico.
  • layout: Define as configurações de layout do gráfico, incluindo estilização dos eixos, legendas, cores de fundo, entre outros.
  • frames: Utilizado para animações, mas está vazio neste exemplo, indicando que não há animações.
  • Detalhes do Dicionário em data
  • hole: Define o tamanho do buraco no meio do gráfico de pizza, criando um efeito de gráfico de rosca (doughnut chart). O valor 0.1 significa que o buraco é 10% do raio do gráfico.
  • name: Um nome identificador para este conjunto específico de dados. Utilizado para referência, especialmente quando se trabalha com múltiplos gráficos ou dados.
  • pull: Controla o afastamento de cada fatia do centro do gráfico. O valor 0 significa que as fatias não são puxadas para fora.
  • type: Define o tipo do gráfico, que neste caso é pie, indicando um gráfico de pizza.
  • domain: Especifica a área do layout onde o gráfico será desenhado, com coordenadas normalizadas entre 0 e 1 para x e y.
  • marker: Define propriedades visuais das fatias, como as cores. Aqui, uma lista de cores em hexadecimal é fornecida para as fatias do gráfico.
  • textinfo: Define quais informações serão mostradas nas fatias do gráfico. label+value mostra o rótulo e o valor numérico de cada fatia.
  • hoverinfo: Controla a informação que aparece quando o mouse passa sobre as fatias. all significa que todas as informações disponíveis serão mostradas.
  • labels: Os rótulos para cada fatia do gráfico de pizza.
  • values: Os valores numéricos para cada fatia, que determinam a proporção de cada uma.
  • showlegend: Controla a exibição da legenda. False significa que a legenda não será exibida.
  • Detalhes do Dicionário em layout
  • title: Título do gráfico.
  • autosize: Quando True, permite que o gráfico ajuste automaticamente seu tamanho para se encaixar no contêiner.

Após executar a aplicação consumidora (python3 main.py CONTRACT_TEST 002), um arquivo HTML é gerado na pasta graph_outpout para ser posteriormente exibido no dashboard do GeoProcess. A imagem a seguir mostra a resposta no frontend do sistema.

Resposta Consumer Dash Básico 2

Arquivo de Configuração env.conf

Existe um arquivo de configuração chamado env.conf na pasta conf_samples. Esse arquivo será copiado para um outro arquivo chamado env.conf na raiz do projeto no passo configurando a aplicação desse tutorial. O arquivo conf_samples/env.conf é um arquivo de exemplo que vem junto com o projeto e não deve ser alterado. O arquivo env.conf, que é uma cópia do anterior, pode ser alterado/customizado conforme a necessidade do desenvolvedor. A seguir é mostrado um exemplo desse arquivo seguido de uma breve explicação.

CONSUMER_CODE=basic
LOG_LEVEL=INFO
#LOCAL
TIME_WAIT_RESTART=10
MESSAGE_BROKER_HOST_DOCKER=host.docker.internal
MESSAGE_BROKER_PORT_DOCKER=5672
CACHE_HOST_DOCKER=host.docker.internal
CACHE_PORT_DOCKER=6379
#DOCKER
MESSAGE_BROKER_HOST=localhost
MESSAGE_BROKER_PORT=5672
MESSAGE_BROKER_USER=admin
MESSAGE_BROKER_PASSWORD=password
CACHE_HOST=localhost
CACHE_PORT=6379
#OPTIONAL
#METRICS_PORT=9091
#PORTAL_DIR=pgst-portal
#DB_NAME=postgres
#DB_USER=postgres
#DB_PASSWORD=root
#DB_HOST=localhost
#DB_PORT=5433

Os primeiros atributos são obrigatórios. O atributo CONSUMER_CODE informa o nome do código consumidor. O atributo LOG_LEVEL informa o nível de detalhes impressos no sistema de log. Os valores possíveis são: DEBUG, INFO, WARNING, ERROR e CRITICAL. Os atributos MESSAGE_BROKER_HOST e MESSAGE_BROKER_PORT informam o IP do sistema de mensageria e a sua porta. Os atributos CACHE_HOST e CACHE_PORT informam o IP do sistema de cache e a sua porta.

Os sete próximos atributos são opcionais. Os atributos DB_NAME, DB_USER, DB_PASSWORD, DB_HOST, DB_PORT são utilizados para estabelecer a conexão com o banco de dados do postgres, caso a aplicação integre com esse banco de dados.

Módulos para Testes

Na raiz do projeto existe uma pasta chamada tests que contém os testes de software implementados. Dentro dessa pasta terá um arquivo chamado test_001.py que define os testes para o primeiro dashbord. A seguir é mostrada uma parte do código do módulo test_001.py.

from loguru import logger
from consumer_dash.basic.service import Service

class Test001():

    service = Service()

    def test(self):
        logger.info("Testando o método test do módulo test_001.py")
        service = Service()
        answer = service.test("graph_1", [])
        assert type(answer) == dict

Repare que o código desse teste é bastante genérico. Ele basicamente cria um consumidor do tipo Service. Quando esse teste for executado, o método com componentId igual a graph_1 será chamado. Em nosso caso, é o método com nome process1 da classe Service que possui esse componentId. Então, ele irá pegar a saída gerada e verificar se a mesma é do tipo dicionário.

Atenção: É necessário criar um teste de software por gráfico a ser plotado nas telas do dashboard.

Diretório graph_output

Na raiz do projeto tem uma pasta chamada graph_output em que ficam armazenados os arquivos com os gráficos que serão utilizados no dashboard.

Ao mandar exibir, por exemplo, o arquivo graph_graph_1.html uma tela semelhante a mostrada a seguir deverá ser exibida.

Tela com gráfico do Dashboard Básico

Esses gráficos em HTML são criados quando executamos os comandos de testes de contrato da seção Executando a Aplicação em Modo Teste.

Arquivo dashboards.json

Na raiz do projeto tem um arquivo chamado dashboards.json que contém configurações importantes em formato JSON. Esse arquivo define uma série de parâmetros sobre o consumidor de dashboard.

A seguir temos um exemplo de arquivo dashboards.json com as configurações de como montar o dashboard da aplicação Hello World.

Arquivo: dashboards.json 
{
    "id": "dash_1",
    "version": 1.0,
    "project_title": "Projeto 1",
    "role_tag": "DASH01",
    "title": "DashBoard - Basic - Hello World",
    "description": "Este painel mostra dados de dois gráficos",
    "consumer_id":"basic",
    "components": [
        {
            "type": "div",
            "style": {
                "width": "49%",
                "display": "inline-block",
                "marginRight": "10px"
            },
            "components": [
                {
                    "type": "slider",
                    "title": "Entrada - Gráfico de Linhas",
                    "id": "data_1",
                    "properties": {
                        "begin": 5,
                        "end": 10,
                        "step": 1,
                        "value": 7
                    }
                },
                {
                    "type": "graph",
                    "id": "graph_1"
                }
            ]
        },
        {
            "type": "div",
            "style": {
                "width": "49%",
                "display": "inline-block"
            },
            "components": [
                {
                    "type": "dropdown",
                    "title": "Entrada - Gráfico de Pizza",
                    "id": "data_2",
                    "properties": {
                        "options": [
                            {
                                "label": "Opção 1",
                                "value": 1
                            },
                            {
                                "label": "Opção 2",
                                "value": 2
                            }
                        ],
                        "default": 2
                    }
                },
                {
                    "type": "graph",
                    "id": "graph_2"
                }
            ]
        }
    ],
    "callbacks": [
        {
            "outputs": [
                "graph_1"
            ],
            "inputs": [
                "data_1"
            ]
        },
        {
            "outputs": [
                "graph_2"
            ],
            "inputs": [
                "data_2"
            ]
        }
    ]
}

Nesse arquivo é importante destacar os seguintes atributos:

  • id: denota um identificador do dashboard.
  • version: denota a versão do dashboard.
  • project_title: denota o título do projeto ao qual o dashboard está vinculado.
  • role_tag: é utilizado para dar permissões de acesso ao dashboard.
  • title: é utilizado para exibir um título na interface do portal.
  • description: é utilizado para especificar uma descrição para o dashboard exibida na interface do portal.
  • components: é utilizado para especificar todos os elementos gráficos que apareceram no dashboard. Informando como será o layout de exibição os tipos de entrada e os tipos de saída.
  • callbacks: é utilizado para relacionar as entradas e saídas dos gráficos, por exemplo, o gráfico graph_1 possui o dado data_1 (slider) como entrada.

Atenção: as role_tag não podem ter o caractere underline (_) nos nomes, pois o underline é usado internamente no Gateway.

Instalação

Para a execução do consumidor de dashboard basic, é necessário preparar o ambiente com as ferramentas adequadas. Abaixo, apresentamos um passo a passo sucinto para instalação e configuração.

Pré-Requisitos

Para que o Consumer-Dash-Basic funcione corretamente, é necessário atender aos seguintes pré-requisitos:

  • Python
  • Pip
  • Git
  • Postgres
  • Postgis
  • Docker Desktop

Além disso, alguns subprojetos do GeoProcess também são necessários. Para isso, clone os seguintes repositórios:

  • pgst-portal
git clone https://github.com/ZETTA-ORG/pgst-portal.git
  • pgst-lib
git clone https://github.com/ZETTA-ORG/pgst-lib.git

Após a instalação dos pré-requisitos, você poderá preparar o Consumer-Dash-Basic.

Preparando a Aplicação

Primeiramente, clone o projeto pgst-consumer-dash-basic com o seguinte o comando:

git clone https://github.com/ZETTA-ORG/pgst-consumer-dash-basic.git

Observação

Esse projeto deve ser clonado dentro de uma pasta geoprocess, conforme a organização do projeto.

Configurando a Aplicação

Em seguida, copie o arquivo de configuração do ambiente com o comando apropriado para o seu sistema operacional:

cp conf_samples/env.conf env.conf

copy conf_samples/env.conf env.conf

Depois, abra o arquivo env.conf e atualize-o conforme as configurações do seu ambiente de trabalho.

Para isolar as dependências do Python, crie um ambiente virtual venv com o comando a seguir:

python3 -m venv venv

py -m venv venv

Ative o ambiente virtual no seu computador utilizando o comando abaixo:

source venv/bin/activate

venv\Scripts\activate

Agora, instale as dependências do projeto utilizando o comando abaixo:

pip3 install -r requirements.txt

Em seguida, instale as dependências do projeto pgst-lib dentro do projeto principal:

pip3 install -e ../pgst-lib/

Executando a Aplicação em Modo Teste

Para executar a aplicação em modo teste de contrato, utilize a linha de comando abaixo:

cd pgst-consumer-dash-basic/
source venv/bin/activate
python3 main.py CONTRACT_TEST 001

Após isso, a saída será gerada no diretório graph_output. Abra os exemplos html dessa pasta utilizando algum servidor web, como o Live Server http://127.0.0.1:5500/graph_output/graph_graph_1.html.

Uma tela semelhante a mostrada a seguir deverá ser exibida.

Tela com gráfico do Dashboard Básico

Informação

Para encerrar a execução do consumidor, basta apertar o botão x ou pressionar Ctrl + C.

Executando a Aplicação junto com Portal

Para executar a aplicação, primeiro é necessário abrir o Docker Desktop e subir o Postgis, pgAdmin e o Redis.

Em seguida, em outro terminal, execute o Consumer-Dash-Basic.

cd pgst-consumer-dash-basic/
source venv/bin/activate
cd consumer_dash/cd
python3 manage.py dash_service

Em seguida, acesse a URL http://0.0.0.0:8000/. Vá em Projeto Dashboard Sample e em Painéis vá em DashBoard - Basic. Repare agora que os gráficos estão sendo exibidos.

Tela do Portal com Dashboard Básico 2

Visualizando os Resultados

Para visualizar os resultados digite:

cd pgst-consumer-dash-basic/
source venv/bin/activate
python3 main.py DASH_DEBUG

Acesse a URL http://0.0.0.0:8050/.

Github do Projeto

A seguir temos o link para o github do projeto.

CONSUMER-DASH-BASIC