Consulter les journaux d'un appareil

Cloud IoT Core peut éventuellement envoyer les journaux d'activité des appareils à Cloud Logging. Les journaux d'activité des appareils incluent des informations telles que les connexions et les erreurs de l'appareil. C'est ce qu'on appelle les événements.

Les échecs d'authentification ne sont pas consignés. Un appareil doit être authentifié auprès de Cloud IoT Core pour générer des journaux d'événements.

Cycle de vie des événements sur l'appareil

Tous les appareils Cloud IoT Core suivent un cycle de vie semblable aux événements suivants. Certains de ces événements et leurs informations sous-jacentes sont enregistrés dans les journaux de l'appareil.

  1. Connexion à Cloud IoT Core...
  2. Envoyer et recevoir des événements de télémétrie et/ou d'état.
  3. Déconnexion de la connexion à Cloud IoT Core, ou suppression de sa connexion.

La façon dont ces événements se produisent et sont consignés est déterminée par l'utilisation des ponts MQTT ou HTTP des appareils.

Enregistrer les activités des appareils

Cloud IoT Core utilise les niveaux de journalisation pour déterminer les événements d'appareil qui sont envoyés à Cloud Logging. Vous pouvez définir des niveaux de journalisation de l'appareil pour un registre et tous ses appareils, ou pour des appareils individuels. Le niveau de journalisation défini pour un registre s'applique à tous les appareils qui y sont enregistrés. Le niveau de journalisation défini pour un appareil individuel remplace celui de son registre.

Le tableau suivant décrit les niveaux de journalisation d'appareils disponibles :

Niveau de journalisation Description
Aucune Aucun journal d'événements d'appareil n'est collecté.
ERROR Capture tous les événements ERROR, tels que les publications ayant échoué. Consultez la liste des événements enregistrés sur les appareils pour obtenir la liste complète des événements ERROR.
INFO (MQTT uniquement) Capture tous les événements INFO, tels que les connexions et les déconnexions via MQTT. Capture également tous les événements ERROR. Consultez la liste des événements enregistrés sur les appareils pour obtenir la liste complète des événements INFO.
DEBUG Enregistre tous les événements DEBUG, tels que les publications, les abonnements et les pulsations. Ce paramètre est particulièrement utile pour identifier les problèmes liés à des appareils spécifiques. Capture également tous les événements ERROR et INFO. Consultez la liste des événements enregistrés sur les appareils pour obtenir la liste complète des événements DEBUG. Pour en savoir plus, consultez la section Journalisation du débogage de l'appareil.

Liste des événements d'appareils consignés

Les tableaux suivants présentent :

  • Événements d'appareil consignés
  • eventType de l'événement tel qu'il est enregistré dans Cloud Logging.
  • Indique si les réussites, les échecs ou les deux sont enregistrés pour chaque événement.
  • Niveau de journalisation qui doit être défini sur un registre ou un appareil pour consigner l'événement.

Pont MQTT

Événement relatif à l'appareil eventType Réussite Échec
S'authentifier auprès du serveur N/A Non consignéd* Non consigné
Se connecter au serveur CONNECT INFO ERROR
Se déconnecter du serveur DISCONNECT INFO Non consigné
Associer un appareil à une passerelle ATTACH_TO_GATEWAY INFO ERROR
Dissocier un appareil d'une passerelle DETACH_FROM_GATEWAY INFO ERROR
Publier un événement ou un état de télémétrie sur le serveur PUBLISH (sur /devices/{device-id}/events ou /devices/{device-id}/state thème MQTT) DEBUG ERROR
Recevoir une mise à jour de la configuration PUBLISH (sur /devices/{device-id}/config sujet MQTT) DEBUG ERROR
S'abonner au sujet de configuration Pub/Sub SUBSCRIBE DEBUG ERROR
Se désabonner du sujet de configuration Pub/Sub UNSUBSCRIBE DEBUG ERROR
PUBACK reçu du serveur PUBACK DEBUG ERROR
Ping keep-alive envoyé au serveur PINGREQ DEBUG ERROR
Commande envoyée à l'appareil depuis le serveur PUBLISH DEBUG ERROR
Commande PUBACK envoyée au serveur PUBACK DEBUG ERROR

