The SpeedSentry Python API

You can use the Inesonic, LLC SpeedSentry Python API easily connect your Python based infrastructure to SpeedSentry.

Downloading The API

The PHP API is maintained on github. You can find the repository at https://github.com/tuxidriver/speedsentry_python_api.

You can download a zip file containing the code by clicking on the Code button and selected Download ZIP.

SpeedSentry Class

The primary class you should use to interface with SpeedSentry through Python is the SpeedSentry class. The short example below demonstrates how you can use this class to obtain a list of your monitors.

import speedsentry
import json

# Replace the lines below with your actual customer ID and secret.
cid = "3b967d892f7f59af"
secret = "HnbJLexPtgDrIbcRlahddz8ohMqH+7sKgkyXXcA+Q+shV+TZmu6remtlu/75a6qPhqnCS1RUhUI="
api = speedsentry.SpeedSentry(
    customer_identifier = cid,
    customer_secret = secret
)

monitors_data = api.monitors_list(order_by = "monitor_id")
print(json.dumps(monitors_data, indent = 4))

The speedsentry package includes a number of typed dictionaries allowing you to more easily query returned data and, in the case of the monitor_update method, more easily build the request. For details, on the provided typed dictionaries, see Typed Dictionaries.

On error, the SpeedSentry class with throw an exception. For details on the exceptions, see Exception Classes.

class speedsentry.SpeedSentry(customer_identifier, customer_secret)

Class you can use to access the SpeedSentry REST API.

AUTHORITY = 'https://rest.1.speed-sentry.com'

The authority for the customer REST API.

SECRET_LENGTH = 56

The expected length of the customer secret after decoding, in bytes.

capabilities_get() → speedsentry.dictionary_object.Capabilities

Method you can use to obtain information on what features are supported by your subscription.

Returns

Returns a Capabilities instance you can use to determine the features supported by your subscription.

Return type

Capabilities

events_create(message: str, type_index=None, monitor_id=None)

Method you can use to generate a customer event.

Parameters

• message (str) – The message to be sent as part of the event.

• type_index – A value indicating the type of customer event to be created. A value of 1 indicates customer_1, a value of 2 indicates customer_2, etc. If not specified, then customer_1 is used.

• monitor_id (int or None) – An optional monitor ID you can tie to this message. If not specified or None, then the first monitor ID is used.

events_get(event_id: int) → speedsentry.dictionary_object.Event

Method you can use to obtain information on a single event.

Parameters

event_id (int) – The ID of the desired event.

Returns

Returns an Event instance describing the event.

Return type

Event instance

events_list(start_timestamp: Optional[int] = None, end_timestamp: Optional[int] = None) → list

Method you can use to obtain a list of events.

Parameters

• start_timestamp (int or None) – An optional starting Unix timestamp for events. A value of None means no start time.

• end_timestamp (int or None) – An optional ending Unix timestamp for events. A value of None means no end time.

Returns

Returns a list of events.

Return type

list

hosts_get(host_scheme_id: int) → speedsentry.dictionary_object.HostScheme

Method you can use to obtain a single host/scheme entry indexed by host/scheme ID.

Parameters

host_scheme_id (int) – The host/scheme ID of the desired host/scheme.

Returns

Returns single HostScheme instance.

Return type

HostScheme

hosts_list() → dict

Method you can use to obtain a dictionary of host/scheme instances indexed by host/scheme ID.

Returns

Returns a dictionary of HostScheme instances indexed by the host/scheme ID.

Return type

dict of HostScheme instances

latency_list(**kwargs) → tuple

Method you can use to obtain latency entries. Information can be limited to a specific timeframe, region, and/or monitor.

Parameters

• start_timestamp – An optional starting Unix timestamp for events. A value of None means no start time.

• end_timestamp – An optional ending Unix timestamp for events. A value of None means no end time.

• region_id – An optional region ID. If specified, then only values for this region will be included. Note that this parameter is mutually exclusive with monitor_id.

• monitor_id – An optional monitor ID. If specified, then only values for this monitor will be included. Note that this parameter is mutually exclusive with region_id.

Returns

Returns a tuple holding a list of LatencyEntry instances followed by a list of AggregatedLatencyEntry instances. The most recent values will be in the first list. The second list represents an aggregation of older values stored at a lower resolution and with additional information.

Return type

tuple

latency_plot(**kwargs) → bytes

Method you can use to obtain a pre-generated plot of latency data.

Parameters

• monitor_id (int) – An optional numeric monitor ID indicating the monitor of interest. Data aggregated from all monitors will be used if this parameter is not included.

• region_id (int) – An optional numeric region ID indicating the region we want latency plots for. Data aggregated for all regions will be used if this parameter is not included.

