Formato JSON della richiesta di generazione della configurazione delle metriche

Questa guida descrive in dettaglio il formato della richiesta JSON per l'endpoint /api/v1/generate_metrics_config dello strumento Generatore di configurazione delle metriche (MCG). Questo formato ti consente di definire una campagna di telemetria, specificando la raccolta dei dati, l'elaborazione sul dispositivo e la generazione di report, in una struttura leggibile.

Lo strumento MCG convalida questo oggetto JSON, verificando la presenza di problemi come mancata corrispondenza dei tipi, dipendenze circolari o riferimenti non definiti, quindi lo compila in un messaggio di buffer di protocollo (protobuf) MetricsConfig. Questo messaggio MetricsConfig è il formato binario che il servizio di telemetria sul dispositivo esegue per pubblicare la campagna.

Prerequisiti: devi avere familiarità con gli schemi JSON, protobuf e le strutture di dati di base. Per una panoramica concettuale, consulta Concetti relativi alla configurazione delle metriche.

Come scrivere una descrizione della configurazione

Per progettare una campagna di raccolta delle metriche, segui questo flusso logico:

1. Specifica le origini dati: definisci la provenienza dei dati.
2. Definisci la logica e l'elaborazione: configura le regole per quando raccogliere i dati e come elaborarli.
3. Crea output: raggruppa i dati elaborati in un messaggio finale.
4. Campi di primo livello: aggiungi campi di primo livello come UUID, definizioni degli indicatori e controllo del ciclo di vita.

Specificare le origini dati

La telemetria supporta la raccolta di dati dai servizi SDV (tramite il middleware SDV) e dagli editori basati sul registro degli editori configurabile.

• Servizi SDV (basati su Pub/Sub): i dati sono disponibili dai canali Pub/Sub definiti in VSIDL.

• Servizi SDV (basati su RPC): i dati sono disponibili se il servizio espone RPC CreateSubscription o GetLatestMessage.

• Publisher basati sul registro dei publisher configurabile:i dati sono disponibili se l'applicazione si registra utilizzando l'interfaccia Binder di Android o la libreria del registro dei publisher configurabile dell'SDK Telemetry.IConfigurablePublisherRegistry

Per utilizzare i dati in SDV, definisci un'origine dati (concetto) e aggiungila all'array data_sources.

Non tutte le opzioni sono disponibili per tutti i tipi di origini dati. Per informazioni dettagliate, consulta la guida all'integrazione delle origini dati.

Formato di source_identifier

Il servizio di telemetria accetta più formati di identificatori di origine. Per una panoramica, consulta Definizione dell'origine dati nelle configurazioni delle metriche.

MCG deduce il tipo di messaggio protobuf da source_identifier solo se utilizza il formato del nome del tipo di unità. Se utilizzi FQIN o un nome personalizzato (dal Configurable Publisher Registry), MCG non può dedurre il tipo. In questi casi, devi fornire data_source_message_types. Se il tipo non è presente nel tuo catalogo, devi fornire anche la sua definizione in 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
}

Definisci la logica e l'elaborazione

La logica viene gestita da due componenti che operano in sinergia: gli attivatori (concetto) definiscono quando si verifica un evento, mentre gli aggregatori (concetto) definiscono come vengono elaborati i dati in base a questi attivatori. Poiché le espressioni (concetto) sono fondamentali per le condizioni di attivazione e la logica di aggregazione, questa sezione descrive innanzitutto come scriverle.

Espressioni

Le espressioni ti consentono di definire calcoli e condizioni utilizzando una sintassi leggibile. MCG compila queste stringhe in un formato eseguibile ottimizzato per la valutazione sul dispositivo.

Le espressioni possono esprimere calcoli aritmetici, condizioni logiche e confronti tra dati. Per la sintassi completa, inclusi operatori e funzioni, consulta Sintassi delle espressioni.

Aggiornamento dei dati:quando un'espressione accede a un'origine dati, il comportamento di recupero dipende dal tipo di connessione:

• SUBSCRIPTION: utilizza l'ultimo messaggio ricevuto memorizzato nella cache dal servizio di telemetria. (Nota: se è impostato sub_sampling_interval_ms, questo valore potrebbe differire dall'ultimo messaggio pubblicato in assoluto.)
• ON_DEMAND: attiva una chiamata immediata per recuperare il messaggio aggiornato dal servizio.

