Este projeto tem o objetivo de facilitar a utilização de conjuntos de dados abertos, fazendo uso da Elastic Stack (Elasticsearch + Logstash + Kibana), que é uma solução baseada em software livre que permite facilmente consumir fontes de dados, manipular/transformar/enriquecer esses dados, indexá-los e, por fim, visualizá-los em dashboards.
Neste projeto está sendo utilizada a versão 6.5.0 da Elastic Stack.
- Roteiro utilizando a ferramenta dados-abertos-elk.sh
- Estrutura de diretórios
- Conjuntos de dados
- Dicionários
- Elastic Stack (ELK)
- Fontes de dados abertos
- Utilidades
- Links úteis
- Baixar os conjuntos de dados abertos desejados nas Fontes de Dados Abertos
- Instalar, executar e testar o Elasticsearch, Kibana e Logstash
$ curl -O https://artifacts.elastic.co/downloads/elasticsearch/elasticsearch-6.5.0.tar.gz
$ tar xfz elasticsearch-6.5.0.tar.gz
$ elasticsearch-6.5.0/bin/elasticsearch
$ curl http://localhost:9200
$ curl -O https://artifacts.elastic.co/downloads/kibana/kibana-6.5.0-linux-x86_64.tar.gz
$ tar xfz kibana-6.5.0.tar.gz
$ kibana-6.5.0/bin/kibana
$ curl http://localhost:5601/
$ curl -O https://artifacts.elastic.co/downloads/logstash/logstash-6.5.0.tar.gz
$ tar xfz logstash-6.5.0.tar.gz
$ logstash-6.5.0/bin/logstash --version
- Clonar este projeto
$ git clone https://github.com/ffknob/dados-abertos-elk.git
- Criar os índices no Elasticsearch a partir dos arquivos que se encontram no diretório elasticsearch/mappings/
dados-abertos-elk/ $ ./dados-abertos-elk.sh -e
- Criar os Dashboards no Kibana a partir dos arquivos que se encontram no diretório kibana/dashboards/
dados-abertos-elk/ $ ./dados-abertos-elk.sh -k
Esses arquivos foram gerados a partir da API de exportação de Dshboards do Kibana e já incluem o Index Pattern, as Visualizations e o Dashboard propriamente dito.
- Opcional: Executar Pipelines para os dicionários no Logstash
dados-abertos-elk/ $ ./dados-abertos-elk.sh -l logstash/pipelines/tcers/dict/municipios.conf
Já foram executados e se encontram na pasta dict/.
Esses Pipelines geram arquivos YAML que serão utilizados pelos Pipelines principais.
- Executar Pipelines no Logstash
dados-abertos-elk/ $ ./dados-abertos-elk.sh -l logstash/pipelines/poa/acidentes-transito.conf
O Logstash ficará em execução aguardando mais eventos nos inputs configurados. Ele deverá ser encerrado manualmente (CTRL+C) assim que o respectivo índice no Elasticsearch não estiver recebendo mais eventos, ou que o indicador do filtro de saída dots {} não estiver mais imprimindo pontos na tela.
- Acessar o Kibana e ir em Dashboards
Consultar a estrutura completa de arquivos e diretórios
- data/: diretório para armazenar os arquivos CSV dos conjuntos de dados, organizado por fonte de origem, tipo e, quando necesário, formato
- dict/: diretório com os dicionários que serão utilziados pelos Pipelines principais
- elasticsearch/mappings/: arquivos de Mapping dos índices que serão criados no Elasticsearch
- kibana/dashboards/: arquivos de configuração dos Dashboards do Kibana, organizado por fonte de origem e tipo
- logstash/pipelines/: arquivos de configuração dos Pipelines do Logstash, organizado por fonte de origem e tipo
O primeiro passo é realizar o download dos conjuntos de dados. Eles poderão ser obtidos nos portais de dados abertos dos órgãos. Os arquivos deverão ser salvos nas respectivas pastas, conforme indicado na tabela Fontes de dados abertos.
Os dicionários são utilizados para enriquecer os conjuntos de dados. Cada dicionário é indexado por uma chave simples, que será utilizada por pipelines do Logstash para encontrar o registro que enriquecerá o evento do conjunto de dados.
Os dicionários são arquivos Yaml gerados também com o uso do Logstash. Para gerar os dicionários basta executar o Logstash informando o arquivo de configuração do pipeline de cada dicionário.
Os dicionários que serão utilizados para enriquecer os conjuntos de dados poderão ser gerados, obedecendo a ordem, de acordo com a tabela Dicionários. No entanto, uma versão gerada desses dicionários já fazem parte do projeto e podem ser encontradas na pasta dict/.
O Elasticsearch é o componente central da stack ELK e é responsável por indexar os dados e fornecer uma API REST para a realização de consultas.
- Download Elasticsearch
${ELASTICSEARCH_BASE}/bin/elasticsearch
O Logstash é a solução de ETL da Elastic, através da qual é possível consumir dados de diversos tipos de fontes diferentes, assim como transformá-los, enriquecê-los e então enviá-los para, também, diversas tipos de destinos diderentes.
Neste projetos os dados serão consumidos de arquivos locais do tipo CSV e enviados para o Elasticsearch.
- Download Logstash
${LOGSTASH_BASE_DIR}/bin/logstash -f arquivo_configuracao_pipeline.conf
Como o Logstash mantém o canal de entrada aberto esperando receber mais eventos, ele não encerra a execução mesmo após consumir todo o arquivo (ele espera que mais eventos sejam adicionados ao arquivo). Portanto, ele precisará ser interrompido manualmente. Para isso, aguarde até que ele não esteja mais gerando a saída dots (ele irá gerar um "." para cada evento consumido) e utilize CTRL+C para interrompê-lo.
O Kibana é o console de acesso e visualização dos dados indexados no Elasticsearch. Através dele é possível realizar consultas nos índices, criars visualizações dos dados e agrupar essas visualizações em dashboards.
- Download Kibana
${KIBANA_BASE}/bin/kibana
Os Index Patterns devem ser configurados no Kibana para definir quais índices comporão uma fonte de dados para a construção de visualizações e dashboards. Para configurar um Index Pattern siga os seguintes passos:
- Acesse o menu Management do Kibana
- Vá em Indexes Patterns
- Create Index Pattern
- Informe o padrão de índices do conjunto de dados desejado
- Informe o campo @timestamp para ser utilizado como marcador da data do evento
As Visualizations possibilitam a visualização dos dados indexados através de componentes visuais como histogramas, gráficos de diversos tipos, mapas, heatmaps, nuvens de tags, gauges e outros.
Dashboards reunem Visualizations possibilitando a criação de painéis de informação.
| Fonte | Conjunto de dados | Path | Download |
|---|---|---|---|
| POA | Acidentes de Trânsito | data/poa/acidentes-transito/ | http://http://www.datapoa.com.br/dataset/acidentes-de-transito/ |
| TCE-RS | Dados auxiliares: Funções | data/tcers/auxiliares/ | http://dados.tce.rs.gov.br/dados/auxiliar/funcoes.csv |
| TCE-RS | Dados auxiliares: Sub-funções | data/tcers/auxiliares/ | http://dados.tce.rs.gov.br/dados/auxiliar/subfuncoes.csv |
| TCE-RS | Dados auxiliares: Tipos de unidades | data/tcers/auxiliares/ | http://dados.tce.rs.gov.br/dados/auxiliar/tipos_unidades.csv |
| TCE-RS | Dados auxiliares: Elementos de despesa | data/tcers/auxiliares/ | http://dados.tce.rs.gov.br/dados/auxiliar/elementos_de_despesa.csv |
| TCE-RS | Dados auxiliares: Modalidades de aplicação | data/tcers/auxiliares/ | http://dados.tce.rs.gov.br/dados/auxiliar/modalidade_de_aplicacao.csv |
| TCE-RS | Dados auxiliares: Órgãos auditados | data/tcers/auxiliares/ | http://dados.tce.rs.gov.br/dados/auxiliar/orgaos_auditados_rs.csv |
| TCE-RS | Dados auxiliares: Municípios | data/tcers/auxiliares/ | http://dados.tce.rs.gov.br/dados/auxiliar/municipios.csv |
| TCE-RS | Balancete de despesa | data/tcers/balancete-despesa/ | http://dados.tce.rs.gov.br/dados/municipal/balancete-despesa/ |
| TCE-RS | Balancete de receita | data/tcers/balancete-receita/ | http://dados.tce.rs.gov.br/dados/municipal/balancete-receita/ |
| TCE-RS | Solicitações de informação | data/tcers/solicitacoes-informacao/ | http://dados.tce.rs.gov.br/dados/lai/solicitacoes-de-informacao/ |
| TCE-RS | Diárias pagas | data/tcers/diarias-pagas/ | http://dados.tce.rs.gov.br/dados/institucional/diarias-pagas/ |
| TCE-RS | Decisões | data/tcers/decisoes/ | http://dados.tce.rs.gov.br/dados/decisoes/ |
Ferramenta utilitária criada para facilitar a utilização deste projeto. Através dela é possível:
- [TODO] Realizar o download dos conjuntos de dados abertos
- Criar os índices no Elasticsearch, já com o mapping necessário
- Criar os dashboards no Kibana
- Executar pipelines do Logstash
dados-abertos-elk/ $ ./dados-abertos-elk.sh -e [indice] | -l <pipeline> | -k [dashboard]
-e cria os índices no Elasticsearch com os devidos mappings
-l executa pipeline do Logstash
-k instala dashboards do Kibana
- Verificar índices existentes
$ curl -XGET http://localhost:9200/_cat/indices?pretty
- Verificar mapping de um índices
$ curl -XGET http://localhost:9200/poa-acidentes-transito/_mappings?pretty
- Criar um índice
$ curl -XPUT -H "Content-Type: application/json" http://localhost:9200/poa-acidentes-transito -d@elasticsearch/mappings/poa/acidentes-transito.mapping
- Excluir um índice
$ curl -XDELETE http://localhost:9200/poa-acidentes-transito/
- Pesquisar em um índice
$ curl -XGET http://localhost:9200/poa-acidentes-transito/_search?pretty
$ curl -XGET http://localhost:9200/poa-acidentes-transito/_search\?q\=CAVALHADA\&pretty
Para uma pesquisa específica deverá ser enviado no body uma query no padrão Query DSL do Elasticsearch (consultar documentação).
- Criar Index Pattern no Kibana:
$ curl -XPOST -H "Content-Type: application/json" -H "kbn-xsrf: true" http://localhost:5601/api/saved_objects/index-pattern/poa-acidentes-transito -d'{"attributes":{"title": "poa-acidentes-transito","timeFieldName": "@timestamp"}}'
- Exportar Dashboard do Kibana (Index Pattern + Visualizations + Dashboard):
$ curl -k -XGET http://localhost:5601/api/kibana/dashboards/export\?dashboard\=ce92e510-ea65-11e8-8fb3-31b5d3f2749f > acidentes-transito.dashboard
O identificador do Dashboard pode ser obtido na query_string da URL ao entrar no Dashboard através do console do Kibana.
- Importar Dashboard no Kibana:
$ curl -XPOST -H "Content-Type: application/json" -H "kbn-xsrf: true" http://localhost:5601/api/kibana/dashboards/import -d @acidentes-transito.dashboard
.
├── data/
│ ├── auxiliares/
│ │ └── municipios.csv
│ ├── poa/
│ │ └── acidentes-transito/
│ │ ├── f1/
│ │ │ ├── acidentes-2010.csv
│ │ │ ├── acidentes-2011.csv
│ │ │ └── acidentes-2012.csv
│ │ ├── f2/
│ │ │ └── acidentes-2013.csv
│ │ ├── f3/
│ │ │ └── acidentes-2014.csv
│ │ ├── f4/
│ │ │ └── acidentes-2015.csv
│ │ └── f5/
│ │ └── acidentes-2016.csv
│ └── tcers/
│ ├── auxiliares/
│ │ ├── elementos_de_despesa.csv
│ │ ├── funcoes.csv
│ │ ├── grupos_natureza.csv
│ │ ├── limites_gastos.csv
│ │ ├── municipios.csv
│ │ ├── orgaos_auditados_rs.csv
│ │ ├── subfuncoes.csv
│ │ └── tipos_unidades.csv
│ ├── balancete-despesa/
│ │ └── 2017.csv
│ ├── balancete-receita/
│ │ └── 2017.csv
│ ├── decisoes/
│ │ ├── 2011.csv
│ │ ├── 2012.csv
│ │ ├── 2013.csv
│ │ ├── 2014.csv
│ │ ├── 2015.csv
│ │ ├── 2016.csv
│ │ └── 2017.csv
│ ├── diarias-pagas/
│ │ ├── 2008.csv
│ │ ├── 2009.csv
│ │ ├── 2010.csv
│ │ ├── 2011.csv
│ │ ├── 2012.csv
│ │ ├── 2013.csv
│ │ ├── 2014.csv
│ │ ├── 2015.csv
│ │ ├── 2016.csv
│ │ └── 2017.csv
│ └── lai/
│ ├── 2012.csv
│ ├── 2013.csv
│ ├── 2014.csv
│ ├── 2015.csv
│ ├── 2016.csv
│ └── 2017.csv
├── dict/
│ ├── auxiliares/
│ │ └── municipios.yml
│ └── tcers/
│ ├── funcoes.yml
│ ├── municipios.yml
│ ├── orgaos-auditados.yml
│ └── subfuncoes.yml
├── elasticsearch/
│ └── mappings/
│ ├── poa/
│ │ └── acidentes-transito.mapping
│ └── tcers/
│ ├── balancete-despesa.mapping
│ ├── balancete-receita.mapping
│ ├── decisoes.mapping
│ ├── diarias-pagas.mapping
│ └── lai.mapping
├── kibana/
│ └── dashboards/
│ ├── poa/
│ │ └── acidentes-transito.dashboard
│ └── tcers/
│ ├── contabil.dashboard
│ ├── diarias-pagas.dashboard
│ └── lai.dashboard
├── logstash/
│ └── pipelines/
│ ├── auxiliares/
│ │ └── dict/
│ │ └── municipios.conf
│ ├── poa/
│ │ └── acidentes-transito.conf
│ └── tcers/
│ ├── dict/
│ │ ├── funcoes.conf
│ │ ├── municipios.conf
│ │ ├── orgaos-auditados.conf
│ │ └── subfuncoes.conf
│ ├── balancete-despesa.conf
│ ├── balancete-receita.conf
│ ├── decisoes.conf
│ ├── diarias-pagas.conf
│ └── lai.conf
├── dados-abertos-elk.sh*
└── README.md