Integre o Vonage ao Grafana para receber notificações por SMS

Introdução

O Grafana é uma plataforma de observabilidade aberta e multiplataforma que os desenvolvedores podem usar para acompanhar métricas de aplicativos ou sistemas na nuvem. Ele gera análises e visualizações a partir dessas métricas por meio de tabelas, gráficos e alertas. Este artigo mostrará como integrar o Vonage a uma instalação do Grafana para receber notificações por SMS usando a Messages API.

A linguagem de ensino será Python. O conhecimento compartilhado por meio do artigo proposto seria útil para equipes de DevOps, SREs e administradores de sistema que utilizam o Grafana para receber notificações sobre atividades e ocorrências incomuns em seus sistemas.

Índice

• Introdução

• Etapa 1: Configurar o Grafana Stack

• Etapa 2: Criar um aplicativo em Python para a implementação da lógica

• Etapa 3: Configurar o Account da Vonage para notificações por SMS da Messages API

• Resumo e recursos adicionais

Etapa 1: Configurar o Grafana Stack

O Grafana permite que você configure sua própria instância do Grafana em seu computador local ou servidor. Como alternativa, você pode usar o Grafana na nuvem ao se cadastrar uma nova conta. Assim, você não precisará instalar nem manter sua instância do Grafana, já que ela é baseada na nuvem e gerenciada.

Criar um painel

Neste tutorial, você criará um painel simples usando a fonte de dados integrada do Grafana. Para um usuário novo do Grafana, o programa exibe um fluxo de trabalho inicial para orientá-lo na criação de um novo painel. Você pode seguir as etapas indicadas nas instruções ou as etapas destacadas nesta seção do artigo. Você pode pular esta seção se já estiver familiarizado com o Grafana.

1. Clique em “Painéis” no menu à esquerda para acessar a página “Painéis”

2. Clique no Novo para abrir um menu suspenso de opções e selecione Novo painel

3. Na página do novo painel, clique em + Adicionar visualização para abrir uma janela na qual você poderá escolher uma fonte de dados.

4. Selecione a janela modal “Selecionar fonte de dados” e escolha a opção -- Grafana -- à direita.

select-data-source.png

Ao selecionar o -- Grafana -- , que é a fonte de dados padrão integrada do Grafana, duas coisas acontecem:

- Grafana configures your query 
- Grafana generates the Random Walk dashboard.

1. Agora você pode clicar no ícone “Atualizar painel” na imagem a seguir para consultar a fonte de dados.

create-contact-point.png

1. Em seguida, você pode clicar em “Salvar”, no canto superior direito. Será solicitado que você insira um nome para o painel antes que ele seja salvo.

Agora você já deve ter um painel básico configurado na sua conta do Grafana. Você pode explorar ainda mais o Grafana adicionando fontes de dados para criar painéis para seus outros projetos.

Etapa 2: Criar um aplicativo em Python para a implementação da lógica

Você precisa instalar o Flask para executar o script em Python que você usará neste tutorial. Você pode executar o seguinte comando no terminal para instalar o Flask.

Escreva a primeira função em Python

Agora, você vai configurar um webhook do Flask para receber alertas do Grafana.

Crie um arquivo chamado `notify.py` e insira o seguinte código em Python.

from flask import Flask, request

app = Flask(__name__)

@app.route("/grafana-webhook", methods=["POST"])

def grafana_webhook():

    if request.method == "POST":

        data = request.json

        alert_description = data["alerts"][0]["annotations"]["desc"]

        print(alert_description)

        return "Webhook received!"

if __name__ == "__main__":

    app.run(host="", port=3000, debug=True)

No código acima, você:

• criou uma POST rota, /grafana-webhook

• A rota decora a função `grafana_webhook`, um endpoint POST para receber solicitações POST.

• extraiu o alert_description da carga útil da solicitação

• Um dos atributos extraídos, alert_summary, é exibido no console durante a execução por meio da função print().

• Você designou a porta 3000 para a execução do aplicativo. Isso permitirá mapear a porta do aplicativo para a porta em que o Ngrok será executado. Dessa forma, o aplicativo será disponibilizado por meio do servidor Ngrok.

Para executar o aplicativo localmente, use o seguinte comando do bash no seu terminal:

Você deverá obter uma saída no terminal semelhante à seguinte, indicando que o servidor de desenvolvimento está ativo:

Configurar o servidor Ngrok

Em seguida, você pode instalar o Ngrok, um servidor online leve para testar a aplicação em Python. Ele permitirá que você disponibilize seu script em Python na internet pública. Siga as instruções de instalação no site oficial site para instalá-lo.

