Introduction

This manual provides information on how to use the SpeedSentry REST API to take full advantage of the advanced features of SpeedSentry. The manual is divided into several key sections:

• This introduction

• Capabilities

• Concepts

• The Inesonic, LLC SpeedSentry PHP API documentation.

• The Inesonic, LLC SpeedSentry Python API documentation.

• The Inesonic, LLC SpeedSentry outbound REST API.

• The Inesonic, LLC SpeedSentry message format, in detail.

• Details on the various REST API endpoints we provide.

Capabilities

SpeedSentry offers users who purchase an appropriate subscription the ability to tie their site directly into SpeedSentry. Our REST API allows you to:

• Extract historical latency and event data about your infrastructure,

• the ability to query and to dynamically change the endpoints monitored by SpeedSentry,

• determine the last reported status of a given endpoint,

• pause and resume monitoring,

• easily generate histograms and plots of latency over time in a number of common image formats, and

• trigger user defined events.

Concepts

The Inesonic, LLC SpeedSentry REST API is relatively simple.

Regions

Inesonic, LLC maintains a fleet of polling servers at various locations around the world that we use to check your infrastructure. Servers are grouped into regions based on their geographic location with all servers in the same region identically configured and mantained in the same data center.

Regions are identified by a region_id and have a name and associated list of polling servers. Inesonic, LLC does not provide information on which server took a specific measurement or made a report although we do track the information internally.

Note that we will ocassionally move customers to new servers within the same region when we upgrade our infrastructure. We will also add servers to the list of servers testing monitors for a host/scheme as we add new servers to our fleet.

Host/Schemes

A “host/scheme” or authority represents one of your systems, identified by a URL such as “https://mysite.com”. Each host/scheme is referenced by a host_scheme_id which is a unique numeric identifier.

You may have multiple host/schemes associated with your account.

For each host/scheme, we optionally track an SSL expiration time and we track one or more monitors.

Monitors

A monitor represents a single web page or REST API endpoint that we test. Each monitor will have a path associated with it that represents the path on the system where the page is served from. Each monitor is reference by a world unique monitor_id.

For each monitor, we track:

Path

The path, combined with the host_scheme_id allows us to track the full URL to the page you wish to monitor. As an example. If the host_scheme_id indicates a URL of “https://mysite.com” and the path is “/mypage/?test=1”, the full URL we use to test your page or endpoint will be “https://mysite.com/mypage/?test=1”.

Host/Scheme ID

The host_scheme_id indicates the server where the page or endpoint to be tested resides.

User Order

The user_order represents the position of the monitor in the user’s Account Settings page. The first monitor is given a value of 0. The second monitor is given a value of 1, etc.

Note

We adjust user order values to remove any gaps in numbering. The user order numbers you provide us may not match the values we return back to you on subsequent requests.

Method

The method indicates the HTTP method or verb used to access your page or endpoint. We support a number of common HTTP methods, including:

• GET

• HEAD

• POST

• PUT

• DELETE

• OPTIONS

• PATCH

If you are testing normal web pages, use the HTTP GET method if you enable some type of content checking. Use the HTTP HEAD if you are not using content checking and wish to reduce the burden on your server.

Content Check Mode

When we check a page or endpoint, we can check the returned content. We currently support the content check modes listed in Table 1.

Table 1 Content Check Modes

Content Check Mode	Function
no_check	Indicates no content checking should be performed.
content_match	Indicates the content should be checked against the previously received content. An event will be reported if any change is detected. Note that the content is not interpreted so changes in spacing, different nonce values, or other content that is not visible from the browser will trigger an event. For this reason, we urge you to only use the content_match mode on static pages.
all_keywords	Indicates that the content should be checked for the presence of specific keywords. An event will be triggered if any keyword is missing.
any_keywords	Indicates that the content should be checked for the presence of specific keywords. An event will be triggered only if all keywords are missing.

Keywords

The monitor keywords is a list of keywords to be checked. The value is only used if the all_keywords or any_keywords content check mode is used.

Request Content Type

The request content type, sometimes called post_content_type indicates the type of content to be indicated in the request sent when testing a page or REST API endpoint. The value maps to values inserted into the “Content-Type” HTTP header field.

Request User Agent

The request user agent, sometimes called the post_user_agent holds the user agent string to be sent in the request header. Note that the user agent can only be sent for requests that contain a body.

Request Content

The request content, often called post_content contains the raw content to be sent in an HTTP request.

Events

Whenever we detect a fault condition or recovery from a fault, we both report and store an event. For each event, we track:

• The event type,

• The monitor_id of the monitor that triggered the event,

• The time of the event,

• An optional message for the event,

Events can be referenced by an event_id.

Inesonic, LLC stores additional side-band information to handle scenarios where multiple polling servers report the same event and will mark the event time as the time that the event was first reported. We guard against repeat events reported by different polling servers.

We treat custom events the same way we treat all other events with the exception that we do not guard against duplicate custom events.

Note

While we record all unique events, we may defer reporting of events to prevent swarming customers with many rapid fire notifications. Voice calls will be limited to one call per hour. SMS, email, and Slack notifications will be limited to one notification every 15 minutes. We do not limit the rate that we generate outbound REST API requests into your infrastructure.

Latency

Inesonic, LLC stores latency information in two formats. Newer values are stored in their raw form. Latency values older than one month are aggregated on an hourly basis to create aggregated latency entries.

Raw Latency

Raw latency values are tracked using four values:

• A monitor ID

• A polling server ID which then maps to a region ID.

• A timestamp indicating when the measurement was taken

• A raw latency value.

Aggregated Latency

Aggregated latency values have one hour resolution but store additional data with each entry. We also select a random raw value over the period we are aggregating in order to facilitate generating latency histograms over longer timeframes. For each aggregated entry, we store.

• A monitor ID

• A polling server ID which then maps to a region ID.

• The timestamp of the randomly selected value.

• The randomly selected raw latency value.

• The timestamp of the earliest raw latency value used to create the aggregated latency entry.

• The timestamp of the last raw latency value used to create the aggregated latency entry.

• The average latency across the aggregation.

• The population variance measured across the aggregation.

• The minimum latency measured across the aggregation.

• The maximum latency measured across the aggregation.