Формат JSON для запроса на создание конфигурации показателей

В этом руководстве подробно описан формат запроса JSON для конечной точки /api/v2/generate_metrics_config инструмента Metrics Configuration Generator (MCG). Этот формат позволяет определить кампанию телеметрии, указав сбор данных, обработку на устройстве и создание отчетов в человекочитаемой структуре.

Инструмент MCG проверяет этот объект JSON на наличие проблем, таких как несоответствие типов, циклические зависимости или неопределенные ссылки, а затем компилирует его в сообщение буфера протокола MetricsConfig. Это сообщение MetricsConfig в двоичном формате, которое сервис телеметрии на устройстве выполняет для запуска кампании.

Предварительные требования. Вы должны быть знакомы со схемами JSON, protobuf и базовыми структурами данных. Общие сведения о настройке показателей приведены в этой статье.

Как составить описание конфигурации

Чтобы разработать кампанию по сбору показателей, следуйте этой логической схеме:

1. Укажите источники данных. Определите, откуда поступают ваши данные.
2. Определите логику и обработку. Настройте правила, определяющие, когда собирать данные и как их обрабатывать.
3. Создание выходных данных. Упаковка обработанных данных в итоговое сообщение.
4. Поля верхнего уровня. Добавьте поля верхнего уровня, такие как UUID, определения сигналов и управление жизненным циклом.

Укажите источники данных

Телеметрия поддерживает сбор данных из сервисов SDV (через промежуточное ПО SDV) и издателей на основе настраиваемого реестра издателей.

• Сервисы SDV (на основе издателя-подписчика). Данные доступны в каналах издателя-подписчика, определенных в VSIDL.

• Сервисы SDV (на основе RPC). Данные доступны, если сервис предоставляет RPC CreateSubscription или GetLatestMessage.

• Издатели, использующие Configurable Publisher Registry. Данные доступны, если приложение регистрируется с помощью IConfigurablePublisherRegistryинтерфейса Android Binder или библиотеки Configurable Publisher Registry из Telemetry SDK.

Чтобы использовать данные в SDV, определите источник данных (концепция) и добавьте его в массив data_sources.

Не все варианты доступны для всех типов источников данных. Подробную информацию вы найдете в руководстве по интеграции источников данных.

Формат source_identifier

Сервис телеметрии принимает несколько форматов идентификаторов источников. Подробнее об определении источника данных в конфигурациях показателей…

MCG определяет тип сообщения protobuf по source_identifier, только если используется формат Unit Type Name. Если вы используете FQIN или собственное название (из настраиваемого реестра издателей), MCG не сможет определить тип. В таких случаях необходимо указать data_source_message_types. Если типа нет в каталоге, необходимо также указать его определение в 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
}

Определите логику и обработку

Логика обрабатывается двумя компонентами, работающими вместе: триггеры (концепция) определяют, когда что-то происходит. Агрегаторы (концепция) определяют, как обрабатываются данные на основе этих триггеров. Поскольку выражения (концепция) являются ключевыми для условий триггеров и логики агрегирования, в этом разделе сначала описывается, как их писать.

Выражения

Выражения позволяют задавать вычисления и условия с помощью человекочитаемого синтаксиса. MCG компилирует эти строки в исполняемый формат, оптимизированный для оценки на устройстве.

Выражения могут представлять собой арифметические вычисления, логические условия и сравнения данных. Полный синтаксис, включая операторы и функции, приведен в статье Синтаксис выражений.

Актуальность данных. Когда выражение обращается к источнику данных, поведение извлечения зависит от типа подключения:

• SUBSCRIPTION – используется последнее полученное сообщение, кешированное сервисом телеметрии. Примечание. Если задано значение sub_sampling_interval_ms, это может быть не самое последнее опубликованное сообщение.
• ON_DEMAND – немедленно запрашивает новое сообщение из сервиса.

Ограничения по типу

• Массивы. Прямой доступ к индексу массива (например, my_data_source.my_array[0]) не поддерживается.
• Типобезопасность. Сравнивайте совместимые типы. Например, не сравнивайте строковое поле со списком целых чисел.

Триггеры: определяют, когда выполняются действия

Триггеры определяют, когда выполняются действия: оценка агрегатора, создание отчета или управление жизненным циклом сбора. Добавьте все заданные триггеры в массив triggers верхнего уровня.

Триггер данных

Активируется, когда источник данных SUBSCRIPTION предоставляет новое сообщение (концепция).

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

Периодический триггер

Срабатывает через регулярные интервалы (концепция).

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

Условный триггер

Срабатывает на основе оценки выражения (концепция). Для запуска оценки требуется один или несколько родительских триггеров. Часто это триггер данных для источников данных или агрегаторов в выражении или периодический триггер для опроса данных.

Типы условий

Словарь condition_type должен содержать в качестве ключа ровно один из доступных типов условий. Подробнее об условных триггерах…

Параметры контура

Объекты rising_options и falling_options содержат следующие поля. Если вы указываете этот параметр, то соответствующий переход должен соответствовать требованиям к длительности. Переходы без указанных параметров выполняются немедленно.

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

Агрегаторы: определяют, как обрабатываются данные

Используйте агрегатор для промежуточной обработки данных с сохранением состояния (концепция). Определите агрегатор и добавьте его в массив aggregators.

Агрегатор преобразует данные и делает их доступными для других агрегаторов и отчетов.

Редактор сообщений

Объект message_builder определяет структуру выходного сообщения и логику агрегирования, используемую для расчета его полей. Он используется как в агрегаторах, так и в конфигурациях отчетов.

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

