argusclient Package

argusclient Package

client Module

This modules contains various client classes to interact with the Argus RESTful webservice endpoints. The implementation is based on API documentation from /help on various endpoints and web service reference.

class argusclient.client.AlertNotificationsServiceClient(argus, alert)

Bases: argusclient.client.BaseUpdatableModelServiceClient

Service class that interfaces with the Argus alert notifications endpoint.

There is no need to instantiate this directly, as it is available as argusclient.client.AlertsServiceClient.notifications attribute.

add(notification)

Adds the notification to this alert.

Returns:the added argusclient.model.Notification with all fields populated.
get(id)

Gets the item with specified id. This method retrieves it from Argus, if the object is not already available in the local collection.

items()

Returns the list of (id, object) pairs as tuples, works like the corresponding method on a dict. Calling this method may result in sending a request to Argus to fetch all relevant objects.

keys()

Returns the list of ids, just like the corresponding method on a dict. Calling this method may result in sending a request to Argus to fetch all relevant objects.

update(id, obj)

Updates the specified item on Argus as well as in the local collection.

Returns:the updated object with all fields populated.
values()

Returns the list of objects, just like the corresponding method on a dict. Calling this method may result in sending a request to Argus to fetch all relevant objects.

class argusclient.client.AlertTriggersServiceClient(argus, alert)

Bases: argusclient.client.BaseUpdatableModelServiceClient

Service class that interfaces with the Argus alert triggers endpoint.

There is no need to instantiate this directly, as it is available as argusclient.client.AlertsServiceClient.triggers attribute.

add(trigger)

Adds the trigger to this alert.

Returns:the added argusclient.model.Trigger with all fields populated.
get(id)

Gets the item with specified id. This method retrieves it from Argus, if the object is not already available in the local collection.

items()

Returns the list of (id, object) pairs as tuples, works like the corresponding method on a dict. Calling this method may result in sending a request to Argus to fetch all relevant objects.

keys()

Returns the list of ids, just like the corresponding method on a dict. Calling this method may result in sending a request to Argus to fetch all relevant objects.

update(id, obj)

Updates the specified item on Argus as well as in the local collection.

Returns:the updated object with all fields populated.
values()

Returns the list of objects, just like the corresponding method on a dict. Calling this method may result in sending a request to Argus to fetch all relevant objects.

class argusclient.client.AlertsServiceClient(argus)

Bases: argusclient.client.BaseUpdatableModelServiceClient

Service class that interfaces with the Argus alerts endpoint.

There is no need to instantiate this directly, as it is available as argusclient.client.ArgusServiceClient.alerts attribute.

triggers

argusclient.client.AlertTriggersServiceClient

Interfaces with the Argus alert triggers endpoint.

notifications

argusclient.client.AlertNotificationsServiceClient

Interfaces with the Argus alert notifications endpoint.

add(alert)

Adds the alert.

Returns:the argusclient.model.Alert object with all fields populated.
add_notification_trigger(alertid, notificationid, triggerid)

Associates the trigger with the specified notification.

Returns:the argusclient.model.Trigger with all fields populated.
delete(id)

Deletes the object from Argus service and also from this collection (if exists).

delete_notification_trigger(alertid, notificationid, triggerid)

Disassociates the trigger with the specified notification. This method has no return value.

get(id)

Gets the item with specified id. This method retrieves it from Argus, if the object is not already available in the local collection.

get_notification_trigger(alertid, notificationid, triggerid)

Returns the trigger only if it is associated with the specified notification.

Returns:the argusclient.model.Trigger object with all fields populated.
get_notification_triggers(alertid, notificationid)

Return all triggers that are associated with the specified notification as a list.

Returns:the list of argusclient.model.Trigger object with all fields populated.
get_user_alert(ownerName, alertName, shared=True)

Looks up an alert with its name and owner. Returns None if not found.

Returns:the argusclient.model.Alert object with all fields populated.
items()

Returns the list of (id, object) pairs as tuples, works like the corresponding method on a dict. Calling this method may result in sending a request to Argus to fetch all relevant objects.

keys()

Returns the list of ids, just like the corresponding method on a dict. Calling this method may result in sending a request to Argus to fetch all relevant objects.

update(id, obj)

Updates the specified item on Argus as well as in the local collection.

