Запрос на генерацию конфигурации метрик в формате JSON

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

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

Предварительные требования: Вам необходимо быть знакомым со схемами JSON, протоколом protobuf и базовыми структурами данных. Для более подробного ознакомления см. раздел «Концепции настройки метрик» .

Как подойти к написанию описания конфигурации

Для разработки кампании по сбору метрик следуйте этой логической последовательности:

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

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

Функция телеметрии поддерживает сбор данных из сервисов SDV (через промежуточное ПО SDV) и издателей, использующих настраиваемый реестр издателей.

• Сервисы SDV (на основе публикации/подписки): Данные доступны через каналы публикации/подписки, определенные в VSIDL .

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

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

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

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

Формат идентификатора источника

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

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

Управление генерацией отчетов осуществляется с помощью поля 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 если конфигурация должна выполняться только один раз (например, для обнаружения первого появления определенного кода ошибки), а затем навсегда деактивироваться на этом устройстве, даже если кампания технически все еще активна.

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

Расширенные настройки: Пользовательские определения протоколов

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

1. Ошибка вывода типа: Как поясняется в описании формата source_identifier , MCG не может определить тип, если source_identifier использует FQIN или пользовательское имя.
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 .

Передайте в массив descriptor_protos объект descriptorpb.FileDescriptorSet закодированный в base64. Сгенерируйте его из файлов .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 см. в справочнике API MCG .

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

Поля высшего уровня

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

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

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

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