Format JSON de la requête de génération de la configuration des métriques

Ce guide décrit en détail le format de requête JSON pour le point de terminaison /api/v1/generate_metrics_config de l'outil Metrics Configuration Generator (MCG). Ce format vous permet de définir une campagne de télémétrie (en spécifiant la collecte de données, le traitement sur l'appareil et la génération de rapports) dans une structure lisible par l'humain.

L'outil MCG valide cet objet JSON en recherchant des problèmes tels que des incompatibilités de type, des dépendances circulaires ou des références non définies, puis le compile en un message de tampon de protocole (protobuf) MetricsConfig. Ce message MetricsConfig est le format binaire que le service de télémétrie sur l'appareil exécute pour diffuser la campagne.

Conditions préalables : vous devez connaître les schémas JSON, protobuf et les structures de données de base. Pour obtenir une présentation conceptuelle, consultez Concepts de configuration des métriques.

Comment rédiger une description de configuration

Pour concevoir une campagne de collecte de métriques, suivez ce flux logique :

1. Spécifiez les sources de données : définissez l'origine de vos données.
2. Définir la logique et le traitement : configurez des règles pour déterminer quand collecter les données et comment les traiter.
3. Créer une sortie : regroupez les données traitées dans un message final.
4. Champs de premier niveau : ajoutez des champs de premier niveau tels que UUID, signal definitions et lifecycle control.

Spécifier des sources de données

La télémétrie permet de collecter des données à partir des services SDV (via le middleware SDV) et des éditeurs basés sur le registre d'éditeurs configurables.

• Services SDV (basés sur Pub/Sub) : les données sont disponibles à partir des canaux Pub/Sub définis dans VSIDL.

• Services SDV (basés sur RPC) : les données sont disponibles si le service expose les RPC CreateSubscription ou GetLatestMessage.

• Éditeurs configurables basés sur le Registre des éditeurs : les données sont disponibles si l'application s'enregistre à l'aide de l'interface Android Binder IConfigurablePublisherRegistry ou de la bibliothèque Registre des éditeurs configurables du SDK Telemetry.

Pour utiliser des données dans SDV, définissez une source de données (concept) et ajoutez-la au tableau data_sources.

Toutes les options ne sont pas disponibles pour tous les types de sources de données. Pour en savoir plus, consultez le guide d'intégration des sources de données.

Format de source_identifier

Le service de télémétrie accepte plusieurs formats d'identifiants de source. Pour obtenir une présentation, consultez Définition de la source de données dans les configurations de métriques.

MCG déduit le type de message protobuf à partir de source_identifier uniquement s'il utilise le format de nom de type d'unité. Si vous utilisez un FQIN ou un nom personnalisé (à partir du Registre des éditeurs configurables), MCG ne peut pas déduire le type. Dans ce cas, vous devez fournir data_source_message_types. Si le type ne figure pas dans votre catalogue, vous devez également fournir sa définition dans descriptor_protos.

{
  "name": "SpeedSource",
  "source_identifier": "mcg.test.subpkg.speed_msg",
  "connection_type": "SUBSCRIPTION",
  "sub_sampling_interval_ms": 1000 // Limit updates to 1 per second
}

Définir la logique et le traitement

La logique est gérée par deux composants qui fonctionnent ensemble : les déclencheurs (concept) définissent quand quelque chose se produit. Les agrégateurs (concept) définissent la façon dont les données sont traitées en fonction de ces déclencheurs. Étant donné que les expressions (concept) sont essentielles aux conditions de déclenchement et à la logique d'agrégation, cette section décrit d'abord comment les écrire.

Expressions

Les expressions vous permettent de définir des calculs et des conditions à l'aide d'une syntaxe lisible. MCG compile ces chaînes dans un format exécutable optimisé pour l'évaluation sur l'appareil.

Les expressions peuvent exprimer des calculs arithmétiques, des conditions logiques et des comparaisons de données. Pour obtenir la syntaxe complète, y compris les opérateurs et les fonctions, consultez Syntaxe des expressions.