Returns:the updated object with all fields populated.
values()

Returns the list of objects, just like the corresponding method on a dict. Calling this method may result in sending a request to Argus to fetch all relevant objects.

class argusclient.client.AnnotationCollectionServiceClient(argus)

Bases: argusclient.client.BaseCollectionServiceClient

Service class that interfaces with the Argus annotations collection endpoint.

There is no need to instantiate this directly, as it is available as argusclient.client.ArgusServiceClient.annotations attribute.

add(data)

Sends data to the collection service.

Returns:argusclient.model.AddListResult object with a summary of the operation.
query(query)

Returns the list of data matching the given query.

class argusclient.client.AnnotationQuery(scope, metric, source, tags=None, stTimeSpec=None, enTimeSpec=None)

Bases: argusclient.client.BaseQuery

This class is used to construct the query string for sending annotations queries to Argus.

>>> from argusclient.client import AnnotationQuery
>>> mquery = AnnotationQuery("test.scope", "test.metric", "test.source", tags={ "test.tag": "test.value" }, stTimeSpec="-1d", enTimeSpec="-0d")
>>> print str(mquery)
-1d:-0d:test.scope:test.metric{test.tag=test.value}:test.source
__str__()

Return string representation of the query that can be used with an Argus query. A metric query has the format: -1d:-0d:scope:metric[{tagk=tagv,...}]:downsample[:aggregator][:namespace]. An annotation query has the format -1d:-0d:scope:metric[{tagk=tagv,...}]:source.

exception argusclient.client.ArgusAuthException

Bases: argusclient.client.ArgusException

An exception type that is thrown for Argus authentication errors.

exception argusclient.client.ArgusException

Bases: exceptions.Exception

An exception type that is thrown for Argus service errors.

class argusclient.client.ArgusServiceClient(user, password, endpoint, timeout=(10, 60), refreshToken=None, accessToken=None)

Bases: object

This is the main class to interact with the Argus webservice.

An instance of this class comes with the below attributes to interact with the different Argus endpoints:

metrics

argusclient.client.MetricCollectionServiceClient

Interfaces with the Argus metrics collection endpoint.

annotations

argusclient.client.AnnotationCollectionServiceClient

Interfaces with the Argus annotations collection endpoint.

dashboards

argusclient.client.DashboardsServiceClient

Interfaces with the Argus dashboards endpoint.

users

argusclient.client.UsersServiceClient

Interfaces with the Argus users endpoint.

namespaces

argusclient.client.NamespacesServiceClient

Interfaces with the Argus namespaces endpoint.

alerts

argusclient.client.AlertsServiceClient

Interfaces with the Argus alerts endpoint.

__init__(user, password, endpoint, timeout=(10, 60), refreshToken=None, accessToken=None)

Creates a new client object to interface with the Argus RESTful API.

Parameters:
  • user (str) – The username for Argus account.
  • password (str) – The password for Argus account. This is optional, unless a valid refreshToken or accessToken is specified. The password will be used to generate a refreshToken and accessToken.
  • endpoint (str) – The Argus endpoint to be used
  • timeout (int or float or tuple) – The timeout(s) to be applied for connection and read. This is passed as is to the calls to requests. For more information, see Requests Timeout
  • refreshToken (str) – A token that can be used to generate an accessToken as and when needed. When the refreshToken expires, the password (if specified) will be used to generate a new token.
  • accessToken – A token that can be used to authenticate with Argus. If a refreshToken or password is specified, the accessToken will be refreshed as and when it is needed.
_request(*args, **kwargs)

This is the low level method used to make the underlying Argus requests. This ensures that all requests are fully authenticated.

Parameters:
  • method (str) – The HTTP method name as a string. Some valid names are: get, post, put and delete.
  • path (str) – The Argus path on which the request needs to be made, e.g. /auth/login
login()

Logs into the Argus service and establishes required tokens. The call to login() is optional, as a session will be established the first time it is required.

Returns:the argusclient.model.User object.
logout()

Logs out of the Argus service and destroys the session.

class argusclient.client.DashboardsServiceClient(argus)

Bases: argusclient.client.BaseUpdatableModelServiceClient

Service class that interfaces with the Argus dashboards endpoint.

