Geräte-Logs aufrufen

Cloud IoT Core kann optional Geräteaktivitätslogs an Cloud Logging senden. Geräteaktivitätslogs enthalten Informationen wie Geräteverbindungen und Fehler. Diese werden als Ereignisse bezeichnet.

Authentifizierungsfehler werden nicht in Logs erfasst. Ein Gerät muss bei Cloud IoT Core authentifiziert sein, um Ereignislogs zu generieren.

Lebenszyklus von Geräteereignissen

Alle Cloud IoT Core-Geräte haben einen ähnlichen Lebenszyklus mit den folgenden Ereignissen. Einige dieser Ereignisse und die zugrunde liegenden Details werden in Gerätelogs erfasst.

  1. Verbindung zu Cloud IoT Core herstellen
  2. Senden und Empfangen von Telemetrie- und/oder Staatsereignissen.
  3. Verbindung zu Cloud IoT Core trennen oder verwerfen

Wie diese Ereignisse auftreten und in Logs erfasst werden, hängt davon ab, ob die Geräte die MQTT-Bridge oder die HTTP-Bridge verwenden.

Logging der Geräteaktivität

Cloud IoT Core verwendet Logebenen, um zu bestimmen, welche Geräteereignisse an Cloud Logging gesendet werden. Sie können Gerätelogebenen für eine Registry und alle zugehörigen Geräte oder für einzelne Geräte festlegen. Die für eine Registry festgelegte Logebene gilt für alle Geräte in der Registry. Die für ein einzelnes Gerät festgelegte Logebene überschreibt die Einstellung der zugehörigen Registry.

In der folgenden Tabelle werden die verfügbaren Gerätelogebenen beschrieben:

Protokollebene Beschreibung
Es werden keine Geräteereignislogs erfasst.
ERROR Erfasst alle ERROR-Ereignisse, beispielsweise fehlgeschlagene Veröffentlichungen. In der Liste der protokollierten Geräteereignisse finden Sie die vollständige Liste der ERROR-Ereignisse.
INFO (nur MQTT) Erfasst alle INFO-Ereignisse, z. B. Verbindungen und Verbindungen über MQTT. Erfasst auch alle ERROR-Ereignisse. In der Liste der protokollierten Geräteereignisse finden Sie die vollständige Liste der INFO-Ereignisse.
DEBUG Erfasst alle DEBUG-Ereignisse wie Veröffentlichungen, Abos und Heartbeats. Nützlich zur Ermittlung von Problemen mit bestimmten Geräten. erfassen außerdem alle Ereignisse des Typs ERROR und INFO In der Liste der protokollierten Geräteereignisse finden Sie die vollständige Liste der DEBUG-Ereignisse. Weitere Informationen

Liste der in Logs erfassten Geräteereignisse

Die folgenden Tabellen zeigen Folgendes:

  • Welche Geräteereignisse in Logs erfasst werden
  • Der eventType des Ereignisses, wie in Cloud Logging erfasst
  • Ob Erfolge, Fehler oder beides für jedes Ereignis in Logs erfasst werden
  • Die Logebene, die für eine Registry oder ein Gerät festgelegt werden muss, um das Ereignis in Logs zu erfassen

MQTT-Bridge

Geräteereignis eventType Erfolg Fehler
Auf Server authentifizieren Nicht in Logs erfasst* Nicht in Logs erfasst
Mit Server verbinden CONNECT INFO ERROR
Verbindung zum Server trennen DISCONNECT INFO Nicht in Logs erfasst
Gerät an ein Gateway anhängen ATTACH_TO_GATEWAY INFO ERROR
Geräte von einem Gateway trennen DETACH_FROM_GATEWAY INFO ERROR
Telemetrieereignis oder -status auf dem Server veröffentlichen PUBLISH (für das MQTT-Thema /devices/{device-id}/events oder /devices/{device-id}/state) DEBUG ERROR
Konfigurationsupdate erhalten PUBLISH (zum MQTT-Thema /devices/{device-id}/config) DEBUG ERROR
Pub/Sub-Konfigurationsthema abonnieren SUBSCRIBE DEBUG ERROR
Pub/Sub-Konfigurationsthema abbestellen UNSUBSCRIBE DEBUG ERROR
PUBACK vom Server empfangen PUBACK DEBUG ERROR
Keep-Alive-Ping an Server gesendet PINGREQ DEBUG ERROR
Befehl vom Server an das Gerät gesendet PUBLISH DEBUG ERROR
Befehl PUBACK an das Gerät gesendet PUBACK DEBUG ERROR

* Wenn die MQTT-Authentifizierung erfolgreich ist, wird das Gerät mit Cloud IoT Core verbunden. Außerdem wird ein CONNECT-Ereignis anstelle des Ereignisses "Auf Server authentifizieren" in Logs erfasst.

HTTP-Bridge

