TCP Monitor Configuration

This page details every option of the monitoring settings for TCP Monitors. We do not recommend reading it start to finish - instead, use it as a reference when needed.

For details about alert settings - which are common to all monitor types - check this page.

For information about TCP Monitors in general, check this page.

Basics

These options are the only ones that must be specified, to configure essential settings.

Monitor name

Default value: (blank)

Use this textbox to give your monitor a name. It is required, and any value up to 50 characters long is valid.

You should choose a name that makes sense to you, as it is shown throughout the console and on any alerts that are sent. The value has no other impact.

Note that this option is only present when creating a new monitor. To edit the name of an existing one, use the Rename panel on the General tab of the settings page.

Host

Default value: (blank)

Here, you should enter the hostname or IP address of the service you wish to monitor.

Enter the host in the textbox using correct formatting as appropriate. Do not include the port here, that should be entered in a separate field.

If the host is an IP address then it must not be in a private range. If it is a domain name then it must be publicly resolvable. localhost is not a valid hostname.

Port

Default value: (blank)

Use this textbox to specify the port of the service you wish the monitor.

You must enter an integer between 1 and 65535. This, along with the host value, should exactly match the remote address of your service.

Check schedule

Default value: Interval: 5 minutes

This option determines when or how often the monitor performs checks.

To have your monitor fire on a regular schedule, enter a valid interval using the textbox and dropdown. Any combination is allowed, so long as the equivalent number of seconds is:

a whole number (e.g. 0.5 minutes is allowed, 0.99 minutes is not)
no more than 2592000 (30 days, in seconds)
no less than the minimum allowed by your plan

The monitor will run for the first time as soon as you create it; then at every specified time interval thereafter.

Business and Enterprise accounts can also use crontab scheduling. For this, enter any valid crontab time expression into the textbox. The monitor will run according to this timetable. Crontab expressions are always evaluated against a clock in the UTC timezone, so you may need to adjust the hour portion accordingly.

You must provide exactly one of interval and crontab.

Using an interval of less than 60 seconds will cause the monitor to consume additional monitor credits. See this page for more details.

Parameters

These options alter the nature of the TCP session, including determining if a request should be sent and how to handle any response.

Timeout

Default value: 10 seconds

The timeout value controls the maximum length of time each check waits before considering the server as non-responsive (and therefore offline).

You can choose any whole number of seconds between 1 and 30, or leave blank to use the default of 10. The same timeout value is used for establishing the TCP connection and, if stop early is disabled, waiting for a TCP response after sending the request body (if any).

If the timeout is too short, then there is a risk of false positives. Your server may be online, but a random networking event (such as packet loss or congestion) may cause a timeout where it would have succeeded if given a little longer.

If the timeout is too long, then it would increase the delay before alerts are sent. If your server stopped responding, then a monitor with a timeout of 30 seconds and a retries setting of 3 would not trigger any alerts for at least 90 seconds.

Retries

Default value: 2 attempts per region

This option determines whether a check should try again in the event of a failure.

Specifically, a failure occurs it is not possible to establish a connection to server. For example, if the hostname does not resolve, the relevant port is not open, the server does not respond to a connection request, etc.

Additionally, if stop early is disabled, the check fails if:

No response is received within the time set by the timeout value
A response is received, but it does not pass response validation rules

If the retries value is set to 1 attempt per region, then any failure causes the check to fail immediately. With a value of 2 attempts per region, any failure causes the check to run again, from the start. Similarly, a check with 3 attempts per region would succeed even if there are two failures in a row, as long as the third one does not fail.

Retries are only used after a failure. For example, if a check has 2 attempts per region and the first one passes then it will not make a second attempt.

More retries reduces the risk of false positives, but cause additional delay before triggering alerts as all attempts must first be exhausted.

The retry logic occurs locally within a region. For example, if a monitor is set to run in London and Sydney with 3 attempts per region and the London check passes first time, then the Sydney check still only has 3 attempts.

Moreover, each region carries out its checks in parallel, with the overall result calculated only once all regions have either passed or exhausted all retries.

Stop early

Default value: False

This option sets which mode of operation to use. By default, the switch is disabled and normal mode is used.

A normal mode check consists of:

Establishing a TCP connection
Sending the request body (if present)
Waiting for a response (or a timeout)
Comparing the response against validation rules