• start_timestamp (int) – An optional Unix timestamp indicating the start date/time to be used for the plot data. IF excluded, then the oldest existing data will be included.

• end_timestamp (int) – An optional Unix timestamp indicating the end date/time to be used for the plot data. If excluded, now is assumed.

• title (str) – An optional title to place on the plot.

• x_axis_label (str) – An optional label to apply to the horizontal axis.

• y_axis_label (str) – An optional label to apply to the vertical axis.

• minimum_latency (float) – The lower bounds for the latency values to plot. If excluded, then a reasonable lower bound will be selected based on the source data.

• maximum_latency (float) – The upper bounds for the latency values to plot. If excluded, then a reasonable upper bound will be selected based on the source data.

• log_scale (bool) – A boolean value indicating that a log scale should be used for latency values. A linear scale will be used by default. This value is only used for history plots.

• width (int) – The desired plot width, in pixels. Value can range from 100 to 2048. The value 1024 will be used by default.

• height (int) – The desired plot height in pixels. Value can range from 100 to 2048. The value 768 will be used by default.

• plot_type (str) – The plot type to be generated. Supported values are “history” and “histogram”. A history plot will be generated by default.

• format (str) – The format of the returned data. Value can be “jpg” or “png”. PNG encoded plots will be returned by default.

Returns

Returns a bytes object holding the plot image.

Return type

bytes

monitors_get(monitor_id: int) → speedsentry.dictionary_object.Monitor

Method you can use to obtain information on a single monitor.

Parameters

monitor_id (int) – The ID of the desired monitor.

Returns

Returns a Monitor instance describing this monitor.

Return type

Monitor instance

monitors_list(order_by: str = 'monitor_id') → dict

Method you can use to obtain a list of all monitors.

Parameters

order_by (str) – A string indicating the desired method the monitors should be indexed. Supported values are “monitor_id”, “user_ordering”, or “url”.

Returns

Returns a dictionary of Monitor instances.

Return type

dict of Monitor instances

monitors_update(monitor_data: list)

Method you can use to update monitor settings.

Parameters

monitor_data (list) – A list of MonitorEntry instances. The first entry has a user ordering of 0, the second entry has a user ordering of 1, etc.

multiple_list() → dict

Method you can use to obtain a dictionary holding multiple useful values in a single request.

Returns

Returns a dictionary holding:

• A dictionary of monitors by user order.

• A dictionary of authorities by host/scheme ID.

• A dictionary of events in chronological order.

• A dictionary of monitor status values by monitor ID.

Return type

dict

regions_get(region_id: int) → speedsentry.dictionary_object.Region

Method you can use to obtain information on a single region.

Parameters

region_id (int) – The ID of the desired region.

Returns

Returns a Region instance describing this region.

Return type

Region instance

regions_list() → dict

Method you can use to obtain a dictionary holding information on all regions. The dictionary will be indexed by region ID.

Returns

Returns a dictionary of regions by region ID.

Return type

dict

status_get(monitor_id: int) → str

Method you can use to obtain status on a specific monitor.

Parameters

monitor_id (int) – The ID of the desired monitor.

Returns

Returns a string holding “unknown”, “working”, or “failed” indicating the last reported status for this monitor.

Return type

str

status_list() → dict

Method you can use to obtain a dictionary holding the status for each monitor under your subscription.

Returns

Returns a dictionary holding the status of each monitor under your subscription. The dictionary is keyed by monitor ID. Each entry holds one of “unknown”, “working”, or “failed” indicating the last reported status for the monitor.

Return type

dict

Typed Dictionaries

The speedsentry module provides a number of typed dictionaries you can use to more easily inspect returned values. All typed dictionaries allow you to view members either as class instance scope properties or as dictionary members.

Depending on the typed dictionary, properties may be read-only or read/write.

Note that all typed dictionaries are implemented as classes ultimately derived from the Python dict type. All properties are implemented as Python properties that bind class instance scope getter/setter methods.

Capabilities

The Capabilities typed dictionary is used to present the return values from the speedsentry.SpeedSentry.capabilities_get() method. All properties are read-only.

class speedsentry.Capabilities(dictionary)

You can use this class to hold information about capabilities available to a customer under their subscription.

property customer_active

A value that holds True if the customer has verified their email address.

property maximum_number_monitors

The maximum number of monitors that can be configured under this subscription.

property multi_region_checking

A value that holds True if customer monitors are checked and their latency is measured from multiple geographic regions.

property paused

A value that holds True if the customer has enabled maintenance mode.

property polling_interval

The polling interval per monitor in seconds.

