יצירת מדדים שמוגדרים על ידי המשתמש באמצעות API

במסמך הזה מוסבר איך ליצור מדדים מוגדרים על ידי המשתמש ואיך לכתוב את נתוני המדדים האלה באמצעות Cloud Monitoring API. מדדים שהוגדרו על ידי המשתמש משתמשים באותם רכיבים שבהם משתמשים המדדים המובנים של Cloud Monitoring:

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

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

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

• יצירת מדדים של מונה
• יצירת מדדים של הפצה

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

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

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

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

כדי להשתמש ב-Cloud Monitoring, צריך ליצור Google Cloud פרויקט עם חיוב מופעל. כשצריך, מבצעים את הפעולות הבאות:

1. בדף לבחירת הפרויקט במסוף Google Cloud , בוחרים פרויקט ב- Google Cloud או יוצרים אותו.

   תפקידים שנדרשים כדי לבחור או ליצור פרויקט

   • Select a project (בחירת פרויקט): כדי לבחור פרויקט לא צריך תפקיד IAM ספציפי – אפשר לבחור כל פרויקט שהוקצה לכם בו תפקיד.
   • יצירת פרויקט: כדי ליצור פרויקט, צריך את התפקיד Project Creator (יצירת פרויקטים) (roles/resourcemanager.projectCreator), שכולל את ההרשאה resourcemanager.projects.create. איך מקצים תפקידים

   כניסה לדף לבחירת הפרויקט

2. מוודאים שהחיוב מופעל בפרויקט Google Cloud .

3. מוודאים ש-Monitoring API מופעל. פרטים נוספים זמינים במאמר בנושא הפעלת Monitoring API.
4. באפליקציות שפועלות מחוץ ל- Google Cloud, צריך לאמת את האפליקציה באמצעות Application Default Credentials (‏ADC) מקומיים. Google Cloud למידע נוסף אפשר לעיין במאמר הגדרת ADC לספק שירותי ענן מקומי או אחר.

יצירת סוג מדד מוגדר על ידי המשתמש

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

יצירה אוטומטית של מתארי מדדים

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

‫Cloud Monitoring יוצר MetricDescriptor חדש כשמתבצעת הפניה לאובייקט Metric שכולל שם של סוג מדד שלא קיים באובייקט TimeSeries שכלול בקריאה ל-timeSeries.create. ‫Cloud Monitoring משתמש בכללים הבאים כדי לאכלס את MetricDescriptor:

• ‫type: הסוג מועתק מהשדה type של אובייקט Metric.
• ‫name: השם נוצר ממזהה הפרויקט בהפעלת method ומערך type באובייקט Metric.
• ‫labels: התוויות שמופיעות באובייקט Metric. כל תיאור של תווית במדד החדש כולל את השדות הבאים:
  • ‫key: מפתח התווית באובייקט Metric.
  • valueType: STRING
  • ‫description: לא מוגדר
• ‫metricKind: סוג המדד מוגדר כ-GAUGE אלא אם מציינים את הפרמטר metricKind של אובייקט TimeSeries. כשמציינים את metricKind, המדד החדש מקבל את הסוג הזה. אפשר לציין רק את הסוגים GAUGE ו-CUMULATIVE.
• ‫valueType: סוג הערך נלקח מהערך המוקלד של Point שנכתב. סוג הערך חייב להיות BOOL,‏ INT64,‏ DOUBLE או DISTRIBUTION. כשמציינים סוג ערך בשדה valueType של TimeSeries, הסוג הזה צריך להיות זהה לסוג של Point.
• ‫unit: לא מוגדר
• description: "Auto created custom metric.".
• ‫displayName: לא מוגדר

בקריאה אחת של timeSeries.create, אפשר לכלול כמה אובייקטים של TimeSeries שמתייחסים לאותו סוג מדד שלא קיים. במקרה כזה, התוויות בתיאור המדד החדש הן איחוד של כל התוויות באובייקטים Metric בכל סדרות הזמן בקריאה הזו אל create.

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

יצירה ידנית של מתארי מדדים

