יצירת כללי מדיניות להתראות באמצעות API

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

במסמך מתוארים הנושאים הבאים:

  • איך מדיניות ההתראות מיוצגת ב-Monitoring API.
  • סוגי התנאים ש-Monitoring API מספק עבור מדיניות התראות.
  • איך ליצור מדיניות התראות באמצעות Google Cloud CLI או ספריות לקוח.

התכונה הזו נתמכת רק בפרויקטים של Google Cloud . בהגדרות של מרכז האפליקציות, בוחרים את הפרויקט המארח או את פרויקט הניהול של מרכז האפליקציות.

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

המבנה AlertPolicy מגדיר את הרכיבים של מדיניות התראות. כשיוצרים מדיניות, מציינים ערכים בשדות AlertPolicy הבאים:

  • ‫displayName: תווית תיאורית של המדיניות.
  • ‫documentation: מומלץ להשתמש בשדה הזה כדי לספק מידע שיעזור למשיבים להתראה. מידע נוסף זמין במאמר הוספת הערות להתראות עם תיעוד שהוגדר על ידי המשתמש.

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

  • ‫conditions[]: מערך של מבני Condition.

  • ‫combiner: אופרטור לוגי שקובע איך לטפל בכמה תנאים.

  • ‫notificationChannels[]: מערך של שמות משאבים, שכל אחד מהם מזהה NotificationChannel.

  • ‫alertStrategy: מציין את הפרטים הבאים:

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

אפשר גם לציין את השדה severity כשמשתמשים ב-Cloud Monitoring API ובמסוף Google Cloud . בשדה הזה אפשר להגדיר את רמת החומרה של ההתראות. אם לא מציינים חומרה, Cloud Monitoring מגדיר את החומרה של מדיניות ההתראות ל-No Severity.

יש שדות נוספים שאפשר להשתמש בהם, בהתאם לתנאים שיוצרים.

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

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

projects/PROJECT_ID/alertPolicies/POLICY_ID

בביטוי הקודם:

  • ‫PROJECT_ID: מזהה הפרויקט. בהגדרות של מרכז האפליקציות, בוחרים את הפרויקט המארח או את פרויקט הניהול של מרכז האפליקציות.
  • POLICY_ID: המזהה של מדיניות ההתראות

סוגי התנאים ב-API

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

תנאים לכללי מדיניות התראות שמבוססים על מדדים

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

תנאים להערכת מדדים שמבוססים על מסננים

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

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

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

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

תנאים להערכת מדדים שמבוססים על PromQL

תנאי PrometheusQueryLanguageCondition משתמש בשאילתות של Prometheus Query Language‏ (PromQL) כדי לבחור נתונים של סדרות זמן ולבצע בהם מניפולציות לצורך מעקב. התנאי יכול לחשב יחס בין מדדים, להעריך השוואות בין מדדים ועוד.

אם משתמשים בתנאי PrometheusQueryLanguageCondition, הוא חייב להיות התנאי היחיד במדיניות ההתראות. מידע נוסף זמין במאמר בנושא כללי מדיניות ליצירת התראות עם PromQL.

תנאים להצגת התראות על יחסים

אפשר ליצור מדיניות התראות של סף מדד כדי לעקוב אחרי היחס בין שני מדדים. אפשר ליצור את כללי המדיניות האלה באמצעות סוג התנאי MetricThreshold או PrometheusQueryLanguageCondition. אפשר גם להשתמש ב-PromQL ישירות במסוף Google Cloud . אי אפשר ליצור או לנהל תנאים שמבוססים על יחסים באמצעות הממשק הגרפי ליצירת תנאי סף.

מומלץ להשתמש ב-PromQL כדי ליצור מדיניות התראות שמבוססת על יחסים. עם PromQL אפשר ליצור שאילתות חזקות וגמישות יותר מאלה שאפשר ליצור באמצעות סוג התנאי MetricTheshold ומסנני Monitoring. לדוגמה, באמצעות תנאי PrometheusQueryLanguageCondition, אפשר לחשב את היחס בין מדד מסוג gauge לבין מדד מסוג delta.

