Zum Hauptinhalt springen

Grafana-Einrichtung

Die Plattform unterstützt zwei Grafana-Datenquellen über ihre API:

  1. Die JSON-Datenquelle. Damit können API-Nutzer ihr eigenes Grafana hosten und Zeitreihendaten der Plattform anzeigen.
  2. Die Infinity-Datenquelle. Damit kann Grafana die gesamte REST-API der IoT-Plattform nutzen, um Daten zu visualisieren und auch den Grafana Alert Manager für Regeln zu verwenden.

Im Folgenden finden Sie Anleitungen und Hilfe zur Einrichtung. Informationen zum Erstellen von Panels nach dem Verbinden finden Sie im Grafana-Benutzerhandbuch.

Einrichtung im Überblick​

Grafana mit der IoT-Plattform zu verbinden umfasst fünf Schritte, in dieser Reihenfolge:

  1. Ein Konto auf der IoT-Plattform erstellen - liefert die Zugangsdaten.
  2. Eine Client-App erstellen auf der IoT-Plattform - das Secret speichern.
  3. Grafana installieren und OAuth gegen die IoT-Plattform konfigurieren (die custom.ini unten).
  4. Eine Datenquelle hinzufügen - JSON für schnelle Zeitreihen & Karten, Infinity für die vollständige REST-API + Alarmierung.
  5. Mit dem Visualisieren beginnen - Ihr erstes Panel erstellen.

Sie benötigen: ein Konto auf der IoT-Plattform und Administratorrechte auf der Grafana-Instanz (um deren Konfiguration zu bearbeiten und Plugins zu installieren). Grafana 9.0.x oder höher.

Versionskompatibilität​

KomponenteVerifizierte Version
Grafana9.0.x oder höher
simpod-json-datasource (JSON)0.6.x
yesoreyeram-infinity-datasource (Infinity)3.6

API-Nutzer​

Stellen Sie zunächst sicher, dass Sie ein Konto auf der IoT-Plattform erstellt haben. Dieses Konto wird verwendet, um die Zugangsdaten zu erstellen, die von der Grafana-App verwendet werden.

Client-App​

Um die API zu nutzen, müssen Sie eine Client-App erstellen. Es wird empfohlen, dafür die interaktive API-Dokumentation zu verwenden. Der zu verwendende Endpunkt ist POST /api/client-apps. Achten Sie darauf, das Secret zu speichern.

Grafana installieren​

Aktuell unterstützen wir Versionen 9.0.x oder höher.

Folgen Sie den Grafana-Installationsanweisungen. Grafana benötigt dann eine benutzerdefinierte Konfiguration, um sich mit der IoT-Plattform zu verbinden; das Beispiel unten ist das Minimum, um es lauffähig zu bekommen (siehe die Grafana-Konfigurationsdokumentation für die Funktionsweise der benutzerdefinierten Konfiguration).

Das Beispiel ist für diesen Server geschrieben (staging.yggio.net). Wenn Sie mit einer anderen Instanz der IoT-Plattform integrieren, verwenden Sie die Dokumentation dieser Plattform für die korrekten URLs.

Ändern Sie Folgendes entsprechend Ihrer Einrichtung:

  • domain - die öffentliche IP oder der Domainname, unter dem Sie Grafana hosten
  • root_url - dasselbe, mit dem http-/https-Schema
  • signout_redirect_url - aktualisieren Sie den Query-Parameter redirect_uri auf Ihre Grafana-Login-URL
  • client_id - die client_id vom Erstellen der Client-App
  • client_secret - das Secret vom Erstellen der Client-App
#### custom.ini ####

[server]
domain = grafana-test.your-domain.com
root_url = https://grafana-test.your-domain.com

[auth]
signout_redirect_url = https://staging.yggio.net/auth/realms/yggio/protocol/openid-connect/logout?redirect_uri=https%3A%2F%2Fgrafana-test.your-domain.com%2Flogin
token_rotation_interval_minutes = 60

[auth.generic_oauth]
enabled = true
allow_sign_up = true
name = Yggio
client_id = grafana-test-client
client_secret = abcabcabcabc-test-test-test-cbacbacbacba
auth_url = https://staging.yggio.net/auth/realms/yggio/protocol/openid-connect/auth
token_url = https://staging.yggio.net/auth/realms/yggio/protocol/openid-connect/token
api_url = https://staging.yggio.net/auth/realms/yggio/protocol/openid-connect/userinfo
scopes = openid, email, profile, offline_access

Der Scope offline_access sorgt dafür, dass nach dem Einloggen in Grafana ein Refresh-Token verwendet wird, um Ihre Sitzung automatisch zu erneuern, sodass Sie sich nicht erneut anmelden müssen. Dadurch fühlt sich Grafana wie eine eingebettete Plattform-Anwendung an.

Wie die Authentifizierung funktioniert​