property supports_content_checking

A value that holds True if you can enable content change monitoring under your subscription.

property supports_keyword_checking

A value that holds True if you can enable and use content keyword checking under your subscription.

property supports_latency_tracking

If True, then latency will be measured for all monitors.

property supports_maintenance_mode

A value that holds True if the customer can use maintenance mode.

property supports_ping_based_polling

A value that holds True if your servers will be checked using echo ICMP messages in addition to normal HTTP messages. The use of ping messages allows for faster reporting of a down server. Note that ping based polling will be performed automatically after your server is tested to confirm that ping messages are not blocked.

property supports_post_method

If True, then you can use any of the available HTTP methods. If False, then only the HTTP GET method is supported.

property supports_rest_api

A value that holds True if the full REST API is supported under this subscription.

property supports_rollups

A value that holds True if the customer can receive weekly rollups via Email.

property supports_ssl_expiration_checking

If True, then the expiration data on all your SSL keys will be checked. Events will be generated if your SSL keys are about to expire.

property supports_wordpress

A value that holds True if WordPress specific REST endpoints are supported.

HostScheme

The HostScheme typed dictionary is used to present the return values from the speedsentry.SpeedSentry.hosts_get() and speedsentry.SpeedSentry.hosts_list() methods. All properties are read-only.

class speedsentry.HostScheme(dictionary)

You can use this class to hold information about a specific host being checked by one or more monitors. The class also includes host specific information such as the SSL expiration date/time if supported by your subscription.

property host_scheme_id

The numeric ID used to reference this host/scheme entry.

property ssl_expiration_timestamp

The Unix timestamp when the hosts’s SSL certificate will expire.

property url

The URL used to access this host. This will generally be of the form https://myhost.com or similar.

Monitor

The Monitor typed dictionary is used to present the return values from the speedsentry.SpeedSentry.monitors_get() and speedsentry.SpeedSentry.monitors_list() methods. All properties are read-only.

class speedsentry.Monitor(dictionary)

You can use this class to hold information about a specific monitor you have configured.

property content_check_mode

Value indicating if content should be checked for changes or for specific keyword. Supported values are “no_check”, “content_match”, “all_keywords”, or “any_keywords”.

property host_scheme_id

The host/scheme ID of the host and scheme associated with this monitor.

property keywords

A list of keywords to be checked. The contents of this entry will be ignored if the content_check_mode value is not “all_keywords” or “any_keywords”.

property method

The method used to access this endpoint. Values will be either “get”, “head”, “post”, “put”, “delete”, “options”, or “patch”.

property monitor_id

The numeric ID used to reference this monitor entry.

property path

The path portion of the URL for this monitor, including query strings.

property post_content

The raw content to be sent to the remote endpoint during a post.

property post_content_type

A value indicating the support post content types. The value supplied is used to specify the “Content-Type” header field sent to the endpoint. Supported values are “text”, “json”, and “xml”.

property post_user_agent

A value indicating the user agent string to be sent to the the remote endpoint.

property url

The full URL for this monitor. This value is not stored but is derived from the monitor’s path and monitor’s host/scheme entry.

property user_ordering

A zero based numeric value indicating the relative order of monitors on the website settings page.

MonitorEntry

The MonitorEntry typed dictionary is used to configure your monitors. Unlike most other typed dictionaries provided by the speedsentry plug-in, the MonitorEntry typed dictionary’s properties are read-write.

A list of MonitorEntry typed dictionary types are accepted by the speedsentry.SpeedSentry.monitors_update() method. Note that this method can also accept traditional Python dictionaries.

class speedsentry.MonitorEntry(dictionary)

You can use this class to update or change your monitors. This class contains a slightly different set of attributes from the Monitor class.

property content_check_mode

You can use this attribute to specify the content check mode to use for this endpoint. Supported values are “no_check”, “content_match”, “all_keywords”, or “any_keywords”. If not specified, then “no_check” will be used.

property keywords

You can use this attribute to specify a list of keywords to be used to check received content. The list can contain either strings or bytes objects. Strings will be converted to UTF-8 encoded bytes objects automatically.

property method

You can use this attribute to specify whether the endpoint should be tested using HTTP GET, HEAD, POST, etc. An HTTP GET method will be used if this parameter is not net. The supplied value should be the HTTP method in lower case.

property post_content

You can use this attribute to specify the content to send during HTTP POST messages. The value is ignored for HTTP GET messages. You can use either string or bytes objects. String objects will be automatically UTF-8 encoded.

property post_content_type

You can use this attribute to specify the content type sent by a HTTP POST message. The value will be ignored if you specify an HTTP GET message. Supported values are “text”, “json”, and “xml”. If not specified, then “text” will be used.