There is no need to instantiate this directly, as it is available as argusclient.client.ArgusServiceClient.dashboards attribute.

add(dashboard)

Adds the dashboard.

Returns:the argusclient.model.Dashboard object with all fields populated.
delete(id)

Deletes the object from Argus service and also from this collection (if exists).

get(id)

Gets the item with specified id. This method retrieves it from Argus, if the object is not already available in the local collection.

get_user_dashboard(ownerName, dashboardName, shared=True)

Looks up a dashboard with its name and owner. Returns None if not found.

Returns:the argusclient.model.Dashboard object with all fields populated.
items()

Returns the list of (id, object) pairs as tuples, works like the corresponding method on a dict. Calling this method may result in sending a request to Argus to fetch all relevant objects.

keys()

Returns the list of ids, just like the corresponding method on a dict. Calling this method may result in sending a request to Argus to fetch all relevant objects.

update(id, obj)

Updates the specified item on Argus as well as in the local collection.

Returns:the updated object with all fields populated.
values()

Returns the list of objects, just like the corresponding method on a dict. Calling this method may result in sending a request to Argus to fetch all relevant objects.

class argusclient.client.MetricCollectionServiceClient(argus)

Bases: argusclient.client.BaseCollectionServiceClient

Service class that interfaces with the Argus metrics collection endpoint.

There is no need to instantiate this directly, as it is available as argusclient.client.ArgusServiceClient.metrics attribute.

add(data)

Sends data to the collection service.

Returns:argusclient.model.AddListResult object with a summary of the operation.
query(query)

Returns the list of data matching the given query.

class argusclient.client.MetricQuery(scope, metric, aggregator, tags=None, namespace=None, downsampler=None, stTimeSpec=None, enTimeSpec=None)

Bases: argusclient.client.BaseQuery

This class is used to construct the query string for sending metric queries to Argus.

>>> from argusclient.client import MetricQuery
>>> mquery = MetricQuery("test.scope", "test.metric", "sum", tags={ "test.tag": "test.value" }, stTimeSpec="-1d", enTimeSpec="-0d", namespace="test.namespace")
>>> print str(mquery)
-1d:-0d:test.scope:test.metric{test.tag=test.value}:sum:test.namespace
__str__()

Return string representation of the query that can be used with an Argus query. A metric query has the format: -1d:-0d:scope:metric[{tagk=tagv,...}]:downsample[:aggregator][:namespace]. An annotation query has the format -1d:-0d:scope:metric[{tagk=tagv,...}]:source.

class argusclient.client.NamespacesServiceClient(argus)

Bases: argusclient.client.BaseModelServiceClient

Service class that interfaces with the Argus namespaces endpoint.

There is no need to instantiate this directly, as it is available as argusclient.client.ArgusServiceClient.namespaces attribute.

add(namespace)

Adds the namespace.

Returns:the new argusclient.model.Namespace with all fields populated.
get(id)

Return the object for the specified id. If the object is not already in the local collection, a one-time attempt would be made to load all objects from Argus.

items()

Returns the list of (id, object) pairs as tuples, works like the corresponding method on a dict. Calling this method may result in sending a request to Argus to fetch all relevant objects.

keys()

Returns the list of ids, just like the corresponding method on a dict. Calling this method may result in sending a request to Argus to fetch all relevant objects.

update(id, namespace)

Updates the specified namespace.

Returns:the updated argusclient.model.Namespace with all fields populated.
update_users(namespaceid, *users)

Updates the namespace with the specified users.

Returns:the updated argusclient.model.Namespace with all fields populated.
values()

Returns the list of objects, just like the corresponding method on a dict. Calling this method may result in sending a request to Argus to fetch all relevant objects.

class argusclient.client.UsersServiceClient(argus)

Bases: argusclient.client.BaseModelServiceClient

Service class that interfaces with the Argus users endpoint.

There is no need to instantiate this directly, as it is available as argusclient.client.ArgusServiceClient.users attribute.

get(key)

Return the User for the specified id/username. If the object is not already in the local collection, an attempt will be made to retrieve it from Argus.

items()

Returns the list of (id, object) pairs as tuples, works like the corresponding method on a dict. Calling this method may result in sending a request to Argus to fetch all relevant objects.

keys()

Returns the list of ids, just like the corresponding method on a dict. Calling this method may result in sending a request to Argus to fetch all relevant objects.