אם משתמשים בתנאי MetricThreshold, המונה והמכנה של היחס צריכים להיות בעלי אותו MetricKind. רשימה של מדדים והמאפיינים שלהם זמינה במאמר רשימות מדדים.

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

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

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

ההבדל במספר הערכים במרווחי ההתאמה המקבילים יכול להוביל לערכי יחס לא הגיוניים של error/total, כמו 1/0 או 2/1.

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

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

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

תנאי למדיניות התראות מבוססת-יומן

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

אל תנסו להשתמש בסוג התנאי LogMatch בשילוב עם מדדים מבוססי-יומן. מדיניות התראות שעוקבת אחרי מדדים מבוססי-יומנים היא מדיניות מבוססת-מדדים. מידע נוסף על בחירה בין מדיניות התראות שמנטרת מדדים מבוססי-יומן או רשומות ביומן זמין במאמר מעקב אחרי היומנים.

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

איך משייכים מדיניות התראות לאפליקציה ב-App Hub

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

כדי לשייך מדיניות התראות לאפליקציה ב-מרכז האפליקציות, צריך לצרף למדיניות תוויות עם המפתחות הבאים:

  • apphub_application_location
  • apphub_application_id
  • apphub_service_id או apphub_workload_id
לדוגמה, הקטע userLabels בייצוג ה-JSON של מדיניות התראות יכול להיראות כך: 

  "userLabels": {
    "apphub_service_id": "my-service-id",
    "apphub_application_location": "my-app-location",
    "apphub_application_id": "my-app"
  },

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

לפני שכותבים קוד שמשתמש בממשק ה-API, צריך:

  • חשוב להכיר את המושגים הכלליים ואת המינוח שמשמשים במדיניות בנושא התראות. מידע נוסף זמין במאמר סקירה כללית על התראות.
  • צריך לוודא ש-Cloud Monitoring API מופעל. מידע נוסף זמין במאמר בנושא הפעלת ה-API.
  • אם אתם מתכננים להשתמש בספריות לקוח, אתם צריכים להתקין את הספריות בשפות שבהן אתם רוצים להשתמש. פרטים נוספים זמינים במאמר ספריות לקוח. תמיכה ב-API להתראות זמינה רק בשפות C#,‏ Go,‏ Java,‏ Node.js ו-Python.

  • אם אתם מתכננים להשתמש ב-Google Cloud CLI, אתם צריכים להתקין אותו. עם זאת, אם אתם משתמשים ב-Cloud Shell, ‏ Google Cloud CLI כבר מותקן.

    במאמר הזה מופיעות גם דוגמאות לשימוש בממשק gcloud. שימו לב: כל הדוגמאות של gcloud מניחות שהפרויקט הנוכחי כבר הוגדר כיעד (gcloud config set project [PROJECT_ID]), ולכן הפעלות לא כוללות את הדגל --project המפורש. המזהה של הפרויקט הנוכחי בדוגמאות הוא a-gcp-project. בהגדרות של מרכז האפליקציות, בוחרים את הפרויקט המארח או את פרויקט הניהול של מרכז האפליקציות.

יצירת מדיניות התראות

כדי ליצור מדיניות התראות בפרויקט, משתמשים ב-method ‏alertPolicies.create. מידע על הפעלת השיטה הזו, על הפרמטרים שלה ועל נתוני התגובה מופיע בדף העזרה alertPolicies.create.

אפשר ליצור מדיניות מקובצי JSON או YAML. ‫Google Cloud CLI מקבל את הקבצים האלה כארגומנטים, ואפשר לקרוא קובצי JSON באופן פרוגרמטי, להמיר אותם לאובייקטים של AlertPolicy וליצור מהם כללי מדיניות באמצעות השיטה alertPolicies.create. אם יש לכם קובץ הגדרות JSON או YAML של Prometheus עם כלל התראות, אז ה-CLI של gcloud יכול להעביר אותו למדיניות התראות של Cloud Monitoring עם תנאי PromQL. מידע נוסף זמין במאמר בנושא העברה של כללי התראות ומקבלים מ-Prometheus.