Geräteereignis methodName Erfolg Fehler
Auf Server authentifizieren Nicht in Logs erfasst** Nicht in Logs erfasst
Telemetrieereignis veröffentlichen google.cloud.iot.v1.PublishEvent DEBUG ERROR
Gerätestatus festlegen google.cloud.iot.v1.SetDeviceState DEBUG ERROR
Konfigurationsupdate erhalten google.cloud.iot.v1.GetDeviceConfig DEBUG ERROR

** Wenn die HTTP-Authentifizierung erfolgreich ist, stellt das Gerät eine Verbindung zu Cloud IoT Core her und die entsprechende Anfragenachricht (GET, wenn eine Konfiguration empfangen wird, oder POST, wenn eine Nachricht veröffentlicht wird) wird in Logs erfasst.

Geräte-Logging aktivieren, ändern und deaktivieren

Sie können auswählen, welche Arten von Logs an Cloud Logging gemeldet werden, wenn Sie in der Google Cloud Console oder mit dem gcloud-Tool eine Registry oder ein Gerät erstellen oder bearbeiten.

Logebenen für eine Registry festlegen

Sie können Gerätelogs für eine Registry über die Google Cloud Console oder gcloud aktivieren, ändern oder deaktivieren. Die Einstellungen des Registrierungsprotokolls gelten automatisch für alle Geräte in der Registry.

Console

So erstellen oder bearbeiten Sie eine Registry und legen ihre Logebene fest:

  1. Rufen Sie in der Google Cloud Console die Seite Registrys auf.

    Zur Seite Registries

  2. Klicken Sie oben auf der Seite auf Registry erstellen.

    Klicken Sie zum Bearbeiten einer vorhandenen Registry auf deren ID auf der Seite Registries und dann oben auf der Seite auf Registry bearbeiten.

  3. Wählen Sie unter Stackdriver-Logging eine Logebene aus.

  4. Klicken Sie auf Erstellen, wenn Sie eine neue Registry erstellen, oder auf Aktualisieren, wenn Sie eine vorhandene Registry bearbeiten.

gcloud

Führen Sie den Befehl gcloud iot registries create mit dem Flag --log-level aus, um eine Registry zu erstellen und die Logebene festzulegen:

gcloud iot registries create REGISTRY_ID \
    --project=PROJECT_ID \
    --region=REGION \
    [--event-notification-config=topic=TOPIC,[subfolder=SUBFOLDER] [--event-notification-config=...]]
    [--state-pubsub-topic=STATE_PUBSUB_TOPIC] \
    --log-level={NONE|INFO|ERROR|DEBUG}

Führen Sie zum Aktualisieren der Logebene eines Geräts den Befehl gcloud iot registries update mit dem Flag --log-level aus:

gcloud iot registries update REGISTRY_ID \
    --project=PROJECT_ID \
    --region=REGION \
    --log-level={NONE|INFO|ERROR|DEBUG}

Logebenen für ein Gerät festlegen

Sie können Geräteprotokolle für ein Gerät über die Google Cloud Console oder gcloud aktivieren, ändern oder deaktivieren. Die Logebene eines Geräts überschreibt die Protokollebene der Registry.

Console

So legen Sie die Protokollebene für ein neues oder vorhandenes Gerät fest:

  1. Rufen Sie in der Google Cloud Console die Seite Registrys auf.

    Zur Seite Registries

  2. Klicken Sie auf die ID der Registry für das Gerät.

  3. Klicken Sie im Registry-Menü links auf Geräte.

  4. Wenn Sie ein neues Gerät erstellen möchten, klicken Sie auf Gerät erstellen.

    Wenn Sie ein vorhandenes Gerät bearbeiten möchten, klicken Sie auf der Seite Geräte auf die zugehörige ID und dann oben auf der Seite auf Gerät bearbeiten.

  5. Wählen Sie unter Stackdriver-Logging eine Logebene aus.

  6. Klicken Sie auf Erstellen, wenn Sie ein neues Gerät erstellen, oder auf Aktualisieren, wenn Sie ein vorhandenes Gerät bearbeiten.

gcloud

Führen Sie den Befehl gcloud iot devices create mit dem Flag --log-level aus, um ein Gerät zu erstellen und eine Logebene festzulegen:

gcloud iot devices create DEVICE_ID \
    --project=PROJECT_ID \
    --region=REGION \
    --registry=REGISTRY_ID \
    --public-key path=PUBLIC_KEY,type=TYPE \
    --log-level={NONE|INFO|ERROR|DEBUG}

Führen Sie zum Aktualisieren der Logebene eines Geräts den Befehl gcloud iot devices update mit dem Flag --log-level aus:

gcloud iot devices update DEVICE_ID \
    --project=PROJECT_ID \
    --region=REGION \
    --registry=REGISTRY_ID \
    --log-level={NONE|INFO|ERROR|DEBUG}

Logs ansehen

Sie können sich Geräteaktivitäts-Logs für Ihr Projekt im Log-Explorer in der Google Cloud Console ansehen. Wählen Sie im Menü für den Lognamen die Option device_activity aus.

Weitere Informationen finden Sie unter Log-Explorer verwenden.

API

Informationen zum Lesen von Logeinträgen mithilfe der Logging API finden Sie unter entries.list.

gcloud