Alternatively, you can enable stop early mode. Here, the check passes as soon as the TCP connection is established. No messages are sent or received.

The best mode to use depends on your circumstances, and on how the monitored server is configured.

Normal mode is often the best choice, as it allows a request body to be sent, and for validation rules to be performed against a response. This can be used to verify that server is returning the correct content, rather than just that it is returning some content.

Note that in normal mode, a check always fails if no response packets are received. It is acceptable to receive an empty response (one with no content), or for multiple packets to be received (which are concatenated in order).

If your server is not configured to send responses, or if you are only interested in monitoring the TCP connection process, then you should consider using stop early mode.

Request body

Default value: (blank)

This textbox allows you to specify content to send in a TCP message.

The content is sent immediately after a connection is established, unless stop early is enabled. If this field is left blank (as is the default), then no request is sent.

If not using stop early, then it is likely that you will need to send some data to cause the server to send a response, which is necessary for the check to succeed.

This is not universally true, but your server would have to be configured in such a way that it sends data as soon as a connection is established, which is unusual.

The correct content to send is highly variable and depends entirely on what sort of server you are trying to watch. You may wish to test this monitor with incidents disabled at first, to ensure your setup is correct.

To make editing easier, this input provides some basic escape sequences. Use \r, \n, and \t to represent carriage return, new line, and tab (respectively). Use \\r, \\n, and \\t to represent the literal values \r, \n, and \t (respectively).

For your convenience, the escaped version of your message will appear below the textbox, as soon as you have entered any content.

Rules

Default value: Content length greater than 0

These rules are used to validate the response that we receive from the server.

A check only passes if a response is received and if it then meets the conditions of the configured rules.

Between 0 and 5 rules can be specified. If no rules are used, then any response is considered valid (although a response still needs to be received).

Rules have three components:

Type: which rule is being applied (i.e. keyword rule or length rule)
Subtype: a rule-dependant configuration option (e.g. for a length rule, whether to compare lengths using equals, less than, greater than, etc.)
Value: the content to use for the rule (e.g. for a keyword rule, the specific word or phrase to search for)

Each item on the panel represents one rule, and consists of two dropdowns, a textbox, and a delete button. The first dropdown controls the type, the second determines the subtype, and the textbox specifies the value.

The options for the subtype dropdown will depend on the type. Similarly, the range of valid values will vary depending on both the selected type and subtype.

To create a new item, click the Add new rule button (which is hidden if no more rules can be added). Similarly, to use the default rules click the Reset to defaults button (which only appears after some edit has been made).

The rule validation logic is carried out as part of each check, in each region. If any rule is not met, the check fails. Depending on the values of retries, this may mean another attempt is made, or simply that the monitor is considered down in this region.

The results of the checks in each region - after rules validation - are combined to determine the overall status, according to the monitor's triggers.

There are currently two types of rule available for TCP monitors: keyword and length. Any combination of these may be used, including multiple of the same type (for example, multiple length rules could be used to establish a range).

Keyword

This rule is used to specify an expected word, phrase, or pattern that the contents (body) of the response should contain.

If the response contains no content, then it is considered as an empty string. Thus, any keyword rule that tests for presence will fail, and any that tests for absence will succeed.

If multiple packets are sent as part of the response, the content in them is concatenated (in order) before any validation rules are applied.

This rule has four subtypes: contains phrase, excludes phrase, matches regex, and fails regex.

Contains phrase

This subtype compares against an exact string. It is the logical inverse of the excludes phrase subtype.

The text given as the value for this rule must be present in the body at least once, in any location. The match is case-insensitive but otherwise exact - if the value contains multiple words then they must appear in the same order. The body can contain any or no text before or after the matched phrase.

For example, if the value is No, I am your father, a response body of:

Luke, I am your father would not match, so the rule fails
No I am your father would not match, so the rule fails
No, your father I am would not match, so the rule fails
no, i am your FATHER would match, so the rule passes
The quote is actually "No, I am your father" would match, so the rule passes.

To avoid potential mistakes, leading and trailing whitespace is trimmed from the value entered. If for some reason you need to test for a value including leading or trailing whitespace, consider using the matches regex subtype.

Excludes phrase

This subtype compares against an exact string. It is the logical inverse of the contains phrase subtype.

The text given as the value for this rule must not be present in the body in any location. The match is case-insensitive but otherwise exact - if the value contains multiple words then they can appear in a different order, just so long as the given value does not appear at any point.

