Formato JSON de la solicitud de generación de la configuración de métricas

En esta guía, se detalla el formato de solicitud JSON para el extremo /api/v1/generate_metrics_config de la herramienta Metrics Configuration Generator (MCG). Este formato te permite definir una campaña de telemetría (especificando la recopilación de datos, el procesamiento en el dispositivo y la generación de informes) en una estructura legible por humanos.

La herramienta de MCG valida este objeto JSON, verifica si hay problemas como discrepancias de tipos, dependencias circulares o referencias no definidas, y, luego, lo compila en un mensaje de búfer de protocolo (protobuf) MetricsConfig. Este mensaje MetricsConfig es el formato binario que ejecuta el servicio de Telemetría integrado en el dispositivo para llevar a cabo la campaña.

Requisitos previos: Debes conocer los esquemas JSON, protobuf y las estructuras de datos básicas. Para obtener una descripción general conceptual, consulta Conceptos de configuración de métricas.

Cómo abordar la escritura de una descripción de configuración

Para diseñar una campaña de recopilación de métricas, sigue este flujo lógico:

1. Especifica las fuentes de datos: Define de dónde provienen tus datos.
2. Define la lógica y el procesamiento: Configura reglas para determinar cuándo recopilar datos y cómo procesarlos.
3. Crear salida: Empaqueta los datos procesados en un mensaje final.
4. Campos de nivel superior: Agrega campos de nivel superior, como UUID, definiciones de indicadores y control del ciclo de vida.

Especifica fuentes de datos

La telemetría admite la recopilación de datos de los servicios de SDV (a través del middleware de SDV) y de los publicadores basados en el registro de publicadores configurable.

• Servicios de SDV (basados en Pub/Sub): Los datos están disponibles en los canales de Pub/Sub definidos en VSIDL.

• Servicios de SDV (basados en RPC): Los datos están disponibles si el servicio expone RPC de CreateSubscription o GetLatestMessage.

• Publicadores configurables basados en el Registro de publicadores: Los datos están disponibles si la aplicación se registra con la interfaz de Binder de IConfigurablePublisherRegistry para Android o la biblioteca del Registro de publicadores configurable del SDK de Telemetría.

Para usar datos en SDV, define una fuente de datos (concepto) y agrégala al array data_sources.

No todas las opciones están disponibles para todos los tipos de fuentes de datos. Consulta la guía de integración de fuentes de datos para obtener información detallada.

Formato de source_identifier

El servicio de telemetría acepta varios formatos de identificadores de origen. Consulta Definición de la fuente de datos en la configuración de métricas para obtener una descripción general.

MCG infiere el tipo de mensaje de protobuf a partir de source_identifier solo si usa el formato de nombre de tipo de unidad. Si usas el FQIN o un nombre personalizado (del Registro de editores configurables), MCG no puede inferir el tipo. En estos casos, debes proporcionar data_source_message_types. Si el tipo no está en tu catálogo, también debes proporcionar su definición en 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
}

Define la lógica y el procesamiento

La lógica se controla con dos componentes que trabajan juntos: los activadores (concepto) definen cuándo sucede algo. Los agregadores (concepto) definen cómo se procesan los datos en función de esos activadores. Dado que las expresiones (concepto) son clave para las condiciones de activación y la lógica de agregación, en esta sección, primero, se describe cómo escribirlas.

Expresiones

Las expresiones te permiten definir cálculos y condiciones con una sintaxis legible. MCG compila estas cadenas en un formato ejecutable optimizado para la evaluación integrado en el dispositivo.

Las expresiones pueden expresar cálculos aritméticos, condiciones lógicas y comparaciones de datos. Para ver la sintaxis completa, incluidos los operadores y las funciones, consulta Sintaxis de expresiones.

Actualidad de los datos: Cuando una expresión accede a una fuente de datos, el comportamiento de recuperación depende del tipo de conexión:

• SUBSCRIPTION: Usa el mensaje recibido por última vez que almacena en caché el servicio de Telemetría. (Nota: Si se configura sub_sampling_interval_ms, es posible que esto difiera del mensaje publicado más reciente).
• ON_DEMAND: Activa una llamada inmediata para recuperar el mensaje actualizado del servicio.

Restricciones de tipo

• Arrays: No se admite el acceso directo al índice de array (por ejemplo, my_data_source.my_array[0]).
• Seguridad de tipos: Asegúrate de comparar tipos compatibles (por ejemplo, no compares un campo de cadena con una lista de números enteros).

Activadores: Define cuándo ocurren las acciones

Los activadores definen cuándo se ejecutan las acciones: evaluar un agregador, generar un informe o controlar el ciclo de vida de la recopilación. Agrega todos los activadores definidos al array triggers de nivel superior.

Activador de datos

Se activa cuando una fuente de datos SUBSCRIPTION proporciona un mensaje nuevo (concepto).

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

Activador periódico

Se dispara a intervalos regulares (concepto).

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

Activador condicional

Se activan en función de la evaluación de una expresión (concepto). Requiere uno o más activadores principales para iniciar su evaluación. A menudo, se trata de un activador de datos para las fuentes de datos o los agregadores de la expresión, o bien un activador periódico para sondear los datos.

Tipos de condiciones

El diccionario condition_type debe contener exactamente uno de los tipos de condición disponibles como clave. Para obtener más información, consulta Activadores condicionales.

Opciones de borde

Los objetos rising_options y falling_options tienen los siguientes campos. Si se proporciona, la transición correspondiente debe satisfacer el requisito de duración. Las transiciones sin opciones especificadas se activan de inmediato.

