מדדים מוגדרים על ידי המשתמש מהסוכן

במדריך הזה מוסבר איך להגדיר את סוכן Monitoring כך שיזהה את מדדי האפליקציה ויעביר אותם ל-Cloud Monitoring.

סוכן Monitoring הוא תוכנת דימון (daemon) של collectd. בנוסף לייצוא של מדדים רבים מוגדרים מראש של המערכת ומדדים של צד שלישי אל Cloud Monitoring, הסוכן יכול לייצא את מדדי האפליקציה collectd שלכם אל Monitoring בתור מדדים שהוגדרו על ידי המשתמש. תוספי collectd יכולים גם לייצא ל-Monitoring.

דרך נוספת לייצא מדדים של אפליקציות ל-Monitoring היא באמצעות StatsD. ‫Cloud Monitoring מספק הגדרת ברירת מחדל שממפה מדדי StatsD למדדים שהוגדרו על ידי המשתמש. אם אתם מרוצים מהמיפוי הזה, אין צורך לבצע את שלבי ההתאמה האישית שמתוארים בהמשך. מידע נוסף זמין במאמר בנושא תוסף StatsD.

מידע נוסף על מדדים זמין במאמרים הבאים:

הפונקציונליות הזו זמינה רק לסוכנים שפועלים ב-Linux. האפשרות הזו לא זמינה ב-Windows.

לפני שמתחילים

מתקינים את הסוכן העדכני ביותר של Monitoring במופע VM ומוודאים שהוא פועל. הוראות לעדכון הסוכן מופיעות במאמר בנושא עדכון הסוכן.
מגדירים את collectd כדי לקבל נתוני מעקב מהאפליקציה. ‫Collectd תומך במסגרות רבות של אפליקציות ובנקודות קצה סטנדרטיות של Monitoring באמצעות פלאגינים לקריאה. מוצאים פלאגין קריאה שמתאים לכם.
(אופציונלי) כדי להוסיף את מסמכי העזר של collectd של הסוכן לדפי man במערכת, מעדכנים את המשתנה MANPATH ומריצים את הפקודה mandb:
```
export MANPATH="$MANPATH:/opt/stackdriver/collectd/share/man"
sudo mandb
```
דפי ה-man מיועדים ל-stackdriver-collectd.

קבצים וספריות חשובים

הקבצים והספריות הבאים, שנוצרו בהתקנת הסוכן, רלוונטיים לשימוש בסוכן Monitoring ‏ (collectd):

/etc/stackdriver/collectd.conf: קובץ התצורה של collectd שבו משתמש הסוכן. עורכים את הקובץ הזה כדי לשנות את ההגדרות הכלליות.