Você pode executar o Ngrok com o seguinte comando no terminal, e ele iniciará um servidor leve para você:

Ao executar o comando acima, um servidor leve será iniciado para você, e você verá sua URL pública no seu terminal, como a seguir:

Isso significa que seu endpoint de webhook, baseado no seu script em Python, é o seguinte:

Esta será a sua URL exclusiva para que o Grafana envie notificações via webhook para sua aplicação em Python.

Conectar o Grafana ao aplicativo em Python

Para conectar o Grafana ao seu aplicativo em Python, você deverá especificar a URL do webhook por meio da qual o Grafana poderá enviar seus alertas ao seu aplicativo. Como você já possui uma URL de webhook para essa finalidade, adicione-a aos pontos de contato de alertas no seu painel do Grafana. Siga as etapas a seguir para configurar os alertas do Grafana com o webhook do seu aplicativo.

1. No menu principal do Grafana, acesse Alertas e IRM > Alertas, conforme mostrado na captura de tela a seguir.

alerting-menu.png

1. Clique Pontos de contato na página “Alertas” para acessar a página Pontos de contato , conforme mostrado na captura de tela a seguir. Clique em botão “+ Adicionar ponto de contato” . Isso o levará à página página “Criar ponto de contato” , conforme mostrado na captura de tela a seguir.

contact-points.png

1. Digite o valor desejado nomee selecione Webhook na lista de . Insira sua URL de webhook dedicada no campo campo URL , conforme mostrado na captura de tela a seguir.

contact-point-setup.png

1. Você pode clicar no botão “Testar” para seguir as instruções e testar o ponto de contato. Tente usar a opção de notificação personalizada durante o teste, em vez da opção predefinida. Isso permitirá que o código do seu endpoint analise corretamente o resumo e a descrição da notificação para que você possa visualizá-los no seu terminal. O teste envia uma notificação fictícia para a URL do seu webhook. Se a notificação for enviada com sucesso, você receberá um alerta de sucesso: “Alerta de teste enviado”, no canto superior direito da página, conforme mostrado na imagem a seguir.

test-alert-sent.png

1. Clique no botão “Salvar ponto de contato” para salvar o ponto de contato.

Etapa 3: Configurar o Account da Vonage para notificações por SMS da Messages API

Definir URLs das aplicações da Vonage

Você pode acrescentar o status e os endpoints de entrada à URL gerada pelo Ngrok. Eles terão a seguinte aparência:

URL de status: https://d5fs-104-25-63-145.eu.ngrok.io/webhooks/message-status

URL de origem: https://d5fs-104-25-63-145.eu.ngrok.io/webhooks/inbound-message

Anote os URLs acima, pois você precisará deles ao configurar seu Account da Vonage para a Messages API na seção a seguir.

Configurar uma aplicação da Vonage

Você precisa se cadastrar um account na Vonage, caso ainda não tenha um.

Você precisa de um Account da Vonage configurado com a Messages API para enviar mensagens SMS aos seus usuários por meio da Vonage. Nesse caso, seu usuário pode ser um colega de equipe a quem você deseja notificar sobre as atualizações do Grafana.

Siga as etapas a seguir para configurar seu Account da Vonage para a Messages API:

1. Acesse o menu “Configurações da API” no menu principal do seu painel da Vonage para acessar as página “Configurações da API” . As Configurações da API

2. Na seção de configurações de SMS, selecione Messages API. Deixe as demais configurações com os valores padrão.

3. Acesse as página de Applications e clique em botão “+ Criar aplicativo” para criar um aplicativo.

4. Digite um nome no campo . Clique no botão botão “Gerar chave pública e privada” . Um arquivo de chave privada private.key será baixado para o seu computador.

5. Selecionar Mensagens na seção .

6. Insira a URL de entrada e a URL de status que você anotou ao configurar o Ngrok.

7. Clique no botão “Gerar novo aplicativo” para concluir a criação. Em seguida, você será redirecionado para a página de visão geral do aplicativo, onde também poderá vincular seu número da Vonage ao aplicativo.

Observação: Confira Gerenciar Numbers com a CLI da Vonage para um guia rápido sobre como comprar um número da Vonage.

É preciso observar o ID DO APLICATIVO na página de visão geral do aplicativo, pois você precisará dela na próxima sessão. Você também deve anotar o caminho local onde o private.key arquivo está localizado. Eles devem ter a seguinte aparência:

ID do pedido: 53a2ed68-f2d8-498c-9b17-032669e3bf90

Caminho da chave privada: /Users/Downloads/private.key

Enviar SMS para o usuário

Nesta subseção, você enviará a notificação do webhook do Grafana ao seu usuário por SMS. É possível usar o SDK do Vonage para Python para esse recurso em um aplicativo Python. Use o seguinte comando bash para instalar o SDK do Vonage para Python em sua máquina local.

Em seguida, adicione o código a seguir ao seu script em Python:

...

import vonage

def grafana_webhook():

    if request.method == "POST":

        ...

        client = vonage.Client(

            application_id=YOUR_VONAGE_APPLICATION_ID,

            private_key=YOUR_APPLICATION_PRIVATE_KEY_PATH,

        )

        notification = client.messages.send_message(

            {

                "channel": "sms",

                "message_type": "text",

                "from": YOUR_VONAGE_NUMBER,

                "to": DESTINATION_PHONE_NUMBER,

                "text": alert_description,

            }

        )

        return "Webhook successfully delivered as a notification message."

No código acima:

• Você inicializou o cliente do SDK do Python com a linha client = vonage.Client(). Substitua o YOUR_VONAGE_APPLICATION_ID e YOUR_APPLICATION_PRIVATE_KEY_PATH pelo ID do aplicativo e caminho da chave privada do aplicativo Vonage que você criou anteriormente.

• Em seguida, você usou a send_message() função na linha notification = client.messages.send_message() para enviar uma mensagem com o cliente inicializado, onde:

  • "canal": é o modo de mensagem, SMS.

  • "message_type": formato de texto da mensagem a ser enviada.

  • "de": o remetente da mensagem. Você pode usar seu número da Vonage aqui. Substitua YOUR_VONAGE_NUMBER pelo número que você adquiriu.

  • "para": o destinatário que receberá o SMS, um número de telefone. Substitua DESTINATION_PHONE_NUMBER pelo número do destinatário.

  • "text": o conteúdo da mensagem a ser enviada, que é a string de descrição do alerta do Grafana.

• Você modificou a instrução `return` para refletir a ação que ocorre quando o código é executado.

O código completo é o seguinte:

from flask import Flask, request

import vonage

app = Flask(__name__)

@app.route("/grafana-webhook", methods=["POST"])

def grafana_webhook():

    if request.method == "POST":

        data = request.json

        alert_description = data["alerts"][0]["annotations"]["desc"]

        print(alert_description)

        client = vonage.Client(

            application_id=YOUR_VONAGE_APPLICATION_ID,

            private_key=YOUR_APPLICATION_PRIVATE_KEY_PATH,

        )

        notification = client.messages.send_message(

            {

                "channel": "sms",

                "message_type": "text",

                "from": YOUR_VONAGE_NUMBER,

                "to": DESTINATION_PHONE_NUMBER,

                "text": alert_description,

            }

        )

        return "Webhook successfully delivered as a notification message."

if __name__ == "__main__":

    app.run(host="", port=3000, debug=True)

Teste o aplicativo

Para testar o código e garantir que a configuração funcione, acesse Pontos de contato no seu painel do Grafana e selecione o botão “Editar ponto de contato” . Isso é mostrado na imagem a seguir.

edit-contact-button.png

Você pode enviar uma notificação de webhook de teste no módulo “Teste de ponto de contato” , conforme mostrado na imagem a seguir.

test-contact-point.png

1. Selecione o guia “Personalizado” para enviar uma mensagem personalizada de teste

2. Forneça os textos de resumo e descrição de sua preferência

3. Role a página para baixo para clicar na botão “Enviar notificação de teste” "Enviar notificação de teste"

4. O destinatário deve receber uma mensagem de teste semelhante à da captura de tela a seguir:

alert-from-grafana.png

Resumo

Este artigo apresentou um guia sobre como usar o sistema de notificações por webhook do Grafana para receber e enviar alertas aos seus usuários por meio da Messages API da Vonage. Abordamos a configuração dos painéis do Grafana, a criação de webhooks em Python com o Flask e a configuração de um aplicativo da Vonage compatível com a Messages API.

Se você tiver dúvidas ou sugestões, junte-se a nós no Slack dos desenvolvedores da Vonage ou envie-nos um tweet no X, antes conhecido como Twitter, e entraremos em contato com você. Mais uma vez, obrigado pela leitura, e nos vemos no próximo artigo!

Outros recursos

• Confira a documentação do Grafana para saber mais Alertas de alertas

• Veja mais maneiras de usar a Messages API na documentação