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/v2/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 des 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 incohérences de type, des dépendances circulaires ou des références non définies, puis le compile dans 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.

Prérequis : 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écifier des sources de données : définissez la provenance 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 : regrouper les données traitées dans un message final.
4. Champs de premier niveau : ajoutez des champs de premier niveau tels que UUID, définitions de signaux et contrôle du cycle de vie.

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 configurable.

• 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 des RPC CreateSubscription ou GetLatestMessage.

• Éditeurs basés sur le registre d'éditeurs configurable : les données sont disponibles si l'application s'enregistre à l'aide de l'interface Android Binder IConfigurablePublisherRegistry ou de la bibliothèque de registre d'éditeurs configurable 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.

Certaines 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 sources. Pour en savoir plus, 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é (du registre d'éditeurs configurable), 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 un événement se produit. Les agrégateurs (concept) définissent la manière dont les données sont traitées en fonction de ces déclencheurs. Étant donné que les expressions (concept) sont essentielles pour les 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 par l'humain. 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 dernier message reçu mis en cache par le service de télémétrie. (Remarque : Si sub_sampling_interval_ms est défini, il peut être différent du tout 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 de tableau (par exemple, my_data_source.my_array[0]) n'est pas accepté.
• Sûreté du typage : veillez à comparer des types compatibles (par exemple, ne comparez pas un champ de chaîne à une liste d'entiers).

Déclencheurs : définissent quand les actions se produisent

Les déclencheurs définissent le moment où les actions sont exécutées : é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

Se déclenche à 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. S'il est fourni, la transition correspondante doit respecter l'exigence de durée. 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. Il est utilisé à la fois dans les agrégateurs et les configurations de rapport.

{
  "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 manière dont les données traitées sont empaquetées et le moment où elles sont générées. Vous pouvez définir plusieurs configurations de rapport dans une configuration de métriques pour réutiliser des composants.

Vous contrôlez la génération de rapports à l'aide du champ trigger_names. Vous pouvez également 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 connecter le traitement à la sortie, utilisez le type d'agrégation none (@type: "none") pour lire les valeurs précalculées à partir d'un agrégateur. Étant donné que les rapports sont généralement des instantanés sans état, cela permet de conserver une logique complexe avec état dans les agrégateurs et de réserver les rapports pour 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 de manière 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, contenant uniquement des lettres minuscules.

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

Définitions des signaux

Pour valider les noms et les types de signaux, MCG doit 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 en savoir plus sur la création et l'importation d'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 quand 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 au cours de ce déploiement.

Vous pouvez ainsi aligner la collecte de données sur les modèles d'utilisation du véhicule, comme un "trajet" (IgnitionOn à IgnitionOff) ou une "session de recharge", sans avoir à désactiver la configuration.

• Contrôle de session (Démarrer/Suspendre) : 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 roule, utilisez IgnitionOn comme déclencheur de démarrage et IgnitionOff comme déclencheur d'arrêt. La configuration reste active sur l'appareil, mais elle est effectivement "mise en pause" (elle arrête de collecter et de traiter les données) lorsque le déclencheur d'arrêt se déclenche. Elle ne reprend que lorsque le déclencheur de démarrage se déclenche à nouveau.

  Important : Cela ne fait que suspendre la collecte. Il ne définit pas de fenêtres logiques, d'ensembles de données distincts ni d'autres effets secondaires. Les valeurs de l'agrégateur ne sont pas réinitialisées lorsque la collecte est suspendue ou reprise.

• Détection ponctuelle (Terminer) : 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 Format source_identifier, MCG ne peut pas déduire 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 qui ne figurent pas 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 à déduire les types et descriptor_protos pour fournir des 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 le 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 obtenir la définition de l'API, consultez la documentation de référence de l'API MCG.

Les sections suivantes fournissent une documentation de référence complète sur 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": "1cbec8e6-46f5-4649-9fa2-09f81bc93f8b", // 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