כדי ליצור מתאר מדד:

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

   1. בוחרים שם מדד למדד שהוגדר על ידי המשתמש.

   2. בוחרים שם לתצוגה ותיאור למדד. השם המוצג משמש במסוף Google Cloud .

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

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

   5. בוחרים את התוויות של המדד – השמות, סוגי הערכים והתיאורים שלהן.

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

   • ‫aws_ec2_instance: מופע Amazon EC2.
   • ‫dataflow_job: משימת Dataflow.
   • ‫gae_instance: מופע של App Engine.
   • ‫gce_instance: מכונה של Compute Engine.
   • ‫generic_node: צומת מחשוב שצוין על ידי המשתמש.
   • ‫generic_task: משימה בהגדרת המשתמש.
   • ‫gke_container: מופע של קונטיינר GKE.
   • ‫global: משתמשים במשאב הזה כשאין סוג משאב אחר שמתאים. ברוב תרחישי השימוש, generic_node או generic_task הם אפשרויות טובות יותר מ-global.
   • ‫k8s_cluster: אשכול Kubernetes.
   • ‫k8s_container: קונטיינר Kubernetes.
   • ‫k8s_node: צומת Kubernetes.
   • ‫k8s_pod: פוד של Kubernetes.

3. יוצרים אובייקט MetricDescriptor ומעבירים אותו כארגומנט לקריאה ל-method‏ metricDescriptors.create.

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

בדוגמה הבאה יוצרים מדד מסוג gauge.

פרוטוקול

כדי ליצור מתאר מדד, משתמשים בשיטה metricDescriptors.create. אפשר להריץ את ה-method הזה באמצעות הווידג'ט של APIs Explorer בדף ההפניה של ה-method. מידע נוסף זמין במאמר בנושא APIs Explorer.

אלה פרמטרים לדוגמה של metricDescriptors.create:

• ‫name (כתובת URL): ‏ projects/[PROJECT_ID]

• גוף הבקשה: צריך לספק אובייקט MetricDescriptor כמו זה שבהמשך:

  {
    "name": "",
    "description": "Daily sales records from all branch stores.",
    "displayName": "Sales",
    "type": "custom.googleapis.com/stores/sales",
    "metricKind": "GAUGE",
    "valueType": "DOUBLE",
    "unit": "{USD}",
    "labels": [
      {
        "key": "store_id",
        "valueType": "STRING",
        "description": "The ID of the store."
      },
    ],
  }
  

מזינים את הערכים האלה בשדות בווידג'ט, ומזינים את מזהה הפרויקט במקום [PROJECT_ID]:

לוחצים על הלחצן Execute (ביצוע) כדי להריץ את השיטה.

רוצים לנסות?

הערה: כדי לראות את הבקשה כפקודת curl, כבקשת HTTP או ב-JavaScript, לוחצים על מסך מלא ב-APIs Explorer.

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

"name": "projects/[PROJECT_ID]/metricDescriptors/custom.googleapis.com/stores/daily_sales"

לדוגמה, אם רוצים לקבל את התיאור של מדד, משתמשים בשם הזה.

C#

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

public static object CreateMetric(string projectId,
    string metricType = "custom.googleapis.com/stores/daily_sales")
{
    // Create client.
    MetricServiceClient metricServiceClient = MetricServiceClient.Create();

    // Prepare custom metric descriptor.      
    MetricDescriptor metricDescriptor = new MetricDescriptor();
    metricDescriptor.DisplayName = "Daily Sales";
    metricDescriptor.Description = "Daily sales records from all branch stores.";
    metricDescriptor.MetricKind = MetricKind.Gauge;
    metricDescriptor.ValueType = MetricDescriptor.Types.ValueType.Double;
    metricDescriptor.Type = metricType;
    metricDescriptor.Unit = "{USD}";
    LabelDescriptor labels = new LabelDescriptor();
    labels.Key = "store_id";
    labels.ValueType = LabelDescriptor.Types.ValueType.String;
    labels.Description = "The ID of the store.";
    metricDescriptor.Labels.Add(labels);
    CreateMetricDescriptorRequest request = new CreateMetricDescriptorRequest
    {
        ProjectName = new ProjectName(projectId),
    };
    request.MetricDescriptor = metricDescriptor;
    // Make the request.
    MetricDescriptor response = metricServiceClient.CreateMetricDescriptor(request);
    Console.WriteLine("Done creating metric descriptor:");
    Console.WriteLine(JObject.Parse($"{response}").ToString());
    return 0;
}

Go

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

