Skip to content

Create a TCP Synthetic Test


TCP Tests check the connection status, response time, and routing of a target port. You can set the expected connection status to established, refused, or timeout and combine it with other assertions to verify whether the port behaves as expected. The response time and route tracing results also help you analyze connection performance and network paths.

A successful TCP connection only indicates that the connection is established, not that the application-layer service is healthy; a connection timeout alone cannot prove that a firewall rule has taken effect or that the port is definitely closed.

Prerequisites

The selected execution nodes must support connection status assessment. When using self-hosted nodes, confirm that the node version supports this capability. For node installation and updates, see Self-hosted Node Management and DataKit Upgrade.

Create a Test

Click Create > API Tests and select TCP.

Timeout and connection status assertion configuration in a TCP test

Step 1: Define the Request Format

  1. Host: Supports entering a host address and port. The host address can be a domain name (such as www.example.com) or an IP address (such as 192.168.0.1), and the port defaults to 443.
  2. Timeout: Sets the total time limit for DNS resolution and TCP connection establishment, in seconds. The default is 10, and integers from 1 to 60 are supported. If the input is empty, not an integer, or out of range, the test cannot be run or saved.
  3. Name: Specify a name for the TCP synthetic test. The name must be unique within the current workspace.
  4. Route tracing: When enabled, a route tracing probe (traceroute) runs to discover all gateways along the path to the target host (❗️the default per-hop timeout for route tracing is 500 ms).

DNS resolution and connection establishment share the configured timeout; when the target is an IP address, timing starts when the connection attempt begins. Queuing, route tracing, and message read/write after the connection is established are not counted against this limit. If the connection is established early or explicitly refused, subsequent assertions run without waiting for the timeout.

The Timeout setting controls the upper waiting limit, while the Response time assertion checks whether the actual elapsed time meets the target. The two take effect independently. The per-hop timeout for route tracing is also independent of this setting.

When editing an existing test, the original timeout configuration is retained if it is not modified; it is not automatically overwritten with 10 seconds. If a historical configuration falls outside the range of the new form, the original value is kept when editing other fields. If the timeout is actively modified, it is validated as an integer between 1 and 60 seconds. Older tests without an explicit timeout continue to use their original default behavior.

Step 2: Assertions

You can add assertions to match data based on the filter conditions. When multiple assertions are selected, you can define the AND or OR logical relationship by choosing All or Any.

When Connection Status is selected, the operator is Equals, and the following expected values are supported:

Expected Status Value Meaning
Established established The TCP connection was established successfully
Refused refused The connection attempt received an explicit refusal
Timeout timeout TCP connection establishment did not complete within the specified time

The assertion passes when the actual connection status matches the expected status. For example, if the expected status is Refused and the actual connection is refused, the connection status assertion passes; the final test result is still determined by all conditions combined with All or Any.

The connection status can be used alone or combined with response time and network hops. For example, with a timeout of 10 seconds, the conditions Connection Status Equals Established and Response Time Less Than 1000 ms, and All selected: if the connection is established at the 5th second, the connection status condition passes, but the response time condition fails, so the final test fails.

Exceptions such as DNS failure, DNS timeout, no route, node failure, user cancellation, and platform execution timeout are not connection status timeout and cannot pass the Connection Status Equals Timeout assertion. Read/write timeouts after the connection is established are also not connection-establishment timeouts.

Testing and Results

After configuring the request and assertions, click Test to view the actual connection status, expected status, and assertion results. When route tracing or a network hops condition is configured, the route tracing results are also returned.

If only Connection Status Equals Refused is configured, an actual refusal is judged as a successful test; if only Connection Status Equals Timeout is configured, an actual connection-establishment timeout is also judged as successful. When multiple conditions are configured, check the result of each condition and the combination logic.

Scheduled executions and on-demand tests use the same timeout and assertion rules. The execution details show the actual connection status, effective timeout, execution-side diagnostic information, and the final test result, which can be analyzed together with the expected status configured in the test. Historical records without a connection status field display "—" and are not inferred from historical pass or fail status. Older tests without a connection status condition keep their original assertion behavior.

Success result in TCP execution details: established connection status, effective timeout, and response time

Note
  • If Network Hops is selected as an assertion, the system returns route tracing data, similar to enabling the Traceroute feature.
  • Test results are independent of the selected synthetic nodes.

Step 3: Select Synthetic Nodes

Currently TrueWatch covers 14 synthetic nodes worldwide. You can select one or more nodes in the China region or overseas regions (Commercial Plan and above only) to quickly begin monitoring site service quality.

Step 4: Select Test Frequency

Select the execution frequency for the synthetic test. The following options are supported:

  • 1 minute (Commercial Plan and above only)
  • 5 minutes (Commercial Plan and above only)
  • 15 minutes (Commercial Plan and above only)
  • 30 minutes
  • 1 hour
  • 6 hours
  • 12 hours
  • 24 hours

In addition to the preset options above, you can enter a custom crontab schedule to configure scheduled executions based on minutes, hours, days, months, weeks, and other intervals.