Você está dando os toques finais em seu plug-in antes de enviá-lo para a página de plug-ins Grafana ? Neste artigo, compartilharei algumas dicas sobre como adicionar aquele polimento extra aos seus plug-ins. Este artigo pressupõe que você já tenha algum conhecimento sobre a construção de plug-ins para o Grafana.
Dica 1: ajude o usuário a começar
Quanto tempo leva para alguém que instalou seu plug-in ir de zero a ser útil? Quanto mais opções os usuários precisam entender e configurar para começar, maior é a probabilidade de desistirem do processo.
Ter um README bem escrito ajuda os usuários a obter uma compreensão mais profunda de como configurar e usar seu plugin. Mas evite torná-la uma leitura obrigatória, se puder. Idealmente, as pessoas deveriam ser capazes de entender como usar seu plugin sem ter que sair do Grafana.
Aqui estão três coisas que você pode fazer para ajudar os usuários a começar:
- Fornece padrões utilizáveis: padrão para uma configuração que funciona para o caso de uso mais comum. Idealmente, o plug-in funciona com pouca ou nenhuma configuração do usuário.
- Forneça texto de ajuda: use descrições para campos de formulário e dicas de ferramentas para campos embutidos para explicar como usar uma determinada opção. Evite simplesmente repetir o nome do rótulo. Em vez disso, em uma ou duas frases, explique quando eles gostariam de usá-lo ou se ele tem impacto em outras opções. Se um tópico precisar de mais explicações, forneça um link em seu plug-in que leve os usuários ao README, onde eles podem ler mais.
- Permitir aprendizado incremental: permite que os usuários aprendam sobre um aspecto de seu plug-in por vez. Oculte opções avançadas usando interruptores ou categorias e permita que os usuários aceitem quando estiverem prontos.
- Recrute testadores beta: se puder, encontre 1-2 pessoas que nunca usaram seu plug-in antes e peça que forneçam feedback sobre suas dificuldades. Isso lhe dará dicas importantes sobre o que você pode fazer para melhorar a experiência ao começar.
Se você estiver construindo um plug-in de painel, considere a detecção automática de campos da consulta com base no tipo de campo, em vez de depender de nomes de campo embutidos em código. Isso aumenta a chance de que os usuários tenham algo útil imediatamente ao alternar entre as visualizações.
Dica 2: documente o esquema do quadro de dados para os plug-ins do painel
O quadro de dados é a estrutura de dados que serve como interface entre as fontes de dados e os painéis. As fontes de dados produzem frames de dados e os painéis os usam para visualização. Se você estiver desenvolvendo um plugin de painel, considere documentar o esquema esperado em vez de apenas como usá-lo com uma fonte de dados específica. Fazendo isso, as pessoas que usam outras fontes de dados podem descobrir como escrever a consulta necessária.
- Quantos campos ele espera?
- Que tipos de campo ele espera?
- Ele espera uma convenção de nomenclatura para os nomes de campo?
Por exemplo, o painel gráfico integrado espera um quadro de dados que contém dois campos: um campo de tempo e um campo de número. Qualquer fonte de dados que pode gerar um quadro de dados que satisfaça esses requisitos pode ser usada com o painel de gráfico.
Documente o esquema do quadro de dados em seu README para que mais usuários possam aproveitar seu plug-in. Depois de documentar o esquema, sinta-se à vontade para fornecer consultas de exemplo para fontes de dados que são comumente usadas com seu painel.
Dica 3: adicione linting e preenchimento automático ao plugin.json
Todos os plug-ins têm um arquivo plugin.json que contém metadados sobre o plug-in e quais recursos ele suporta. Às vezes, pode ser difícil lembrar todas as propriedades e seus valores possíveis. Felizmente, o esquema JSON para o plugin.jsonarquivo está disponível no GitHub. Muitos editores e IDEs modernos oferecem suporte integrado para esquemas JSON, o que significa que podemos usá-lo para adicionar linting e preenchimento automático dentro de seu editor de código.
Por exemplo, no VS Code você pode adicionar o seguinte trecho ao seu settings.jsonpara habilitar o linting para seus plugin.jsonarquivos.
{
"json.schemas": [
{
"fileMatch": ["/plugin.json"],
"url": "https://raw.githubusercontent.com/grafana/grafana/master/docs/sources/developers/plugins/plugin.schema.json"
}
],
}JSON
Se você definir o esquema no plugin.json, o VS Code fornece até mesmo preenchimento automático para as diferentes propriedades.
{
"$schema": "https://github.com/grafana/grafana/raw/master/docs/sources/developers/plugins/plugin.schema.json",
"type": "datasource",
"name": "JSON API",
"id": "marcusolsson-json-datasource"
}JSON
Dica 4: adicione emblemas dinâmicos ao seu README
Embora dificilmente sejam a parte mais crítica do desenvolvimento de plug-ins, os emblemas transmitem informações úteis rapidamente para qualquer pessoa que navegue em seu README no GitHub. O Grafana não tem suporte oficial para emblemas, mas você ainda pode usar Shields.io junto com a API Grafana.com para criar emblemas dinâmicos que são atualizados automaticamente quando você publica uma nova versão no mercado.
Por exemplo, o link a seguir gera um emblema que exibe a versão mais recente no mercado de plug-ins. Substitua <YOUR_PLUGIN_ID>pelo ID do plugin de um plugin publicado, como o grafana-clock-panel .
https://img.shields.io/badge/dynamic/json?logo=grafana&color=F47A20&label=marketplace&prefix=v&query=%24.items%5B%3F%28%40.slug%20%3D%3D%20%22<YOUR_PLUGIN_ID>%22%29%5D.version&url=https%3A%2F%2Fgrafana.com%2Fapi%2FpluginsPara dar aos seus usuários uma noção de quão popular o plug-in é, adicione um emblema que mostre o número de vezes que o plug-in foi baixado: grafana-clock-panel .
https://img.shields.io/badge/dynamic/json?logo=grafana&color=F47A20&label=downloads&query=%24.items%5B%3F%28%40.slug%20%3D%3D%20%22<YOUR_PLUGIN_ID>%22%29%5D.downloads&url=https%3A%2F%2Fgrafana.com%2Fapi%2FpluginsCole o seguinte Markdown em seu README.md para adicionar os dois selos acima desse link à página do plug-in ao clicar neles:
[](https://grafana.com/grafana/plugins/<YOUR_PLUGIN_ID>)
[](https://grafana.com/grafana/plugins/<YOUR_PLUGIN_ID>)Dica 5: automatize seus lançamentos usando ações do GitHub
Em algum momento, você pode querer publicar seu plug- in no mercado de plug-ins . Isso significa que você precisa construir, testar, assinar e empacotar o plug-in para prepará-lo para publicação. Plug-ins empacotados incorretamente é um dos comentários de revisão mais comuns quando um plug-in é enviado para publicação.
Se o seu plug-in estiver disponível no GitHub, certifique-se de adicionar os fluxos de trabalho do GitHub para o desenvolvimento do plug-in ao seu repositório.
O fluxo de trabalho de CI ajuda a detectar erros logo no início, criando e testando seu plug-in em cada confirmação.
Quando estiver pronto para publicar seu plug-in, use o fluxo de trabalho de lançamento para assinar, empacotar e lint seu plug-in antes de enviá-lo para revisão. O fluxo de trabalho esboça uma versão do GitHub, com o plug-in assinado e empacotado como ativos da versão. O fluxo de trabalho de lançamento ainda lança o plug-in usando o validador de plug – in .
Dica 6: valide seu plug-in antes de publicá-lo
Se você publicou um plug-in recentemente, pode ter sido solicitado a usar o validador de plug – in , um aplicativo da web que gera um relatório de quaisquer problemas que impedem a publicação de seu plug-in.
O que você pode não saber é que o validador de plug-in também está disponível como uma ferramenta CLI que você pode executar em sua máquina local ou em seu fluxo de trabalho de CI.
Para instalá-lo, certifique-se de que o Go esteja instalado em sua máquina e execute:
go get -u github.com/grafana/plugin-validator/cmd/plugincheckPara executá-lo, digite plugincheckseguido por um URL ou caminho local para um plugin empacotado.
plugincheck ./marcusolsson-json-datasource-0.6.0.zipSe estiver usando os fluxos de trabalho do GitHub da dica anterior, você já está validando seu plug-in como parte do lançamento!
Agora que você está pronto para publicar seu plug-in, vá para github.com/grafana/grafana-plugin-repository e abra uma solicitação de pull para enviar seu plug-in para revisão!
Créditos: grafana.com