import (
	"context"
	"fmt"
	"io"

	monitoring "cloud.google.com/go/monitoring/apiv3"
	"cloud.google.com/go/monitoring/apiv3/v2/monitoringpb"
	"google.golang.org/genproto/googleapis/api/label"
	"google.golang.org/genproto/googleapis/api/metric"
	metricpb "google.golang.org/genproto/googleapis/api/metric"
)

// createCustomMetric creates a custom metric specified by the metric type.
func createCustomMetric(w io.Writer, projectID, metricType string) (*metricpb.MetricDescriptor, error) {
	ctx := context.Background()
	c, err := monitoring.NewMetricClient(ctx)
	if err != nil {
		return nil, err
	}
	defer c.Close()
	md := &metric.MetricDescriptor{
		Name: "Custom Metric",
		Type: metricType,
		Labels: []*label.LabelDescriptor{{
			Key:         "environment",
			ValueType:   label.LabelDescriptor_STRING,
			Description: "An arbitrary measurement",
		}},
		MetricKind:  metric.MetricDescriptor_GAUGE,
		ValueType:   metric.MetricDescriptor_INT64,
		Unit:        "s",
		Description: "An arbitrary measurement",
		DisplayName: "Custom Metric",
	}
	req := &monitoringpb.CreateMetricDescriptorRequest{
		Name:             "projects/" + projectID,
		MetricDescriptor: md,
	}
	m, err := c.CreateMetricDescriptor(ctx, req)
	if err != nil {
		return nil, fmt.Errorf("could not create custom metric: %w", err)
	}

	fmt.Fprintf(w, "Created %s\n", m.GetName())
	return m, nil
}

Java

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

// Your Google Cloud Platform project ID
final String projectId = System.getProperty("projectId");

try (final MetricServiceClient client = MetricServiceClient.create();) {
  ProjectName projectName = ProjectName.of(projectId);

  MetricDescriptor descriptor =
      MetricDescriptor.newBuilder()
          .setType(type)
          .addLabels(
              LabelDescriptor.newBuilder()
                  .setKey("store_id")
                  .setValueType(LabelDescriptor.ValueType.STRING))
          .setDescription("This is a simple example of a custom metric.")
          .setMetricKind(MetricDescriptor.MetricKind.GAUGE)
          .setValueType(MetricDescriptor.ValueType.DOUBLE)
          .build();

  CreateMetricDescriptorRequest request =
      CreateMetricDescriptorRequest.newBuilder()
          .setName(projectName.toString())
          .setMetricDescriptor(descriptor)
          .build();

  descriptor = client.createMetricDescriptor(request);
  System.out.println("Created descriptor " + descriptor.getName());
}

Node.js

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

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

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

/**
 * TODO(developer): Uncomment and edit the following lines of code.
 */
// const projectId = 'YOUR_PROJECT_ID';
async function createMetricDescriptor() {
  const request = {
    name: client.projectPath(projectId),
    metricDescriptor: {
      description: 'Daily sales records from all branch stores.',
      displayName: 'Daily Sales',
      type: 'custom.googleapis.com/stores/daily_sales',
      metricKind: 'GAUGE',
      valueType: 'DOUBLE',
      unit: '{USD}',
      labels: [
        {
          key: 'store_id',
          valueType: 'STRING',
          description: 'The ID of the store.',
        },
      ],
    },
  };

  // Creates a custom metric descriptor
  const [descriptor] = await client.createMetricDescriptor(request);
  console.log('Created custom Metric:\n');
  console.log(`Name: ${descriptor.displayName}`);
  console.log(`Description: ${descriptor.description}`);
  console.log(`Type: ${descriptor.type}`);
  console.log(`Kind: ${descriptor.metricKind}`);
  console.log(`Value Type: ${descriptor.valueType}`);
  console.log(`Unit: ${descriptor.unit}`);
  console.log('Labels:');
  descriptor.labels.forEach(label => {
    console.log(`  ${label.key} (${label.valueType}) - ${label.description}`);
  });
}
createMetricDescriptor();

PHP

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

use Google\Api\LabelDescriptor;
use Google\Api\MetricDescriptor;
use Google\Cloud\Monitoring\V3\Client\MetricServiceClient;
use Google\Cloud\Monitoring\V3\CreateMetricDescriptorRequest;

/**
 * Create a new metric in Stackdriver Monitoring.
 * Example:
 * ```
 * create_metric($projectId);
 * ```
 *
 * @param string $projectId Your project ID
 */
