> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chronosphere.io/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 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:

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

## 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](https://docs.chronosphere.io/ingest/cxdot-collector/autodiscovery).

   Metrics from discovered pods arrive with that pod's Kubernetes metadata attached.
   For more information, see
   [enrichment](https://docs.chronosphere.io/ingest/cxdot-collector/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:

   ```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 Kubernetes mode, the cluster Collector connects to static targets. For more
   information, see
   [architecture](https://docs.chronosphere.io/ingest/cxdot-collector/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:

   ```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 your Helm chart:

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

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

3. In 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, 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.

For more information about diagnosing a failing integration, see
[Troubleshooting](https://docs.chronosphere.io/ingest/cxdot-collector/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.


## Related topics

- [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)
- [TCP source plugin](/ingest/pipeline/plugins/source-plugins/tcp.md)
- [Azure metrics available in Chronosphere Observability Platform](/ingest/xcor/integrations/server/azure/azure-metrics.md)