Guide pratique pour utiliser des fonctions de débogage définies par l’utilisateur dans Azure Digital Twins

Cet article explique brièvement comment diagnostiquer et déboguer des fonctions définies par l’utilisateur dans in Azure Digital Twins. Il décrit ensuite certains des scénarios plus courants rencontrés lors de leur débogage.

Résoudre les problèmes

Savoir comment diagnostiquer les problèmes au sein d'Azure Digital Twins vous permet d'analyser efficacement les problèmes, d'en identifier les causes et d’y apporter des solutions appropriées.

Une variété d'outils de journalisation, d'analyse et de diagnostic sont fournis à cette fin.

Activer la journalisation pour votre instance

Azure Digital Twins prend en charge de solides fonctionnalités de journalisation, de supervision et d’analytique. Les développeurs de solutions peuvent utiliser les journaux Azure Monitor, les journaux de diagnostic, les journaux d’activité et d’autres services pour prendre en charge les besoins de supervision complexes d’une application IoT. Vous pouvez combiner les options de journalisation afin d’interroger ou d’afficher des enregistrements entre plusieurs services et de fournir une couverture de journalisation précise pour de nombreux services.

• Pour la configuration de journalisation spécifique à Azure Digital Twins, consultez Guide pratique pour configurer la supervision et la journalisation.
• Consultez la vue d’ensemble Azure Monitor pour en savoir plus sur les puissants paramètres de journalisation activés via Azure Monitor.
• Consultez l’article Collecter et consommer des données de journal à partir de vos ressources Azure pour configurer les paramètres du journal de diagnostic dans Azure Digital Twins via les Portail Azure, Azure CLI ou PowerShell.

Une fois la configuration terminée, vous pourrez sélectionner toutes les catégories de journaux, de métriques, et utiliser les puissants espaces de travail Log Analytics d'Azure Monitor pour soutenir vos efforts de débogage.

Tracer les données de télémétrie des capteurs

Pour suivre la télémétrie du capteur, vérifiez que les paramètres de diagnostic sont activés pour votre instance Azure Digital Twins. Ensuite, assurez-vous que toutes les catégories de journaux souhaitées sont sélectionnées. Enfin, vérifiez que les journaux d’activité souhaités sont envoyés aux journaux Azure Monitor.

Pour faire correspondre un message de télémétrie de capteur à ses journaux d’activité respectifs, vous pouvez spécifier un ID de corrélation sur les données d’événement envoyées. Pour ce faire, définissez la propriété x-ms-client-request-id sur un GUID.

Après avoir envoyé les données de télémétrie, ouvrez Azure Monitor Log Analytics pour rechercher les journaux à l’aide de l’ID de corrélation défini :

AzureDiagnostics
| where CorrelationId == 'YOUR_CORRELATION_IDENTIFIER'

Pour lire tous les journaux de télémétrie récents, exécutez la requête :

AzureDiagnostics
| order by CorrelationId desc

Si vous activez la journalisation pour votre fonction définie par l’utilisateur, les journaux d’activité correspondants apparaissent dans votre instance Log Analytics avec la catégorie UserDefinedFunction. Pour les récupérer, entrez la condition de requête suivante dans Log Analytics :

AzureDiagnostics
| where Category == 'UserDefinedFunction'

Pour plus d’informations sur les opérations de requête puissantes, lisez Prise en main des requêtes.

Identifier les problèmes courants

Le diagnostic et l’identification des problèmes courants sont importants pour résoudre les problèmes liés à votre solution. Plusieurs problèmes couramment rencontrés durant le développement de fonctions définies par l’utilisateur sont récapitulés dans les sous-sections suivantes.

Dans les exemples ci-dessous, YOUR_MANAGEMENT_API_URL fait référence à l’URI des API Digital Twins :

https://YOUR_INSTANCE_NAME.YOUR_LOCATION.azuresmartspaces.net/management/api/v1.0

Vérifier si une vérification a été créée

À défaut d’attribution de rôle créée dans l’API de gestion, la fonction définie par l’utilisateur ne dispose pas de l’accès nécessaire pour effectuer des actions telles que l’envoi de notifications, la récupération de métadonnées et la définition de valeurs calculées au sein de la topologie.

Vérifiez s’il existe une attribution de rôle pour votre fonction définie par l’utilisateur par le biais de votre API de gestion :

