TCP Check

The TCP Check integration requires CXDOT Collector 1.4.0 or greater. A TCP connection probe opens a Transmission Control Protocol (TCP) connection to a host and port. Use the TCP Check CXDOT Collector integration to monitor whether service ports, such as databases, caches, and message brokers, accept connections and how long connections take to establish. The TCP Check CXDOT Collector integration works with any software that accepts TCP connections. For each target, the integration opens one connection, closes it after the connection is established, and sends no payload.

​

Supported telemetry types

The following table lists the telemetry types the TCP Check CXDOT Collector integration supports:

​

Prerequisites

The TCP Check CXDOT Collector integration has the following prerequisite:

• Ensure that the CXDOT Collector can reach each host and port that you want to monitor.

​

Configure

To configure the TCP Check CXDOT Collector integration, follow these steps:

1. To discover checks from pods or Services in your Kubernetes cluster, add autodiscovery annotations that specify the host and port to monitor. The integration is enabled by default, so you don’t need to add a tcp_check configuration block. For more information, see autodiscovery. Metrics from discovered pods arrive with that pod’s Kubernetes metadata attached.
2. Optional: Configure static targets to monitor hosts that autodiscovery doesn’t cover, such as a database outside your Kubernetes cluster. For example, add the following to the values.yaml file for the CXDOT Collector Helm chart:
   config:
     integrations:
       tcp_check:
         instances:
           - endpoint: db.internal.example:5432
           - endpoint: 10.0.0.2:6379
   
   The integration instance checks only the listed targets and disables autodiscovery. In cluster mode, the cluster-tier CXDOT Collector connects to static targets. For more information, see architecture.
3. Optional: Configure separate integration instances to monitor both discovered and static targets. For example, add the following to the values.yaml file for the CXDOT Collector Helm chart:
   config:
     integrations:
       tcp_check: {}
       tcp_check/external:
         instances:
           - endpoint: db.internal.example:5432
   
   The tcp_check/external key defines a named instance for the static targets. Configuring a named instance suppresses the implicit default instance, so the empty tcp_check: {} entry is required to keep autodiscovery running.
4. Optional: Disable the integration to stop monitoring annotated targets. For example, add the following to the values.yaml file for the CXDOT Collector Helm chart:
   config:
     integrations:
       tcp_check:
         enabled: false
   

​

Validate

To validate the TCP Check CXDOT Collector integration, follow these steps:

1. Confirm target health in Live Telemetry Analyzer or Metrics Explorer:
   • In Live Telemetry Analyzer, add the following filters:
     • __name__=cxdot.integration.target.health
     • cxdot.integration.name=tcp_check
     Confirm that one time series appears for each target you configured, identified by the cxdot.integration.target attribute.
   • In Metrics Explorer, run the following query:
     {"cxdot.integration.target.health", "cxdot.integration.name"="tcp_check"}
     
     Confirm that each reachable target reports 1 and each unreachable target reports 0.
2. In Metrics Explorer, run the following query:
   {"tcpcheck.duration", "cxdot.integration.name"="tcp_check"}
   
   Confirm that the query returns the connection time in milliseconds for each reachable target. For a hostname target, the time includes resolving the name.

​

Troubleshooting

• A target reports 0 for cxdot.integration.target.health: In Metrics Explorer, run the following query to group recent failed checks by target and cause:
  sum by ("server.address", "server.port", "error.code") (count_over_time({"tcpcheck.error", "cxdot.integration.name"="tcp_check"}[$__rate_interval]))
  
  The error.code label identifies whether the connection was refused, timed out, or found the network unreachable.

​

Configuration reference

Configure one TCP Check integration instance with the following settings. In Helm values, place these settings under config.integrations.tcp_check. In a Collector configuration file, place them under cxdot.integrations.tcp_check.

​

Optional settings

• enabled Type: boolean. Optional. Default: true. Whether to enable this TCP Check integration instance. If true, the Collector performs connectivity tests. If false, the Collector doesn’t run this integration instance.
• instances Type: array of object. Optional. Default: []. Connectivity targets. Each endpoint uses host:port format, such as db.internal.example:5432. The integration opens a connection to each target during every interval and reports each target separately. When this list contains a target, the integration monitors only the listed targets and disables discovery through annotations for this integration instance. When the list is empty, the integration monitors targets supplied through TCP Check annotations.
• instances[].endpoint Type: string. Required. Network address of the target in host:port format.
• collection_interval Type: duration. Optional. Default: 15s. How often the integration opens a connection to each target.
• timeout Type: duration. Optional. Default: 10s. Maximum time allowed for a connection attempt and the complete connectivity test during one interval. The value must be greater than 0s and must not exceed collection_interval. A target supplied through an annotation can set a shorter timeout.