values()

Returns the list of objects, just like the corresponding method on a dict. Calling this method may result in sending a request to Argus to fetch all relevant objects.

dashboardtags Module

This module provides functions for generating dashboard tags. These functions are simple wrappers on top of the lxml ElementMaker API. These functions can be combined with additional HTML tags to produce the required XML to define dashboards.

>>> import lxml.etree
>>> from argusclient.dashboardtags import E, DASHBOARD, CHART, TITLE, METRIC
>>> h1 = E.h1
>>> hr = E.hr
>>> dashboard = DASHBOARD(h1("Test Dashboard"), hr(), CHART(TITLE("hdara.test"), METRIC("-1d:-0d:test.scope:test.metric:sum", name="hdara.test.metric"), name="Chart"))
>>> print lxml.etree.tostring(dashboard, pretty_print=True)
<ag-dashboard>
  <h1>Test Dashboard</h1>
  <hr/>
  <ag-chart name="Chart">
    <ag-option name="title.text" value="hdara.test"/>
    <ag-metric name="hdara.test.metric">-1d:-0d:test.scope:test.metric:sum</ag-metric>
  </ag-chart>
</ag-dashboard>
>>> print lxml.etree.tostring(dashboard, method="html")
<ag-dashboard><h1>Test Dashboard</h1><hr/><ag-chart name="Chart"><ag-option name="title.text" value="hdara.test"/><ag-metric name="hdara.test.metric">-1d:-0d:test.scope:test.metric:sum</ag-metric></ag-chart></ag-dashboard>

Argus cant’t handle auto-closed XML tags, so using “html” method is recommended.

argusclient.dashboardtags.AREA_CHART(*args, **kwargs)

Generates an ag-chart tag with type=’stackarea’.

argusclient.dashboardtags.CHART(*args, **kwargs)

Generates an ag-chart tag.

argusclient.dashboardtags.DASHBOARD(*args, **kwargs)

Generates an ag-dashboard tag.

argusclient.dashboardtags.DATE(*args, **kwargs)

Generates an ag-date tag.

argusclient.dashboardtags.E

Use this to create additional XML/HTML tags, e.g., E.h1 will create the <h1> tag

argusclient.dashboardtags.END_DATE(name='end', label='End Date', default='-0d')

Generates a ag-date tag with sensible defaults for name, label and default for specifying end date.

argusclient.dashboardtags.FLAGS(*args, **kwargs)

Generates an ag-flags tag.

argusclient.dashboardtags.METRIC(*args, **kwargs)

Generates an ag-metric tag.

argusclient.dashboardtags.OPTION(*args, **kwargs)

Generates an ag-option tag.

argusclient.dashboardtags.START_DATE(name='start', label='Start Date', default='-1d')

Generates a ag-date tag with sensible defaults for name, label and default for specifying a start date.

argusclient.dashboardtags.STATUS_INDICATOR(*args, **kwargs)

Generates an ag-status-indicator tag with the passed in name,`hi`,`low` and METRIC attributes

argusclient.dashboardtags.SUBMIT(*args, **kwargs)

Generates an ag-submit tag.

argusclient.dashboardtags.SUB_TITLE(subTitle)

Generates a ag-option tag with the specified subtitle.

argusclient.dashboardtags.TABULAR(*args, **kwargs)

Generates an ag-table tag.

argusclient.dashboardtags.TEXT(*args, **kwargs)

Generates an ag-text tag.

argusclient.dashboardtags.TEXT_BOX(name, label=None, default=None)

Generates a ag-text tag with sensible defaults for type, name, label and default for specifying text field.

argusclient.dashboardtags.TITLE(title)

Generates a ag-option tag with the specified title.

argusclient.dashboardtags.XMAX(value)

Generates a ag-option tag with the specified xaxis.max value.

argusclient.dashboardtags.XMIN(value)

Generates a ag-option tag with the specified xaxis.min value.

argusclient.dashboardtags.YMAX(value)

Generates a ag-option tag with the specified yaxis.max value.

argusclient.dashboardtags.YMIN(value)

Generates a ag-option tag with the specified yaxis.min value.

model Module

Module containing the classes that model the Argus base objects.

class argusclient.model.AddListResult(**kwargs)