כל מדיניות התראות שייכת לפרויקט היקף של היקף המדדים בפרויקט. כל פרויקט יכול להכיל עד 2,000 כללי מדיניות. כשמבצעים קריאות ל-API, צריך לספק 'מזהה פרויקט'. משתמשים במזהה של פרויקט ההיקף של היקף המדדים כערך. בדוגמאות האלה, המזהה של פרויקט ההיקף של היקף המדדים הוא a-gcp-project.

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

gcloud

כדי ליצור מדיניות התראות בפרויקט, משתמשים בפקודה gcloud monitoring policies create. בדוגמה הבאה נוצרת מדיניות התראות ב-a-gcp-project מהקובץ rising-cpu-usage.json:

gcloud monitoring policies create --policy-from-file="rising-cpu-usage.json"

אם הפקודה מסתיימת ללא שגיאות, היא מחזירה את השם של המדיניות החדשה, למשל:

Created alert policy [projects/a-gcp-project/alertPolicies/12669073143329903307].

הקובץ rising-cpu-usage.json מכיל את ה-JSON של מדיניות עם שם התצוגה 'שיעור שינוי גבוה של CPU'. פרטים על המדיניות הזו זמינים במאמר מדיניות שיעור השינוי.

מידע נוסף מופיע במפרט של השיטה ב-gcloud monitoring policies create.

C#

כדי לבצע אימות ב-Monitoring, צריך להגדיר את Application Default Credentials. מידע נוסף זמין במאמר הגדרת אימות לסביבת פיתוח מקומית. 

static void RestorePolicies(string projectId, string filePath)
{
    var policyClient = AlertPolicyServiceClient.Create();
    var channelClient = NotificationChannelServiceClient.Create();
    List<Exception> exceptions = new List<Exception>();
    var backup = JsonConvert.DeserializeObject<BackupRecord>(
        File.ReadAllText(filePath), new ProtoMessageConverter());
    var projectName = new ProjectName(projectId);
    bool isSameProject = projectId == backup.ProjectId;
    // When a channel is recreated, rather than updated, it will get
    // a new name.  We have to update the AlertPolicy with the new
    // name.  Track the names in this map.
    var channelNameMap = new Dictionary<string, string>();
    foreach (NotificationChannel channel in backup.Channels)
    {
    }
    foreach (AlertPolicy policy in backup.Policies)
    {
        string policyName = policy.Name;
        // These two fields cannot be set directly, so clear them.
        policy.CreationRecord = null;
        policy.MutationRecord = null;
        // Update channel names if the channel was recreated with
        // another name.
        for (int i = 0; i < policy.NotificationChannels.Count; ++i)
        {
            if (channelNameMap.ContainsKey(policy.NotificationChannels[i]))
            {
                policy.NotificationChannels[i] =
                    channelNameMap[policy.NotificationChannels[i]];
            }
        }
        try
        {
            Console.WriteLine("Updating policy.\n{0}",
                policy.DisplayName);
            bool updated = false;
            if (isSameProject)
                try
                {
                    policyClient.UpdateAlertPolicy(null, policy);
                    updated = true;
                }
                catch (Grpc.Core.RpcException e)
                when (e.Status.StatusCode == StatusCode.NotFound)
                { }
            if (!updated)
            {
                // The policy no longer exists.  Recreate it.
                policy.Name = null;
                foreach (var condition in policy.Conditions)
                {
                    condition.Name = null;
                }
                policyClient.CreateAlertPolicy(projectName, policy);
            }
            Console.WriteLine("Restored {0}.", policyName);
        }
        catch (Exception e)
        {
            // If one failed, continue trying to update the others.
            exceptions.Add(e);
        }
    }
    if (exceptions.Count > 0)
    {
        throw new AggregateException(exceptions);
    }
}

Go

כדי לבצע אימות ב-Monitoring, צריך להגדיר את Application Default Credentials. מידע נוסף זמין במאמר הגדרת אימות לסביבת פיתוח מקומית. 