For example, if the value is No, I am your father, a response body of:

Luke, I am your father would not match, so the rule passes
No I am your father would not match, so the rule passes
No, your father I am would not match, so the rule passes
no, i am your FATHER would match, so the rule fails
The quote is actually "No, I am your father" would match, so the rule fails.

Matches regex

This subtype compares against a regular expression. It is the logical inverse of the fails regex subtype.

This value must be a valid regular expression using the Python regex syntax. This rule passes only if the regex matches the response body at least once. Matching is case-insensitive, but otherwise follows default regex behaviour.

For example, if the value is (satur|sun)day, a response body of:

Monday would not match, so the rule fails
Saturday would match, so the rule passes
Today is sunday! would match, so the rule passes

Using a tool such as Regex101 can help with testing your expressions.

Fails regex

This subtype compares against a regular expression. It is the logical inverse of the matches regex subtype.

This value must be a valid regular expression using the Python regex syntax. This rule passes only if the regex does not match the response body. Matching is case-insensitive, but otherwise follows default regex behaviour.

For example, if the value is (satur|sun)day, a response body of:

Monday would not match, so the rule passes
Saturday would match, so the rule fails
Today is sunday! would match, so the rule fails

Using a tool such as Regex101 can help with testing your expressions.

Length

This rule is used to specify the expected length of the contents (body) of the response.

If the response contains no content, then it is considered to have a length of 0.

If multiple packets are sent as part of the response, the content in them is concatenated (in order) before any validation rules are applied.

Content length is measured in bytes, any only includes the body (if any). Packet header fields are not counted.

This rule has six subtypes: equal to, not equal to, less than, less or equal to, greater than, and greater or equal to.

Equal to

This subtype compares against a single value. It is the logical inverse of the not equal to subtype.

You must specify a non-negative integer, and the response is considered valid if its content length is exactly the same.

Not equal to

This subtype compares against a single value. It is the logical inverse of the equal to subtype.

You must specify a non-negative integer, and the response is considered valid if its content length is any other value.

Less than

This subtype compares against a single value. It is the logical inverse of the greater or equal to subtype.

You must specify a non-negative integer, and the response is considered valid if its content length is (strictly) less than this value.

Less or equal to

This subtype compares against a single value. It is the logical inverse of the greater than subtype.

You must specify a non-negative integer, and the response is considered valid if its content length is less than or equal to this value.

Greater than

This subtype compares against a single value. It is the logical inverse of the less or equal to subtype.

You must specify a non-negative integer, and the response is considered valid if its content length is (strictly) greater than this value.

Greater or equal to

This subtype compares against a single value. It is the logical inverse of the less than subtype.

You must specify a non-negative integer, and the response is considered valid if its content length is greater than or equal to this value.

Triggers

This configuration panel is used to control how the monitor status should be updated after each check.

The check first runs in each region. After it succeeds, or all retries are exhausted, the region reports this success or failure. All results are then collated centrally, with the monitor's status set according to the triggers set here.

The Down trigger is checked first, then Partial, then Degraded. The monitor's internal status is set to the first trigger whose condition is met. If none of the conditions are met, then it is set to Online.

Down

Default: All regions

The value of this trigger determines under what condition the monitor's internal status should be set to Down, based on the results of a check.

By default, the check must have failed in all regions for it to be considered Down. This is because if any region succeeds, then it would appear that the service is at least partially available, and another status may be more appropriate.

However, you can use the dropdown to adjust this threshold according to your specific circumstances and to better suit your needs.

A check is considered to have failed if it is not possible to establish a connection to server. For example, if the hostname does not resolve, the relevant port is not open, the server does not respond to a connection request, etc.

Additionally, if stop early is disabled, the check fails if:

No response is received within the time set by the timeout value
A response is received, but it does not pass response validation rules

A monitor accumulates downtime while its internal status is Down or Partial.

If the condition of this trigger is not met then the Partial trigger is considered next.

Partial

Default: 2 or more regions

The value of this trigger determines under what condition the monitor's internal status should be set to Partial, based on the results of a check.

By default, the check must have failed in 2 or more regions for it to be considered Partially down. This is to prevent a potential error in a single region from causing a false positive and sending alerts inappropriately.

However, you can use the dropdown to adjust this threshold according to your specific circumstances and to better suit your needs.

