Störungsmeldung mit PagerDuty und Vonage

Einführung

PagerDuty ist ein Incident Reporting Management System, das Benachrichtigungen und automatische Eskalationen bereitstellt, um Ingenieurteams dabei zu helfen, Probleme zu erkennen und zu beheben, sobald sie in ihrer Infrastruktur auftreten. In diesem Beitrag sehen wir uns an, wie wir Vonage nutzen können, um Mitglieder eines Ingenieurteams zu benachrichtigen, wenn ein Vorfall in ihrer Infrastruktur auftritt.

Mithilfe der Vonage Dispatch-API, die eine automatische Failover-Option bietet, werden wir zunächst Benachrichtigungen über Facebook Messenger als primäres Medium und dann über SMS als Ausweichoption versenden.

Technische Anforderungen

Um mitzumachen, benötigen Sie Folgendes:

• PHP Version 7.1 oder höher

• Laravel 5.8

• Ngrok das es Ihnen ermöglicht, Ihren lokalen Webserver dem Internet auszusetzen. Um mehr darüber zu erfahren, wie Sie Ihre lokale Umgebung mit Ngrok einrichten, können Sie sich die Dokumentation ansehen hier.

• Komponist

• Vonage CLI

• A Facebook Konto

• A PagerDuty Konto

Vonage API-Konto

Um dieses Tutorial durchzuführen, benötigen Sie ein Vonage API-Konto. Wenn Sie noch keines haben, können Sie sich noch heute anmelden und mit einem kostenlosen Guthaben beginnen. Sobald Sie ein Konto haben, finden Sie Ihren API-Schlüssel und Ihr API-Geheimnis oben auf dem Vonage-API-Dashboard.

Sind Sie bereit, mit dem Bau zu beginnen?

Erleben Sie nahtlose Konnektivität, Echtzeit-Messaging und kristallklare Sprach- und Videoanrufe - alles auf Knopfdruck.

Einrichten

Um die Dispatch-API nutzen zu können, müssen wir in unserem Vonage-Konto ein paar Dinge tun. Gehen Sie zu Ihrem Vonage-Dashboard und erstellen Sie unter dem Abschnitt "Nachrichten und Versand" eine neue Nachrichtenanwendung.

new message app in dashboard

\

• Die Status-URL ist der Webhook-Endpunkt, an den Vonage eine POST-Anfrage stellt, wenn wir SMS-Benachrichtigungen verschicken. So können wir den aktuellen Status der versendeten SMS ermitteln, d.h. zugestellt, abgelehnt oder übermittelt. Da wir Ngrok verwenden werden, sollte die Status-URL etwa so aussehen qc43v7.ngrok.io/webhooks/status.

• Die Inbound-URL ist der Endpunkt, an den Vonage eine Anfrage stellt, wenn eingehende Nachrichten empfangen werden, und sollte ähnlich wie folgt aussehen qc43v7.ngrok.io/webhooks/inbound-message

• Als Nächstes erzeugen Sie ein öffentliches/privates Schlüsselpaar. Dabei wird automatisch auch die Datei mit dem privaten Schlüssel heruntergeladen. Notieren Sie sich diese Datei, da wir sie in Kürze benötigen werden.

• Erstellen Sie die Anwendung und notieren Sie sich dann die Anwendungs-ID. Als Nächstes werden Sie aufgefordert, Nummern und externe Konten mit dieser Anwendung zu verknüpfen. Dies ist völlig optional, Sie können also auch einfach die Standardeinstellungen verwenden und die Anwendung erstellen.

PagerDuty einrichten

Gehen Sie rüber zu PagerDuty und erstellen Sie ein Konto, falls Sie noch keins haben. Wir müssen auch einen Service erstellen. Ein Service in PagerDuty repräsentiert alles, gegen das wir Incidents öffnen möchten. Das kann eine Anwendung, eine Komponente oder sogar ein Team sein. Wann immer also ein neuer Vorfall bei diesem Service auftritt, wollen wir Webhook-Benachrichtigungen an einen bestimmten Endpunkt in unserer Anwendung senden.

Gehen Sie in Ihrem PagerDuty Dashboard zu Konfiguration -> Dienste und erstellen Sie einen neuen Dienst.

pager duty dashboard

Da wir unsere eigene benutzerdefinierte Integration verwenden werden, wählen Sie für den Integrationstyp die Option use our API directly aus und wählen Sie dann Events API V2 und füllen Sie alle anderen notwendigen Details aus. Sie können mehr über die Erstellung eines Dienstes auf PagerDuty lesen hier.