Bases: argusclient.model.BaseEncodable

Represents the result of metric or annotation collection add request.

Ex: {“Error Messages”:[],”Error”:”0 metrics”,”Success”:”1 metrics”}

argus_id

The property that gives access to the Argus ID. This is None for new objects.

error_count()

Return error count from the result.

error_messages()

Return any error messsages from the result.

owner_id

The ID of the object that owns this object or None. Only applicable to a few types that are not first-class objects.

success_count()

Return success count from the result.

class argusclient.model.Alert(name, expression, cronEntry, **kwargs)

Bases: argusclient.model.BaseEncodable

Represents an Alert object in Argus.

Alert name has to be unique across the alerts owned by the current user.

Required parameters to the constructor:

Parameters:
  • name (str) – The name of the alert
  • expression (str) – The metric query expression
  • cronEntry (str) – The cron expression

Optional parameters to the constructor:

Parameters:
  • enabled (bool) – The enabled state of the alert
  • missingDataNotificationEnabled (bool) – The enabled state of missing data notification
  • triggerIds (list of int) – The list of IDs for the triggers owned by this alert.
  • notificationIds (list of int) – The list of IDs for the notifications owned by this alert.
  • shared – The shared state of the alert
argus_id

The property that gives access to the Argus ID. This is None for new objects.

notification

A convenience property to be used when notifications contains a single argusclient.model.Notification.

notifications

Property to get and set notifications on the alert.

owner_id

The ID of the object that owns this object or None. Only applicable to a few types that are not first-class objects.

trigger

A convenience property to be used when triggers contains a single argusclient.model.Trigger.

triggers

Property to get and set triggers on the alert.

class argusclient.model.Annotation(source, scope, metric, id, timestamp, type, **kwargs)

Bases: argusclient.model.BaseEncodable

Represents an Annotation object in Argus.

Required parameters to the constructor:

Parameters:
  • source (str) – The source of the annotation
  • scope (str) – The scope for the annotation
  • metric (str) – The metric name of the annotation
  • timestamp (int) – The timestamp of the annotation
  • id (int) – An external id for the annotation

Optional parameters to the constructor:

Parameters:
  • tags (dict of str:str) – A dictionary of tags. Both keys and values should be valid strings.
  • fields (dict of str:str) – A dictionary of fields. Both keys and values should be valid strings.
__str__()

Return a string representation of the annotation that can be directly used as the annotation expresson in an annotation query and has the format: scope:metric[{tagk=tagv,...}]:source

argus_id

The property that gives access to the Argus ID. This is None for new objects.

owner_id

The ID of the object that owns this object or None. Only applicable to a few types that are not first-class objects.

class argusclient.model.Dashboard(name, content, **kwargs)

Bases: argusclient.model.BaseEncodable

Represents a Dashboard object in Argus.

Dashboard name has to be unique across the dashboards owned by the current user.

Required parameters to the constructor:

Parameters:
  • name (str) – The name of the dashboard
  • content (str) – The XML content

Optional parameters to the constructor:

Parameters:
  • description (str) – A description for the dashboard
  • shared (bool) – The shared state of the dashboard.
  • id (int) – The Argus id of the dashboard
argus_id

The property that gives access to the Argus ID. This is None for new objects.

owner_id

The ID of the object that owns this object or None. Only applicable to a few types that are not first-class objects.

class argusclient.model.Metric(scope, metric, **kwargs)

Bases: argusclient.model.BaseEncodable

Represents a Metric object in Argus.

Required parameters to the constructor:

Parameters:
  • scope (str) – The scope for the annotation
  • metric (str) – The metric name of the annotation

Optional parameters to the constructor:

Parameters:
  • namespace (str) – The namespace for the metric
  • displayName (str) – The display name of the metric
  • unitType (str) – The unit type of the metric value
  • datapoints (dict of int:object) – The actual metric data points as a dictionary of values with epoc timestamp as the keys.
  • tags (dict of str:str) – A dictionary of tags. Both keys and values should be valid strings.
__str__()

Return a string representation of the metric that can be directly used as the metric expressoin in a metric query and has the format: scope:metric[{tagk=tagv,...}][:namespace]

argus_id

The property that gives access to the Argus ID. This is None for new objects.

owner_id