* Si l'authentification MQTT réussit, l'appareil se connecte à Cloud IoT Core et un événement CONNECT est consigné au lieu d'un événement "Authentification sur le serveur".

Pont HTTP

Événement relatif à l'appareil methodName Réussite Échec
S'authentifier auprès du serveur N/A Non consigné** Non consigné
Publier un événement de télémétrie google.cloud.iot.v1.PublishEvent DEBUG ERROR
Définir l'état de l'appareil google.cloud.iot.v1.SetDeviceState DEBUG ERROR
Recevoir une mise à jour de la configuration google.cloud.iot.v1.GetDeviceConfig DEBUG ERROR

** Si l'authentification HTTP aboutit, l'appareil se connecte à Cloud IoT Core et le message de requête approprié (GET si une configuration est reçue, ou POST si un message est publié) est consigné.

Activer, modifier et désactiver la journalisation des appareils

Vous pouvez choisir les types de journaux à communiquer à Cloud Logging lorsque vous créez ou modifiez un registre ou un appareil dans Google Cloud Console ou à l'aide de l'outil gcloud.

Définir les niveaux de journal d'un registre

Vous pouvez activer, modifier ou désactiver les journaux de l'appareil pour un registre à l'aide de Google Cloud Console ou de gcloud. Les paramètres de journal de registre s'appliquent automatiquement à tous les appareils du registre.

Console

Pour créer ou modifier un registre et définir son niveau de journalisation :

  1. Accédez à la page Registres de Google Cloud Console.

    Accéder à la page Registres

  2. En haut de la page, cliquez sur Créer un registre.

    Pour modifier un registre existant, cliquez sur son identifiant sur la page Registres, puis sur Edit Registry (Modifier le registre) en haut de la page.

  3. Sous Stackdriver Logging, sélectionnez un niveau de journalisation.

  4. Cliquez sur Créer (si vous créez un registre) ou sur Mettre à jour (si vous modifiez un registre existant).

gcloud

Pour créer un registre et définir son niveau de journalisation, exécutez la commande gcloud iot registries create avec l'option --log-level :

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}

Pour mettre à jour le niveau de journalisation d'un appareil, exécutez la commande gcloud iot registries update avec l'option --log-level :

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

Définition des niveaux de journalisation pour un appareil

Vous pouvez activer, modifier ou désactiver les journaux d'un appareil à l'aide de Google Cloud Console ou de gcloud. Le niveau de journalisation d'un appareil remplace celui de votre registre.

Console

Pour définir le niveau de journalisation pour un appareil nouveau ou existant, procédez comme suit :

  1. Accédez à la page Registres de Google Cloud Console.

    Accéder à la page Registres

  2. Cliquez sur l'ID du registre de l'appareil.

  3. Dans le menu de registre, à gauche, cliquez sur Appareils.

  4. Pour créer un appareil, cliquez sur Créer un appareil.

    Pour modifier un appareil, cliquez sur son ID sur la page Appareils, puis sur Modifier l'appareil en haut de la page.

  5. Sous Stackdriver Logging, sélectionnez un niveau de journalisation.

  6. Cliquez sur Créer (si vous créez un appareil) ou sur Mettre à jour (si vous modifiez un appareil existant).

gcloud

Pour créer un appareil et définir un niveau de journalisation, exécutez la commande gcloud iot devices create avec l'option --log-level :

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}

Pour mettre à jour le niveau de journalisation d'un appareil, exécutez la commande gcloud iot devices update avec l'option --log-level :

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

Afficher les journaux

Vous pouvez consulter les journaux d'activité des appareils pour votre projet dans l'explorateur de journaux de Google Cloud Console. Sélectionnez device_activity dans le menu du nom du journal.

Pour plus d'informations, consultez Utiliser l'explorateur de journaux.

API

Pour lire vos entrées de journal à l'aide de l'API Logging, consultez la page sur entries.list.

gcloud

Pour lire vos entrées de journaux à l'aide de gcloud, consultez la page consacrée à la lecture des entrées de journaux.

Exportation des journaux de l'appareil...

