פורמט JSON של בקשה ליצירת הגדרות של מדדים

במדריך הזה מפורט פורמט בקשת ה-JSON לנקודת הקצה /api/v1/generate_metrics_config של הכלי Metrics Configuration Generator (מחולל הגדרות מדדים, MCG). הפורמט הזה מאפשר להגדיר קמפיין טלמטריה – לציין איסוף נתונים, עיבוד במכשיר ויצירת דוחות – במבנה שקריא לאנשים.

הכלי MCG מאמת את אובייקט ה-JSON הזה, בודק אם יש בעיות כמו אי התאמות בסוגים, תלות מעגלית או הפניות לא מוגדרות, ואז מהדר אותו להודעת MetricsConfig מאגר אחסון לפרוטוקולים (protobuf). ההודעה הזו היא בפורמט בינארי ששירות הטלמטריה במכשיר מריץ כדי להפעיל את הקמפיין.MetricsConfig

דרישות מוקדמות: מומלץ להכיר סכימות JSON,‏ protobuf ומבני נתונים בסיסיים. סקירה כללית של המושגים מופיעה במאמר מושגים בנושא הגדרת מדדים.

איך כותבים תיאור של הגדרה

כדי לתכנן קמפיין לאיסוף מדדים, צריך לפעול לפי הרצף הלוגי הבא:

1. ציון מקורות נתונים: מגדירים מאיפה מגיעים הנתונים.
2. הגדרת לוגיקה ועיבוד: מגדירים כללים לקביעת הזמן שבו הנתונים ייאספו ולאופן העיבוד שלהם.
3. יצירת פלט: אריזת הנתונים המעובדים בהודעה סופית.
4. שדות ברמה העליונה: מוסיפים שדות ברמה העליונה כמו UUID,‏ signal definitions ו-lifecycle control.

ציון מקורות נתונים

טלמטריה תומכת באיסוף נתונים משירותי SDV (באמצעות SDV Middleware) וממפרסמים מבוססי-Configurable Publisher Registry.

• שירותי SDV (מבוססי pub/sub): הנתונים זמינים מערוצי pub/sub שמוגדרים ב-VSIDL.

• שירותי SDV (מבוססי RPC): הנתונים זמינים אם השירות חושף CreateSubscription או GetLatestMessage RPC.

• בעלי תוכן דיגיטלי שניתן להגדיר אותם ומבוססים על מאגר בעלי תוכן דיגיטלי: הנתונים זמינים אם האפליקציה נרשמת באמצעות IConfigurablePublisherRegistryממשק Android Binder או ספריית מאגר בעלי תוכן דיגיטלי שניתן להגדרה מתוך Telemetry SDK.

כדי להשתמש בנתונים ב-SDV, צריך להגדיר מקור נתונים (מושג) ולהוסיף אותו למערך data_sources.

לא כל האפשרויות זמינות לכל סוגי מקורות הנתונים. מידע מפורט זמין במדריך לשילוב מקורות נתונים.

הפורמט של source_identifier

שירות הטלמטריה מקבל כמה פורמטים של מזהי מקורות. מידע נוסף מופיע במאמר הגדרת מקור נתונים בהגדרות של מדדים.

‫MCG מסיק את סוג הודעת ה-protobuf מ-source_identifier רק אם הוא משתמש בפורמט של שם סוג היחידה. אם משתמשים ב-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") כדי לקרוא ערכים שחושבו מראש מתוך Aggregator. מכיוון שדוחות הם בדרך כלל תמונות מצב חסרות מצב, הפעולה הזו מאפשרת לשמור את הלוגיקה המורכבת של מצב בתוך Aggregators ולשמור את הדוחות לעיצוב.

{
  "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, הכלי להמרת מטבעות משתמש בו. אחרת, המערכת יוצרת סיסמה אקראית. כדי לשמור על עקביות בין פריסות וכלים, צריך לציין 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 אם ההגדרה צריכה לפעול רק פעם אחת (לדוגמה, כדי לזהות את המופע הראשון של קוד תקלה ספציפי) ואז להשבית את עצמה באופן קבוע במכשיר הזה, גם אם הקמפיין עדיין פעיל מבחינה טכנית.

אם לא מציינים טריגרים של מחזור חיים, איסוף הנתונים מתחיל מיד כשהקמפיין מפעיל את ההגדרה, וממשיך ברציפות עד שהקמפיין מסתיים.

מתקדם: הגדרות proto מותאמות אישית

בשני מקרים עיקריים, vs_version לבד לא מספיק כדי ש-MCG יבין את כל סוגי ההודעות בתיאור של הגדרת מדדים:

1. כשל בהסקת סוג: כפי שמוסבר בsource_identifierפורמט, MCG לא יכול להסיק את הסוג כשמשתמשים ב-FQIN או בשם מותאם אישית.source_identifier
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 שהוגדר.

מעבירים descriptorpb.FileDescriptorSet בקידוד Base64 במערך descriptor_protos. אפשר ליצור את הקובץ הזה מקובצי .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 מופיעה במאמר MCG API reference.

בקטעים הבאים מופיע תיאור מלא של הגדרת מדדים. אפשר להשתמש בו כמדריך ליצירת תיאור משלכם של הגדרת מדדים.

שדות ברמה העליונה

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

תחביר של ביטויים