function create_metric($projectId)
{
    $metrics = new MetricServiceClient([
        'projectId' => $projectId,
    ]);

    $projectName = 'projects/' . $projectId;

    $descriptor = new MetricDescriptor();
    $descriptor->setDescription('Daily sales records from all branch stores.');
    $descriptor->setDisplayName('Daily Sales');
    $descriptor->setType('custom.googleapis.com/stores/daily_sales');
    $descriptor->setMetricKind(MetricDescriptor\MetricKind::GAUGE);
    $descriptor->setValueType(MetricDescriptor\ValueType::DOUBLE);
    $descriptor->setUnit('{USD}');
    $label = new LabelDescriptor();
    $label->setKey('store_id');
    $label->setValueType(LabelDescriptor\ValueType::STRING);
    $label->setDescription('The ID of the store.');
    $labels = [$label];
    $descriptor->setLabels($labels);
    $createMetricDescriptorRequest = (new CreateMetricDescriptorRequest())
        ->setName($projectName)
        ->setMetricDescriptor($descriptor);

    $descriptor = $metrics->createMetricDescriptor($createMetricDescriptorRequest);
    printf('Created a metric: ' . $descriptor->getName() . PHP_EOL);
}

Python

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

from google.api import label_pb2 as ga_label
from google.api import metric_pb2 as ga_metric
from google.cloud import monitoring_v3

client = monitoring_v3.MetricServiceClient()
project_name = f"projects/{project_id}"
descriptor = ga_metric.MetricDescriptor()
descriptor.type = "custom.googleapis.com/my_metric" + str(uuid.uuid4())
descriptor.metric_kind = ga_metric.MetricDescriptor.MetricKind.GAUGE
descriptor.value_type = ga_metric.MetricDescriptor.ValueType.DOUBLE
descriptor.description = "This is a simple example of a custom metric."

labels = ga_label.LabelDescriptor()
labels.key = "TestLabel"
labels.value_type = ga_label.LabelDescriptor.ValueType.STRING
labels.description = "This is a test label"
descriptor.labels.append(labels)

descriptor = client.create_metric_descriptor(
    name=project_name, metric_descriptor=descriptor
)
print("Created {}.".format(descriptor.name))

Ruby

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

gem "google-cloud-monitoring"
require "google/cloud/monitoring"

# Your Google Cloud Platform project ID
# project_id = "YOUR_PROJECT_ID"

# Example metric type
# metric_type = "custom.googleapis.com/my_metric"

client = Google::Cloud::Monitoring.metric_service
project_name = client.project_path project: project_id

descriptor = Google::Api::MetricDescriptor.new(
  type:        metric_type,
  metric_kind: Google::Api::MetricDescriptor::MetricKind::GAUGE,
  value_type:  Google::Api::MetricDescriptor::ValueType::DOUBLE,
  description: "This is a simple example of a custom metric."
)

result = client.create_metric_descriptor name:              project_name,
                                         metric_descriptor: descriptor
p "Created #{result.name}"
p result

אם נתקלתם בבעיות, אפשר לעיין במאמר בנושא פתרון בעיות בקריאות ל-API.

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

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

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

כדי לכתוב נקודות נתונים, מעבירים רשימה של אובייקטים מסוג TimeSeries אל timeSeries.create. הגודל המקסימלי של הרשימה הוא 200, וכל אובייקט ברשימה חייב לציין סדרת זמן שונה:

• הערכים בשדות metric ו-resource מזהים אובייקט TimeSeries ספציפי. השדות האלה מייצגים את סוג המדד של הנתונים ואת המשאב המפוקח שממנו נאספו הנתונים.
• לא כוללים את השדות metricKind ו-valueType. המערכת מתעלמת מהם כשכותבים נקודות נתונים.

• כל אובייקט TimeSeries חייב להכיל רק אובייקט Point אחד:

  • הערך של הנקודה ומרווח הזמן צריכים להיות תואמים להגדרה של סוג המדד. מידע על מרווחי זמן לסוגים שונים של מדדים זמין במאמר TimeInterval.
  • מרווח הזמן של הנקודה צריך להיות מאוחר יותר מכל נקודה שכבר נמצאת בסדרת הזמן.
  • שעת הסיום של המרווח לא יכולה להיות יותר מ-25 שעות בעבר או יותר מחמש דקות בעתיד.

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

פרוטוקול