// restorePolicies updates the project with the alert policies and
// notification channels in r.
func restorePolicies(w io.Writer, projectID string, r io.Reader) error {
	b := backup{}
	if err := json.NewDecoder(r).Decode(&b); err != nil {
		return err
	}
	sameProject := projectID == b.ProjectID

	ctx := context.Background()

	alertClient, err := monitoring.NewAlertPolicyClient(ctx)
	if err != nil {
		return err
	}
	defer alertClient.Close()
	channelClient, err := monitoring.NewNotificationChannelClient(ctx)
	if err != nil {
		return err
	}
	defer channelClient.Close()

	// When a channel is recreated, rather than updated, it will get
	// a new name.  We have to update the AlertPolicy with the new
	// name.  channelNames keeps track of the new names.
	channelNames := make(map[string]string)
	for _, c := range b.Channels {
		fmt.Fprintf(w, "Updating channel %q\n", c.GetDisplayName())
		c.VerificationStatus = monitoringpb.NotificationChannel_VERIFICATION_STATUS_UNSPECIFIED
		updated := false
		if sameProject {
			req := &monitoringpb.UpdateNotificationChannelRequest{
				NotificationChannel: c.NotificationChannel,
			}
			_, err := channelClient.UpdateNotificationChannel(ctx, req)
			if err == nil {
				updated = true
			}
		}
		if !updated {
			req := &monitoringpb.CreateNotificationChannelRequest{
				Name:                "projects/" + projectID,
				NotificationChannel: c.NotificationChannel,
			}
			oldName := c.GetName()
			c.Name = ""
			newC, err := channelClient.CreateNotificationChannel(ctx, req)
			if err != nil {
				return err
			}
			channelNames[oldName] = newC.GetName()
		}
	}

	for _, policy := range b.AlertPolicies {
		fmt.Fprintf(w, "Updating alert %q\n", policy.GetDisplayName())
		policy.CreationRecord = nil
		policy.MutationRecord = nil
		for i, aChannel := range policy.GetNotificationChannels() {
			if c, ok := channelNames[aChannel]; ok {
				policy.NotificationChannels[i] = c
			}
		}
		updated := false
		if sameProject {
			req := &monitoringpb.UpdateAlertPolicyRequest{
				AlertPolicy: policy.AlertPolicy,
			}
			_, err := alertClient.UpdateAlertPolicy(ctx, req)
			if err == nil {
				updated = true
			}
		}
		if !updated {
			req := &monitoringpb.CreateAlertPolicyRequest{
				Name:        "projects/" + projectID,
				AlertPolicy: policy.AlertPolicy,
			}
			if _, err = alertClient.CreateAlertPolicy(ctx, req); err != nil {
				log.Fatal(err)
			}
		}
	}
	fmt.Fprintf(w, "Successfully restored alerts.")
	return nil
}

Java

כדי לבצע אימות ב-Monitoring, צריך להגדיר את Application Default Credentials. מידע נוסף זמין במאמר הגדרת אימות לסביבת פיתוח מקומית. 

private static void restoreRevisedPolicies(
    String projectId, boolean isSameProject, List<AlertPolicy> policies) throws IOException {
  try (AlertPolicyServiceClient client = AlertPolicyServiceClient.create()) {
    for (AlertPolicy policy : policies) {
      if (!isSameProject) {
        policy = client.createAlertPolicy(ProjectName.of(projectId), policy);
      } else {
        try {
          client.updateAlertPolicy(null, policy);
        } catch (Exception e) {
          policy =
              client.createAlertPolicy(
                  ProjectName.of(projectId), policy.toBuilder().clearName().build());
        }
      }
      System.out.println(String.format("Restored %s", policy.getName()));
    }
  }
}

Node.js

כדי לבצע אימות ב-Monitoring, צריך להגדיר את Application Default Credentials. מידע נוסף זמין במאמר הגדרת אימות לסביבת פיתוח מקומית. 

const fs = require('fs');

// Imports the Google Cloud client library
const monitoring = require('@google-cloud/monitoring');

// Creates a client
const client = new monitoring.AlertPolicyServiceClient();

