Python Client

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


ZMON python client library is part of ZMON CLI.

pip3 install --upgrade zmon-cli


Using ZMON client is pretty straight forward.

>>> from zmon_cli.client import Zmon

>>> zmon = Zmon('', token='123')

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

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

>>> check = zmon.get_check_definition(123)

>>> check['command']

>>> 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



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.


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.

  • 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.


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.


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


    "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.
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.


- bound_at: 2016-09-08 14:00:12.645999
  bound_expires: 1503744673506
  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.

  • q (str) – search query.
  • teams (list) – List of team IDs. Default is None.

Search result.

Return type:



    "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.

  • check_definition (dict) – ZMON check definition dict.
  • skip_validation (bool) – Skip validation of the check command syntax.

Check definition dict.

Return type:


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.