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)[source]¶
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 [source]¶
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
- events_create(message: str, type_index=None, monitor_id=None)[source]¶
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 [source]¶
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 [source]¶
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 [source]¶
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
- hosts_list() dict [source]¶
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 [source]¶
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 [source]¶
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 [source]¶
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 [source]¶
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)[source]¶
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 [source]¶
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 [source]¶
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 [source]¶
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 [source]¶
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 [source]¶
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.
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.
CustomerIdentifierException
¶
The CustomerIdentifierException
will be thrown by the
speedsentry.SpeedSentry.__init__()
method if the supplied customer
identifier has an invalid length.
CustomerSecretException
¶
The CustomerSecretException
will be thrown by the
speedsentry.SpeedSentry.__init__()
method if the supplied customer
secret has an invalid byte length.
CommunicationErrorException
¶
The CommunicationErrorException
will be thrown if the SpeedSentry Python
API encounters a communication error of some kind.
DecodingErrorException
¶
The DecodingErrorException
is thrown if an error occurs while decoding the
response received from an endpoint.