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/v2/generate_metrics_config da ferramenta Metrics Configuration Generator (MCG). Esse formato permite definir uma campanha de telemetria, especificando a coleta de dados, o processamento no dispositivo e a 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 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: você precisa conhecer 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: empacotar 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 em canais de pub/sub definidos em VSIDL.

• Serviços de SDV (baseados em RPC): os dados estarão disponíveis se o serviço expor RPCs CreateSubscription ou GetLatestMessage.

• Editores baseados no Configurable Publisher Registry: os dados ficam disponíveis se o aplicativo se registrar usando a interface do Binder do Android IConfigurablePublisherRegistry ou a biblioteca do Configurable Publisher Registry 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 da fonte de dados nas configurações de métricas para uma visão geral.

O MCG infere o tipo de mensagem do protobuf do source_identifier somente se ele usar o formato de nome do tipo de unidade. Se você usar o FQIN ou um nome personalizado (do registro de editor configurável), o MCG não poderá inferir o tipo. Nesses casos, é necessário fornecer data_source_message_types. Se o tipo não estiver no catálogo, você também precisará 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 acionadores. Como as expressões (conceito) são fundamentais para as condições de acionamento e a lógica de agregação, esta seção descreve primeiro como escrevê-las.

Expressões

As expressões permitem definir cálculos e condições usando uma sintaxe legível por humanos. O MCG compila essas strings em um formato executável otimizado para avaliação no dispositivo.

As expressões podem expressar cálculos aritméticos, condições lógicas e comparações de dados. Para ver 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 última mensagem recebida armazenada em cache pelo serviço de telemetria. Observação: se sub_sampling_interval_ms estiver definido, isso pode ser diferente da mensagem publicada mais recente.
• ON_DEMAND: aciona uma chamada imediata para buscar a mensagem mais recente do serviço.

Restrições de tipo

• Matrizes: o acesso direto ao índice de matriz (por exemplo, my_data_source.my_array[0]) não é compatível.
• Segurança de tipos: 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: avaliar um agregador, gerar um relatório ou controlar o ciclo de vida da coleta. Adicione todos os acionadores definidos à matriz triggers de nível superior.

Acionador de dados

É acionado 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 requer um ou mais acionadores pai para iniciar a avaliação. Geralmente, é um acionador de dados para as fontes ou agregadores de dados na expressão ou um acionador periódico para consultar 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 campos a seguir. Se for fornecida, a transição correspondente precisará 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 processados

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ório.

{
  "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 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, é possível 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 normalmente são snapshots sem estado, isso mantém a lógica com estado complexa dentro dos 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 requer 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 coleção.

Definir UUID

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

A string precisa ser um UUID válido com hifens e conter 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. Este é um FileDescriptorSet de protobuf que contém as definições de 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, é possível usar acionadores de ciclo de vida para controlar com precisão quando os dados são coletados nessa implantação.

Isso permite alinhar a coleta de dados com os 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 estiver em movimento, use IgnitionOn como o gatilho de início e IgnitionOff como o gatilho de parada. A configuração permanece ativa no dispositivo, mas é "pausada" (interrompe a coleta e o processamento) quando o acionador de parada é disparado, retomando apenas quando o acionador de início é disparado 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, em seguida, se desativar permanentemente no dispositivo, mesmo que a campanha ainda esteja tecnicamente ativa.

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

Avançado: definições de proto personalizadas

Em dois casos principais, o vs_version sozinho não é suficiente para que o 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, o MCG não pode 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 mensagem usados em data_source_message_types ou message_builder que não estejam 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 ver 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 um guia para criar sua própria descrição de uma configuração de métricas.

Campos de nível superior

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

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: gatilhos

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