Vincoli di tipo

• Array:l'accesso diretto all'indice dell'array (ad esempio, my_data_source.my_array[0]) non è supportato.
• Sicurezza dei tipi:assicurati di confrontare tipi compatibili (ad esempio, non confrontare un campo stringa con un elenco di numeri interi).

Trigger: definisci quando si verificano le azioni

Gli attivatori definiscono quando vengono eseguite le azioni: valutando un aggregatore, generando un report o controllando il ciclo di vita della raccolta. Aggiungi tutti i trigger definiti all'array triggers di primo livello.

Trigger dati

Si attiva quando un'origine dati SUBSCRIPTION fornisce un nuovo messaggio (concetto).

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

Trigger periodico

Viene attivato a intervalli regolari (concetto).

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

Trigger condizionale

Viene attivato in base alla valutazione di un'espressione (concetto). Richiede uno o più trigger genitore per iniziare la valutazione. Spesso si tratta di un trigger di dati per le origini dati o gli aggregatori nell'espressione oppure di un trigger periodico per eseguire il polling dei dati.

Tipi di condizione

Il dizionario condition_type deve contenere esattamente uno dei tipi di condizione disponibili come chiave. Per saperne di più, consulta Trigger condizionali.

Opzioni per il bordo

Gli oggetti rising_options e falling_options hanno i seguenti campi. Se fornita, la transizione corrispondente deve soddisfare il requisito di durata. Le transizioni senza opzioni specificate vengono attivate immediatamente.

{
  "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
        }
      }
    }
  }
}

Aggregatori: definisci come vengono trattati i dati

Utilizza un aggregatore per l'elaborazione dei dati intermedi con stato (concetto). Definisci un aggregatore e aggiungilo all'array aggregators.

Un aggregatore trasforma i dati e li rende disponibili ad altri aggregatori e report.

Generatore di messaggi

Un oggetto message_builder definisce la struttura del messaggio di output e la logica di aggregazione utilizzata per calcolare i relativi campi. Viene utilizzato sia negli aggregatori che nelle configurazioni dei report.

{
  "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
        }
      }
    ]
  }
}

Crea output

Per definire l'output finale della campagna di telemetria, aggiungi oggetti all'array report_configs (concetto). Queste configurazioni determinano il modo in cui i dati elaborati vengono pacchettizzati e quando vengono generati. Puoi definire più configurazioni dei report in una configurazione delle metriche per riutilizzare i componenti.

Controlli la generazione dei report utilizzando il campo trigger_names. Inoltre, puoi utilizzare report_initial per generare un report immediatamente quando la configurazione si attiva e report_incomplete per generare un report finale quando la raccolta dei dati viene interrotta.

Nota:per collegare l'elaborazione all'output, utilizza il tipo di aggregazione none (@type: "none") per leggere i valori precalcolati da un aggregatore. Poiché i report sono in genere snapshot senza stato, questa operazione mantiene la logica stateful complessa all'interno degli aggregatori e riserva i report alla formattazione.

{
  "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"
        }
      }
    ]
  }
}

Campi di primo livello

Oltre agli array data_sources, aggregators, triggers e report_configs, la descrizione di una configurazione delle metriche richiede un riferimento al catalogo dei segnali. Puoi anche includere campi facoltativi per assegnare un UUID specifico e gestire il ciclo di vita della raccolta.

Imposta UUID

Ogni MetricsConfig richiede un identificatore univoco universale (UUID). Se fornisci un existing_uuid, MCG lo utilizza. In caso contrario, ne crea uno casuale. Per garantire la coerenza tra deployment e strumenti, specifica un existing_uuid.

La stringa deve essere un UUID valido con trattini contenente solo lettere minuscole.

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

Definizioni degli indicatori

Per convalidare i nomi e i tipi di indicatori, MCG richiede l'accesso a un catalogo di indicatori del veicolo. Si tratta di un file protobuf FileDescriptorSet contenente le definizioni VSIDL .proto (compresse e caricate su MCG). Per informazioni dettagliate sulla creazione e sul caricamento di un catalogo, consulta Cataloghi di indicatori del veicolo.