Additionally, if stop early is disabled, the check fails if:

No response is received within the time set by the timeout value
A response is received, but it does not pass response validation rules

It is not possible for a monitor with only a single region to be in a Partial state, as any value for this trigger would also meet the conditions of the Down trigger in that situation.

A monitor accumulates downtime while its internal status is Down or Partial.

If the condition of this trigger is not met then the Degraded trigger is considered next.

Degraded

Default: 1500 milliseconds

The value of this trigger determines under what condition the monitor's internal status should be set to Degraded, based on the results of a check.

By default, the average response time across all regions must be greater than 1500 milliseconds for it to be considered as having Degraded performance. This is because response times above this value may indicate a significant performance issue.

However, you can use the textbox to adjust this threshold according to your specific circumstances and to better suit your needs.

Response time is calculated as the time between attempting a TCP connection and receiving the first byte of data. In stop early mode, it is just the connection time.

If the condition of this trigger is not met then the internal status is set to Online.

Incidents

This configuration panel is used to determine various incident behaviours in response to a change in the monitor's internal status.

As alerts are sent when an incident is opened, it also affects when you will be notified about any potential issues.

Automatically open an incident

Default: True, for Down and Partial

This setting determines if an incident is created automatically when the monitor reaches a certain status.

Alerts (if any, as configured separately) are sent when an incident is opened.

By default, it is set to open if the monitor has an internal status of Down or Partial. This means that alerts will be sent if your service is down, but not if it is simply experiencing performance issues.

While for most users this is likely the right balance between false positives and false negatives, you are free to adjust it to better suit you needs, by selecting the relevant checkboxes. You may also wish to review the relevant trigger thresholds.

If you choose the Disable incident management for this monitor option, an incident will never be automatically opened. As this will effectively prevent any alerts being sent, it is not recommended in most cases. However, it could be useful for monitors that just gather metrics, or when other incident management services are already in place.

Show on public status pages

Default: True

This option determines if automatically-opened incidents are added to public status pages by default.

It is always possible to show incidents (of any type) on public status pages by choosing this option from the incident details page, but by default we can also do this automatically. This allows your users to see the latest details immediately, and may reassure them that the issue is being dealt with.

However, if you wish to have stronger control over your status pages, you may deselect this checkbox. Any future automatically-opened incidents will not appear on status pages until manually added. Existing incidents will still show, until manually removed.

As with all status page messages, an incident will only ever appear on status pages that feature the associated monitor as part of their content.

This setting does not affect internal status pages, which always show all incidents relevant to their contents, to keep staff up-to-date with the latest developments.

This option only applies to incidents opened automatically and thus has no effect if Automatically open an incident is disabled.

Incidents opened manually from the dashboard allow the choice of where they should be shown, during the creation process. Incidents reported by team members are never shown on public status pages until confirmed or acknowledged manually.

Automatically resolve incidents

Default: True

This setting controls how automatically-opened incidents are resolved.

With this option enabled, as is the default, they are automatically resolved as soon as the monitor reaches an internal status of Online.

Only automatically-opened incidents are ever automatically-resolved. It has no effect on those opened manually from the console, or reported by team members.

However, if you would rather ensure that all incidents raised by this monitor are only ever resolvable manually, you can uncheck this option.

Regions

Default: Worldwide

This option allows you to customize which regions your monitor performs checks in.

Using the default value of Worldwide allows us to choose the regions for you. We will always use at least three regions, each on a different continent.

Each check runs across the selected regions in parallel, with the results from each then collated centrally and processed according to the trigger settings.

If your server is only available from certain countries, or you wish greater control for another reason, you can specify exactly which regions should be used.

For example, if you run a server only accessible from Europe, you should not select any region outside this area. Otherwise, when running checks the server will appear offline in those regions and could cause false positives.

Specifying more than 3 regions will cause the monitor to consume additional monitor credits. This does not affect monitors set to Worldwide, regardless of how many regions they run in. See this page for more details.

You may also wish to control monitoring locations to comply with various legal requirements, particularly data localization or data residency regulations. Regardless of region setting, data is stored and processed in (at least) the United Kingdom and European Union.

For more information on data processing, read our data transparency statement or contact our support team. However, be aware that StatusCloud does not and cannot provide legal advice; please contact professional counsel for such queries.

Last updated on Saturday 27th August 2022