Skip to content

Commit 62ea7bc

Browse files
rimeyrimey
committed
Add support for creating and deleting descriptors for custom metrics. (googleapis#1755)
1 parent c3331eb commit 62ea7bc

File tree

11 files changed

+559
-71
lines changed

11 files changed

+559
-71
lines changed

‎docs/monitoring-resource.rst‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
1-
Resource Descriptors
2-
====================
1+
Monitored Resource Descriptors
2+
==============================
33

44
.. automodule:: gcloud.monitoring.resource
55
:members:

‎docs/monitoring-usage.rst‎

Lines changed: 47 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -24,8 +24,13 @@ Essential concepts:
2424
Please refer to the documentation for the `Monitoring API`_ for
2525
more information.
2626

27-
At present, this client library supports querying of time series,
28-
metric descriptors, and resource descriptors.
27+
At present, this client library supports the following features
28+
of the API:
29+
30+
- Querying of time series.
31+
- Querying of metric descriptors and monitored resource descriptors.
32+
- Creation and deletion of metric descriptors for custom metrics.
33+
- (Writing of custom metric data will be coming soon.)
2934

3035
.. _Monitoring API: https://cloud.google.com/monitoring/api/v3/
3136

@@ -101,6 +106,46 @@ You can list all of these with the
101106
See :class:`~gcloud.monitoring.metric.MetricDescriptor` and the
102107
`Metric Descriptors`_ API documentation for more information.
103108

109+
You can create new metric descriptors to define custom metrics in
110+
the ``custom.googleapis.com`` namespace. You do this by creating a
111+
:class:`~gcloud.monitoring.metric.MetricDescriptor` object using the
112+
client's :meth:`~gcloud.monitoring.client.Client.metric_descriptor`
113+
factory and then calling the object's
114+
:meth:`~gcloud.monitoring.metric.MetricDescriptor.create` method::
115+
116+
>>> from gcloud.monitoring import MetricKind, ValueType
117+
>>> descriptor = client.metric_descriptor(
118+
... 'custom.googleapis.com/my_metric',
119+
... metric_kind=MetricKind.GAUGE,
120+
... value_type=ValueType.DOUBLE,
121+
... description='This is a simple example of a custom metric.')
122+
>>> descriptor.create()
123+
124+
You can delete such a metric descriptor as follows::
125+
126+
>>> descriptor = client.metric_descriptor(
127+
... 'custom.googleapis.com/my_metric')
128+
>>> descriptor.delete()
129+
130+
To define a custom metric parameterized by one or more labels,
131+
you must build the appropriate
132+
:class:`~gcloud.monitoring.label.LabelDescriptor` objects
133+
and include them in the
134+
:class:`~gcloud.monitoring.metric.MetricDescriptor` object
135+
before you call
136+
:meth:`~gcloud.monitoring.metric.MetricDescriptor.create`::
137+
138+
>>> from gcloud.monitoring import LabelDescriptor, LabelValueType
139+
>>> label = LabelDescriptor('response_code', LabelValueType.INT64,
140+
... description='HTTP status code')
141+
>>> descriptor = client.metric_descriptor(
142+
... 'custom.googleapis.com/my_app/response_count',
143+
... metric_kind=MetricKind.CUMULATIVE,
144+
... value_type=ValueType.INT64,
145+
... labels=[label],
146+
... description='Cumulative count of HTTP responses.')
147+
>>> descriptor.create()
148+
104149
.. _platform metrics: https://cloud.google.com/monitoring/api/metrics
105150
.. _agent metrics: https://cloud.google.com/monitoring/agent/
106151
.. _custom metrics: https://cloud.google.com/monitoring/custom-metrics/

‎gcloud/monitoring/client.py‎

Lines changed: 81 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,8 @@
3030
from gcloud.client import JSONClient
3131
from gcloud.monitoring.connection import Connection
3232
from gcloud.monitoring.metric import MetricDescriptor
33+
from gcloud.monitoring.metric import MetricKind
34+
from gcloud.monitoring.metric import ValueType
3335
from gcloud.monitoring.query import Query
3436
from gcloud.monitoring.resource import ResourceDescriptor
3537

@@ -60,7 +62,7 @@ def query(self,
6062
metric_type=Query.DEFAULT_METRIC_TYPE,
6163
end_time=None,
6264
days=0, hours=0, minutes=0):
63-
"""Construct a query object for listing time series.
65+
"""Construct a query object for retrieving metric data.
6466
6567
Example::
6668
@@ -112,6 +114,82 @@ def query(self,
112114
end_time=end_time,
113115
days=days, hours=hours, minutes=minutes)
114116

117+
def metric_descriptor(self, type_,
118+
metric_kind=MetricKind.METRIC_KIND_UNSPECIFIED,
119+
value_type=ValueType.VALUE_TYPE_UNSPECIFIED,
120+
labels=(), unit='', description='', display_name=''):
121+
"""Construct a metric descriptor object.
122+
123+
Metric descriptors specify the schema for a particular metric type.
124+
125+
This factory method is used most often in conjunction with the metric
126+
descriptor :meth:`~gcloud.monitoring.metric.MetricDescriptor.create`
127+
method to define custom metrics::
128+
129+
>>> descriptor = client.metric_descriptor(
130+
... 'custom.googleapis.com/my_metric',
131+
... metric_kind=MetricKind.GAUGE,
132+
... value_type=ValueType.DOUBLE,
133+
... description='This is a simple example of a custom metric.')
134+
>>> descriptor.create()
135+
136+
Here is an example where the custom metric is parameterized by a
137+
metric label::
138+
139+
>>> label = LabelDescriptor('response_code', LabelValueType.INT64,
140+
... description='HTTP status code')
141+
>>> descriptor = client.metric_descriptor(
142+
... 'custom.googleapis.com/my_app/response_count',
143+
... metric_kind=MetricKind.CUMULATIVE,
144+
... value_type=ValueType.INT64,
145+
... labels=[label],
146+
... description='Cumulative count of HTTP responses.')
147+
>>> descriptor.create()
148+
149+
:type type_: string
150+
:param type_:
151+
The metric type including a DNS name prefix. For example:
152+
``"custom.googleapis.com/my_metric"``
153+
154+
:type metric_kind: string
155+
:param metric_kind:
156+
The kind of measurement. It must be one of
157+
:data:`MetricKind.GAUGE`, :data:`MetricKind.DELTA`,
158+
or :data:`MetricKind.CUMULATIVE`.
159+
See :class:`~gcloud.monitoring.metric.MetricKind`.
160+
161+
:type value_type: string
162+
:param value_type:
163+
The value type of the metric. It must be one of
164+
:data:`ValueType.BOOL`, :data:`ValueType.INT64`,
165+
:data:`ValueType.DOUBLE`, :data:`ValueType.STRING`,
166+
or :data:`ValueType.DISTRIBUTION`.
167+
See :class:`ValueType`.
168+
169+
:type labels: list of :class:`~gcloud.monitoring.label.LabelDescriptor`
170+
:param labels:
171+
A sequence of zero or more label descriptors specifying the labels
172+
used to identify a specific instance of this metric.
173+
174+
:type unit: string
175+
:param unit: An optional unit in which the metric value is reported.
176+
177+
:type description: string
178+
:param description: An optional detailed description of the metric.
179+
180+
:type display_name: string
181+
:param display_name: An optional concise name for the metric.
182+
"""
183+
return MetricDescriptor(
184+
self, type_,
185+
metric_kind=metric_kind,
186+
value_type=value_type,
187+
labels=labels,
188+
unit=unit,
189+
description=description,
190+
display_name=display_name,
191+
)
192+
115193
def fetch_metric_descriptor(self, metric_type):
116194
"""Look up a metric descriptor by type.
117195
@@ -163,7 +241,7 @@ def list_metric_descriptors(self, filter_string=None, type_prefix=None):
163241
type_prefix=type_prefix)
164242

165243
def fetch_resource_descriptor(self, resource_type):
166-
"""Look up a resource descriptor by type.
244+
"""Look up a monitored resource descriptor by type.
167245
168246
Example::
169247
@@ -181,7 +259,7 @@ def fetch_resource_descriptor(self, resource_type):
181259
return ResourceDescriptor._fetch(self, resource_type)
182260

183261
def list_resource_descriptors(self, filter_string=None):
184-
"""List all resource descriptors for the project.
262+
"""List all monitored resource descriptors for the project.
185263
186264
Example::
187265

‎gcloud/monitoring/label.py‎

Lines changed: 23 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -48,7 +48,7 @@ class LabelDescriptor(object):
4848
:param description: A human-readable description for the label.
4949
"""
5050

51-
def __init__(self, key, value_type, description):
51+
def __init__(self, key, value_type=LabelValueType.STRING, description=''):
5252
self.key = key
5353
self.value_type = value_type
5454
self.description = description
@@ -70,6 +70,28 @@ def _from_dict(cls, info):
7070
info.get('description', ''),
7171
)
7272

73+
def _to_dict(self):
74+
"""Build a dictionary ready to be serialized to the JSON wire format.
75+
76+
:rtype: dict
77+
:returns: A dictionary.
78+
"""
79+
info = {
80+
'key': self.key,
81+
'valueType': self.value_type,
82+
}
83+
84+
if self.description:
85+
info['description'] = self.description
86+
87+
return info
88+
89+
def __eq__(self, other):
90+
return self.__dict__ == other.__dict__
91+
92+
def __ne__(self, other):
93+
return self.__dict__ != other.__dict__
94+
7395
def __repr__(self):
7496
return (
7597
'LabelDescriptor(key={key!r}, value_type={value_type!r},'

0 commit comments

Comments
 (0)