async function restorePolicies() {
  // Note: The policies are restored one at a time due to limitations in
  // the API. Otherwise, you may receive a 'service unavailable'  error
  // while trying to create multiple alerts simultaneously.

  /**
   * TODO(developer): Uncomment the following lines before running the sample.
   */
  // const projectId = 'YOUR_PROJECT_ID';

  console.log('Loading policies from ./policies_backup.json');
  const fileContent = fs.readFileSync('./policies_backup.json', 'utf-8');
  const policies = JSON.parse(fileContent);

  for (const index in policies) {
    // Restore each policy one at a time
    let policy = policies[index];
    if (await doesAlertPolicyExist(policy.name)) {
      policy = await client.updateAlertPolicy({
        alertPolicy: policy,
      });
    } else {
      // Clear away output-only fields
      delete policy.name;
      delete policy.creationRecord;
      delete policy.mutationRecord;
      policy.conditions.forEach(condition => delete condition.name);

      policy = await client.createAlertPolicy({
        name: client.projectPath(projectId),
        alertPolicy: policy,
      });
    }

    console.log(`Restored ${policy[0].name}.`);
  }
  async function doesAlertPolicyExist(name) {
    try {
      const [policy] = await client.getAlertPolicy({
        name,
      });
      return policy ? true : false;
    } catch (err) {
      if (err && err.code === 5) {
        // Error code 5 comes from the google.rpc.code.NOT_FOUND protobuf
        return false;
      }
      throw err;
    }
  }
}
restorePolicies();

PHP

כדי לבצע אימות ב-Monitoring, צריך להגדיר את Application Default Credentials. מידע נוסף זמין במאמר הגדרת אימות לסביבת פיתוח מקומית. 

use Google\Cloud\Monitoring\V3\AlertPolicy;
use Google\Cloud\Monitoring\V3\AlertPolicy\Condition;
use Google\Cloud\Monitoring\V3\AlertPolicy\Condition\MetricThreshold;
use Google\Cloud\Monitoring\V3\AlertPolicy\ConditionCombinerType;
use Google\Cloud\Monitoring\V3\Client\AlertPolicyServiceClient;
use Google\Cloud\Monitoring\V3\ComparisonType;
use Google\Cloud\Monitoring\V3\CreateAlertPolicyRequest;
use Google\Protobuf\Duration;

/**
 * @param string $projectId Your project ID
 */
function alert_create_policy($projectId)
{
    $alertClient = new AlertPolicyServiceClient([
        'projectId' => $projectId,
    ]);
    $projectName = 'projects/' . $projectId;

    $policy = new AlertPolicy();
    $policy->setDisplayName('Test Alert Policy');
    $policy->setCombiner(ConditionCombinerType::PBOR);
    /** @see https://cloud.google.com/monitoring/api/resources for a list of resource.type */
    /** @see https://cloud.google.com/monitoring/api/metrics_gcp for a list of metric.type */
    $policy->setConditions([new Condition([
        'display_name' => 'condition-1',
        'condition_threshold' => new MetricThreshold([
            'filter' => 'resource.type = "gce_instance" AND metric.type = "compute.googleapis.com/instance/cpu/utilization"',
            'duration' => new Duration(['seconds' => '60']),
            'comparison' => ComparisonType::COMPARISON_LT,
        ])
    ])]);
    $createAlertPolicyRequest = (new CreateAlertPolicyRequest())
        ->setName($projectName)
        ->setAlertPolicy($policy);

    $policy = $alertClient->createAlertPolicy($createAlertPolicyRequest);
    printf('Created alert policy %s' . PHP_EOL, $policy->getName());
}

Python

כדי לבצע אימות ב-Monitoring, צריך להגדיר את Application Default Credentials. מידע נוסף זמין במאמר הגדרת אימות לסביבת פיתוח מקומית. 