Nachdem Sie den Dienst erfolgreich erstellt haben, wählen Sie auf der Registerkarte "Integrationen" die Option "Neue Erweiterung" und geben ihr den Typ Generic V2 webhook. Der Abschnitt "Details" besteht aus dem Endpunkt in unserer Anwendung, an dem wir Benachrichtigungen von PagerDuty erhalten möchten und sollte in etwa so aussehen qc43v7.ngrok.io/webhooks/incident

pager duty

Einrichten von Laravel

Wir werden Composer verwenden, um ein neues Laravel-Projekt zu installieren. Erstellen Sie in der Befehlszeile ein neues Laravel-Projekt mit dem folgenden Befehl:

Routen und Controller

Bearbeiten Sie die routes/web.php mit folgendem Code:

<?php

Route::post('/webhooks/inbound-message', 'WebhookController@inboundMessage');
Route::post('/webhooks/status', 'WebhookController@status');
Route::post('/webhooks/incident', 'WebhookController@report');

Ein Cross-Site-Request-Forgery-Angriff ist eine Art von bösartigem Angriff, bei dem nicht autorisierte Befehle im Namen eines authentifizierten Benutzers ausgeführt werden. Um solche Angriffe zu verhindern, generiert Laravel automatisch ein Csrf Token für jeden authentifizierten Benutzer, mit dessen Hilfe überprüft werden kann, ob der authentifizierte Benutzer tatsächlich derjenige ist, der eine Anfrage an die Anwendung stellt. Da diese Anfragen jedoch von außerhalb der Anwendung kommen und wir der Quelle vertrauen, müssen wir die Csrf Validierung für diese Routen deaktivieren. Die VerifyCsrfToken Middleware wird für die Validierung aller Token verwendet. Glücklicherweise akzeptiert die Middleware ein except Array, das eine Liste aller Routen enthält, für die die CSRF-Überprüfung deaktiviert werden soll.

Bearbeiten Sie die app\Http\Middleware\VerifyCsrfToken.php Datei mit dem folgenden Code:

protected $except = [
        '/webhooks/*'
    ];

Führen Sie anschließend den folgenden Befehl aus, um einen Controller zu erstellen:

php artisan make:controller WebhookController 

Dadurch wird eine WebhookController.php Datei für uns im app\Http\Controllers Verzeichnis. Bearbeiten Sie die Datei mit dem folgenden Code:

<?php

namespace App\Http\Controllers;

use Illuminate\Http\Request;
use Illuminate\Support\Facades\Log;
use App\Jobs\ReportIncident;

class WebhookController extends Controller
{
    public function inboundMessage(Request $request)
    {
        return Log::debug('Inbound Message', $request->all());
    }

    public function status(Request $request)
    {
        return Log::debug('Status', $request->all());
    }

    public function report(Request $request)
    {
        Log::debug('Incident', $request->all());

        dispatch(new ReportIncident());

        return response('Webhook received');
    }
}

Für die inboundMessage() und status() protokollieren wir einfach die Anfragedaten von Vonage in der von Laravel bereitgestellten Protokolldatei. Die Methode report() Methode sendet einen ReportIncident Job, den wir in Kürze erstellen werden. Dieser Job ist für die Auslösung von SMS-Benachrichtigungen mithilfe eines benutzerdefinierten Wrappers um die Vonage-API verantwortlich.

Verknüpfung von Facebook mit Ihrem Vonage-Konto

Um erfolgreich Nachrichten von Vonage an Facebook senden zu können, müssen Sie zunächst eine Facebook-Seite, die mit Ihrem Facebook-Konto verknüpft ist, mit Ihrem Vonage-Konto verbinden. Wie Sie das tun können, erfahren Sie hier.

Wenn Sie mit der Verknüpfung fertig sind, senden Sie eine Nachricht von Ihrem Facebook-Konto an die Facebook-Seite. Da es sich um eine eingehende Nachricht handelt, sendet Vonage eine Anfrage mit den Details der Nachricht an den /webhooks/inbound-message Endpunkt, den wir zuvor erstellt haben. Überprüfen Sie Ihre Protokolldatei und Sie sollten einen Eintrag ähnlich dem folgenden sehen:

Inbound Message{  
   "message_uuid":"0a2088d2-e028-4aa0-aa4a-ae11a6f82fb0",
   "to":{  
      "id":"1923256201474167",
      "type":"messenger"
   },
   "from":{  
      "id":"23037543461244470",
      "type":"messenger"
   },
   "timestamp":"2019-08-06T21:56:16.887Z",
   "direction":"inbound",
   "message":{  
      "content":{  
         "type":"text",
         "text":"Hello"
      }
   }
}