Fraîcheur des données : lorsqu'une expression accède à une source de données, le comportement de récupération dépend du type de connexion :

• SUBSCRIPTION : utilise le message reçu en dernier mis en cache par le service de télémétrie. (Remarque : Si sub_sampling_interval_ms est défini, cela peut différer du dernier message publié.)
• ON_DEMAND : déclenche un appel immédiat pour récupérer le nouveau message du service.

Contraintes de type

• Tableaux : l'accès direct à l'index du tableau (par exemple, my_data_source.my_array[0]) n'est pas accepté.
• Sûreté du typage : assurez-vous de comparer des types compatibles (par exemple, ne comparez pas un champ de chaîne à une liste d'entiers).

Déclencheurs : définissez le moment où les actions se produisent

Les déclencheurs définissent le moment où les actions s'exécutent : évaluation d'un agrégateur, génération d'un rapport ou contrôle du cycle de vie de la collecte. Ajoutez tous les déclencheurs définis au tableau triggers de premier niveau.

Déclencheur de données

Se déclenche lorsqu'une source de données SUBSCRIPTION fournit un nouveau message (concept).

{
  "name": "OnNewSpeed",
  "data": {
    "source_name": "SpeedSource" // Reference to the defined data source
  }
}

Déclencheur périodique

Déclenchement à intervalles réguliers (concept).

{
  "name": "EveryMinute",
  "periodic": {
    "period_ms": 60000 // 60,000 ms = 60 seconds
  }
}

Déclencheur conditionnel

Se déclenche en fonction de l'évaluation d'une expression (concept). Il nécessite un ou plusieurs déclencheurs parents pour démarrer son évaluation. Il s'agit souvent d'un déclencheur de données pour les sources de données ou les agrégateurs de l'expression, ou d'un déclencheur périodique pour interroger les données.

Types de conditions

Le dictionnaire condition_type doit contenir exactement l'un des types de conditions disponibles en tant que clé. Pour en savoir plus, consultez Déclencheurs conditionnels.

Options de périphérie

Les objets rising_options et falling_options comportent les champs suivants. Si une transition correspondante est fournie, elle doit respecter la durée requise. Les transitions sans options spécifiées se déclenchent immédiatement.

{
  "name": "SpeedingFor5Seconds",
  "conditional": {
    "triggers": ["OnNewSpeed"],
    "expression": "SpeedSource.speed > 27.7",
    "condition_type": {
      "rising_edge": {
        "rising_options": {
          "min_duration_ms": 5000 // Condition must hold for 5s in new state
        }
      }
    }
  }
}

Agrégateurs : définissez la façon dont les données sont traitées.

Utilisez un agrégateur pour le traitement des données intermédiaires avec état (concept). Définissez un agrégateur et ajoutez-le au tableau aggregators.

Un agrégateur transforme les données et les met à la disposition d'autres agrégateurs et rapports.

Générateur de message

Un objet message_builder définit la structure du message de sortie et la logique d'agrégation utilisée pour calculer ses champs. Elle est utilisée dans les agrégateurs et les configurations de rapports.

{
  "name": "SpeedAggregator",
  "trigger_names": ["OnNewSpeed"], // Update aggregation on new speed data
  "reset_on_get": true, // Reset stats after they are read by the report configuration
  "message_builder": {
    "field_assignments": [
      {
        "field_name": "average_speed",
        "aggregation": {
          "@type": "avg",
          "expression": "SpeedSource.speed"
        }
      },
      {
        "field_name": "speed_reading_count",
        "aggregation": {
          "@type": "count" // Counts triggers (that is, processed speed readings) since last reset
        }
      },
      {
        "field_name": "speed_history_last5",
        "aggregation": {
          "@type": "vector",
          "expression": "SpeedSource.speed",
          "max_length": 5 // Keep last 5 readings
        }
      }
    ]
  }
}

Créer une sortie

Pour définir le résultat final de votre campagne de télémétrie, ajoutez des objets au tableau report_configs (concept). Ces configurations déterminent la façon dont les données traitées sont regroupées et le moment où elles sont générées. Vous pouvez définir plusieurs configurations de rapports dans une même configuration de métriques pour réutiliser des composants.

Vous contrôlez la génération de rapports à l'aide du champ trigger_names. De plus, vous pouvez utiliser report_initial pour générer un rapport immédiatement lorsque la configuration est activée, et report_incomplete pour générer un rapport final lorsque la collecte de données est interrompue.

Remarque : Pour associer le traitement au résultat, utilisez le type d'agrégation none (@type: "none") pour lire les valeurs précalculées d'un agrégateur. Étant donné que les rapports sont généralement des instantanés sans état, cela permet de conserver une logique avec état complexe dans les agrégateurs et de réserver les rapports à la mise en forme.

{
  "name": "MinuteReport",
  "trigger_names": ["EveryMinute"], // Generate report every minute
  "message_builder": {
    "field_assignments": [
      {
        "field_name": "average_speed",
        "aggregation": {
          "@type": "none", // Read the value directly from the aggregator
          "expression": "SpeedAggregator.average_speed"
        }
      },
      {
        "field_name": "reading_count",
        "aggregation": {
          "@type": "none",
          "expression": "SpeedAggregator.speed_reading_count"
        }
      }
    ]
  }
}

Champs de premier niveau

En plus des tableaux data_sources, aggregators, triggers et report_configs, la description d'une configuration de métriques nécessite une référence au catalogue de signaux. Vous pouvez également inclure des champs facultatifs pour attribuer un UUID spécifique et gérer le cycle de vie de la collection.

Définir l'UUID

Chaque MetricsConfig nécessite un identifiant unique universel (UUID). Si vous fournissez un existing_uuid, MCG l'utilise. Sinon, il en crée un aléatoire. Pour assurer la cohérence entre les déploiements et les outils, spécifiez un existing_uuid.

La chaîne doit être un UUID valide avec des traits d'union et ne contenir que des lettres minuscules.

"existing_uuid": "a1a2a3a4-b1b2-c1c2-d1d2-d3d4d5d6d7d8",

Définitions des signaux

Pour valider les noms et les types de signaux, MCG a besoin d'accéder à un catalogue de signaux de véhicule. Il s'agit d'un protobuf FileDescriptorSet contenant vos définitions VSIDL .proto (empaquetées et importées dans MCG). Pour savoir comment créer et importer un catalogue, consultez Catalogues de signaux de véhicules.

Spécifiez la version du catalogue dans le champ vs_version de l'objet JSON :

"vs_version": "v1.0",

Définir des déclencheurs de cycle de vie

Dans le contexte d'une campagne de télémétrie, le cycle de vie d'un MetricsConfig détermine le moment où les données sont réellement enregistrées. Pendant que le système de gestion des campagnes déploie et active la configuration sur l'appareil, vous pouvez utiliser des déclencheurs de cycle de vie pour contrôler précisément quand les données sont collectées lors de ce déploiement.

Cela vous permet d'aligner la collecte de données sur les habitudes d'utilisation du véhicule, comme un "trajet" (IgnitionOn à IgnitionOff) ou une "session de recharge", sans avoir à désactiver la configuration.

• Contrôle de la session (démarrer/mettre en veille) : utilisez start_trigger_name et stop_trigger_name pour contrôler le moment où la collecte a lieu. Par exemple, pour collecter des données uniquement lorsque le véhicule est en mouvement, utilisez IgnitionOn comme déclencheur de début et IgnitionOff comme déclencheur de fin. La configuration reste active sur l'appareil, mais est effectivement "mise en pause" (la collecte et le traitement des données s'arrêtent) lorsque le déclencheur d'arrêt se déclenche, et ne reprend que lorsque le déclencheur de démarrage se déclenche à nouveau.

  Important : Cette action ne fait que suspendre la collecte. Elle ne définit pas de fenêtres logiques ni de jeux de données distincts, et n'a aucun autre effet secondaire. Les valeurs d'agrégateur ne sont pas réinitialisées lorsque la collecte est suspendue ou reprise.