כדי לכתוב נתוני מדדים, משתמשים בשיטה timeSeries.create. אפשר להריץ את ה-method הזה באמצעות הווידג'ט של APIs Explorer בדף ההפניה של ה-method. מידע נוסף זמין ב-APIs Explorer.

כדי לכתוב נקודה למדד stores/daily_sales שנוצר ביצירה ידנית של מתארי מדדים:

1. עוברים אל דף העזר בנושא timeSeries.create.
2. מזינים את הפרמטרים הבאים בווידג'ט של APIs Explorer.
3. לוחצים על הלחצן Execute.

אפשר להשתמש בפרמטרים לדוגמה הבאים:

• name: projects/[PROJECT_ID]

• גוף הבקשה: כולל רשימה של אובייקטים TimeSeries. בדוגמה הבאה יש רק סדרת זמן אחת ברשימה.

  הערה: חובה לשנות את הערכים project_id ו-endTime בגוף הבקשה הבא. משתמשים במזהה הפרויקט. הערך של endTime צריך להיות קרוב לזמן הנוכחי. הפונקציה date -Iseconds מחזירה את הזמן הנוכחי בפורמט שניתן לשימוש.

  {
   "timeSeries": [
    {
     "metric": {
      "type": "custom.googleapis.com/my_metric",
      "labels": {
       "my_label": "my_value"
      }
     },
     "resource": {
      "type": "gce_instance",
      "labels": {
       "project_id": "[PROJECT_ID]",
       "instance_id": "1234567890123456789",
       "zone": "us-central1-f"
      }
     },
     "points": [
      {
       "interval": {
        "endTime": "2018-06-01T10:00:00-04:00"
       },
       "value": {
        "doubleValue": 123.45
       }
      }
     ]
    }
   ]
  }
  

רוצים לנסות?

הערה: כדי לראות את הבקשה כפקודת curl, כבקשת HTTP או ב-JavaScript, לוחצים על מסך מלא ב-APIs Explorer.

C#

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

public static object WriteTimeSeriesData(string projectId)
{
    // Create client.
    MetricServiceClient metricServiceClient = MetricServiceClient.Create();
    // Initialize request argument(s).
    ProjectName name = new ProjectName(projectId);
    // Prepare a data point. 
    Point dataPoint = new Point();
    TypedValue salesTotal = new TypedValue();
    salesTotal.DoubleValue = 123.45;
    dataPoint.Value = salesTotal;
    Timestamp timeStamp = new Timestamp();
    timeStamp.Seconds = (long)(DateTime.UtcNow - s_unixEpoch).TotalSeconds;
    TimeInterval interval = new TimeInterval();
    interval.EndTime = timeStamp;
    dataPoint.Interval = interval;

    // Prepare custom metric.
    Metric metric = new Metric();
    metric.Type = "custom.googleapis.com/stores/daily_sales";
    metric.Labels.Add("store_id", "Pittsburgh");

    // Prepare monitored resource.
    MonitoredResource resource = new MonitoredResource();
    resource.Type = "global";
    resource.Labels.Add("project_id", projectId);

    // Create a new time series using inputs.
    TimeSeries timeSeriesData = new TimeSeries();
    timeSeriesData.Metric = metric;
    timeSeriesData.Resource = resource;
    timeSeriesData.Points.Add(dataPoint);

    // Add newly created time series to list of time series to be written.
    IEnumerable<TimeSeries> timeSeries = new List<TimeSeries> { timeSeriesData };
    // Write time series data.
    metricServiceClient.CreateTimeSeries(name, timeSeries);
    Console.WriteLine("Done writing time series data:");
    Console.WriteLine(JObject.Parse($"{timeSeriesData}").ToString());
    return 0;
}

Go

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

// writeTimeSeriesValue writes a value for the custom metric created
func writeTimeSeriesValue(projectID, metricType string) error {
	ctx := context.Background()
	c, err := monitoring.NewMetricClient(ctx)
	if err != nil {
		return err
	}
	defer c.Close()
	now := &timestamp.Timestamp{
		Seconds: time.Now().Unix(),
	}
	req := &monitoringpb.CreateTimeSeriesRequest{
		Name: "projects/" + projectID,
		TimeSeries: []*monitoringpb.TimeSeries{{
			Metric: &metricpb.Metric{
				Type: metricType,
				Labels: map[string]string{
					"environment": "STAGING",
				},
			},
			Resource: &monitoredres.MonitoredResource{
				Type: "gce_instance",
				Labels: map[string]string{
					"instance_id": "test-instance",
					"zone":        "us-central1-f",
				},
			},
			Points: []*monitoringpb.Point{{
				Interval: &monitoringpb.TimeInterval{
					StartTime: now,
					EndTime:   now,
				},
				Value: &monitoringpb.TypedValue{
					Value: &monitoringpb.TypedValue_Int64Value{
						Int64Value: rand.Int63n(10),
					},
				},
			}},
		}},
	}
	log.Printf("writeTimeseriesRequest: %+v\n", req)

	err = c.CreateTimeSeries(ctx, req)
	if err != nil {
		return fmt.Errorf("could not write time series value, %w ", err)
	}
	return nil
}