Die Facebook-Absenderkennung ist die to.id, während die Empfänger-ID die from.id. Notieren Sie sich diese Angaben, da wir sie in Kürze benötigen werden.

Erstellen eines benutzerdefinierten Wrappers

Da sich die Dispatch-API zum Zeitpunkt der Erstellung dieses Tutorials noch im Beta-Stadium befindet, bietet die PHP-Bibliothek von Vonage noch keine Unterstützung dafür. Daher werden wir einen benutzerdefinierten Wrapper verwenden, um mit der API von Nexmo zu interagieren. Um loszulegen, müssen wir zunächst ein Json Web Token (JWT) generieren, das wir für die Authentifizierung mit der API verwenden werden.

Verwendung der Vonage CLIführen Sie den folgenden Befehl aus:

vonage jwt --key_file=./private.key --app_id=VONAGE_APPLICATION_ID

./private.key ist der Pfad zu der privaten Schlüsseldatei, die bei der Erstellung der Nachrichten- und Versandanwendung für Sie erzeugt wurde, während die app_id die Anwendungs-ID ist, die wir zuvor notiert haben. Kopieren Sie nun die Ausgabe dieses Befehls.

Umgebungs- und Konfig-Variablen

Fügen Sie das soeben generierte JWT zu Ihrem .env, die Messenger-Details, die wir zuvor notiert haben, und die Telefonnummern, die für das Senden und Empfangen von SMS-Benachrichtigungen zuständig sein werden.

VONAGE_JWT = xxxx
FB_SENDER_ID = xxxx
FB_RECIPIENT_ID = xxxx
SMS_FROM = xxxx
SMS_TO = xxxx

Als Nächstes werden wir die Umgebungsvariablen, die wir gerade definiert haben, in unserer Konfigurationsdatei referenzieren. Gehen Sie in das config Verzeichnis und fügen Sie unter der Datei services.php Datei eine neue Vonage array.

'vonage' => [
        'jwt' => env('VONAGE_JWT'),
        'fb_sender_id' => env('FB_SENDER_ID'),
        'fb_recipient_id' => env('FB_RECIPIENT_ID'),
        'sms_from' => env('SMS_FROM'),
        'sms_to' => env('SMS_TO')
    ]

Installation von Abhängigkeiten

Die einzige Abhängigkeit, die unser Projekt haben wird, ist die GuzzleHTTP Bibliothek, die wir für die API-Aufrufe verwenden werden. Führen Sie den folgenden Befehl aus, um die Bibliothek zu installieren:

composer require guzzlehttp/guzzle

Erstellen des Wrappers

Im Verzeichnis app Verzeichnis erstellen Sie eine Vonage.php Datei und fügen Sie den folgenden Code in diese Datei ein:

<?php

namespace App;

use GuzzleHttp\Client;

class Vonage
{
    protected $client;

    public function __construct()
    {
        $this->client = $this->setUpClient();
    }

    protected function setUpClient()
    {
        $authBearer = 'Bearer ' . config('services.vonage.jwt');

        return new Client([
            'base_uri' => 'https://api.nexmo.com',
            'headers' => [
                'Authorization' => $authBearer,
                'Content-Type' => 'application/json',
                'Accept' => 'application/json'
            ]
        ]);
    }


    public function dispatch()
    {
        $response  = $this->client->request('POST', '/v0.1/dispatch', [
            'json' => [
                'template' => 'failover',
                'workflow' => [
                 [
                    'from' => [ 'type' => 'messenger','id' => config('services.vonage.fb_recipient_id')],
                    'to' => ['type' => 'messenger', 'id' => config('services.vonage.fb_sender_id')],
                    'message' => [
                      'content' => [
                        'type' => 'text',
                        'text' => 'An incident just occurred',
                      ]
                     ],
                    'failover' =>[
                      'expiry_time' => 15,
                      'condition_status' => 'read',
                    ]
                   ],
                  [
                    'from' => ['type' => 'sms','number' => config('services.vonage.sms_from')],
                    'to' => ['type' => 'sms','number' => config('services.vonage.sms_to')],
                    'message' => [
                      'content' => [
                        'type' => 'text',
                        'text' => 'An incident just occurred',
                      ]
                    ]
                  ]
                ]
            ]
        ]);

        return json_decode($response->getBody());
    }
}