• Détection unique (fin) : utilisez deactivate_trigger_name si la configuration ne doit s'exécuter qu'une seule fois (par exemple, pour détecter la première occurrence d'un code d'erreur spécifique), puis se désactiver définitivement sur cet appareil, même si la campagne est techniquement toujours active.

Si vous ne spécifiez aucun déclencheur de cycle de vie, la collecte de données commence immédiatement lorsque la configuration est activée par la campagne et se poursuit en continu jusqu'à la fin de la campagne.

Avancé : Définitions proto personnalisées

Dans deux cas principaux, vs_version seul ne suffit pas pour que MCG comprenne tous les types de messages dans la description d'une configuration de métriques :

1. Échec de l'inférence de type : comme expliqué dans le format source_identifier, MCG ne peut pas inférer le type lorsque source_identifier utilise un FQIN ou un nom personnalisé.
2. Messages personnalisés : la description de la configuration des métriques utilise des messages protobuf introuvables dans le catalogue VSIDL spécifié dans vs_version. Cela se produit lorsque vous définissez message_type dans un message_builder pour un format de rapport personnalisé.

Dans ce cas, utilisez data_source_message_types pour aider MCG à inférer les types et descriptor_protos pour fournir les définitions de message.

data_source_message_types

Mappez la chaîne source_identifier à son type de message protobuf complet. La clé dans data_source_message_types doit correspondre à la valeur source_identifier de l'entrée data_sources :