Java

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

String projectId = System.getProperty("projectId");

// Prepares an individual data point
TimeInterval interval =
    TimeInterval.newBuilder()
        .setEndTime(Timestamps.fromMillis(System.currentTimeMillis()))
        .build();
TypedValue value = TypedValue.newBuilder().setDoubleValue(123.45).build();
Point point = Point.newBuilder().setInterval(interval).setValue(value).build();

List<Point> pointList = new ArrayList<>();
pointList.add(point);

ProjectName name = ProjectName.of(projectId);

// Prepares the metric descriptor
Map<String, String> metricLabels = new HashMap<>();
Metric metric =
    Metric.newBuilder()
        .setType("custom.googleapis.com/my_metric")
        .putAllLabels(metricLabels)
        .build();

// Prepares the monitored resource descriptor
Map<String, String> resourceLabels = new HashMap<>();
resourceLabels.put("instance_id", "1234567890123456789");
resourceLabels.put("zone", "us-central1-f");

MonitoredResource resource =
    MonitoredResource.newBuilder().setType("gce_instance").putAllLabels(resourceLabels).build();

// Prepares the time series request
TimeSeries timeSeries =
    TimeSeries.newBuilder()
        .setMetric(metric)
        .setResource(resource)
        .addAllPoints(pointList)
        .build();

List<TimeSeries> timeSeriesList = new ArrayList<>();
timeSeriesList.add(timeSeries);

CreateTimeSeriesRequest request =
    CreateTimeSeriesRequest.newBuilder()
        .setName(name.toString())
        .addAllTimeSeries(timeSeriesList)
        .build();

// Writes time series data
try (final MetricServiceClient client = MetricServiceClient.create();) {
  client.createTimeSeries(request);
}
System.out.println("Done writing time series value.");

Node.js

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

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

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

async function writeTimeSeriesData() {
  /**
   * TODO(developer): Uncomment and edit the following lines of code.
   */
  // const projectId = 'YOUR_PROJECT_ID';

  const dataPoint = {
    interval: {
      endTime: {
        seconds: Date.now() / 1000,
      },
    },
    value: {
      doubleValue: 123.45,
    },
  };

  const timeSeriesData = {
    metric: {
      type: 'custom.googleapis.com/stores/daily_sales',
      labels: {
        store_id: 'Pittsburgh',
      },
    },
    resource: {
      type: 'global',
      labels: {
        project_id: projectId,
      },
    },
    points: [dataPoint],
  };

  const request = {
    name: client.projectPath(projectId),
    timeSeries: [timeSeriesData],
  };

  // Writes time series data
  const result = await client.createTimeSeries(request);
  console.log('Done writing time series data.', result);
}
writeTimeSeriesData();

PHP

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

use Google\Api\Metric;
use Google\Api\MonitoredResource;
use Google\Cloud\Monitoring\V3\Client\MetricServiceClient;
use Google\Cloud\Monitoring\V3\CreateTimeSeriesRequest;
use Google\Cloud\Monitoring\V3\Point;
use Google\Cloud\Monitoring\V3\TimeInterval;
use Google\Cloud\Monitoring\V3\TimeSeries;
use Google\Cloud\Monitoring\V3\TypedValue;
use Google\Protobuf\Timestamp;

/**
 * Example:
 * ```
 * write_timeseries($projectId);
 * ```
 *
 * @param string $projectId Your project ID
 */
