Skip to main content
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

The TCP Check integration is enabled by default. You can configure targets either by annotating pods in your Kubernetes cluster or by listing static endpoints in your Helm values. To configure the integration, follow these steps:
  1. To monitor a port that a pod listens on in Kubernetes, such as a message broker listener, add a CXDOT integration annotation to the pod template. The annotation key must end with the container name. For example, add the following annotation to your workload:
    The Collector replaces ${target.host} with the pod IP address and ${target.port.mqtt} with the container port named mqtt.
  2. Optional: To monitor hosts outside your Kubernetes cluster, such as a database, configure static targets. For example, add the following to the values.yaml file for the CXDOT Collector Helm chart:
    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: Name a static target. The CXDOT Collector adds the name to every time series from the target as the cxdot.integration.target.name attribute. For example, add the following to the values.yaml file for the CXDOT Collector Helm chart:
    A target found from a Datadog tcp_check annotation takes the name from the instance’s name setting.
  4. Optional: Configure separate integration instances to monitor both annotated and static targets. For example, add the following to the values.yaml file for the CXDOT Collector Helm chart:
    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.
  5. 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:
Metrics from each discovered pod include that pod’s Kubernetes metadata. For more information, see autodiscovery.

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:
      Confirm that each reachable target reports 1 and each unreachable target reports 0.
  2. In Metrics Explorer, run the following query:
    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:
    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 collection.cxdot.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. The integration opens a connection to each target during every interval and reports each target separately.
  • instances[].endpoint Type: string. Required. Network address of the target in host:port format.
  • instances[].name Type: string. Optional. Minimum length: 1. Name for this target, added to every time series from it as the cxdot.integration.target.name attribute. For example, db. A target found from a Datadog tcp_check annotation takes the instance’s name, spelled as Datadog’s instance tag spells it.
  • 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 takes its timeout from the annotation’s timeout.