Grafana meldet Nutzer über OpenID Connect ([auth.generic_oauth]) beim Identity-Provider der IoT-Plattform (Keycloak) an. Für jede Datenquelle ist außerdem Forward OAuth Identity aktiviert, sodass Grafana das Token des angemeldeten Nutzers bei jeder Anfrage an die API der IoT-Plattform weiterleitet. Dadurch sieht jeder Grafana-Nutzer genau die Geräte und Daten, auf die sein eigenes Konto auf der IoT-Plattform Zugriff hat - es gibt kein gemeinsames Service-Konto, und der Zugriff wird durch die Berechtigungen der IoT-Plattform geregelt. Der Scope offline_access hält die Sitzung durch Erneuerung des Tokens aufrecht.

Datenquellen​

Beachten Sie, dass Administratorrechte erforderlich sind, um Plugins in Grafana hinzuzufügen und zu konfigurieren.

Hier finden Sie einige Informationen zur Installation von Plugins in Grafana.

Installation der JSON-Datenquelle​

Aktuell unterstützen wir die Plugin-Versionen 0.6.x von simpod-json-datasource.

Hier ist eine Anleitung zur speziellen Installation des JSON-Datenquellen-Plugins.

Konfiguration

Lassen Sie alles auf den Standardwerten außer den beiden folgenden Einstellungen.

  • URL: <yggio rest-api URl>/api/grafana/iotnodes (z. B. https://staging.yggio.net/api/grafana/iotnodes)
  • Forward OAuth Identity: true

Installation der Infinity-Datenquelle​

Aktuell unterstützen wir yesoreyeram-infinity-datasource. Die Unterstützung ist mit Version 3.6 verifiziert.

Hier ist die Dokumentation und Anleitung zur speziellen Installation des Infinity-Datenquellen-Plugins.

Konfiguration

Lassen Sie alles auf den Standardwerten außer den beiden folgenden Einstellungen.

  • Forward OAuth Identity: true
  • Allowed Host: <Platform URL> (z. B. https://staging.yggio.net)

So sollten Sie die Infinity-Datenquelle konfigurieren und verwenden

time-series

Welche Datenquelle soll ich verwenden?​

JSON-DatenquelleInfinity-Datenquelle
ZweckZeitreihenwerte für Diagramme/KartenBeliebiger Endpunkt der REST-API der IoT-Plattform (Tabellen, Diagramme, Karten)
Endpunkt/api/grafana/iotnodes (fest)jede GET-URL, die Sie aus Swagger einfügen
Am besten fürSchnelle Geräte-Werte- & GPS-DiagrammeVolle Flexibilität + Grafana-Alarmierung

Wie die Daten der IoT-Plattform in Grafana erscheinen​

  • Eine Metrik in der JSON-Datenquelle ist ein iotnode (Gerät). Die Auswahl des Platzhalters * liefert alle Ihre aktiven Geräte.
  • Die Felder jedes Geräts verwenden die kanonischen Feldnamen der IoT-Plattform (z. B. temperature, relativeHumidity, lnglat, rssi, snr) - dieselben Namen über alle Hersteller hinweg, sodass ein Dashboard über gemischte Hardware hinweg funktioniert. Siehe die Datenmodell-Feldtabelle in der Referenz Translator API.
  • Standort: Ein Gerät mit lnglat stellt lat/lng für Geomap-Panels bereit (filtern Sie sie mit einer Filter by name-Transformation aus Zeitreihendiagrammen heraus).
  • Zeitreihen über die Infinity-Datenquelle stammen von GET /api/iotnodes/<id>/stats?measurement=<field>&start=<unix ms>&distance=<seconds>.

Alarmierung​

Die Infinity-Datenquelle funktioniert mit dem Alert Manager von Grafana, sodass Sie Alarmregeln direkt auf den REST-API-Daten der IoT-Plattform definieren können (Schwellenwerte, Ausbleiben von Daten usw.) und Benachrichtigungen über die Kontaktpunkte von Grafana weiterleiten können. Die JSON-Datenquelle ist eher für die Visualisierung als für die Alarmierung gedacht.

Fehlerbehebung​

  • Login-Schleifen / Redirect-Fehler - der redirect_uri in signout_redirect_url und Grafanas root_url/domain müssen der tatsächlichen öffentlichen URL Ihres Grafana entsprechen, und die erlaubte Redirect-URL der Client-App muss sie enthalten.
  • Panels zeigen keine Daten, aber der Login funktioniert - prüfen Sie, ob Forward OAuth Identity auf der Datenquelle auf true gesetzt ist; ohne das ruft Grafana die API unauthentifiziert auf.
  • Infinity: Anfrage blockiert - fügen Sie Ihre IoT-Plattform-Domain den Allowed Hosts der Datenquelle hinzu.
  • Ein Gerät oder Feld fehlt - Grafana sieht nur, worauf Ihr Konto auf der IoT-Plattform Zugriff hat, und ein Gerät stellt nur die Felder bereit, die sein Übersetzer ausgibt; bestätigen Sie beides in https://staging.yggio.net/swagger.

Los geht's mit Diagrammen!​

Sobald die obigen Schritte abgeschlossen sind, sollte es möglich sein, ein Dashboard und ein Panel mit Daten der Plattform zu erstellen! Gehen Sie zum Benutzerhandbuch für Grafana