function write_timeseries($projectId)
{
    $metrics = new MetricServiceClient([
        'projectId' => $projectId,
    ]);

    $projectName = 'projects/' . $projectId;

    $endTime = new Timestamp();
    $endTime->setSeconds(time());
    $interval = new TimeInterval();
    $interval->setEndTime($endTime);

    $value = new TypedValue();
    $value->setDoubleValue(123.45);

    $point = new Point();
    $point->setValue($value);
    $point->setInterval($interval);
    $points = [$point];

    $metric = new Metric();
    $metric->setType('custom.googleapis.com/stores/daily_sales');
    $labels = ['store_id' => 'Pittsburg'];
    $metric->setLabels($labels);

    $resource = new MonitoredResource();
    $resource->setType('global');
    $labels = ['project_id' => $projectId];
    $resource->setLabels($labels);

    $timeSeries = new TimeSeries();
    $timeSeries->setMetric($metric);
    $timeSeries->setResource($resource);
    $timeSeries->setPoints($points);
    $createTimeSeriesRequest = (new CreateTimeSeriesRequest())
        ->setName($projectName)
        ->setTimeSeries([$timeSeries]);

    $metrics->createTimeSeries($createTimeSeriesRequest);

    printf('Done writing time series data.' . PHP_EOL);
}

Python

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

from google.cloud import monitoring_v3

client = monitoring_v3.MetricServiceClient()
project_name = f"projects/{project_id}"

series = monitoring_v3.TimeSeries()
series.metric.type = "custom.googleapis.com/my_metric" + str(uuid.uuid4())
series.resource.type = "gce_instance"
series.resource.labels["instance_id"] = "1234567890123456789"
series.resource.labels["zone"] = "us-central1-c"
series.metric.labels["TestLabel"] = "My Label Data"
now = time.time()
seconds = int(now)
nanos = int((now - seconds) * 10**9)
interval = monitoring_v3.TimeInterval(
    {"end_time": {"seconds": seconds, "nanos": nanos}}
)
point = monitoring_v3.Point({"interval": interval, "value": {"double_value": 3.14}})
series.points = [point]
client.create_time_series(name=project_name, time_series=[series])

Ruby

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

gem "google-cloud-monitoring"
require "google/cloud/monitoring"

# Your Google Cloud Platform project ID
# project_id = "YOUR_PROJECT_ID"

# Example metric type
# metric_type = "custom.googleapis.com/my_metric"

client = Google::Cloud::Monitoring.metric_service
project_name = client.project_path project: project_id

series = Google::Cloud::Monitoring::V3::TimeSeries.new
series.metric = Google::Api::Metric.new type: metric_type

resource = Google::Api::MonitoredResource.new type: "global"
resource.labels["project_id"] = project_id
series.resource = resource

point = Google::Cloud::Monitoring::V3::Point.new
point.value = Google::Cloud::Monitoring::V3::TypedValue.new double_value: 3.14
now = Time.now
end_time = Google::Protobuf::Timestamp.new seconds: now.to_i, nanos: now.nsec
point.interval = Google::Cloud::Monitoring::V3::TimeInterval.new end_time: end_time
series.points << point

client.create_time_series name: project_name, time_series: [series]
p "Time series created."

אם נתקלתם בבעיות, אפשר לעיין במאמר בנושא פתרון בעיות בקריאות ל-API.

מחיקה של מדדים שהוגדרו על ידי המשתמש

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

אי אפשר למחוק את תיאור המדד של מדד מובנה.

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

כדי למחוק את תיאור המדד, צריך לבצע קריאה ל-method‏ metricDescriptors.delete.

פרוטוקול

כדי למחוק תיאור מדד, משתמשים בשיטה metricDescriptors.delete. אפשר להריץ את ה-method הזה באמצעות הווידג'ט של APIs Explorer בדף ההפניה של ה-method. מידע נוסף זמין ב-APIs Explorer.

כדי למחוק את המדד stores/daily_sales שנוצר בקטע יצירה ידנית של תיאורי מדדים:

1. עוברים אל דף העזר בנושא metricDescriptors.delete:

2. מזינים את השם של מתאר המדד בווידג'ט של API Explorer:

   name: projects/[PROJECT_ID]/metricDescriptors/custom.googleapis.com/stores/daily_sales

3. לוחצים על הלחצן Execute.

רוצים לנסות?

הערה: כדי לראות את הבקשה כפקודת curl, כבקשת HTTP או ב-JavaScript, לוחצים על מסך מלא ב-APIs Explorer.

C#

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