The ID of the object that owns this object or None. Only applicable to a few types that are not first-class objects.

class argusclient.model.Namespace(qualifier, **kwargs)

Bases: argusclient.model.BaseEncodable

Represents a Namespace object in Argus.

Required parameters to the constructor:

Parameters:qualifier (str) – The namespace qualifier

Optional parameters to the constructor:

Parameters:
  • usernames (list of str) – The list of usernames that are authorized to post metrics to the namespace.
  • id (int) – The Argus id of this namespace
argus_id

The property that gives access to the Argus ID. This is None for new objects.

owner_id

The ID of the object that owns this object or None. Only applicable to a few types that are not first-class objects.

class argusclient.model.Notification(name, notifierName, metricsToAnnotate=None, **kwargs)

Bases: argusclient.model.BaseEncodable

Represents a Notification object in Argus.

Required parameters to the constructor:

Parameters:
  • name (str) – The name of the notification
  • notifierName (str) – The name of the notifier implementation. Must be one of EMAIL, AUDIT, GOC, GUS

Optional parameters to the constructor:

Parameters:
  • subscriptions (list of str) – The subscriptions for the notifier implementation, such as email ids in case of EMAIL.
  • cooldownPeriod (float) – The cooldown period
  • cooldownExpiration (float) – The cooldown expiration
  • triggerIds (list of int) – List of IDs of triggers that this notification is associated with.
  • alertId (int) – ID of the alert that this trigger belongs to.
AUDIT = 'com.salesforce.dva.argus.service.alert.notifier.AuditNotifier'
EMAIL = 'com.salesforce.dva.argus.service.alert.notifier.EmailNotifier'
GOC = 'com.salesforce.dva.argus.service.alert.notifier.GOCNotifier'
GUS = 'com.salesforce.dva.argus.service.alert.notifier.GusNotifier'
VALID_NOTIFIERS = frozenset(['com.salesforce.dva.argus.service.alert.notifier.AuditNotifier', 'com.salesforce.dva.argus.service.alert.notifier.EmailNotifier', 'com.salesforce.dva.argus.service.alert.notifier.GOCNotifier', 'com.salesforce.dva.argus.service.alert.notifier.GusNotifier'])

Set of all valid notifier implementation names.

argus_id

The property that gives access to the Argus ID. This is None for new objects.

owner_id

The ID of the object that owns this object or None. Only applicable to a few types that are not first-class objects.

class argusclient.model.Trigger(name, type, threshold, inertia, **kwargs)

Bases: argusclient.model.BaseEncodable

Represents a Trigger object in Argus.

Required parameters to the constructor:

Parameters:

Optional parameters to the constructor:

Parameters:
  • secondaryThreshold (float) – Secondary threshold.
  • notificationIds (list of int) – List of IDs of notifications that this trigger is associated with.
  • alertId (int) – ID of the alert that this trigger belongs to.
BETWEEN = 'BETWEEN'
EQUAL = 'EQUAL'
GREATER_THAN = 'GREATER_THAN'
GREATER_THAN_OR_EQ = 'GREATER_THAN_OR_EQ'
LESS_THAN = 'LESS_THAN'
LESS_THAN_OR_EQ = 'LESS_THAN_OR_EQ'
NOT_BETWEEN = 'NOT_BETWEEN'
NOT_EQUAL = 'NOT_EQUAL'
VALID_TYPES = frozenset(['LESS_THAN_OR_EQ', 'NOT_EQUAL', 'GREATER_THAN_OR_EQ', 'EQUAL', 'NOT_BETWEEN', 'BETWEEN', 'GREATER_THAN', 'LESS_THAN'])

Set of all valid trigger types.

argus_id

The property that gives access to the Argus ID. This is None for new objects.

owner_id

The ID of the object that owns this object or None. Only applicable to a few types that are not first-class objects.

class argusclient.model.User(userName, **kwargs)

Bases: argusclient.model.BaseEncodable

Represents a User object in Argus.

Required parameters to the constructor:

Parameters:userName (str) – The username of the Argus user

Optional parameters to the constructor:

Parameters:email (str) – The email address of the Argus user
argus_id

The property that gives access to the Argus ID. This is None for new objects.

owner_id

The ID of the object that owns this object or None. Only applicable to a few types that are not first-class objects.