הערה: סוכן המעקב לא משתמש בהגדרת ברירת המחדל של המערכת collectd,‏ /etc/collectd.conf.
/etc/stackdriver/collectd.d/: הספרייה של קובצי הגדרה שהמשתמשים הוסיפו. כדי לשלוח מדדים שהוגדרו על ידי המשתמש מהסוכן, צריך למקם בספרייה הזו את קובצי ההגדרות הנדרשים, שמפורטים בהמשך. לצורך תאימות לאחור, הסוכן מחפש גם קבצים ב-/opt/stackdriver/collectd/etc/collectd.d/.
/opt/stackdriver/collectd/share/man/*: התיעוד של גרסת הסוכן של collectd. אפשר להוסיף את הדפים האלה לקבוצת הדפים של man במערכת. פרטים נוספים מופיעים בקטע לפני שמתחילים.
/etc/init.d/stackdriver-agent: סקריפט ההפעלה של הסוכן.

איך Monitoring מטפל במדדים של collectd

כדי לספק רקע, סוכן Monitoring מעבד מדדים של collectd ושולח אותם אל Monitoring, שמתייחס לכל מדד כאל חבר באחת מהקטגוריות הבאות:

מדדים שהוגדרו על ידי המשתמש. מדדים של Collectd שיש להם מפתח מטא-נתונים stackdriver_metric_type ומקור נתונים יחיד מטופלים כמדדים שהוגדרו על ידי המשתמש ונשלחים אל Monitoring באמצעות השיטה projects.timeSeries.create ב-Monitoring API.
מדדים שנבחרו בקפידה. כל המדדים האחרים של collectd נשלחים אל Monitoring באמצעות API פנימי. רק המדדים שברשימת המדדים המיוחדים מתקבלים ומעובדים.
מדדים שהמערכת פסלה. מדדים שנאספים ולא מופיעים ברשימת המדדים הנבחרים או במדדים שהוגדרו על ידי המשתמש, נמחקים בשקט על ידי Monitoring. הסוכן עצמו לא יודע אילו מדדים מתקבלים או נפסלים.

כתיבת מדדים מוגדרים על ידי המשתמש באמצעות הסוכן

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

כדי שמדד collectd יטופל כמדד שהוגדר על ידי המשתמש, צריך להוסיף למדד את המטא-נתונים המתאימים:

‫stackdriver_metric_type : (חובה) שם המדד שמיוצא. לדוגמה: custom.googleapis.com/my_custom_metric.
‫label:[LABEL] : (אופציונלי) תוויות נוספות למדד המיוצא. לדוגמה, אם רוצים להגדיר תווית STRING של Monitoring בשם color, מפתח המטא-נתונים יהיה label:color והערך של המפתח יכול להיות "blue". אפשר להוסיף עד 10 תוויות לכל סוג מדד.

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

דוגמה

בדוגמה הזו ננטר חיבורים פעילים של Nginx משני שירותי Nginx:‏ my_service_a ו-my_service_b. אנחנו נשלח את הנתונים האלה ל-Monitoring באמצעות מדד שהוגדר על ידי המשתמש. אנחנו נבצע את הפעולות הבאות:

מזהים את מדדי collectd לכל שירות Nginx.
הגדרת תיאור מדד Monitoring.
מגדירים שרשרת מסננים של collectd כדי להוסיף מטא-נתונים למדדים של collectd, בהתאם לדרישות של סוכן המעקב.

מדדים נכנסים של collectd

המדדים ש-Collectd מצפה לקבל מורכבים מהרכיבים הבאים. חמשת הרכיבים הראשונים מרכיבים את המזהה של המדד ב-collectd:

    Host, Plugin, Plugin-instance, Type, Type-instance, [value]

בדוגמה הזו, המדדים שרוצים לשלוח כמדד מוגדר על ידי המשתמש כוללים את הערכים הבאים:

רכיב	ערכים צפויים
מארח	כל
פלאגין	`curl_json`
מופע של פלאגין	‫`nginx_my_service_a` או `nginx_my_service_b`¹
סוג	`gauge`
מופע של סוג	`active-connections`
`[value]`	כל ערך²

הערות:
¹ בדוגמה הזו, הערך הזה מקודד גם את האפליקציה (Nginx) וגם את שם השירות המקושר.‫
² הערך הוא בדרך כלל חותמת זמן ומספר עם דיוק כפול. המעקב מטפל בפרטים של פירוש סוגי הערכים השונים. הסוכן לניטור לא תומך בערכים מורכבים.

תיאור מדד של Monitoring וסדרת זמנים

בצד Monitoring, מעצבים מתאר מדד למדד שהוגדר על ידי המשתמש. המאפיין הבא הוא בחירה סבירה לנתונים בדוגמה הזו:

שם: custom.googleapis.com/nginx/active_connections
תוויות:
- ‫service_name (מחרוזת): השם של השירות שמחובר ל-Nginx.
סוג: GAUGE
טיפוס: DOUBLE

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

נתוני הסדרה העיתית של תיאור המדד הזה חייבים לכלול את המידע הבא, בגלל האופן שבו תיאור המדד מוגדר:

סוג המדד: custom.googleapis.com/nginx/active_connections
ערכים של תוויות מדדים:
- ‫service_name: "my_service_a" או "my_service_b"

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

שרשרת המסננים

יוצרים קובץ, /opt/stackdriver/collectd/etc/collectd.d/nginx_curl_json.conf, שמכיל את הקוד הבא:

LoadPlugin match_regex
LoadPlugin target_set
LoadPlugin target_replace

# Insert a new rule in the default "PreCache" chain, to divert your metrics.
PreCacheChain "PreCache"
<Chain "PreCache">
  <Rule "jump_to_custom_metrics_from_curl_json">
    # If the plugin name and instance match, this is PROBABLY a metric we're looking for:
    <Match regex>
      Plugin "^curl_json$"
      PluginInstance "^nginx_"
    </Match>
    <Target "jump">
      # Go execute the following chain; then come back.
      Chain "PreCache_curl_json"
    </Target>
  </Rule>
  # Continue processing metrics in the default "PreCache" chain.
</Chain>

# Following is a NEW filter chain, just for your metric.
# It is only executed if the default chain "jumps" here.
<Chain "PreCache_curl_json">

  # The following rule does all the work for your metric:
  <Rule "rewrite_curl_json_my_special_metric">
    # Do a careful match for just your metrics; if it fails, drop down
    # to the next rule:
    <Match regex>
      Plugin "^curl_json$"                   # Match on plugin.
      PluginInstance "^nginx_my_service_.*$" # Match on plugin instance.
      Type "^gauge$"                         # Match on type.
      TypeInstance "^active-connections$"    # Match on type instance.
    </Match>

    <Target "set">
      # Specify the metric descriptor type:
      MetaData "stackdriver_metric_type" "custom.googleapis.com/nginx/active_connections"
      # Specify a value for the "service_name" label; clean it up in the next Target:
      MetaData "label:service_name" "%{plugin_instance}"
    </Target>

    <Target "replace">
      # Remove the "nginx_" prefix in the service_name to get the real service name:
      MetaData "label:service_name" "nginx_" ""
    </Target>
  </Rule>

  # The following rule is run after rewriting your metric, or
  # if the metric wasn't one of your user-defined metrics. The rule returns
  # to the default "PreCache" chain. The default processing
  # will write all metrics to Cloud Monitoring,
  # which will drop any unrecognized metrics: ones that aren't
  # in the list of curated metrics and don't have
  # the user-defined metric metadata.
  <Rule "go_back">
    Target "return"
  </Rule>
</Chain>

טעינת ההגדרה החדשה

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

sudo service stackdriver-agent restart

המידע על המדדים שהוגדרו על ידי המשתמשים מתחיל לזרום אל Monitoring.

הפניות ושיטות מומלצות

תיאורי מדדים וסדרות זמן

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

תיאורי מדדים. מתאר מדד כולל את החלקים המשמעותיים הבאים:

סוג הטופס ‫custom.googleapis.com/[NAME1]/.../[NAME0]. לדוגמה:
```
custom.googleapis.com/my_measurement
custom.googleapis.com/instance/network/received_packets_count
custom.googleapis.com/instance/network/sent_packets_count
```
השמות המומלצים הם היררכיים, כדי שאנשים יוכלו לעקוב אחרי המדדים בקלות. שמות של סוגי מדדים לא יכולים להכיל מקפים. למידע על כללי מתן השמות המדויקים, אפשר לעיין במאמר מתן שמות לסוגי מדדים ולתוויות.
עד 10 תוויות לציון נתוני המדד, כמו device_name,‏ fault_type או response_code. הערכים של התוויות לא מצוינים בתיאור המדד.
הסוג וסוג הערך של נקודות הנתונים, כמו 'ערך מד מסוג double'. מידע נוסף זמין במאמרים MetricKind וValueType.

סדרות זמנים. נקודת נתונים של מדד כוללת את החלקים החשובים הבאים:

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

יצירת תיאורי מדדים

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

עם זאת, יש יתרונות ליצירת תיאור משלכם למדד:

מומלץ לכלול תיעוד מפורט של המדד והתוויות שלו.
אפשר לציין סוגים נוספים של מדדים. השילובים היחידים של (סוג, סוג) שנתמכים על ידי הסוכן הם (GAUGE, DOUBLE) ו-(CUMULATIVE, INT64). מידע נוסף זמין במאמר סוגי מדדים וסוגי ערכים.
אפשר לציין סוגי תוויות אחרים מלבד STRING.

אם כותבים נקודת נתונים ל-Monitoring שמשתמשת בסוג מדד שלא הוגדר, נוצר מתאר מדד חדש לנקודת הנתונים. התנהגות כזו עלולה להיות בעייתית כשמבצעים ניפוי באגים בקוד שכותב נתוני מדדים – איות שגוי של סוג המדד יוביל לתיאורי מדדים שגויים.

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

פרטים נוספים על יצירת תיאורי מדדים זמינים במאמר יצירת מדד.

תמחור

למידע על התמחור של Cloud Monitoring, אפשר לעיין בדף התמחור של Google Cloud Observability.

מגבלות

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

אם גיליתם שיצרתם תיאורי מדדים שאתם לא רוצים יותר, אתם יכולים למצוא ולמחוק את התיאורים באמצעות Monitoring API. מידע נוסף זמין במאמר projects.metricDescriptors.

פתרון בעיות

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

הפעלת write_log

התוסף write_log כלול בחבילה stackdriver-agent. כדי להפעיל את הפלאגין:

בתור root, עורכים את קובץ התצורה הבא:
```
/etc/stackdriver/collectd.conf
```
מיד אחרי LoadPlugin write_gcm, מוסיפים:
```
LoadPlugin write_log
```
מיד אחרי <Plugin "write_gcm">…</Plugin>, מוסיפים:
```
<Plugin "write_log">
  Format JSON
</Plugin>
```
מחפשים את <Target "write">…</Target> ואחרי כל Plugin "write_gcm", מוסיפים:
```
Plugin "write_log"
```
שומרים את השינויים ומפעילים מחדש את הסוכן:
```
sudo service stackdriver-agent restart
```

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

הפלט של write_log

אם השלב הקודם בוצע בהצלחה, הפלט של write_log יופיע ביומני המערכת:

‫Linux מבוסס Debian: /var/log/syslog
‫Linux שמבוסס על Red Hat: /var/log/messages

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

Dec  8 15:13:45 test-write-log collectd[1061]: write_log values:#012[{
    "values":[1933524992], "dstypes":["gauge"], "dsnames":["value"],
    "time":1481210025.252, "interval":60.000,
    "host":"test-write-log.c.test-write-log.internal",
    "plugin":"df", "plugin_instance":"udev", "type":"df_complex", "type_instance":"free"}]

Dec  8 15:13:45 test-write-log collectd[1061]: write_log values:#012[{
    "values":[0], "dstypes":["gauge"], "dsnames":["value"],
    "time":1481210025.252, "interval":60.000,
    "host":"test-write-log.c.test-write-log.internal",
    "plugin":"df", "plugin_instance":"udev", "type":"df_complex", "type_instance":"reserved"}]