"data_source_message_types": {
  "MyCustomSpeedService": "com.sdv.example.SampleMessage"
}

descriptor_protos

Fournissez des définitions pour tous les types de messages utilisés dans data_source_message_types ou message_builder qui ne figurent pas dans vs_version configuré.

Transmettez un descriptorpb.FileDescriptorSet encodé en base64 dans le tableau descriptor_protos. Générez-le à partir des fichiers .proto à l'aide du compilateur Protobuf protoc.

"descriptor_protos": [
  "Cu8BCiZtY2cvdGVzdGRhdGEvbWF4YXZnY3..." // Base64 string
]

{
  "existing_uuid": "a1a2a3a4-b1b2-c1c2-d1d2-d3d4d5d6d7d8", // Unique identifier for the configuration
  "vs_version": "example_version", // Version of the VSIDL catalog to use
  "data_sources": [
    {
      "name": "SpeedSource",
      "source_identifier": "mcg.test.subpkg.speed_msg",
      "connection_type": "SUBSCRIPTION",
      "sub_sampling_interval_ms": 1000
    }
  ],
  "aggregators": [
    {
      "name": "SpeedAggregator",
      "trigger_names": ["OnNewSpeed"],
      "reset_on_get": true,
      "message_builder": {
        "field_assignments": [
          {
            "field_name": "average_speed",
            "aggregation": {
              "@type": "avg",
              "expression": "SpeedSource.speed"
            }
          },
          {
            "field_name": "speed_reading_count",
            "aggregation": { "@type": "count" }
          },
          {
            "field_name": "speed_history_last5",
            "aggregation": {
              "@type": "vector",
              "expression": "SpeedSource.speed",
              "max_length": 5
            }
          }
        ]
      }
    }
  ],
  "triggers": [
    {
      "name": "OnNewSpeed",
      "data": { "source_name": "SpeedSource" }
    },
    {
      "name": "EveryMinute",
      "periodic": { "period_ms": 60000 }
    }
  ],
  "report_configs": [
    {
      "name": "MinuteReport",
      "trigger_names": ["EveryMinute"],
      "message_builder": {
        "field_assignments": [
          {
            "field_name": "average_speed",
            "aggregation": {
              "@type": "none",
              "expression": "SpeedAggregator.average_speed"
            }
          },
          {
            "field_name": "reading_count",
            "aggregation": {
              "@type": "none",
              "expression": "SpeedAggregator.speed_reading_count"
            }
          }
        ]
      }
    }
  ]
}

Modèle de référence

Pour la définition de l'API, consultez la documentation de référence de l'API MCG.

