Metrik yapılandırması oluşturma isteği JSON biçimi

Bu kılavuzda, Metrik Yapılandırma Oluşturucu (MCG) aracının /api/v1/generate_metrics_config uç noktası için JSON isteği biçimi ayrıntılı olarak açıklanmaktadır. Bu biçim, telemetri kampanyası tanımlamanıza (veri toplama, cihaz üzerinde işleme ve rapor oluşturma işlemlerini belirterek) olanak tanır.

MCG aracı, bu JSON nesnesini doğrulayarak tür uyuşmazlıkları, döngüsel bağımlılıklar veya tanımlanmamış referanslar gibi sorunları kontrol eder ve ardından MetricsConfig protokol arabelleği (protobuf) mesajı olarak derler. Bu MetricsConfig mesaj, kampanyayı çalıştırmak için cihazdaki Telemetri hizmetinin yürüttüğü ikili biçimdir.

Ön koşullar: JSON şemaları, protobuf ve temel veri yapıları hakkında bilgi sahibi olmanız gerekir. Kavramsal genel bakış için Metrik yapılandırması kavramları başlıklı makaleyi inceleyin.

Yapılandırma açıklaması yazmaya nasıl yaklaşılır?

Metrik toplama kampanyası tasarlamak için şu mantıksal akışı izleyin:

1. Veri kaynaklarını belirtin: Verilerinizin kaynağını tanımlayın.
2. Mantığı ve işlemeyi tanımlama: Verilerin ne zaman toplanacağı ve nasıl işleneceğiyle ilgili kurallar belirleyin.
3. Çıkış oluşturma: İşlenen verileri nihai bir mesajda paketleyin.
4. Üst düzey alanlar: UUID, signal definitions ve lifecycle control gibi üst düzey alanlar ekleyin.

Veri kaynaklarını belirtme

Telemetri, SDV Hizmetleri'nden (SDV Ara Katmanı aracılığıyla) ve Yapılandırılabilir Yayıncı Kaydı tabanlı yayıncılardan veri toplamayı destekler.

• SDV Hizmetleri (pub/sub tabanlı): Veriler, VSIDL'de tanımlanan pub/sub kanallarından alınabilir.

• SDV Hizmetleri (RPC tabanlı): Hizmet CreateSubscription veya GetLatestMessage RPC'leri kullanıma sunuyorsa veriler kullanılabilir.

• Yapılandırılabilir Yayıncı Kayıt Defteri tabanlı yayıncılar: Uygulama, Telemetri SDK'sından IConfigurablePublisherRegistry Android Binder arayüzünü veya Yapılandırılabilir Yayıncı Kayıt Defteri kitaplığını kullanarak kendini kaydettirirse veriler kullanılabilir.

SDV'de veri kullanmak için bir veri kaynağı (kavram) tanımlayın ve bunu data_sources dizisine ekleyin.

Tüm seçenekler, tüm veri kaynağı türlerinde kullanılamaz. Ayrıntılı bilgi için veri kaynağı entegrasyonu kılavuzuna bakın.

source_identifier biçimi

Telemetri hizmeti, birden fazla kaynak tanımlayıcı biçimini kabul eder. Genel bakış için Metrik yapılandırmalarında veri kaynağı tanımı başlıklı makaleyi inceleyin.