In der dispatch() Methode haben wir eine Failover-Vorlage und einen Workflow definiert. Immer wenn ein Vorfall über PagerDuty auftritt, erhalten wir eine Benachrichtigung über den Vorfall auf Facebook Messenger. Wenn die Benachrichtigung nicht innerhalb von 15 Sekunden gelesen wird, wird die Failover-Bedingung ausgelöst und eine SMS-Benachrichtigung als Ausweichlösung gesendet.

Den Auftrag erstellen

Führen Sie den folgenden Befehl im Terminal aus, um eine neue Auftragsklasse zu erstellen:

php artisan make:job ReportIncident

Bearbeiten Sie die app\Http\Jobs\ReportIncident Datei mit dem folgenden Code:

<?php

namespace App\Jobs;

use Illuminate\Bus\Queueable;
use Illuminate\Queue\SerializesModels;
use Illuminate\Queue\InteractsWithQueue;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Foundation\Bus\Dispatchable;
use App\Vonage;

class ReportIncident implements ShouldQueue
{
    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;

    /**
     * Create a new job instance.
     *
     * @return void
     */
    public function __construct()
    {
    }

    /**
     * Execute the job.
     *
     * @return void
     */
    public function handle(Voange $vonage)
    {
        $vonage->dispatch();
    }
}

Die handle() Methode empfängt den benutzerdefinierten Vonage-Wrapper, den wir zuvor als Abhängigkeit erstellt haben, und ruft dann die Dispatch-Methode der Klasse auf.

Alles unter einen Hut bringen

Jetzt ist es an der Zeit, das zu testen, was wir bisher aufgebaut haben. Gehen Sie zu Ihrem PagerDuty Dashboard und erstellen Sie einen neuen Vorfall.

incidents screenshot

Dies löst eine Webhook-Benachrichtigung aus, die an den Endpunkt gesendet wird, den wir zuvor zu unserem PagerDuty-Konto hinzugefügt haben, das wiederum eine Nachricht an die Facebook-Seite sendet, die wir zuvor mit unserem Vonage-Konto verknüpft haben. In der Annahme, dass alles gut gelaufen ist, sollten Sie Ihre Protokolldatei überprüfen, da Vonage eine Aktualisierung des Status der soeben übermittelten Nachricht gesendet hätte.

{  
   "message_uuid":"c1bcf89b-c16e-427f-a4b7-15816327832f",
   "to":{  
      "id":"1923256201474167",
      "type":"messenger"
   },
   "from":{  
      "id":"23037543461244470",
      "type":"messenger"
   },
   "timestamp":"2019-08-08T01:53:07.922Z",
   "status":"read",
   "_links":{  
      "dispatch":{  
         "href":"v0.1/dispatch/15756412-30d6-4664-8a1e-abcd029ea7a4",
         "dispatch_uuid":"15756412-30d6-4664-8a1e-abcd029ea7a4"
      }
   }
},
{  
   "template":"failover",
   "status":"completed",
   "timestamp":"2019-08-08T01:53:07.959Z",
   "usage":{  
      "price":"0.003",
      "currency":"EUR"
   },
   "dispatch_uuid":"15756412-30d6-4664-8a1e-abcd029ea7a4",
   "_links":{  
      "messages":[  
         {  
            "message_uuid":"c1bcf89b-c16e-427f-a4b7-15816327832f",
            "href":"v0.1/messages/c1bcf89b-c16e-427f-a4b7-15816327832f",
            "channel":"messenger",
            "usage":{  
               "price":"0.001",
               "currency":"EUR"
            },
            "status":"read"
         }
      ]
   }
}

Aus den obigen Protokollen geht zunächst eine Statusaktualisierung hervor, die uns darüber informiert, dass die Nachricht gelesen wurde, und anschließend eine weitere Statusaktualisierung, die uns darüber informiert, dass der Versandworkflow abgeschlossen wurde. Da die Nachricht innerhalb von 15 Sekunden gelesen wurde, war die Failover-Bedingung erfüllt; infolgedessen wurde die SMS-Benachrichtigung nie ausgelöst.

Um zu testen, ob die SMS-Benachrichtigung versendet wird, wenn die Failover-Bedingung nicht erfüllt ist, können Sie den gleichen Vorgang wiederholen, aber diesmal die Facebook-Messenger-Benachrichtigung nicht lesen. Sie werden feststellen, dass dieses Mal die SMS-Benachrichtigung ausgelöst wird.

Schlussfolgerung

In diesem Tutorial haben wir gesehen, wie wir eine benutzerdefinierte Integration mit PagerDuty und Vonage erstellen können, um ein robustes Fallback-Alarmsystem für den Notfall zu gewährleisten. Einen Link zum Github Repo finden Sie hier.