Formato JSON da solicitação de geração de configuração de métricas

Este guia detalha o formato de solicitação JSON para o endpoint /api/v1/generate_metrics_config da ferramenta Metrics Configuration Generator (MCG). Esse formato permite definir uma campanha de telemetria especificando coleta de dados, processamento no dispositivo e geração de relatórios em uma estrutura legível por humanos.

A ferramenta MCG valida esse objeto JSON, verificando problemas como incompatibilidades de tipo, dependências circulares ou referências indefinidas, e depois o compila em uma mensagem de buffer de protocolo (protobuf) MetricsConfig. Essa mensagem MetricsConfig é o formato binário que o serviço de telemetria no dispositivo executa para veicular a campanha.

Pré-requisitos:é preciso ter familiaridade com esquemas JSON, protobuf e estruturas de dados básicas. Para uma visão geral conceitual, consulte Conceitos de configuração de métricas.

Como escrever uma descrição de configuração

Para criar uma campanha de coleta de métricas, siga este fluxo lógico:

1. Especificar fontes de dados: defina de onde vêm seus dados.
2. Defina a lógica e o processamento: configure regras para quando coletar dados e como processá-los.
3. Criar saída: empacote os dados processados em uma mensagem final.
4. Campos de nível superior: adicione campos de nível superior, como UUID, definições de indicador e controle de ciclo de vida.

Especificar fontes de dados

A telemetria permite coletar dados de serviços de SDV (pelo middleware de SDV) e de editores baseados no registro de editores configuráveis.

• Serviços de SDV (baseados em pub/sub): os dados estão disponíveis nos canais de pub/sub definidos em VSIDL.

• Serviços SDV (baseados em RPC): os dados ficam disponíveis se o serviço expuser RPCs CreateSubscription ou GetLatestMessage.

• Editores configuráveis com base no registro de editores:os dados estão disponíveis se o aplicativo se registrar usando a interface do Binder do Android IConfigurablePublisherRegistry ou a biblioteca do registro de editores configuráveis do SDK de telemetria.

Para usar dados no SDV, defina uma fonte de dados (conceito) e adicione-a à matriz data_sources.

Nem todas as opções estão disponíveis para todos os tipos de fontes de dados. Consulte o guia de integração de fontes de dados para mais informações.

Formato de source_identifier

O serviço de telemetria aceita vários formatos de identificador de origem. Consulte Definição de fonte de dados nas configurações de métricas para uma visão geral.

O MCG infere o tipo de mensagem protobuf do source_identifier somente se ele usar o formato de nome do tipo de unidade. Se você usar FQIN ou um nome personalizado (do registro de editores configuráveis), o MCG não poderá inferir o tipo. Nesses casos, é necessário fornecer data_source_message_types. Se o tipo não estiver no seu catálogo, também será necessário fornecer a definição dele em 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
}

Definir lógica e processamento

A lógica é processada por dois componentes que trabalham juntos: os gatilhos (conceito) definem quando algo acontece. Os agregadores (conceito) definem como os dados são processados com base nesses gatilhos. Como as expressões (conceito) são essenciais para condições de acionamento e lógica de agregação, esta seção descreve primeiro como escrevê-las.

Expressões

Com as expressões, é possível definir cálculos e condições usando uma sintaxe legível. O MCG compila essas strings em um formato executável otimizado para avaliação no dispositivo.

Elas podem expressar cálculos aritméticos, condições lógicas e comparações de dados. Para conferir a sintaxe completa, incluindo operadores e funções, consulte Sintaxe de expressões.

Atualização de dados:quando uma expressão acessa uma fonte de dados, o comportamento de recuperação depende do tipo de conexão:

• SUBSCRIPTION: usa a mensagem recebida por último armazenada em cache pelo serviço de telemetria. Observação: se sub_sampling_interval_ms estiver definido, isso poderá ser diferente da mensagem publicada mais recente.
• ON_DEMAND: aciona uma chamada imediata para buscar a mensagem atualizada do serviço.

Restrições de tipo

• Arrays:o acesso direto ao índice de array (por exemplo, my_data_source.my_array[0]) não é compatível.
• Segurança de tipo:compare tipos compatíveis. Por exemplo, não compare um campo de string com uma lista de números inteiros.

Gatilhos: definem quando as ações ocorrem

Os gatilhos definem quando as ações são executadas: avaliando um agregador, gerando um relatório ou controlando o ciclo de vida da coleta. Adicione todos os gatilhos definidos à matriz triggers de nível superior.

Gatilho de dados

Acionada quando uma fonte de dados SUBSCRIPTION fornece uma nova mensagem (conceito).

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

Acionador periódico

É acionado em um intervalo regular (conceito).

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

Gatilho condicional

É acionado com base na avaliação de uma expressão (conceito). Ele exige um ou mais acionadores principais para iniciar a avaliação. Geralmente, é um acionador de dados para as fontes de dados ou agregadores na expressão ou um acionador periódico para pesquisar dados.

Tipos de condição

O dicionário condition_type precisa conter exatamente um dos tipos de condição disponíveis como chave. Para mais informações, consulte Gatilhos condicionais.

Opções de borda

Os objetos rising_options e falling_options têm os seguintes campos. Se fornecida, a transição correspondente precisa atender ao requisito de duração. As transições sem opções especificadas são acionadas imediatamente.

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

Agregadores: definem como os dados são tratados

Use um agregador para processamento de dados intermediários com estado (conceito). Defina um agregador e adicione-o à matriz aggregators.

Um agregador transforma dados e os disponibiliza para outros agregadores e relatórios.