{
  "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: Definen cómo se procesan los datos

Usa un agregador para el procesamiento de datos intermedio y con estado (concepto). Define un agregador y agrégalo al array aggregators.

Un agregador transforma los datos y los pone a disposición de otros agregadores y de los informes.

Creador de mensajes

Un objeto message_builder define la estructura del mensaje de salida y la lógica de agregación que se usa para calcular sus campos. Se usa en los agregadores y en las configuraciones de informes.

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

Crear resultado

Para definir el resultado final de tu campaña de telemetría, agrega objetos al array report_configs (concepto). Estos parámetros de configuración determinan cómo se empaquetan los datos procesados y cuándo se generan. Puedes definir varias configuraciones de informes en una configuración de métricas para reutilizar componentes.

Puedes controlar la generación de informes con el campo trigger_names. Además, puedes usar report_initial para generar un informe de inmediato cuando se active la configuración y report_incomplete para generar un informe final cuando se interrumpa la recopilación de datos.

Nota: Para conectar el procesamiento con la salida, usa el tipo de agregación none (@type: "none") para leer los valores precalculados de un agregador. Dado que los informes suelen ser instantáneas sin estado, esto mantiene la lógica compleja con estado dentro de los agregadores y reserva los informes para el formato.

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

Además de los arrays data_sources, aggregators, triggers y report_configs, la descripción de una configuración de métricas requiere una referencia al catálogo de indicadores. También puedes incluir campos opcionales para asignar un UUID específico y administrar el ciclo de vida de la colección.

Establece el UUID

Cada MetricsConfig requiere un identificador único universal (UUID). Si proporcionas un existing_uuid, MCG lo usará. De lo contrario, crea uno aleatorio. Para garantizar la coherencia entre las implementaciones y las herramientas, especifica un existing_uuid.

La cadena debe ser un UUID válido con guiones que contenga solo letras minúsculas.

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

Definiciones de indicadores

Para validar los nombres y tipos de indicadores, MCG requiere acceso a un catálogo de indicadores del vehículo. Es un archivo FileDescriptorSet de protobuf que contiene las definiciones de .proto de VSIDL (empaquetadas y subidas a MCG). Para obtener detalles sobre cómo crear y subir un catálogo, consulta Catálogos de señales de vehículos.

Especifica la versión del catálogo en el campo vs_version del objeto JSON:

"vs_version": "v1.0",

Define activadores del ciclo de vida

En el contexto de una campaña de telemetría, el ciclo de vida de un MetricsConfig determina cuándo se registran los datos. Mientras el sistema de administración de campañas implementa y activa la configuración en el dispositivo, puedes usar activadores de ciclo de vida para controlar con precisión cuándo se recopilan los datos dentro de esa implementación.

Esto te permite alinear la recopilación de datos con los patrones de uso del vehículo, como un "viaje" (IgnitionOn a IgnitionOff) o una "sesión de carga", sin necesidad de desactivar la configuración.

• Control de sesión (iniciar/pausar): Usa start_trigger_name y stop_trigger_name para controlar cuándo se realiza la recopilación. Por ejemplo, para recopilar datos solo mientras el vehículo está en movimiento, usa IgnitionOn como el activador de inicio y IgnitionOff como el activador de detención. La configuración permanece activa en el dispositivo, pero se "pausa" (deja de recopilar y procesar) de manera efectiva cuando se activa el disparador de detención y se reanuda solo cuando se vuelve a activar el disparador de inicio.

  Importante: Esto solo pausa la recopilación. No define ventanas lógicas, conjuntos de datos separados ni tiene ningún otro efecto secundario. Los valores del agregador no se restablecen cuando se pausa o se reanuda la recopilación.

• Detección única (finalización): Usa deactivate_trigger_name si la configuración debe ejecutarse solo una vez (por ejemplo, para detectar la primera aparición de un código de falla específico) y, luego, desactivarse de forma permanente en ese dispositivo, incluso si la campaña técnicamente sigue activa.

Si no especificas ningún activador de ciclo de vida, la recopilación de datos comienza de inmediato cuando la campaña activa la configuración y continúa de forma continua hasta que finaliza la campaña.

Avanzado: Definiciones de .proto personalizadas

En dos casos principales, vs_version por sí solo no es suficiente para que MCG comprenda todos los tipos de mensajes en la descripción de una configuración de métricas:

1. Falla en la inferencia de tipos: Como se explica en el formato de source_identifier, MCG no puede inferir el tipo cuando source_identifier usa el FQIN o un nombre personalizado.
2. Mensajes personalizados: La descripción de la configuración de métricas usa mensajes de protobuf que no se encuentran en el catálogo de VSIDL especificado en vs_version. Esto sucede cuando se configura message_type en un message_builder para un formato de informe personalizado.

En estos casos, usa data_source_message_types para ayudar a MCG a inferir tipos y descriptor_protos para proporcionar definiciones de mensajes.

data_source_message_types

Asigna la cadena source_identifier a su tipo de mensaje de protobuf completamente calificado. La clave en data_source_message_types debe coincidir con el valor de source_identifier de la entrada data_sources:

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

descriptor_protos

Proporciona definiciones para cualquier tipo de mensaje que se use en data_source_message_types o message_builder que no se encuentre en el vs_version configurado.

Pasa un descriptorpb.FileDescriptorSet codificado en base64 en el array descriptor_protos. Se genera a partir de archivos .proto con el compilador de 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"
            }
          }
        ]
      }
    }
  ]
}

Plantilla de referencia

Para obtener la definición de la API, consulta la referencia de la API de MCG.

En las siguientes secciones, se proporciona una referencia completa de la descripción de una configuración de métricas. Úsala como guía para crear tu propia descripción de una configuración de métricas.

Campos de nivel 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: Fuentes de datos y 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 y procesamiento: activadores

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

Salida: Configuraciones de informes

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

Sintaxis de expresiones