Les sections suivantes fournissent une référence complète de la description d'une configuration de métriques. Utilisez-le comme guide pour créer votre propre description d'une configuration de métriques.

Champs de premier niveau

{
  "existing_uuid": "00000000-0000-0000-0000-000000000000", // Optional
  "vs_version": "example_version", // Optional
  "descriptor_protos": ["..."], // Optional. Base64 encoded FileDescriptorSet
  "data_source_message_types": {
    "ExampleServiceName": "com.example.ProtoMessage"
  }, // Optional
  "start_trigger_name": "DataTriggerExample", // Optional
  "stop_trigger_name": "ConditionalTriggerExample", // Optional
  "deactivate_trigger_name": "PeriodicTriggerExample" // Optional
}

Entrée : sources de données et agrégateurs

{
  "data_sources": [
    {
      "name": "SubscriptionExample",
      "source_identifier": "com.example.sdv.ExampleMessage|example-unit",
      "connection_type": "SUBSCRIPTION", // Options: SUBSCRIPTION (default), ON_DEMAND
      "sub_sampling_interval_ms": 100, // Optional
      "fetch_last_message": false // Optional. Default: false
    },
    {
      "name": "RegistryExample",
      // Configurable Publisher Registry-based publisher (matches data_source_message_types)
      "source_identifier": "ExampleServiceName",
      "connection_type": "SUBSCRIPTION"
    },
    {
      "name": "GetterExample",
      "source_identifier": "com.example.sdv.ExampleConfig|example-unit",
      "connection_type": "ON_DEMAND",
      "configuration": {
        "type_url": "type.googleapis.com/example.Config",
        "value_json": {} // Or value_textproto, value (base64)
      }
    }
  ],
  "aggregators": [
    {
      "name": "AggregatorExample",
      "trigger_names": ["DataTriggerExample"],
      "reset_on_get": false, // Optional. Default: false. If true, resets state after it's read
      "message_builder": {
        "message_type": "com.example.AggregatedMessage", // Optional
        "field_assignments": [
          {
            "field_name": "avg_example",
            "aggregation": {
              // Options: avg, count, min, max, sum, stddev, delta, vector, none
              "@type": "avg",
              "expression": "SubscriptionExample.value"
            }
          },
          {
            "field_name": "count_example",
            "aggregation": {
              "@type": "count" // Counts number of evaluations. No expression needed
            }
          },
          {
            "field_name": "vector_example",
            "aggregation": {
              "@type": "vector",
              "expression": "SubscriptionExample.value",
              "max_length": 10 // Optional. If set, creates a ring buffer
            }
          }
        ]
      }
    }
  ]
}

Logique et traitement : déclencheurs

{
  "triggers": [
    {
      "name": "PeriodicTriggerExample",
      "periodic": { "period_ms": 1000 }
    },
    {
      "name": "DataTriggerExample",
      "data": { "source_name": "SubscriptionExample" }
    },
    {
      "name": "ConditionalTriggerExample",
      "conditional": {
        "triggers": ["PeriodicTriggerExample"],
        "expression": "SubscriptionExample.value > 0",
        "condition_type": {
          // Options: is_true, is_false, rising_edge, falling_edge, all_changes
          "rising_edge": {
            "rising_options": { "min_duration_ms": 0, "require_exact": false }
          }
        }
      }
    }
  ]
}

Sortie : configurations de rapport

{
  "report_configs": [
    {
      "name": "ReportExample",
      "trigger_names": ["PeriodicTriggerExample"],
      "report_incomplete": false, // Optional. Default: false
      "report_initial": false, // Optional. Default: false
      "message_builder": {
        "message_type": "com.example.ReportMessage", // Optional. Must be defined in VSIDL catalog or descriptor_protos. Message type will be inferred if not provided
        "field_assignments": [
          {
            "field_name": "avg_example",
            "aggregation": {
              "@type": "none", // Passthrough since aggregation is done in AggregatorExample
              "expression": "AggregatorExample.avg_example"
            }
          }
        ]
      }
    }
  ]
}

Syntaxe des expressions