Specifica la versione del catalogo nel campo vs_version dell'oggetto JSON:

"vs_version": "v1.0",

Definisci i trigger del ciclo di vita

Nel contesto di una campagna di telemetria, il ciclo di vita di un MetricsConfig determina quando i dati vengono effettivamente registrati. Mentre il sistema di gestione delle campagne esegue il deployment e attiva la configurazione sul dispositivo, puoi utilizzare i trigger del ciclo di vita per controllare con precisione quando vengono raccolti i dati all'interno di questo deployment.

In questo modo puoi allineare la raccolta dei dati ai pattern di utilizzo del veicolo, ad esempio un "Viaggio" (da IgnitionOn a IgnitionOff) o una "Sessione di ricarica", senza dover disattivare la configurazione.

• Controllo sessione (avvio/pausa): utilizza start_trigger_name e stop_trigger_name per controllare quando avviene la raccolta. Ad esempio, per raccogliere dati solo mentre il veicolo è in movimento, utilizza IgnitionOn come trigger di avvio e IgnitionOff come trigger di arresto. La configurazione rimane attiva sul dispositivo, ma viene "messa in pausa" (interrompe la raccolta e l'elaborazione) quando viene attivato il trigger di interruzione e riprende solo quando viene attivato di nuovo il trigger di avvio.

  Importante:questa operazione mette in pausa la raccolta. Non definisce finestre logiche, set di dati separati o ha altri effetti collaterali. I valori dell'aggregatore non vengono reimpostati quando la raccolta viene sospesa o ripresa.

• Rilevamento una tantum (fine): utilizza deactivate_trigger_name se la configurazione deve essere eseguita una sola volta (ad esempio, per rilevare la prima occorrenza di un codice di errore specifico) e poi disattivarsi definitivamente sul dispositivo, anche se la campagna è tecnicamente ancora attiva.

Se non specifichi trigger del ciclo di vita, la raccolta dei dati inizia immediatamente quando la configurazione viene attivata dalla campagna e continua ininterrottamente fino al termine della campagna.

Avanzate: definizioni proto personalizzate

In due casi principali, vs_version da solo non è sufficiente per consentire a MCG di comprendere tutti i tipi di messaggi nella descrizione di una configurazione delle metriche:

1. Errore di inferenza del tipo:come spiegato nel source_identifier formato, MCG non può dedurre il tipo quando source_identifier utilizza FQIN o un nome personalizzato.
2. Messaggi personalizzati:la descrizione della configurazione delle metriche utilizza messaggi protobuf che non si trovano nel catalogo VSIDL specificato in vs_version. Ciò si verifica quando imposti message_type in un message_builder per un formato di report personalizzato.

In questi casi, utilizza data_source_message_types per aiutare MCG a dedurre i tipi e descriptor_protos per fornire le definizioni dei messaggi.

data_source_message_types

Mappa la stringa source_identifier al tipo di messaggio protobuf completo. La chiave in data_source_message_types deve corrispondere al valore source_identifier della voce data_sources:

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

descriptor_protos

Fornisci le definizioni per tutti i tipi di messaggio utilizzati in data_source_message_types o message_builder che non sono presenti in vs_version configurato.

Trasmetti un descriptorpb.FileDescriptorSet con codifica Base64 nell'array descriptor_protos. Genera questo file dai file .proto utilizzando il compilatore 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"
            }
          }
        ]
      }
    }
  ]
}

Modello di riferimento

Per la definizione dell'API, consulta il riferimento API MCG.

Le sezioni seguenti forniscono un riferimento completo alla descrizione di una configurazione delle metriche. Utilizzalo come guida per creare la tua descrizione di una configurazione delle metriche.

Campi di primo livello

{
  "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
}

Input: origini dati e aggregatori

{
  "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
            }
          }
        ]
      }
    }
  ]
}

Logica ed elaborazione: trigger

{
  "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 }
          }
        }
      }
    }
  ]
}

Output: configurazioni dei report

{
  "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"
            }
          }
        ]
      }
    }
  ]
}

Sintassi delle espressioni