> ## Documentation Index
> Fetch the complete documentation index at: https://docs-xcor.paloaltonetworks.com/llms.txt
> Use this file to discover all available pages before exploring further.

# TCP Check

> Connectivity checks for TCP endpoints — whether a connection to each configured host and port can be established, how long the connect takes, and failed attempts by cause.

The TCP Check integration requires CXDOT Collector 1.4.0 or greater.

A TCP connection probe opens a
[Transmission Control Protocol (TCP)](https://www.rfc-editor.org/rfc/rfc9293)
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:

| Type | Supported |
| :-: | :-: |
| Logs | No |
| Metrics | Yes |
| Traces | No |
| Events | No |

## 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](https://docs-xcor.paloaltonetworks.com/ingest/xcor/collector/discover/kubernetes).

   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:

   ```yaml theme={null}
   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](https://docs-xcor.paloaltonetworks.com/ingest/xcor/collector/install/kubernetes/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:

   ```yaml theme={null}
   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:

   ```yaml theme={null}
   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](https://docs-xcor.paloaltonetworks.com/investigate/analyze/telemetry-analyzer)
   or
   [Metrics Explorer](https://docs-xcor.paloaltonetworks.com/investigate/querying/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:

     ```text theme={null}
     {"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](https://docs-xcor.paloaltonetworks.com/investigate/querying/metrics/explorer),
   run the following query:

   ```text theme={null}
   {"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](https://docs-xcor.paloaltonetworks.com/investigate/querying/metrics/explorer),
  run the following query to group recent failed checks by target and cause:

  ```text theme={null}
  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.


## Related topics

- [CXDOT Collector integrations](/ingest/xcor/integrations/collector.md)
- [Networking](/ingest/pipeline/v2/configure/networking.md)
- [HTTP Check](/ingest/xcor/integrations/collector/http_check.md)
- [TCP destination plugin](/ingest/pipeline/plugins/destination-plugins/tcp.md)
- [Discover Kubernetes scrape targets with the CXDOT Collector](/ingest/xcor/collector/discover/kubernetes.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.