def restore(project_name, backup_filename):
    """Restore alert policies in a project.

    Arguments:
        project_name (str): The Google Cloud Project to use. The project name
            must be in the format - 'projects/<PROJECT_NAME>'.
        backup_filename (str): Name of the file (along with its path) from
            which the alert policies will be restored.
    """
    print(
        "Loading alert policies and notification channels from {}.".format(
            backup_filename
        )
    )
    record = json.load(open(backup_filename, "rt"))
    is_same_project = project_name == record["project_name"]
    # Convert dicts to AlertPolicies.
    policies_json = [json.dumps(policy) for policy in record["policies"]]
    policies = [
        monitoring_v3.AlertPolicy.from_json(policy_json)
        for policy_json in policies_json
    ]
    # Convert dicts to NotificationChannels
    channels_json = [json.dumps(channel) for channel in record["channels"]]
    channels = [
        monitoring_v3.NotificationChannel.from_json(channel_json)
        for channel_json in channels_json
    ]

    # Restore the channels.
    channel_client = monitoring_v3.NotificationChannelServiceClient()
    channel_name_map = {}

    for channel in channels:
        updated = False
        print("Updating channel", channel.display_name)
        # This field is immutable and it is illegal to specify a
        # non-default value (UNVERIFIED or VERIFIED) in the
        # Create() or Update() operations.
        channel.verification_status = (
            monitoring_v3.NotificationChannel.VerificationStatus.VERIFICATION_STATUS_UNSPECIFIED
        )

        if is_same_project:
            try:
                channel_client.update_notification_channel(notification_channel=channel)
                updated = True
            except google.api_core.exceptions.NotFound:
                pass  # The channel was deleted.  Create it below.

        if not updated:
            # The channel no longer exists.  Recreate it.
            old_name = channel.name
            del channel.name
            new_channel = channel_client.create_notification_channel(
                name=project_name, notification_channel=channel
            )
            channel_name_map[old_name] = new_channel.name

    # Restore the alerts
    alert_client = monitoring_v3.AlertPolicyServiceClient()

    for policy in policies:
        print("Updating policy", policy.display_name)
        # These two fields cannot be set directly, so clear them.
        del policy.creation_record
        del policy.mutation_record

        # Update old channel names with new channel names.
        for i, channel in enumerate(policy.notification_channels):
            new_channel = channel_name_map.get(channel)
            if new_channel:
                policy.notification_channels[i] = new_channel

        updated = False

        if is_same_project:
            try:
                alert_client.update_alert_policy(alert_policy=policy)
                updated = True
            except google.api_core.exceptions.NotFound:
                pass  # The policy was deleted.  Create it below.
            except google.api_core.exceptions.InvalidArgument:
                # Annoying that API throws InvalidArgument when the policy
                # does not exist.  Seems like it should throw NotFound.
                pass  # The policy was deleted.  Create it below.

        if not updated:
            # The policy no longer exists.  Recreate it.
            old_name = policy.name
            del policy.name
            for condition in policy.conditions:
                del condition.name
            policy = alert_client.create_alert_policy(
                name=project_name, alert_policy=policy
            )
        print("Updated", policy.name)

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

הגדרה של התראות חוזרות למדיניות התראות שמבוססת על מדדים

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

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

  • ‫renotifyInterval: המרווח בשניות בין התראות חוזרות.

    אם משנים את הערך של השדה renotifyInterval כשמתקבלת התראה על מדיניות ההתראות, קורה אחד מהדברים הבאים:

    • מדיניות ההתראות שולחת התראה נוספת.
    • מדיניות ההתראות מפעילה מחדש את תקופת המרווח.

  • ‫notificationChannelNames: מערך של שמות משאבים של ערוצי התראות, שהם מחרוזות בפורמט projects/PROJECT_ID/notificationChannels/CHANNEL_ID, כאשר CHANNEL_ID הוא ערך מספרי. במאמר רשימת ערוצי התראות בפרויקט מוסבר איך לאחזר את מזהה הערוץ.

לדוגמה, בדוגמת ה-JSON הבאה מוצגת אסטרטגיית התראה שהוגדרה לשליחת התראות חוזרות כל 1,800 שניות (30 דקות) לערוץ התראות אחד:

  "alertStrategy": {
    "notificationChannelStrategy": [
      {
        "notificationChannelNames": [
          "projects/PROJECT_ID/notificationChannels/CHANNEL_ID"
        ],
        "renotifyInterval": "1800s"
      }
    ]
  }

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

המאמרים הבאים