Informationen zum Lesen der Logeinträge mit gcloud finden Sie unter Logeinträge lesen.

Gerätelogs exportieren

Sie können Gerätelogs genauso wie andere Arten von Logs exportieren. Einzelheiten zum Exportieren von Logs finden Sie unter Logs exportieren.

In den folgenden Beispielen werden Gründe zum Exportieren von Gerätelogs beschrieben:

  • Sie können Kopien Ihrer Gerätelogs nach Cloud Storage, BigQuery oder Pub/Sub exportieren, um Gerätelogs über einen längeren Zeitraum hinweg aufzubewahren oder leistungsfähigere Suchfunktionen zu verwenden. Mit Pub/Sub haben Sie die Möglichkeit, die Logs in andere Anwendungen, andere Repositories und Systeme von Drittanbietern zu exportieren.

  • Verwalten Sie Ihre Gerätelogs organisationsweit, indem Sie zusammengefasste Exportsenken erstellen, mit denen sich Logs aus beliebigen oder allen Projekten in der Organisation exportieren lassen.

Limits für das Geräte-Logging

Für Projekte gelten Kontingente und Limits für Geräteprotokolle. Sie werden getrennt von anderen Cloud Logging-Kontingenten und -Beschränkungen gemessen und nicht auf diese angerechnet. Kontingente für Geräteprotokolle sind aufgebraucht. Cloud Logging-Kontingente für andere Dienste sind davon nicht betroffen. Dies gilt auch umgekehrt.

Kontingente für Gerätelogs basieren auf zwei Faktoren:

  • Die Anzahl der Geräteereignisse, die pro Sekunde protokolliert werden. Zu den Ereignissen gehören Veröffentlichungen, Verbindungen, Verbindungsabbrüche usw.
  • Die Gesamtgröße der pro Minute erfassten Geräteereignisse (in Byte).

Wenn eines der Kontingente für Gerätelogs überschritten wird, werden die Gerätelogs vorübergehend angehalten.

Eine Liste der Kontingente und Limits für Geräteprotokolle finden Sie unter Kontingente und Limits.

Best Practices

Logging von Geräte-Debugging

Wie in der Liste der in Logs erfassten Geräteereignisse dargestellt, können durch Festlegen der Logebene DEBUG für eine Registry oder ein einzelnes Gerät große Mengen an Logging-Informationen generiert werden. Wenn Sie das Debug-Logging für eine Registry mit einer großen Anzahl von Geräten aktivieren, werden daher möglicherweise Logging-Datensätze aufgrund der hohen Geschwindigkeit und Anzahl von Logs verworfen.

Angenommen, Sie haben eine Registry mit 100.000 Geräten und die Debug-Logebene ist für die Registry festgelegt. Wenn jedes Gerät eine Telemetrieereignis pro Sekunde veröffentlicht, werden nur 1.000 von 100.000 Telemetrieereignissen pro Sekunde in Logs erfasst. Dies liegt daran, dass maximal 1.000 Logeinträge pro Sekunde erfasst werden, wie unter Kontingente und Limits gezeigt.

Die besten Ergebnisse erzielen Sie, wenn Sie das Debug-Logging entweder nur für einen kurzen Zeitraum oder nur für eine kleine Anzahl von Geräten aktivieren.

Fehler beim Schreiben von Logs beheben

Beim erstmaligen Aktivieren der Google Cloud IoT Core API für ein Projekt wird automatisch einem neuen Dienstkonto für das Projekt eine Rolle zugewiesen (cloudiot.serviceAgent), die das Schreiben von Logs in Cloud Logging ermöglicht. Wenn Sie diese Standardrolle später aus dem entsprechenden Projektdienstkonto entfernen, kann es zu Fehlern kommen. Wenn Sie keine Geräteaktivität in Cloud Logging schreiben können, führen Sie die folgenden Schritte aus:

  1. Prüfen Sie auf der IAM-Seite in der Google Cloud Console, ob die Rolle Cloud IoT Core Service Agent in der Liste Members des entsprechenden Projektdienstkontos angezeigt wird. (Suchen Sie nach dem Projektdienstkonto, das auf @gcp-sa-cloudiot.iam.gserviceaccount.com endet.)

  2. Wenn die Rolle Cloud IoT Core-Dienst-Agentnicht in der Liste Mitgliedererscheint, fügen Sie gclouddie Rolle cloudiot.serviceAgentzu dem Konto des relevanten Dienstes hinzu. Diese Rolle umfasst die Berechtigung zum Schreiben von Logs in Cloud Logging.

    Führen Sie den folgenden Befehl aus, um Ihrem Projekt die Rolle cloudiot.serviceAgent hinzuzufügen. Informationen zum Ermitteln von PROJECT_ID und PROJECT_NUMBER finden Sie unter Projekte identifizieren.

    gcloud projects add-iam-policy-binding PROJECT_ID \
      --member=serviceAccount:service-PROJECT_NUMBER@gcp-sa-cloudiot.iam.gserviceaccount.com \
      --role=roles/cloudiot.serviceAgent