GET YOUR_MANAGEMENT_API_URL/roleassignments?path=/&traverse=Down&objectId=YOUR_USER_DEFINED_FUNCTION_ID

Consultez cet article sur la façon de créer une attribution de rôle pour votre fonction définie par l’utilisateur si aucune attribution de rôle n’existe.

Vérifier si le système de correspondance (« matcher ») fonctionne pour les données de télémétrie d’un capteur

En utilisant l’appel suivant de l’API de gestion de vos instances Azure Digital Twins, vous pouvez déterminer si un matcher donné s’applique pour le capteur donné.

GET YOUR_MANAGEMENT_API_URL/matchers/YOUR_MATCHER_IDENTIFIER/evaluate/YOUR_SENSOR_IDENTIFIER?enableLogging=true

Réponse :

{
    "success": true,
    "logs": [
        "$.dataType: \"Motion\" Equals \"Motion\" => True"
    ]
}

Vérifier ce qu’un capteur déclenche

En utilisant l’appel suivant de l’API de gestion de vos instances Azure Digital Twins, vous pouvez déterminer les identificateurs de vos fonctions définies par l’utilisateur qui sont déclenchées par les données de télémétrie entrantes du capteur donné :

GET YOUR_MANAGEMENT_API_URL/sensors/YOUR_SENSOR_IDENTIFIER/matchers?includes=UserDefinedFunctions

Réponse :

[
    {
        "id": "48a64768-797e-4832-86dd-de625f5f3fd9",
        "name": "MotionMatcher",
        "spaceId": "2117b3e1-b6ce-42c1-9b97-0158bef59eb7",
        "conditions": [
            {
                "id": "024a067a-414f-415b-8424-7df61392541e",
                "target": "Sensor",
                "path": "$.dataType",
                "value": "\"Motion\"",
                "comparison": "Equals"
            }
        ],
        "userDefinedFunctions": [
            {
                "id": "373d03c5-d567-4e24-a7dc-f993460120fc",
                "spaceId": "2117b3e1-b6ce-42c1-9b97-0158bef59eb7",
                "name": "Motion User-Defined Function",
                "disabled": false
            }
        ]
    }
]

Problème de réception des notifications

Si vous ne recevez aucune notification de la fonction définie par l’utilisateur déclenchée, vérifiez que votre paramètre de type d’objet de topologie correspond au type d’identificateur utilisé.

Incorrect Exemple:

var customNotification = {
    Message: 'Custom notification that will not work'
};

sendNotification(telemetry.SensorId, "Space", JSON.stringify(customNotification));

Dans ce scénario, l’identificateur utilisé fait référence à un capteur alors que le type d’objet de topologie spécifié est Space.

Correcte Exemple:

var customNotification = {
    Message: 'Custom notification that will work'
};

sendNotification(telemetry.SensorId, "Sensor", JSON.stringify(customNotification));

Le moyen le plus simple d’éviter ce problème consiste à utiliser la méthode Notify sur l’objet des métadonnées.

Exemple :

function process(telemetry, executionContext) {
    var sensorMetadata = getSensorMetadata(telemetry.SensorId);

    var customNotification = {
        Message: 'Custom notification'
    };

    // Short-hand for above methods where object type is known from metadata.
    sensorMetadata.Notify(JSON.stringify(customNotification));
}

Exceptions de diagnostics courantes

Si vous activez les paramètres de diagnostic, vous pouvez rencontrer ces exceptions courantes :

1. Limitation : si votre fonction définie par l’utilisateur dépasse les limites de taux d’exécution décrites dans l’article Limites de service, elle fait l’objet d’une limitation. Aucune autre opération n’est exécutée correctement jusqu’à l’expiration de la limitation.

2. Données introuvables : si votre fonction définie par l’utilisateur tente d’accéder à des métadonnées inexistantes, l’opération échoue.

3. Non autorisé : si votre fonction définie par l’utilisateur n’a pas d’attribution de rôle définie ou ne dispose pas d’autorisations suffisantes pour accéder à certaines métadonnées à partir de la topologie, l’opération échoue.

Étapes suivantes

• Découvrez comment activer la supervision et les journaux d’activité dans Azure Digital Twins.

• Lisez l’article Vue d’ensemble du journal d’activité Azure pour découvrir d’autres options de journalisation Azure.