public static object DeleteMetric(string projectId, string metricType)
{
    // Create client.
    MetricServiceClient metricServiceClient = MetricServiceClient.Create();
    // Initialize request argument(s).
    MetricDescriptorName name = new MetricDescriptorName(projectId, metricType);
    // Make the request.
    metricServiceClient.DeleteMetricDescriptor(name);
    Console.WriteLine($"Done deleting metric descriptor: {name}");
    return 0;
}

Go

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

import (
	"context"
	"fmt"
	"io"

	monitoring "cloud.google.com/go/monitoring/apiv3"
	"cloud.google.com/go/monitoring/apiv3/v2/monitoringpb"
)

// deleteMetric deletes the given metric. name should be of the form
// "projects/PROJECT_ID/metricDescriptors/METRIC_TYPE".
func deleteMetric(w io.Writer, name string) error {
	ctx := context.Background()
	c, err := monitoring.NewMetricClient(ctx)
	if err != nil {
		return err
	}
	defer c.Close()
	req := &monitoringpb.DeleteMetricDescriptorRequest{
		Name: name,
	}

	if err := c.DeleteMetricDescriptor(ctx, req); err != nil {
		return fmt.Errorf("could not delete metric: %w", err)
	}
	fmt.Fprintf(w, "Deleted metric: %q\n", name)
	return nil
}

Java

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

final String projectId = System.getProperty("projectId");
try (final MetricServiceClient client = MetricServiceClient.create();) {
  MetricDescriptorName metricName = MetricDescriptorName.of(projectId, type);
  client.deleteMetricDescriptor(metricName);
  System.out.println("Deleted descriptor " + type);
}

Node.js

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

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

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

async function deleteMetricDescriptor() {
  /**
   * TODO(developer): Uncomment and edit the following lines of code.
   */
  // const projectId = 'YOUR_PROJECT_ID';
  // const metricId = 'custom.googleapis.com/stores/daily_sales';

  const request = {
    name: client.projectMetricDescriptorPath(projectId, metricId),
  };

  // Deletes a metric descriptor
  const [result] = await client.deleteMetricDescriptor(request);
  console.log(`Deleted ${metricId}`, result);
}
deleteMetricDescriptor();

PHP

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

use Google\Cloud\Monitoring\V3\Client\MetricServiceClient;
use Google\Cloud\Monitoring\V3\DeleteMetricDescriptorRequest;

/**
 * Example:
 * ```
 * delete_metric($projectId, $databaseId);
 * ```
 *
 * @param string $projectId Your project ID
 * @param string $metricId  The ID of the Metric Descriptor to delete
 */
function delete_metric($projectId, $metricId)
{
    $metrics = new MetricServiceClient([
        'projectId' => $projectId,
    ]);

    $metricPath = $metrics->metricDescriptorName($projectId, $metricId);
    $deleteMetricDescriptorRequest = (new DeleteMetricDescriptorRequest())
        ->setName($metricPath);
    $metrics->deleteMetricDescriptor($deleteMetricDescriptorRequest);

    printf('Deleted a metric: ' . $metricPath . PHP_EOL);
}

Python

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

from google.cloud import monitoring_v3

client = monitoring_v3.MetricServiceClient()
client.delete_metric_descriptor(name=descriptor_name)
print("Deleted metric descriptor {}.".format(descriptor_name))

Ruby

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

gem "google-cloud-monitoring"
require "google/cloud/monitoring"

# Your Google Cloud Platform project ID
# project_id = "YOUR_PROJECT_ID"

# Example metric type
# metric_type = "custom.googleapis.com/my_metric"

client = Google::Cloud::Monitoring.metric_service
metric_name = client.metric_descriptor_path project:           project_id,
                                            metric_descriptor: metric_type

client.delete_metric_descriptor name: metric_name
p "Deleted metric descriptor #{metric_name}."

אם נתקלתם בבעיות, אפשר לעיין במאמר בנושא פתרון בעיות בקריאות ל-API.

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

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

כדי להוסיף תוויות למדד קיים שהוגדר על ידי המשתמש, משתמשים בשיטה timeSeries.create וכוללים את התוויות החדשות בנתוני הסדרות העיתיות. התוויות מתווספות לתיאור המדד אם התוויות שניסיתם לכתוב תקינות ומספר התוויות הכולל קטן מ-30.

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

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

אי אפשר לשנות את השם של מדד.

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

• הצגה וניהול של השימוש במדדים
• רשימת מדדים מובנים
• רשימת המשאבים שבמעקב