def create(self, label=None, name=None, critical_state=None, ok_state=None,
warning_state=None):
"""
Creates a notification plan to be executed when a monitoring check
triggers an alarm. You can optionally label (or name) the plan.
A plan consists of one or more notifications to be executed when an
associated alarm is triggered. You can have different lists of actions
for CRITICAL, WARNING or OK states.
"""
uri = "/%s" % self.uri_base
body = {"label": label or name}
def make_list_of_ids(parameter):
params = utils.coerce_to_list(parameter)
return [utils.get_id(param) for param in params]
if critical_state:
critical_state = utils.coerce_to_list(critical_state)
body["critical_state"] = make_list_of_ids(critical_state)
if warning_state:
warning_state = utils.coerce_to_list(warning_state)
body["warning_state"] = make_list_of_ids(warning_state)
if ok_state:
ok_state = utils.coerce_to_list(ok_state)
body["ok_state"] = make_list_of_ids(ok_state)
resp, resp_body = self.api.method_post(uri, body=body)
return self.get(resp.headers["x-object-id"])
def create(self, label=None, name=None, critical_state=None, ok_state=None,
warning_state=None):
"""
Creates a notification plan to be executed when a monitoring check
triggers an alarm. You can optionally label (or name) the plan.
A plan consists of one or more notifications to be executed when an
associated alarm is triggered. You can have different lists of actions
for CRITICAL, WARNING or OK states.
"""
uri = "/%s" % self.uri_base
body = {"label": label or name}
def make_list_of_ids(parameter):
params = utils.coerce_to_list(parameter)
return [utils.get_id(param) for param in params]
if critical_state:
critical_state = utils.coerce_to_list(critical_state)
body["critical_state"] = make_list_of_ids(critical_state)
if warning_state:
warning_state = utils.coerce_to_list(warning_state)
body["warning_state"] = make_list_of_ids(warning_state)
if ok_state:
ok_state = utils.coerce_to_list(ok_state)
body["ok_state"] = make_list_of_ids(ok_state)
resp, resp_body = self.api.method_post(uri, body=body)
return self.get(resp.headers["x-object-id"])
def update(self, check, label=None, name=None, disabled=None,
metadata=None, monitoring_zones_poll=None, timeout=None,
period=None, target_alias=None, target_hostname=None,
target_receiver=None):
if monitoring_zones_poll:
monitoring_zones_poll = utils.coerce_to_list(monitoring_zones_poll)
monitoring_zones_poll = [utils.get_id(mzp)
for mzp in monitoring_zones_poll]
body = {}
local_dict = locals()
label = label or name
params = ("label", "disabled", "metadata", "monitoring_zones_poll",
"timeout", "period", "target_alias", "target_hostname",
"target_receiver")
body = _params_to_dict(params, body, locals())
entity = check.entity
uri = "/%s/%s" % (self.uri_base, utils.get_id(check))
try:
resp, resp_body = self.api.method_put(uri, body=body)
except exc.BadRequest as e:
msg = e.message
dtls = e.details
if msg.startswith("Validation error"):
raise exc.InvalidMonitoringCheckUpdate("The update failed "
"validation: %s: %s" % (msg, dtls))
else:
# Some other issue.
raise
return resp_body
def delete_by_ids(self, ids):
"""
Deletes the messages whose IDs are passed in from this queue.
"""
ids = utils.coerce_to_list(ids)
uri = "/%s?ids=%s" % (self.uri_base, ",".join(ids))
return self.api.method_delete(uri)
def delete_by_ids(self, ids):
"""
Deletes the messages whose IDs are passed in from this queue.
"""
ids = utils.coerce_to_list(ids)
uri = "/%s?ids=%s" % (self.uri_base, ",".join(ids))
return self.api.method_delete(uri)
def update(self, check, label=None, name=None, disabled=None,
metadata=None, monitoring_zones_poll=None, timeout=None,
period=None, target_alias=None, target_hostname=None,
target_receiver=None):
if monitoring_zones_poll:
monitoring_zones_poll = utils.coerce_to_list(monitoring_zones_poll)
monitoring_zones_poll = [utils.get_id(mzp)
for mzp in monitoring_zones_poll]
body = {}
local_dict = locals()
label = label or name
params = ("label", "disabled", "metadata", "monitoring_zones_poll",
"timeout", "period", "target_alias", "target_hostname",
"target_receiver")
body = _params_to_dict(params, body, locals())
entity = check.entity
uri = "/%s/%s" % (self.uri_base, utils.get_id(check))
try:
resp, resp_body = self.api.method_put(uri, body=body)
except exc.BadRequest as e:
msg = e.message
dtls = e.details
if msg.startswith("Validation error"):
raise exc.InvalidMonitoringCheckUpdate("The update failed "
"validation: %s: %s" % (msg, dtls))
else:
# Some other issue.
raise
return resp_body
def _list(self,
uri,
obj_class=None,
body=None,
return_raw=False,
other_keys=None):
"""
Handles the communication with the API when getting
a full listing of the resources managed by this class.
"""
if body:
resp, resp_body = self.api.method_post(uri, body=body)
else:
resp, resp_body = self.api.method_get(uri)
if return_raw:
return (resp, resp_body)
if obj_class is None:
obj_class = self.resource_class
data = self._data_from_response(resp_body)
ret = [obj_class(self, res, loaded=False) for res in data if res]
if other_keys:
keys = utils.coerce_to_list(other_keys)
other = [self._data_from_response(resp_body, key) for key in keys]
return (ret, other)
else:
return ret
def _encode_personality(self, personality):
"""
Personality files must be base64-encoded before transmitting.
"""
if personality is None:
personality = []
else:
personality = utils.coerce_to_list(personality)
for pfile in personality:
if "contents" in pfile:
pfile["contents"] = base64.b64encode(pfile["contents"])
return personality
def _encode_personality(self, personality):
"""
Personality files must be base64-encoded before transmitting.
"""
if personality is None:
personality = []
else:
personality = utils.coerce_to_list(personality)
for pfile in personality:
if "contents" in pfile:
pfile["contents"] = base64.b64encode(pfile["contents"])
return personality
def list_by_ids(self, ids):
"""
If you wish to retrieve a list of messages from this queue and know the
IDs of those messages, you can pass in a list of those IDs, and only
the matching messages will be returned. This avoids pulling down all
the messages in a queue and filtering on the client side.
"""
ids = utils.coerce_to_list(ids)
uri = "/%s?ids=%s" % (self.uri_base, ",".join(ids))
# The API is not consistent in how it returns message lists, so this
# workaround is needed.
curr_prkey = self.plural_response_key
self.plural_response_key = ""
# BROKEN: API returns a list, not a dict.
ret = self._list(uri)
self.plural_response_key = curr_prkey
return ret
def list_by_ids(self, ids):
"""
If you wish to retrieve a list of messages from this queue and know the
IDs of those messages, you can pass in a list of those IDs, and only
the matching messages will be returned. This avoids pulling down all
the messages in a queue and filtering on the client side.
"""
ids = utils.coerce_to_list(ids)
uri = "/%s?ids=%s" % (self.uri_base, ",".join(ids))
# The API is not consistent in how it returns message lists, so this
# workaround is needed.
curr_prkey = self.plural_response_key
self.plural_response_key = ""
# BROKEN: API returns a list, not a dict.
ret = self._list(uri)
self.plural_response_key = curr_prkey
return ret
def _get_db_names(self, dbs, strict=True):
"""
Accepts a single db (name or object) or a list of dbs, and returns a
list of database names. If any of the supplied dbs do not exist, a
NoSuchDatabase exception will be raised, unless you pass strict=False.
"""
dbs = utils.coerce_to_list(dbs)
db_names = [utils.get_name(db) for db in dbs]
if strict:
good_dbs = self.instance.list_databases()
good_names = [utils.get_name(good_db) for good_db in good_dbs]
bad_names = [db_name for db_name in db_names
if db_name not in good_names]
if bad_names:
bad = ", ".join(bad_names)
raise exc.NoSuchDatabase("The following database(s) were not "
"found: %s" % bad)
return db_names
def _get_db_names(self, dbs, strict=True):
"""
Accepts a single db (name or object) or a list of dbs, and returns a
list of database names. If any of the supplied dbs do not exist, a
NoSuchDatabase exception will be raised, unless you pass strict=False.
"""
dbs = utils.coerce_to_list(dbs)
db_names = [utils.get_name(db) for db in dbs]
if strict:
good_dbs = self.instance.list_databases()
good_names = [utils.get_name(good_db) for good_db in good_dbs]
bad_names = [
db_name for db_name in db_names if db_name not in good_names
]
if bad_names:
bad = ", ".join(bad_names)
raise exc.NoSuchDatabase("The following database(s) were not "
"found: %s" % bad)
return db_names
def _list(self, uri, obj_class=None, body=None, return_raw=False, other_keys=None):
"""
Handles the communication with the API when getting
a full listing of the resources managed by this class.
"""
if body:
resp, resp_body = self.api.method_post(uri, body=body)
else:
resp, resp_body = self.api.method_get(uri)
if return_raw:
return (resp, resp_body)
if obj_class is None:
obj_class = self.resource_class
data = self._data_from_response(resp_body)
ret = [obj_class(self, res, loaded=False) for res in data if res]
if other_keys:
keys = utils.coerce_to_list(other_keys)
other = [self._data_from_response(resp_body, key) for key in keys]
return (ret, other)
else:
return ret
def test_coerce_to_list_list(self):
val = [utils.random_ascii(), utils.random_ascii()]
ret = utils.coerce_to_list(val)
self.assertEqual(ret, val)
def make_list_of_ids(parameter):
params = utils.coerce_to_list(parameter)
return [utils.get_id(param) for param in params]
def test_coerce_to_list_list(self):
val = [utils.random_ascii(), utils.random_ascii()]
ret = utils.coerce_to_list(val)
self.assertEqual(ret, val)
def test_coerce_to_list(self):
val = utils.random_ascii()
ret = utils.coerce_to_list(val)
self.assertEqual(ret, [val])
def get_metric_data_points(self, metric, start, end, points=None,
resolution=None, stats=None):
"""
Returns the data points for a given metric for the given period. The
'start' and 'end' times must be specified; they can be be either Python
date/datetime values, or a Unix timestamp.
The 'points' parameter represents the number of points to return. The
'resolution' parameter represents the granularity of the data. You must
specify either 'points' or 'resolution'. The allowed values for
resolution are:
FULL
MIN5
MIN20
MIN60
MIN240
MIN1440
Finally, the 'stats' parameter specifies the stats you want returned.
By default only the 'average' is returned. You omit this parameter,
pass in a single value, or pass in a list of values. The allowed values
are:
average
variance
min
max
"""
allowed_resolutions = ("FULL", "MIN5", "MIN20", "MIN60", "MIN240",
"MIN1440")
if not (points or resolution):
raise exc.MissingMonitoringCheckGranularity("You must specify "
"either the 'points' or 'resolution' parameter when "
"fetching metrics.")
if resolution:
if resolution.upper() not in allowed_resolutions:
raise exc.InvalidMonitoringMetricsResolution("The specified "
"resolution '%s' is not valid. The valid values are: "
"%s." % (resolution, str(allowed_resolutions)))
start_tm = utils.to_timestamp(start)
end_tm = utils.to_timestamp(end)
# NOTE: For some odd reason, the timestamps required for this must be
# in milliseconds, instead of the UNIX standard for timestamps, which
# is in seconds. So the values here are multiplied by 1000 to make it
# work. If the API is ever corrected, the next two lines should be
# removed. GitHub #176.
start_tm *= 1000
end_tm *= 1000
qparms = []
# Timestamps with fractional seconds currently cause a 408 (timeout)
qparms.append("from=%s" % int(start_tm))
qparms.append("to=%s" % int(end_tm))
if points:
qparms.append("points=%s" % points)
if resolution:
qparms.append("resolution=%s" % resolution.upper())
if stats:
stats = utils.coerce_to_list(stats)
for stat in stats:
qparms.append("select=%s" % stat)
qparm = "&".join(qparms)
uri = "/%s/%s/plot?%s" % (self.uri_base, metric, qparm)
try:
resp, resp_body = self.api.method_get(uri)
except exc.BadRequest as e:
msg = e.message
dtls = e.details
if msg.startswith("Validation error"):
raise exc.InvalidMonitoringMetricsRequest("Your request was "
"invalid: '%s'" % dtls)
else:
raise
return resp_body["values"]
def create_check(self, label=None, name=None, check_type=None,
details=None, disabled=False, metadata=None,
monitoring_zones_poll=None, timeout=None, period=None,
target_alias=None, target_hostname=None, target_receiver=None,
test_only=False, include_debug=False):
"""
Creates a check on the entity with the specified attributes. The
'details' parameter should be a dict with the keys as the option name,
and the value as the desired setting.
If the 'test_only' parameter is True, then the check is not created;
instead, the check is run and the results of the test run returned. If
'include_debug' is True, additional debug information is returned.
According to the current Cloud Monitoring docs:
"Currently debug information is only available for the
remote.http check and includes the response body."
"""
if details is None:
raise exc.MissingMonitoringCheckDetails("The required 'details' "
"parameter was not passed to the create_check() method.")
if not (target_alias or target_hostname):
raise exc.MonitoringCheckTargetNotSpecified("You must specify "
"either the 'target_alias' or 'target_hostname' when "
"creating a check.")
ctype = utils.get_id(check_type)
is_remote = ctype.startswith("remote")
monitoring_zones_poll = utils.coerce_to_list(monitoring_zones_poll)
monitoring_zones_poll = [utils.get_id(mzp)
for mzp in monitoring_zones_poll]
if is_remote and not monitoring_zones_poll:
raise exc.MonitoringZonesPollMissing("You must specify the "
"'monitoring_zones_poll' parameter for remote checks.")
body = {"label": label or name,
"details": details,
"disabled": disabled,
"type": utils.get_id(check_type),
}
params = ("monitoring_zones_poll", "timeout", "period",
"target_alias", "target_hostname", "target_receiver")
body = _params_to_dict(params, body, locals())
if test_only:
uri = "/%s/test-check" % self.uri_base
if include_debug:
uri = "%s?debug=true" % uri
else:
uri = "/%s" % self.uri_base
try:
resp, resp_body = self.api.method_post(uri, body=body)
except exc.BadRequest as e:
msg = e.message
dtls = e.details
match = _invalid_key_pat.match(msg)
if match:
missing = match.groups()[0].replace("details.", "")
if missing in details:
errcls = exc.InvalidMonitoringCheckDetails
errmsg = "".join(["The value passed for '%s' in the ",
"details parameter is not valid."]) % missing
else:
errmsg = "".join(["The required value for the '%s' ",
"setting is missing from the 'details' ",
"parameter."]) % missing
utils.update_exc(e, errmsg)
raise e
else:
if msg == "Validation error":
# Info is in the 'details'
raise exc.InvalidMonitoringCheckDetails("Validation "
"failed. Error: '%s'." % dtls)
else:
if resp.status_code == 201:
check_id = resp.headers["x-object-id"]
return self.get(check_id)
def test_coerce_to_list(self):
val = utils.random_ascii()
ret = utils.coerce_to_list(val)
self.assertEqual(ret, [val])
def make_list_of_ids(parameter):
params = utils.coerce_to_list(parameter)
return [utils.get_id(param) for param in params]
def create_check(self, label=None, name=None, check_type=None,
details=None, disabled=False, metadata=None,
monitoring_zones_poll=None, timeout=None, period=None,
target_alias=None, target_hostname=None, target_receiver=None,
test_only=False, include_debug=False):
"""
Creates a check on the entity with the specified attributes. The
'details' parameter should be a dict with the keys as the option name,
and the value as the desired setting.
If the 'test_only' parameter is True, then the check is not created;
instead, the check is run and the results of the test run returned. If
'include_debug' is True, additional debug information is returned.
According to the current Cloud Monitoring docs:
"Currently debug information is only available for the
remote.http check and includes the response body."
"""
if details is None:
raise exc.MissingMonitoringCheckDetails("The required 'details' "
"parameter was not passed to the create_check() method.")
if not (target_alias or target_hostname):
raise exc.MonitoringCheckTargetNotSpecified("You must specify "
"either the 'target_alias' or 'target_hostname' when "
"creating a check.")
ctype = utils.get_id(check_type)
is_remote = ctype.startswith("remote")
monitoring_zones_poll = utils.coerce_to_list(monitoring_zones_poll)
monitoring_zones_poll = [utils.get_id(mzp)
for mzp in monitoring_zones_poll]
if is_remote and not monitoring_zones_poll:
raise exc.MonitoringZonesPollMissing("You must specify the "
"'monitoring_zones_poll' parameter for remote checks.")
body = {"label": label or name,
"details": details,
"disabled": disabled,
"type": utils.get_id(check_type),
}
params = ("monitoring_zones_poll", "timeout", "period",
"target_alias", "target_hostname", "target_receiver")
body = _params_to_dict(params, body, locals())
if test_only:
uri = "/%s/test-check" % self.uri_base
if include_debug:
uri = "%s?debug=true" % uri
else:
uri = "/%s" % self.uri_base
try:
resp, resp_body = self.api.method_post(uri, body=body)
except exc.BadRequest as e:
msg = e.message
dtls = e.details
match = _invalid_key_pat.match(msg)
if match:
missing = match.groups()[0].replace("details.", "")
if missing in details:
errcls = exc.InvalidMonitoringCheckDetails
errmsg = "".join(["The value passed for '%s' in the ",
"details parameter is not valid."]) % missing
else:
errmsg = "".join(["The required value for the '%s' ",
"setting is missing from the 'details' ",
"parameter."]) % missing
utils.update_exc(e, errmsg)
raise e
else:
if msg == "Validation error":
# Info is in the 'details'
raise exc.InvalidMonitoringCheckDetails("Validation "
"failed. Error: '%s'." % dtls)
else:
if resp.status_code == 201:
check_id = resp.headers["x-object-id"]
return self.get(check_id)
def get_metric_data_points(self, metric, start, end, points=None,
resolution=None, stats=None):
"""
Returns the data points for a given metric for the given period. The
'start' and 'end' times must be specified; they can be be either Python
date/datetime values, or a Unix timestamp.
The 'points' parameter represents the number of points to return. The
'resolution' parameter represents the granularity of the data. You must
specify either 'points' or 'resolution'. The allowed values for
resolution are:
FULL
MIN5
MIN20
MIN60
MIN240
MIN1440
Finally, the 'stats' parameter specifies the stats you want returned.
By default only the 'average' is returned. You omit this parameter,
pass in a single value, or pass in a list of values. The allowed values
are:
average
variance
min
max
"""
allowed_resolutions = ("FULL", "MIN5", "MIN20", "MIN60", "MIN240",
"MIN1440")
if not (points or resolution):
raise exc.MissingMonitoringCheckGranularity("You must specify "
"either the 'points' or 'resolution' parameter when "
"fetching metrics.")
if resolution:
if resolution.upper() not in allowed_resolutions:
raise exc.InvalidMonitoringMetricsResolution("The specified "
"resolution '%s' is not valid. The valid values are: "
"%s." % (resolution, str(allowed_resolutions)))
start_tm = utils.to_timestamp(start)
end_tm = utils.to_timestamp(end)
# NOTE: For some odd reason, the timestamps required for this must be
# in milliseconds, instead of the UNIX standard for timestamps, which
# is in seconds. So the values here are multiplied by 1000 to make it
# work. If the API is ever corrected, the next two lines should be
# removed. GitHub #176.
start_tm *= 1000
end_tm *= 1000
qparms = []
# Timestamps with fractional seconds currently cause a 408 (timeout)
qparms.append("from=%s" % int(start_tm))
qparms.append("to=%s" % int(end_tm))
if points:
qparms.append("points=%s" % points)
if resolution:
qparms.append("resolution=%s" % resolution.upper())
if stats:
stats = utils.coerce_to_list(stats)
for stat in stats:
qparms.append("select=%s" % stat)
qparm = "&".join(qparms)
uri = "/%s/%s/plot?%s" % (self.uri_base, metric, qparm)
try:
resp, resp_body = self.api.method_get(uri)
except exc.BadRequest as e:
msg = e.message
dtls = e.details
if msg.startswith("Validation error"):
raise exc.InvalidMonitoringMetricsRequest("Your request was "
"invalid: '%s'" % dtls)
else:
raise
return resp_body["values"]