Criador de mensagens

Um objeto message_builder define a estrutura da mensagem de saída e a lógica de agregação usada para calcular os campos. Ele é usado em agregadores e configurações de relatórios.

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

Criar saída

Para definir a saída final da sua campanha de telemetria, adicione objetos à matriz report_configs (conceito). Essas configurações determinam como os dados processados são empacotados e quando são gerados. É possível definir várias configurações de relatório em uma configuração de métricas para reutilizar componentes.

Você controla a geração de relatórios usando o campo trigger_names. Além disso, você pode usar report_initial para gerar um relatório imediatamente quando a configuração é ativada e report_incomplete para gerar um relatório final quando a coleta de dados é interrompida.

Observação:para conectar o processamento à saída, use o tipo de agregação none (@type: "none") para ler valores pré-calculados de um agregador. Como os relatórios são geralmente snapshots sem estado, isso mantém a lógica com estado complexa nos agregadores e reserva os relatórios para formatação.

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

Campos de nível superior

Além das matrizes data_sources, aggregators, triggers e report_configs, a descrição de uma configuração de métricas exige uma referência ao catálogo de indicadores. Também é possível incluir campos opcionais para atribuir um UUID específico e gerenciar o ciclo de vida da coleta.

Definir UUID

Cada MetricsConfig exige um identificador universal exclusivo (UUID). Se você fornecer um existing_uuid, o MCG vai usá-lo. Caso contrário, ele cria um aleatório. Para manter a consistência entre implantações e ferramentas, especifique um existing_uuid.

A string precisa ser um UUID hifenizado válido que contenha apenas letras minúsculas.

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

Definições de indicadores

Para validar nomes e tipos de indicadores, o MCG precisa de acesso a um catálogo de indicadores de veículos. É um protobuf FileDescriptorSet que contém suas definições VSIDL .proto (empacotadas e enviadas para o MCG). Para detalhes sobre como criar e fazer upload de um catálogo, consulte Catálogos de sinais de veículos.

Especifique a versão do catálogo no campo vs_version do objeto JSON:

"vs_version": "v1.0",

Definir gatilhos de ciclo de vida

No contexto de uma campanha de telemetria, o ciclo de vida de um MetricsConfig determina quando os dados são realmente registrados. Enquanto o sistema de gerenciamento de campanhas implanta e ativa a configuração no dispositivo, você pode usar gatilhos de ciclo de vida para controlar precisamente quando os dados são coletados nessa implantação.

Isso permite alinhar a coleta de dados com padrões de uso do veículo, como uma "Viagem" (IgnitionOn a IgnitionOff) ou uma "Sessão de carregamento", sem precisar desativar a configuração.

• Controle de sessão (iniciar/pausar): use start_trigger_name e stop_trigger_name para controlar quando a coleta acontece. Por exemplo, para coletar dados apenas enquanto o veículo está dirigindo, use IgnitionOn como o acionador de início e IgnitionOff como o acionador de parada. A configuração permanece ativa no dispositivo, mas é "pausada" (interrompe a coleta e o processamento) quando o gatilho de parada é acionado, sendo retomada apenas quando o gatilho de início é acionado novamente.

  Importante:isso apenas pausa a coleta. Ela não define janelas lógicas, conjuntos de dados separados nem tem outros efeitos colaterais. Os valores do agregador não são redefinidos quando a coleta é pausada ou retomada.

• Detecção única (conclusão): use deactivate_trigger_name se a configuração precisar ser executada apenas uma vez (por exemplo, para detectar a primeira ocorrência de um código de falha específico) e depois se desativar permanentemente no dispositivo, mesmo que a campanha ainda esteja tecnicamente ativa.

Se você não especificar nenhum gatilho de ciclo de vida, a coleta de dados vai começar imediatamente quando a configuração for ativada pela campanha e vai continuar até o fim dela.

Avançado: definições de protocolo personalizadas

Em dois casos principais, vs_version sozinho não é suficiente para que a MCG entenda todos os tipos de mensagem na descrição de uma configuração de métricas:

1. Falha na inferência de tipo:conforme explicado no formato source_identifier, a MCG não consegue inferir o tipo quando source_identifier usa FQIN ou um nome personalizado.
2. Mensagens personalizadas:a descrição da configuração de métricas usa mensagens protobuf que não são encontradas no catálogo VSIDL especificado em vs_version. Isso acontece ao definir message_type em um message_builder para um formato de relatório personalizado.

Nesses casos, use data_source_message_types para ajudar o MCG a inferir tipos e descriptor_protos para fornecer definições de mensagens.

data_source_message_types

Mapeie a string source_identifier para o tipo de mensagem protobuf totalmente qualificado. A chave em data_source_message_types precisa corresponder ao valor source_identifier da entrada data_sources:

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

descriptor_protos

Forneça definições para todos os tipos de mensagens usados em data_source_message_types ou message_builder que não estão no vs_version configurado.

Transmita um descriptorpb.FileDescriptorSet codificado em base64 na matriz descriptor_protos. Gere isso de arquivos .proto usando o compilador 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"
            }
          }
        ]
      }
    }
  ]
}

Modelo de referência

Para a definição da API, consulte a referência da API MCG.

As seções a seguir fornecem uma referência completa da descrição de uma configuração de métricas. Use-o como guia para criar sua própria descrição de uma configuração de métricas.

Campos de nível superior

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

Entrada: fontes de dados e agregadores

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

Lógica e processamento: acionadores

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

Saída: configurações de relatório

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

Sintaxe de expressões