Plugins personalizados

Este post é o primeiro de uma série de tutoriais sobre o desenvolvimento de plugins na Unit Platform. Os próximos posts ensinam como cadastrar um plugin, coletar dados do protocolo SNMP e usar um plugin personalizado com o Netwall Direct Agent.

O que é um plugin?

Plugins são scripts ou programas compilados que realizam a coleta de uma informação específica sobre algum dispositivo, serviço, aplicação ou protocolo.

A customização de plugin é necessária quando os plugins pré-cadastrados na ferramenta não atendem a alguma necessidade específica de monitoramento. Nesse caso, a personalização do plugin é imprescindível.

Onde os plugins são executados?

Os plugins podem ser executados localmente na Unit Platform ou em servidores remotos Windows e Linux que tenham o agente Netwall Direct Agent instalado.

Os plugins são disparados pelo serviço de monitoramento do produto Multisite Monitoring, independente se está sendo executado localmente ou nos servidores remotos.

Com quais tecnologias os plugins podem ser desenvolvidos?

Se o plugin for desenvolvido com objetivo de ser executado localmente na Unit Platform, recomendamos as seguintes tecnologias:

Bash

• Versão 4.1.2
• Caminho do executável: /bin/bash

Perl

• Versão 5.10.1
• Caminho do executável: /usr/bin/perl

Python

• Versão 2.7.11
• Caminho do executável: /opt/3rdparty/python27/bin/python

PHP

• Versão 5.6.11
• Caminho do executável: /usr/bin/php

Awk

• Versão 3.1.7
• Caminho do executável: /bin/awk

Executável

• Distribuição CentOS 6.5 x64

Se o plugin for desenvolvido para executar em servidores remotos, qualquer tecnologia pode ser utilizada, contanto que o servidor suporte esta tecnologia. Seguem as tecnologias mais comuns:

Linux

• Bash
• Perl
• Python
• C/C++
• Java

Windows

• Powershell
• VBScript
• Java
• C/C++
• Batch file (.bat)

Como são os padrões de entrada e saída dos plugins?

Para que os plugins sejam suportados pelo Multisite Monitoring, existem alguns padrões que devem ser seguidos obrigatoriamente.

Entrada de Argumentos

A primeira exigência é os padrões de entrada. Todos os argumentos que precisam ser transmitidos para o plugin devem ser declarados em linha de comando. Seguem abaixo alguns exemplos:

plugin_1 [argument1] [argument2] [argument3]
plugin_2 -n [argument1] -i [argument2] -c [argument3]
plugin_3 --name [argument1] --id [argument2] --compare [argument3]

Nos exemplos acima, foram exibidos três formatos diferentes e válidos.

O primeiro exemplo, plugin_1, os argumentos são declarados em forma sequencial sem identificação e obrigatória.

No segundo e no terceiro exemplos, os argumentos não são sequências e todos podem ser opcionais, o que difere os últimos dois exemplos são as declarações resumidas e extensas. Esse padrão é aconselhado em scripts que executam em sistemas Linux (no exemplo -n e --name são idênticos).

Outra prática muito utilizada é adicionar duas opções no plugin, uma para versão e outra para debug, conforme exibido abaixo:

• Versão: -vou --version
• Debug: -d ou --debug

Saída do Plugin

A segunda etapa que deve ser seguida são as regras de saída. A Unit Platform, para possibilitar o maior nível de customização das regras de monitoramento exige um formato específico de saída de dados. O plugin deverá imprimir apenas os resultados em uma única linha e devem seguir o formato abaixo:

[strings auxiliares]|[resultados]

Onde as strings auxiliares serão utilizadas para compor as mensagens exibidas pelos serviços no monitoramento e os resultados serão os dados que o Multisite Monitoring usará para definir o estado dos serviços e exibir os gráficos de performance. Observa-se que o que separa as strings dos resultados é o caracter “|”. Caso o plugin não retorne nenhuma string auxiliar, ou seja, apenas os resultados, esse caracter é opcional e toda a saída do plugin será considerada como um “resultado”.

Ambos os lados do “|” suportam que sejam retornados mais que um valor por vez. Se houver mais de um valor, os mesmos devem ser separados por “;”.

Seguem abaixo alguns exemplos de saídas de plugins, que não fazem uso das strings auxiliares:

35.91
0.27;0.45;0.29
Welcome
Google Search;I’m felling lucky

Observação: os resultados, caso exista mais que um, devem obrigatoriamente estar na mesma unidade de medida e ser do mesmo tipo.

Seguem abaixo os tipos de resultados que o plugin pode imprimir:

• Texto: Qualquer conjunto de palavras. Os caracteres “|”, “;” e “!” não podem ser utilizados.
• Número: Neste caso não deve ter os indicadores de unidades de medida, apenas o valor numérico. Se o valor for fracionado, o separador decimal deve ser o “.” (ponto).

Plugins que retornam valores numéricos exibirão gráficos de performance na interface da Unit Platform. Plugins com saída textual não possuirão gráficos.

Segue abaixo alguns exemplos de saídas que usam as strings auxiliares:

C:/|142080884
In;Out|12;18
Firefox.exe|17

A finalização do plugin deve ser com o exitcode 0, caso seja diferente, o resultado não será processado.

Como fazer meu primeiro plugin?

Nesta seção explicaremos como criar o primeiro plugin que será executado dentro da Unit Platform. Este exemplo de plugin tem como objetivo coletar a temperatura de uma cidade e exibir algumas informações adicionais.

Para a execução desse plugin, é necessário que a Unit Platform tenha acesso à internet através da porta HTTP para coletar as informações via WebService.

Na sua estação de trabalho crie um arquivo com extensão PHP, a linguagem que usaremos no primeiro exemplo de plugin. Chamaremos este arquivo de my_first_plugin.php. Copie o código abaixo para o arquivo e salve-o.

#!/usr/bin/php
<?php

$cid = $argv[1];
$dados = json_decode(file_get_contents('http://api.hgbrasil.com/weather/?cid='.$cid.'&format=json'), true);

echo $dados['results']['city_name'].";".$dados['results']['description'].";".$dados['results']['humidity'].";".$dados['results']['wind_speedy']."|".$dados['results']['temp'];
?>

A saída desse script, se executada na linha de comando, deverá exibir algo bem parecido com o exemplo abaixo:

Porto Alegre;Ensolarado;77;11.27 km/h|18

Conforme explicado anteriormente, as strings auxiliares são separados por “;” e o resultado do comando está após o “|”. Os textos adicionais são respectivamente “Nome da Cidade”, “Descrição da previsão do tempo”, “Humidade” e “Velocidade do vento”, já o resultado é apenas a “Temperatura”.

Outro detalhe que deve ser observado é o cabeçalho do script #!/usr/bin/php. No Linux é necessário adicionar o caminho do executável na primeira linha do script, pois a extensão “.php” no Linux é apenas por questões de organização, diferente do Windows que o executável está relacionado à extensão do arquivo.

Lembrando que a execução na linha de comando não é necessária, é apenas informativa neste documento. Caso se queira executar esse plugin específico fora da Unit Platform, é necessário ter um ambiente com o PHP instalado.

Terminados esses passos, avançaremos para a segunda parte deste tutorial: o carregamento e uso do plugin na Unit Platform.