Создать выходные данные

Чтобы определить конечный результат кампании телеметрии, добавьте объекты в массив report_configs (концепция). Эти конфигурации определяют, как упаковываются обработанные данные и когда они генерируются. Чтобы повторно использовать компоненты, можно определить несколько конфигураций отчетов в одной конфигурации показателей.

Создание отчетов контролируется с помощью поля trigger_names. Кроме того, вы можете использовать report_initial, чтобы создать отчет сразу после активации конфигурации, и report_incomplete, чтобы создать итоговый отчет, когда сбор данных будет прерван.

Примечание. Чтобы связать обработку с выводом, используйте тип агрегирования none (@type: "none"), который позволяет считывать предварительно рассчитанные значения из агрегатора. Поскольку отчеты обычно представляют собой снимки без отслеживания состояния, это позволяет сохранить сложную логику с отслеживанием состояния в агрегаторах и зарезервировать отчеты для форматирования.

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

Поля верхнего уровня

Помимо массивов data_sources, aggregators, triggers и report_configs, в описании конфигурации показателей должна быть ссылка на каталог сигналов. Вы также можете добавить необязательные поля, чтобы назначить определенный UUID и управлять жизненным циклом коллекции.

Задать UUID

Для каждого MetricsConfig требуется универсальный уникальный идентификатор (UUID). Если вы укажете existing_uuid, MCG будет использовать его. В противном случае будет создан случайный идентификатор. Чтобы обеспечить согласованность между развертываниями и инструментами, укажите existing_uuid.

Строка должна быть действительным UUID с дефисами, содержащим только строчные буквы.

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

Определения сигналов

Чтобы проверять названия и типы сигналов, MCG требуется доступ к каталогу сигналов транспортного средства. Это protobuf-файл FileDescriptorSet, содержащий определения VSIDL .proto (упакованные и загруженные в MCG). Подробнее о том, как создать и загрузить каталог, рассказывается в статье Каталоги сигналов транспортных средств.

Укажите версию каталога в поле vs_version объекта JSON:

"vs_version": "v1.0",

Определите триггеры жизненного цикла

В контексте кампании телеметрии жизненный цикл MetricsConfig определяет, когда данные фактически записываются. Пока система управления кампаниями развертывает и активирует конфигурацию на устройстве, вы можете использовать триггеры жизненного цикла, чтобы точно контролировать, когда данные собираются в рамках этого развертывания.

Это позволяет согласовать сбор данных с шаблонами использования автомобиля, такими как "Поездка" (IgnitionOn–IgnitionOff) или "Сеанс зарядки", без необходимости деактивировать конфигурацию.

• Управление сеансом (запуск/пауза). Используйте кнопки start_trigger_name и stop_trigger_name, чтобы управлять сбором данных. Например, чтобы собирать данные только во время движения автомобиля, используйте IgnitionOn в качестве триггера запуска и IgnitionOff в качестве триггера остановки. Конфигурация остается активной на устройстве, но фактически приостанавливается (прекращает сбор и обработку данных), когда срабатывает триггер остановки, и возобновляет работу только после повторного срабатывания триггера запуска.

  Важно! Это лишь приостанавливает сбор данных. Она не определяет логические окна, отдельные наборы данных и не имеет других побочных эффектов. Значения агрегатора не сбрасываются, когда сбор данных приостанавливается или возобновляется.

• Однократное обнаружение (завершение). Используйте deactivate_trigger_name, если конфигурация должна запуститься только один раз (например, чтобы обнаружить первое появление определенного кода ошибки), а затем навсегда деактивироваться на этом устройстве, даже если кампания технически все ещё активна.

Если вы не укажете триггеры жизненного цикла, сбор данных начнется сразу после активации конфигурации кампанией и будет продолжаться до окончания кампании.

Дополнительно: специальные определения proto

В двух основных случаях одного vs_version недостаточно, чтобы MCG понимал все типы сообщений в описании конфигурации показателей:

1. Ошибка вывода типа. Как объясняется в разделе Формат source_identifier, MCG не может вывести тип, если в source_identifier используется полное имя интерфейса или специальное название.
2. Специальные сообщения. В описании конфигурации показателей используются сообщения protobuf, которых нет в каталоге VSIDL, указанном в vs_version. Это происходит при настройке message_type в message_builder для специального формата отчета.

В таких случаях используйте data_source_message_types, чтобы помочь MCG определить типы, и descriptor_protos, чтобы предоставить определения сообщений.

data_source_message_types

Сопоставьте строку source_identifier с ее полным типом сообщения protobuf. Ключ в data_source_message_types должен соответствовать значению source_identifier из записи data_sources:

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

descriptor_protos

Укажите определения для всех типов сообщений, используемых в data_source_message_types или message_builder, которых нет в настроенном vs_version.

Передайте закодированный по стандарту Base64 параметр descriptorpb.FileDescriptorSet в массиве descriptor_protos. Сгенерируйте его из файлов .proto с помощью компилятора 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"
            }
          }
        ]
      }
    }
  ]
}

Шаблон цифрового отпечатка

Определение API приведено в справочнике по MCG API.

В следующих разделах приведено полное описание конфигурации показателей. Используйте его как руководство для создания собственного описания конфигурации показателей.

Поля верхнего уровня

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

Входные данные: источники данных и агрегаторы

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

Логика и обработка: триггеры

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

Выходные данные: конфигурации отчетов

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

Синтаксис выражений