Python Client¶

ZMON provides a python client library that can be imported and used in your own software.

Installation¶

ZMON python client library is part of ZMON CLI.

pip3 install --upgrade zmon-cli

Usage¶

Using ZMON client is pretty straight forward.

>>> from zmon_cli.client import Zmon

>>> zmon = Zmon('https://zmon.example.org', token='123')

>>> entity = zmon.get_entity('entity-1')
{
    'id': 'entity-1',
    'team': 'ZMON',
    'type': 'instance',
    'data': {'host': '192.168.20.16', 'port': 8080, 'name': 'entity-1-instance'}
}

>>> zmon.delete_entity('entity-102')
True

>>> check = zmon.get_check_definition(123)

>>> check['command']
http('http://www.custom-service.example.org/health').code()

>>> check['command'] = "http('http://localhost:9090/health').code()"

>>> zmon.update_check_definition(check)
{
    'command': "http('http://localhost:9090/health').code()",
    'description': 'Check service health',
    'entities': [{'application_id': 'custom-service', 'type': 'instance'}],
    'id': 123,
    'interval': 60,
    'last_modified_by': 'admin',
    'name': 'Check service health',
    'owning_team': 'ZMON',
    'potential_analysis': None,
    'potential_impact': None,
    'potential_solution': None,
    'source_url': None,
    'status': 'ACTIVE',
    'technical_details': None
}

Client¶

Exceptions¶

class zmon_cli.client.ZmonError(message='')[source]¶: ZMON client error.

class zmon_cli.client.ZmonArgumentError(message='')[source]¶: A ZMON client error indicating that a supplied object has missing or invalid attributes.

Zmon¶

class zmon_cli.client.Zmon(url, token=None, username=None, password=None, timeout=10, verify=True, user_agent='zmon-client/1.1.61')[source]¶

ZMON client class that enables communication with ZMON backend.

Parameters:

url (str) – ZMON backend base url.
token (str) – ZMON authentication token.
username (str) – ZMON authentication username. Ignored if token is used.
password (str) – ZMON authentication password. Ignored if token is used.
timeout (int) – HTTP requests timeout. Default is 10 sec.
verify (bool) – Verify SSL connection. Default is True.
user_agent (str) – ZMON user agent. Default is generated by ZMON client and includes lib version.

add_entity(entity: dict, **kwargs) → requests.models.Response[source]¶

Create or update an entity on ZMON.

Note

ZMON PUT entity API doesn’t return JSON response.

Parameters:	entity (dict) – Entity dict.
Returns:	Response object.
Return type:	`requests.Response`

alert_details_url(alert: dict) → str[source]¶

Return direct deeplink to alert details view on ZMON UI.

Parameters:	alert (dict) – alert dict.
Returns:	Deeplink to alert details view.
Return type:	str

check_definition_url(check_definition: dict) → str[source]¶

Return direct deeplink to check definition view on ZMON UI.

Parameters:	check_definition (dict) – check_difinition dict.
Returns:	Deeplink to check definition view.
Return type:	str

create_alert_definition(alert_definition: dict, **kwargs) → dict[source]¶

Create new alert definition.

Attributes last_modified_by and check_definition_id are required. If status is not set, then it will be set to ACTIVE.

Parameters:	alert_definition (dict) – ZMON alert definition dict.
Returns:	Alert definition dict.
Return type:	dict

create_downtime(downtime: dict, **kwargs) → dict[source]¶

Create a downtime for specific entities.

Atrributes entities list, start_time and end_time timestamps are required.

Parameters:	downtime (dict) – Downtime dict.
Returns:	Downtime dict.
Return type:	dict

Example downtime:

{
    "entities": ["entity-id-1", "entity-id-2"],
    "comment": "Planned maintenance",
    "start_time": 1473337437.312921,
    "end_time": 1473341037.312921,
}

dashboard_url(dashboard_id: int) → str[source]¶

Return direct deeplink to ZMON dashboard.

Parameters:	dashboard_id (int) – ZMON Dashboard ID.
Returns:	Deeplink to dashboard.
Return type:	str

delete_alert_definition(alert_definition_id: int, **kwargs) → dict[source]¶

Delete existing alert definition.

Parameters:	alert_definition_id (int) – ZMON alert definition ID.
Returns:	Alert definition dict.
Return type:	dict

delete_check_definition(check_definition_id: int, **kwargs) → requests.models.Response[source]¶

Delete existing check definition.

Parameters:	check_definition_id (int) – ZMON check definition ID.
Returns:	HTTP response.
Return type:	`requests.Response`

delete_entity(entity_id: str, **kwargs) → bool[source]¶

Delete entity from ZMON.

Note

ZMON DELETE entity API doesn’t return JSON response.

Parameters:	entity_id (str) – Entity ID.
Returns:	True if succeeded, False otherwise.
Return type:	bool

get_alert_data(alert_id: int, **kwargs) → dict[source]¶

Retrieve alert data.

Response is a dict with entity ID as a key, and check return value as a value.

Parameters:	alert_id (int) – ZMON alert ID.
Returns:	Alert data dict.
Return type:	dict

Example:

{
    "entity-id-1": 122,
    "entity-id-2": 0,
    "entity-id-3": 100
}

get_alert_definition(alert_id: int, **kwargs) → dict[source]¶

Retrieve alert definition.

Parameters:	alert_id (int) – Alert definition ID.
Returns:	Alert definition dict.
Return type:	dict

get_alert_definitions() → list[source]¶

Return list of all active alert definitions.

Returns:	List of alert-defs.
Return type:	list

get_check_definition(definition_id: int, **kwargs) → dict[source]¶

Retrieve check defintion.

Parameters:	defintion_id (int) – Check defintion id.
Returns:	Check definition dict.
Return type:	dict

get_check_definitions() → list[source]¶

Return list of all active check definitions.

Returns:	List of check-defs.
Return type:	list

get_dashboard(dashboard_id: str, **kwargs) → dict[source]¶

Retrieve a ZMON dashboard.

Parameters:	dashboard_id (int, str) – ZMON dashboard ID.
Returns:	Dashboard dict.
Return type:	dict

get_entities(query=None, **kwargs) → list[source]¶

Get ZMON entities, with optional filtering.

Parameters:	query (dict) – Entity filtering query. Default is `None`. Example query `{'type': 'instance'}` to return all entities of type: `instance`.
Returns:	List of entities.
Return type:	list

get_entity(entity_id: str, **kwargs) → str[source]¶

Retrieve single entity.

Parameters:	entity_id (str) – Entity ID.
Returns:	Entity dict.
Return type:	dict

get_grafana_dashboard(grafana_dashboard_uid: str, **kwargs) → dict[source]¶

Retrieve Grafana dashboard.

Parameters:	grafana_dashboard_uid (str) – Grafana dashboard UID.
Returns:	Grafana dashboard dict.
Return type:	dict

get_onetime_token() → str[source]¶

Retrieve new one-time token.

You can use zmon_cli.client.Zmon.token_login_url() to return a deeplink to one-time login.

Returns:	One-time token.
Retype:	str

grafana_dashboard_url(dashboard: dict) → str[source]¶

Return direct deeplink to Grafana dashboard.

Parameters:	dashboard (dict) – Grafana dashboard dict.
Returns:	Deeplink to Grafana dashboard.
Return type:	str

list_onetime_tokens() → list[source]¶

List exisitng one-time tokens.

Returns:	List of one-time tokens, with relevant attributes.
Retype:	list

Example:

- bound_at: 2016-09-08 14:00:12.645999
  bound_expires: 1503744673506
  bound_ip: 192.168.20.16
  created: 2016-08-26 12:51:13.506000
  token: 9pSzKpcO

search(q, limit=None, teams=None, **kwargs) → dict[source]¶

Search ZMON dashboards, checks, alerts and grafana dashboards with optional team filtering.

Parameters:	q (str) – search query. teams (list) – List of team IDs. Default is None.
Returns:	Search result.
Return type:	dict

Example:

{
    "alerts": [{"id": "123", "title": "ZMON alert", "team": "ZMON"}],
    "checks": [{"id": "123", "title": "ZMON check", "team": "ZMON"}],
    "dashboards": [{"id": "123", "title": "ZMON dashboard", "team": "ZMON"}],
    "grafana_dashboards": [{"id": "123", "title": "ZMON grafana", "team": ""}],
}

status() → dict[source]¶

Return ZMON status from status API.

Returns:	ZMON status.
Return type:	dict

token_login_url(token: str) → str[source]¶

Return direct deeplink to ZMON one-time login.

Parameters:	token (str) – One-time token.
Returns:	Deeplink to ZMON one-time login.
Return type:	str

update_alert_definition(alert_definition: dict, **kwargs) → dict[source]¶

Update existing alert definition.

Atrributes id, last_modified_by and check_definition_id are required. If status is not set, then it will be set to ACTIVE.

Parameters:	alert_definition (dict) – ZMON alert definition dict.
Returns:	Alert definition dict.
Return type:	dict

update_check_definition(check_definition, skip_validation=False, **kwargs) → dict[source]¶

Update existing check definition.

Atrribute owning_team is required. If status is not set, then it will be set to ACTIVE.

Parameters:	check_definition (dict) – ZMON check definition dict. skip_validation (bool) – Skip validation of the check command syntax.
Returns:	Check definition dict.
Return type:	dict

update_dashboard(dashboard: dict, **kwargs) → dict[source]¶

Create or update dashboard.

If dashboard has an id then dashboard will be updated, otherwise a new dashboard is created.

Parameters:	dashboard (int, str) – ZMON dashboard dict.
Returns:	Dashboard dict.
Return type:	dict

update_grafana_dashboard(grafana_dashboard: dict, **kwargs) → dict[source]¶

Update existing Grafana dashboard.

Atrributes uid and title are required.

Parameters:	grafana_dashboard (dict) – Grafana dashboard dict.
Returns:	Grafana dashboard dict.
Return type:	dict

static validate_check_command(src)[source]¶

Validates if check command is valid syntax. Raises exception in case of invalid syntax.

Parameters:	src (str) – Check command python source code.
Raises:	ZmonError