Vous pouvez exporter les journaux d'appareil de la même manière que vous exportez d'autres types de journaux. Pour plus de détails sur l'exportation des journaux, consultez la page Exporter des journaux.

Les exemples suivants décrivent les raisons pour lesquelles exporter les journaux d'un appareil :

  • Pour conserver les journaux d'appareil pendant une période plus longue ou pour utiliser des fonctionnalités de recherche plus puissantes, vous pouvez exporter des copies des journaux d'appareil vers Cloud Storage, BigQuery ou Pub/Sub. Avec Pub/Sub, vous avez la possibilité d'exporter vos journaux vers d'autres applications, d'autres dépôts, ainsi que vers des organisations tierces.

  • Pour gérer les journaux d'appareil à l'échelle de votre organisation, vous pouvez créer des récepteurs d'exportation agrégés. Ces récepteurs permettent d'exporter les journaux pour un projet spécifique ou pour l'ensemble des projets de l'organisation.

Limites de journalisation des appareils

Les quotas et les limites des journaux d'appareils s'appliquent au niveau du projet. Ils sont mesurés séparément des autres quotas et limites Cloud Logging et ne sont pas comptabilisés. Si les quotas de journaux des appareils sont épuisés, les quotas Cloud Logging des autres services ne sont pas affectés. L'inverse est également vrai.

Les quotas de journaux des appareils sont basés sur deux facteurs :

  • Nombre d'événements d'appareil enregistrés par seconde. Les événements incluent les publications, les connexions, les déconnexions, etc.
  • La taille totale (en octets) d'événements d'appareil enregistrés par minute.

En cas de dépassement de l'un des quotas de journaux de l'appareil, les journaux de l'appareil s'arrêtent temporairement.

Pour obtenir la liste des quotas et des limites des journaux d'appareil, consultez Quotas et limites.

Bonnes pratiques

Journalisation du débogage de l'appareil

Comme indiqué dans la liste des événements d'appareils enregistrés, la définition du niveau de journalisation DEBUG d'un registre ou d'un appareil individuel peut générer de grandes quantités de données de journalisation. Par conséquent, si vous activez la journalisation de débogage pour un registre avec un parc important d'appareils, les enregistrements de journalisation peuvent être supprimés en raison de la rapidité et de la quantité des journaux.

Par exemple, supposons que vous ayez un registre avec 100 000 appareils et que le niveau de journalisation du débogage soit défini pour le registre. Si chaque appareil publie un événement de télémétrie par seconde, seuls 1 000 événements de télémétrie sur 100 000 sont enregistrés chaque seconde. En effet, comme indiqué dans la section Quotas et limites, le nombre maximal d'entrées consignées est de 1 000 par seconde.

Pour de meilleurs résultats, activez la journalisation du débogage pendant une courte période ou sur un petit nombre d'appareils.

Résoudre les erreurs d'écriture de journaux

Lorsque vous activez pour la première fois l'API Google Cloud IoT Core pour un projet, un nouveau compte de service pour le projet se voit automatiquement attribuer un rôle (cloudiot.serviceAgent) qui permet d'écrire des journaux dans Cloud Logging. Si vous supprimez ultérieurement ce rôle par défaut du compte de service du projet concerné, vous risquez de rencontrer des erreurs. Si vous ne parvenez pas à écrire l'activité d'un appareil dans Cloud Logging, procédez comme suit:

  1. Sur la page IAM de Google Cloud Console, vérifiez que le rôle Agent de service Cloud IoT Core apparaît dans la liste des membres du compte de service du projet concerné. (Recherchez le compte de service de projet qui se termine par @gcp-sa-cloudiot.iam.gserviceaccount.com.)

  2. Si le rôle Agent de service Cloud IoT Core n'apparaît pas dans la liste Membres, utilisez gcloud pour ajouter le rôle cloudiot.serviceAgent au compte de service du projet concerné. Ce rôle inclut l'autorisation d'écrire des journaux dans Cloud Logging.

    Exécutez la commande suivante pour ajouter le rôle cloudiot.serviceAgent à votre projet. Pour trouver PROJECT_ID et PROJECT_NUMBER, consultez la section Identifier des projets.

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