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 Generador de configuración de métricas (MCG). Este formato te permite definir una campaña de telemetría, que especifica 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) de MetricsConfig. Este mensaje MetricsConfig es el formato binario que ejecuta el servicio de telemetría integrado en el dispositivo para publicar 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 escribir una descripción de la 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 resultado: 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 las 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 CreateSubscription o GetLatestMessage.

• Publicadores basados en el registro de publicadores configurable: Los datos están disponibles si la aplicación se registra con la interfaz de Binder de Android IConfigurablePublisherRegistry o la biblioteca de registro de publicadores configurable del SDK de Telemetry.

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 las configuraciones de métricas para obtener una descripción general.

MCG infiere el tipo de mensaje de protobuf 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 publicadores configurable), 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 funcionan 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. Debido a 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 por humanos. MCG compila estas cadenas en un formato ejecutable optimizado para la evaluación integrada en el dispositivo.

Las expresiones pueden representar 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.

Actualización 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 último mensaje recibido que almacenó en caché el servicio de telemetría. (Nota: Si se establece sub_sampling_interval_ms, esto puede diferir del mensaje publicado más reciente absoluto).
• ON_DEMAND: Activa una llamada inmediata para recuperar el mensaje nuevo del servicio.

Restricciones de tipo

• Arrays: No se admite el acceso directo al índice de arrays (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: Definen cuándo se producen 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 de SUBSCRIPTION proporciona un mensaje nuevo (concepto).

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

Activador periódico

Se activa en un intervalo regular (concepto).

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

Activador condicional

Se activa según la evaluación de una expresión (concepto). Requiere uno o más activadores superiores para iniciar su evaluación. Suele ser un activador de datos para las fuentes de datos o los agregadores de la expresión, o un activador periódico para sondear 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 cumplir con 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 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 mensaje

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 tanto en los agregadores como 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
        }
      }
    ]
  }
}

Crea un resultado

Para definir el resultado final de tu campaña de telemetría, agrega objetos al array report_configs (concepto). Estas configuraciones determinan cómo se empaquetan los datos procesados y cuándo se generan. Puedes definir varios parámetros de configuración de informes en un parámetro de 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 activa la configuración y report_incomplete para generar un informe final cuando se interrumpe la recopilación de datos.

Nota: Para conectar el procesamiento con el resultado, usa el tipo de agregación none (@type: "none") para leer los valores calculados previamente de un agregador. Dado que los informes suelen ser instantáneas sin estado, esto mantiene la lógica con estado compleja 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 usa. De lo contrario, se crea uno aleatorio. Para obtener 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 de vehículos. Este es un protobuf FileDescriptorSet que contiene tus definiciones de VSIDL .proto (empaquetadas y subidas a MCG). Para obtener detalles sobre cómo crear y subir un catálogo, consulta Catálogos de indicadores 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" (de IgnitionOn a IgnitionOff) o una "sesión de carga", sin necesidad de desactivar la configuración.

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

  Importante: Esto solo detiene la recopilación. No define ventanas lógicas, conjuntos de datos independientes ni tiene ningún otro efecto secundario. Los valores del agregador no se restablecen cuando se pausa o 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 instancia de un código de error 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 comenzará de inmediato cuando la campaña active la configuración y continuará de forma ininterrumpida hasta que finalice 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 de inferencia de tipo: Como se explica en el formato source_identifier, MCG no puede inferir el tipo cuando source_identifier usa FQIN o un nombre personalizado.
2. Mensajes personalizados: La descripción de la configuración de las 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 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 esté en el vs_version configurado.

Pasa un descriptorpb.FileDescriptorSet codificado en base64 en el array descriptor_protos. Genera esto 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": "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: 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 }
          }
        }
      }
    }
  ]
}

Resultado: parámetros de configuración 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 las expresiones