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/v2/generate_metrics_config uç noktası için JSON istek biçimi ayrıntılı olarak açıklanmaktadır. Bu biçim, bir telemetri kampanyası tanımlamanıza olanak tanır. Bu sayede veri toplama, cihaz üzerinde işleme ve rapor oluşturma işlemlerini okunabilir bir yapıda belirtebilirsiniz.

MCG aracı bu JSON nesnesini doğrular, tür uyuşmazlıkları, döngüsel bağımlılıklar veya tanımlanmamış referanslar gibi sorunları kontrol eder ve ardından bir MetricsConfig protokol arabelleği (protobuf) mesajı olarak derler. Bu MetricsConfig mesajı, cihaz üzerindeki Telemetri hizmetinin kampanyayı çalıştırmak için 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 bir genel bakış için Metrik yapılandırma kavramları başlıklı makaleyi inceleyin.

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

Metrik toplama kampanyası tasarlamak için aşağıdaki mantıksal akışı izleyin:

1. Veri kaynaklarını belirtme: Verilerinizin nereden geldiğini 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 paketler.
4. Üst düzey alanlar: UUID, sinyal tanımları ve yaşam döngüsü kontrolü gibi üst düzey alanlar ekleyin.

Veri kaynaklarını belirtme

Telemetri, SDV hizmetlerinden (SDV ara katman yazılımı aracılığıyla) ve yapılandırılabilir yayıncı kayıt defteri 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ındaki IConfigurablePublisherRegistryAndroid Binder arayüzünü veya Yapılandırılabilir Yayıncı Kayıt Defteri kitaplığını kullanarak kaydolursa veriler kullanılabilir.

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

Tüm seçenekler her veri kaynağı türü için kullanılamaz. Ayrıntılı bilgi için veri kaynağı entegrasyon 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 birim türü adı biçimini kullanıyorsa source_identifier öğesinden çıkarır. FQIN veya özel bir ad (Yapılandırılabilir Yayıncı Kayıt Defteri'nden) kullanırsanız MCG türü tahmin edemez. Bu durumlarda data_source_message_types sağlamanız gerekir. Tür, kataloğunuzda yoksa tanımını descriptor_protos içinde de 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 yönetilir: Tetikleyiciler (concept) 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), tetikleyici koşulları ve toplama mantığı için önemli olduğundan bu bölümde öncelikle 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 tam söz dizimi için İfadelerin söz dizimi başlıklı makaleyi inceleyin.

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ı almak için anında bir çağrı tetikler.

Tür kısıtlamaları

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

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

Tetikleyiciler, işlemlerin ne zaman yürütüleceğini tanımlar: 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 değerlendirmesine göre tetiklenir (kavram). Değerlendirmesinin başlaması 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 veri yoklamak için periyodik bir tetikleyicidir.

Koşul türleri

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

Kenar seçenekleri

rising_options ve falling_options nesneleri aşağıdaki alanlara sahiptir. Sağlanıyorsa ilgili geçiş, süre şartını karşılamalıdır. Belirli seçenekleri olmayan 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ımlama

Durum bilgisi olan ara veri işleme için bir toplayıcı kullanma (kavram) Bir toplayıcı tanımlayın ve aggregators dizisine ekleyin.

Toplayıcı, verileri dönüştürür ve diğer toplayıcılar ile raporların kullanımına sunar.

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ılarda 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 (kavram) 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.

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

Not: İşlemeyi çıkışa bağlamak için none toplama türünü (@type: "none") kullanarak önceden hesaplanan değerleri bir toplayıcıdan okuyun. Raporlar genellikle durum bilgisi olmayan anlık görüntüler olduğundan, bu sayede karmaşık durum bilgisi olan mantık toplayıcılarda tutulur ve raporlar biçimlendirme için ayrılı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 bir evrensel benzersiz tanımlayıcı (UUID) gerekir. existing_uuid sağlarsanız MCG bunu kullanır. Aksi takdirde rastgele bir ad oluşturulur. Dağıtımlar ve araçlar arasında tutarlılık sağlamak için bir 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ç sinyal kataloğuna erişim gerektirir. Bu, VSIDL .proto tanımlarınızı (paketlenmiş ve MCG'ye yüklenmiş) içeren bir protobuf FileDescriptorSet dosyasıdır. Katalog oluşturma ve yükleme hakkında ayrıntılı bilgi için Araç Sinyali Katalogları başlıklı makaleyi inceleyin.

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

"vs_version": "v1.0",

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

Telemetri kampanyası bağlamında, MetricsConfig yaşam döngüsü, verilerin ne zaman kaydedileceğini belirler. Kampanya yönetim sistemi, yapılandırmayı cihazda dağıtıp etkinleştirirken yaşam döngüsü tetikleyicilerini kullanarak bu dağıtım kapsamında verilerin ne zaman toplanacağını hassas bir şekilde kontrol edebilirsiniz.

Bu sayede, yapılandırmayı devre dışı bırakmanıza gerek kalmadan veri toplamayı "Gezi" (IgnitionOn - IgnitionOff) veya "Şarj Oturumu" gibi araç kullanım kalıplarıyla 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 simgelerini kullanın. Örneğin, yalnızca araç sürülürken veri toplamak için başlatma tetikleyicisi olarak IgnitionOn, durdurma tetikleyicisi olarak IgnitionOff kullanın. Yapılandırma cihazda etkin kalır ancak durdurma tetikleyicisi etkinleştiğinde etkili bir şekilde "duraklatılır" (toplama ve işlemeyi durdurur) ve yalnızca başlatma tetikleyicisi tekrar etkinleştiğinde devam eder.

  Önemli: Bu işlem yalnızca veri toplamayı duraklatır. Mantıksal pencereler veya ayrı veri kümeleri tanımlamaz ya da başka yan etkilere neden olmaz. Toplayıcı değerleri, toplama işlemi duraklatıldığında veya devam ettirildiğinde sıfırlanmaz.

• Tek Seferlik Algılama (Son): Yapılandırmanın yalnızca bir kez çalışması (örneğin, belirli bir hata kodunun ilk kez oluştuğunu algılamak için) ve ardından kampanya teknik olarak hâlâ etkin olsa bile söz konusu cihazda kendisini kalıcı olarak devre dışı bırakması gerekiyorsa deactivate_trigger_name değerini kullanın.

Herhangi bir yaşam döngüsü tetikleyicisi belirtmezseniz veri toplama işlemi, yapılandırma kampanya tarafından etkinleştirildiğinde hemen başlar ve kampanya sona erene kadar devam eder.

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

İki ana durumda, MCG'nin 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çimi bölümünde açıklandığı gibi, source_identifier FQIN veya özel bir ad kullandığında MCG türü tahmin edemez.
2. Özel mesajlar: Metrik yapılandırma açıklamasında, vs_version içinde belirtilen VSIDL kataloğunda bulunmayan protobuf mesajları kullanılıyor. Bu durum, özel bir rapor biçimi için message_builder içinde message_type ayarlanırken gerçekleşir.

Bu gibi durumlarda, MCG'nin türleri tahmin etmesine yardımcı olmak için data_source_message_types, mesaj 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 ancak 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 kodlu bir descriptorpb.FileDescriptorSet iletin. Protobuf derleyicisi protoc kullanarak .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ının tam referansı verilmiştir. Bu örneği, kendi metrik yapılandırmanızı oluştururken kılavuz olarak kullanabilirsiniz.

Üst düzey alanlar

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

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

İfadelerin söz dizimi