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 integration with Chronosphere XDOT to monitor whether service ports, such as databases, caches, and message brokers, accept connections and how long connections take to establish. The TCP Check 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 TCP Check integration supports these telemetry types:

​

Prerequisites

The TCP Check integration has the following prerequisite:

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

​

Configure

To configure the TCP Check 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. For more information, see enrichment.
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 your 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 Kubernetes mode, the cluster 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 your 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 your Helm chart:
   config:
     integrations:
       tcp_check:
         enabled: false
   

​

Validate

To validate the TCP Check integration, follow these steps:

1. In the 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, identified by its server.address and server.port labels.
2. 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.
3. 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.

For more information about diagnosing a failing integration, see Troubleshooting.

​

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. 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.