MCG, protobuf mesaj türünü yalnızca source_identifier birim türü adı biçimini kullanıyorsa çıkarır. FQIN veya özel bir ad (Yapılandırılabilir Yayıncı Kaydı'ndan) kullanıyorsanız MCG türü çıkaramaz. Bu durumlarda data_source_message_types sağlamanız gerekir. Tür kataloğunuzda yoksa tanımını da descriptor_protos içinde sağlamanız gerekir.

{
  "name": "SpeedSource",
  "source_identifier": "mcg.test.subpkg.speed_msg",
  "connection_type": "SUBSCRIPTION",
  "sub_sampling_interval_ms": 1000 // Limit updates to 1 per second
}

Mantığı ve işlemeyi tanımlama

Mantık, birlikte çalışan iki bileşen tarafından işlenir: Tetikleyiciler (kavram), bir şeyin ne zaman gerçekleşeceğini tanımlar. Toplayıcılar (kavram), verilerin bu tetikleyicilere göre nasıl işleneceğini tanımlar. İfadeler (kavram), koşulları ve toplama mantığını tetiklemek için önemli olduğundan bu bölümde önce ifadelerin nasıl yazılacağı açıklanmaktadır.

İfadeler

İfadeler, okunabilir bir söz dizimi kullanarak hesaplamalar ve koşullar tanımlamanıza olanak tanır. MCG, bu dizeleri cihaz üzerinde değerlendirme için optimize edilmiş, yürütülebilir bir biçimde derler.

İfadeler; aritmetik hesaplamaları, mantıksal koşulları ve veri karşılaştırmalarını ifade edebilir. Operatörler ve işlevler dahil olmak üzere söz diziminin tamamı için İfadeler söz dizimi konusuna bakın.

Veri güncelliği: Bir ifade bir veri kaynağına eriştiğinde, alma davranışı bağlantı türüne bağlıdır:

• SUBSCRIPTION: Telemetri hizmeti tarafından önbelleğe alınan son alınan mesajı kullanır. (Not: sub_sampling_interval_ms ayarlanmışsa bu, yayınlanan en son mesajdan farklı olabilir.)
• ON_DEMAND: Hizmetten yeni mesajı getirmek için hemen bir çağrı tetikler.

Tür kısıtlamaları

• Diziler: Doğrudan dizi dizini erişimi (örneğin, my_data_source.my_array[0]) desteklenmez.
• Tür güvenliği: Uyumlu türleri karşılaştırdığınızdan emin olun (örneğin, bir dize alanını bir tamsayı listesiyle karşılaştırmayın).

Tetikleyiciler: İşlemlerin ne zaman gerçekleşeceğini tanımlayın

Tetikleyiciler, işlemlerin ne zaman yürütüleceğini tanımlar: bir toplayıcıyı değerlendirme, rapor oluşturma veya toplama yaşam döngüsünü kontrol etme. Tanımlanan tüm tetikleyicileri üst düzey triggers dizisine ekleyin.

Veri tetikleyici

Bir SUBSCRIPTION veri kaynağı yeni bir mesaj (kavram) sağladığında tetiklenir.

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

Periyodik tetikleyici

Düzenli aralıklarla tetiklenir (kavram).

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

Koşullu tetikleyici

Bir ifadenin (kavram) değerlendirilmesine göre tetiklenir. Değerlendirmesinin başlatılması için bir veya daha fazla üst tetikleyici gerekir. Bu genellikle ifadedeki veri kaynakları veya toplayıcılar için bir veri tetikleyicisi ya da verileri yoklamak için kullanılan periyodik bir tetikleyicidir.

Koşul türleri

condition_type sözlüğü, anahtar olarak mevcut koşul türlerinden yalnızca birini içermelidir. Daha fazla bilgi için Koşullu tetikleyiciler başlıklı makaleyi inceleyin.

Edge seçenekleri

rising_options ve falling_options nesnelerinde aşağıdaki alanlar bulunur. Sağlanmışsa ilgili geçiş, süre koşulunu karşılamalıdır. Belirtilen seçenekler olmadan geçişler hemen tetiklenir.

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

Toplayıcılar: Verilerin nasıl işleneceğini tanımlar.

Durumlu, ara veri işleme için bir toplayıcı kullanın (kavram). Bir toplayıcı tanımlayın ve aggregators dizisine ekleyin.

Bir toplayıcı, verileri dönüştürür ve diğer toplayıcılar ile raporlar için kullanılabilir hale getirir.

Mesaj oluşturucu

message_builder nesnesi, çıkış mesajı yapısını ve alanlarını hesaplamak için kullanılan toplama mantığını tanımlar. Hem Toplayıcılar'da hem de Rapor Yapılandırmaları'nda kullanılır.

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

Çıkış oluşturma

Telemetri kampanyanızın nihai çıkışını tanımlamak için report_configs dizisine (concept) nesneler ekleyin. Bu yapılandırmalar, işlenen verilerin nasıl paketleneceğini ve ne zaman oluşturulacağını belirler. Bileşenleri yeniden kullanmak için bir metrik yapılandırmasında birden fazla rapor yapılandırması tanımlayabilirsiniz.

trigger_names alanını kullanarak rapor oluşturmayı kontrol edebilirsiniz. Ayrıca, yapılandırma etkinleştirildiğinde hemen rapor oluşturmak için report_initial, veri toplama işlemi kesintiye uğradığında ise nihai rapor oluşturmak için report_incomplete simgesini kullanabilirsiniz.

Not: İşlemeyi çıkışa bağlamak için, bir toplayıcıdan önceden hesaplanmış değerleri okumak üzere none toplama türünü (@type: "none") kullanın. Raporlar genellikle durumsuz anlık görüntüler olduğundan bu, karmaşık durumlu mantığı toplayıcılar içinde tutar ve raporları biçimlendirme için ayırır.

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

Üst düzey alanlar

data_sources, aggregators, triggers ve report_configs dizilerine ek olarak, metrik yapılandırmasının açıklaması için sinyal kataloğuna referans verilmesi gerekir. Belirli bir UUID atamak ve koleksiyon yaşam döngüsünü yönetmek için isteğe bağlı alanları da ekleyebilirsiniz.

UUID'yi ayarlama

Her MetricsConfig için Evrensel Olarak Benzersiz Tanımlayıcı (UUID) gerekir. existing_uuid sağlarsanız MCG bunu kullanır. Aksi takdirde rastgele bir kimlik oluşturulur. Dağıtımlar ve araçlar arasında tutarlılık sağlamak için existing_uuid belirtin.

Dize, yalnızca küçük harf içeren geçerli bir kısa çizgili UUID olmalıdır.

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

Sinyal tanımları

MCG, sinyal adlarını ve türlerini doğrulamak için bir Araç Sinyali Kataloğu'na erişim gerektirir. Bu, VSIDL FileDescriptorSet tanımlarınızı .proto içeren bir protobuf'tur (paketlenmiş ve MCG'ye yüklenmiş). Katalog oluşturma ve yüklemeyle ilgili ayrıntılar için Araç Sinyali Katalogları başlıklı makaleyi inceleyin.

JSON nesnesinin vs_version alanında katalog sürümünü belirtin:

"vs_version": "v1.0",

Yaşam döngüsü tetikleyicilerini tanımlama

Bir telemetri kampanyası bağlamında, MetricsConfig yaşam döngüsü, verilerin ne zaman kaydedileceğini belirler. Kampanya yönetim sistemi, yapılandırmayı cihaza dağıtıp etkinleştirirken bu dağıtımda verilerin ne zaman toplanacağını hassas bir şekilde kontrol etmek için yaşam döngüsü tetikleyicilerini kullanabilirsiniz.

Bu sayede, yapılandırmayı devre dışı bırakmanıza gerek kalmadan veri toplamayı araç kullanım kalıplarıyla (ör. "Seyahat" (IgnitionOn - IgnitionOff) veya "Şarj Oturumu") uyumlu hale getirebilirsiniz.

• Oturum Kontrolü (Başlat/Duraklat): Toplamanın ne zaman gerçekleşeceğini kontrol etmek için start_trigger_name ve stop_trigger_name öğelerini kullanın. Örneğin, verileri yalnızca araç sürülürken toplamak için başlangıç tetikleyicisi olarak IgnitionOn, durdurma tetikleyicisi olarak IgnitionOff öğesini kullanın. Yapılandırma cihazda etkin kalır ancak durdurma tetikleyicisi etkinleştiğinde etkili bir şekilde "duraklatılır" (toplama ve işleme durdurulur) ve yalnızca başlangıç tetikleyicisi tekrar etkinleştiğinde devam eder.

  Önemli: Bu işlem yalnızca toplamayı duraklatır. Mantıksal pencereleri tanımlamaz, veri kümelerini ayırmaz veya başka bir yan etkisi olmaz. Toplama duraklatıldığında ya da devam ettirildiğinde toplayıcı değerleri sıfırlanmaz.

• Tek seferlik algılama (Tamamlama): Yapılandırma yalnızca bir kez çalıştırılmalıysa (örneğin, belirli bir hata kodunun ilk oluşumunu algılamak için) ve kampanya teknik olarak hâlâ etkin olsa bile o cihazda kalıcı olarak devre dışı bırakılmalıysa deactivate_trigger_name öğesini kullanın.

Yaşam döngüsü tetikleyicileri belirtmezseniz yapılandırma kampanya tarafından etkinleştirildiğinde veri toplama işlemi hemen başlar ve kampanya sona erene kadar kesintisiz olarak devam eder.

Gelişmiş: Özel proto tanımları

İki temel durumda, Çoklu Müşteri Yapılandırması'nın bir metrik yapılandırmasının açıklamasındaki tüm mesaj türlerini anlaması için vs_version tek başına yeterli değildir:

1. Tür çıkarımı hatası: source_identifier biçiminde açıklandığı gibi, source_identifier FQIN veya özel ad kullandığında MCG türü çıkaramaz.
2. Özel mesajlar: Metrik yapılandırma açıklaması, vs_version içinde belirtilen VSIDL kataloğunda bulunmayan protobuf mesajlarını kullanıyor.message_type, özel bir rapor biçimi için message_builder içinde ayarlandığında bu durum ortaya çıkar.

Bu gibi durumlarda, MCG'nin türleri tahmin etmesine yardımcı olmak için data_source_message_types, ileti tanımları sağlamak için ise descriptor_protos kullanın.

data_source_message_types

source_identifier dizesini tam nitelikli protobuf mesaj türüyle eşleyin. data_source_message_types içindeki anahtar, data_sources girişindeki source_identifier değeriyle eşleşmelidir:

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

descriptor_protos

data_source_message_types veya message_builder içinde kullanılan ve yapılandırılmış vs_version içinde bulunmayan tüm mesaj türleri için tanımlar sağlayın.

descriptor_protos dizisinde base64 olarak kodlanmış bir descriptorpb.FileDescriptorSet iletin. Bunu, Protobuf derleyici protoc kullanılarak .proto dosyalarından oluşturun.

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

Referans şablonu

API tanımı için MCG API referansı'na bakın.

Aşağıdaki bölümlerde, metrik yapılandırmasının açıklamasıyla ilgili eksiksiz bir referans verilmektedir. Bu referansı, kendi metrik yapılandırması açıklamanızı oluşturmak için kılavuz olarak kullanın.

Üst düzey alanlar

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

Giriş: veri kaynakları ve toplayıcılar

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

Mantık ve işleme: tetikleyiciler

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

Çıkış: rapor yapılandırmaları

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

İfadeler söz dizimi