property post_user_agent

You can use this attribute to specify the User-Agent string to include in the HTTP POST header message. The value is ignored for HTTP GET messages.

property uri

You can populate this attribute with either a full URL to the endpoint you want monitored or you can populate this attribute with the path. If a path is used then the host and scheme will be taken from the previous entry based on the user ordering you specify. This is the only required field.

Region

The Region typed dictionary is used to represent a region where your site(s) are monitored from. The dictionary is returned by the speedsentry.SpeedSentry.regions_get() and speedsentry.SpeedSentry.regions_list() methods. Note that all properties in this dictionary are read-only.

class speedsentry.Region(dictionary)

You can use this class to hold information about a region.

property description

A short textual description of this region.

property region_id

The numeric ID used to identify this region.

Event

The Event typed dictionary is used to represent an event detected on your infrastructure by SpeedSentry. The typed dictionary is returned by the speedsentry.SpeedSentry.events_get() and speedsentry.SpeedSentry.events_list() methods. Note that all properties in this dictionary are read-only.

class speedsentry.Event(dictionary)

You can use this class to hold information about an event.

property event_id

The numeric ID used to identify this event.

property event_type

The event type. Supported values are “working”, “no_response”, “content_changed”, “keywords”, “ssl_certificate_expiring”, “ssl_certificate_renewed”, “customer_1”, “customer_2”, … “customer_10”.

property monitor_id

The numeric ID of the monitor that triggered this event.

property timestamp

The Unix timestamp indicating when the event occurred.

LatencyEntry

The LatencyEntry typed dictionary is used to represent a single recorded raw latency entry and is returned by the speedsentry.SpeedSentry.latency_list() method. All properties are read-only.

class speedsentry.LatencyEntry(dictionary)

You can use this class to hold information about a latency datapoint.

property latency

The measured latency value, in seconds.

property monitor_id

The monitor ID of the monitor where this measurement was taken.

property region_id

The region ID of the region where the Inesonic polling server that took this measurement is located.

property timestamp

The Unix timestamp indicating when this measurement was taken.

AggregatedLatencyEntry

The AggregatedLatencyEntry typed dictionary is used to represent a single aggregated latency entry. A list of these entries are returned by the speedsentry.SpeedSentry.latency_list() method. All properties are read-only.

class speedsentry.AggregatedLatencyEntry(dictionary)

You can use this class to hold information about an aggregation of latency entries. This class is similar to LatencyEntry except that it holds additional statistical data.

property average

The average latency measured across the original population that this aggregation represents.

property end_timestamp

The most recent or latest timestamp of any sample in the original population.

property latency

The measured latency value, in seconds, of a single randomly selected value from the original population.

property maximum

The maximum or worst latency found in the original population.

property minimum

The lowest measured or best latency found in the original population.

property monitor_id

The monitor ID of the monitor where this measurement was taken.

property number_samples

The number of raw samples in the original population that were used to generate this aggregation.

property region_id

The region ID of the region where the Inesonic polling server that took this measurement is located.

property start_timestamp

The earliest timestamp of any sample in the original population.

property timestamp

The Unix timestamp indicating when a single randomly selected sample from the original population was taken.

property variance

The population variance of the original population that this aggregation represents.

Exception Classes

The speedsentry Python API relies on exceptions to report most error conditions to you.

SpeedSentryException

The SpeedsentryException class is the base class for all exceptions that the speedsentry plugin may throw.

class speedsentry.SpeedSentryException(error_reason)

Base class for all SpeedSentry exception classes.

property error_reason

Read-only property that provides the reason for this error.

Type

str

CustomerIdentifierException

The CustomerIdentifierException will be thrown by the speedsentry.SpeedSentry.__init__() method if the supplied customer identifier has an invalid length.

class speedsentry.CustomerIdentifierException(error_reason)

Exception class that is raised when an invalid customer identifier is provided.

CustomerSecretException

The CustomerSecretException will be thrown by the speedsentry.SpeedSentry.__init__() method if the supplied customer secret has an invalid byte length.

class speedsentry.CustomerSecretException(error_reason)

Exception class that is raised when an invalid customer secret is provided.

CommunicationErrorException

The CommunicationErrorException will be thrown if the SpeedSentry Python API encounters a communication error of some kind.

class speedsentry.CommunicationErrorException(status_code=None, status_message=None)

Exception class that is raised when an communication error occurs.

DecodingErrorException

The DecodingErrorException is thrown if an error occurs while decoding the response received from an endpoint.

class speedsentry.DecodingErrorException(status_message=None)

Exception class that is raised when received data could not be decoded.