# ClickStack

### Supported Telemetry Types

| Logs | Metrics | Traces |
| ---- | ------- | ------ |
| ✓    | ✓       | ✓      |

### Prerequisites

Before configuring the ClickStack destination, ensure you have:

* A running ClickStack instance (local, Docker, or ClickHouse Cloud)
* Network connectivity from your Bindplane agent to the ClickStack OTLP endpoint
* An API ingestion key (found in ClickStack Team Settings → API Keys)
* The appropriate network ports open (default: HTTP `4318` or gRPC `4317`)

For help deploying ClickStack, see the [ClickStack Getting Started documentation](https://clickhouse.com/docs/use-cases/observability/clickstack/getting-started?loc=use-case-observability).

### Configuration

#### Basic Configuration

The minimum configuration requires the hostname/endpoint and API ingestion key. The destination will use HTTP protocol on port `4318` by default.

<figure><img src="https://1405008107-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FgmiOMzBfoNFwmKJFHMcJ%2Fuploads%2FPNWtsNoaaiBS4fdejNUE%2Fbpss_clickstack_basic.png?alt=media&#x26;token=fe399269-93f0-430a-aef4-630599d31938" alt=""><figcaption></figcaption></figure>

| Parameter             | Description                                                       | Default                        |
| --------------------- | ----------------------------------------------------------------- | ------------------------------ |
| **Telemetry Type**    | Select which types of telemetry to export (Logs, Metrics, Traces) | All types                      |
| **Protocol**          | The OTLP protocol (HTTP or gRPC)                                  | `http`                         |
| **Hostname**          | Hostname or IP address of the ClickStack OTLP endpoint            | `localhost`                    |
| **Port**              | TCP port for OTLP communication                                   | `4318` (HTTP) or `4317` (gRPC) |
| **API Ingestion Key** | The API key for authentication                                    | (required)                     |

#### Advanced Configuration

**Compression**

Compression reduces bandwidth usage when sending telemetry to ClickStack.

| **Parameter**          | **Description**                         | **Valid Values**                        | **Default** |
| ---------------------- | --------------------------------------- | --------------------------------------- | ----------- |
| **Compression (HTTP)** | Compression algorithm for HTTP protocol | gzip, deflate, snappy, zlib, zstd, none | `gzip`      |
| **Compression (gRPC)** | Compression algorithm for gRPC protocol | gzip, snappy, zstd, none                | `gzip`      |

**TLS Configuration**

TLS encryption is available for secure communication with ClickStack.

| **Parameter**                         | **Description**                                          | **Default** |
| ------------------------------------- | -------------------------------------------------------- | ----------- |
| **Enable TLS**                        | Whether to use TLS encryption                            | `false`     |
| **Skip TLS Certificate Verification** | Enable to skip verification of the server's certificate  | `false`     |
| **TLS Certificate Authority File**    | Optional CA file for validating the server's certificate | (none)      |
| **Server Name Override**              | Optional virtual hostname override                       | (none)      |
| **Mutual TLS**                        | Enable client certificate authentication (mTLS)          | `false`     |
| **TLS Client Certificate File**       | Path to client certificate for mTLS                      | (none)      |
| **TLS Client Private Key**            | Path to client private key for mTLS                      | (none)      |

**Retry and Queuing**

This destination supports the [retry settings](https://docs.bindplane.com/configuration/bindplane-otel-collector/retry-on-failure), the [sending queue settings](https://docs.bindplane.com/configuration/bindplane-otel-collector/sending-queue), and the [persistent queue settings.](https://docs.bindplane.com/configuration/bindplane-otel-collector/persistent-queue)

| Sending Queue | Persistent Queue | Retry on Failure |
| ------------- | ---------------- | ---------------- |
| ✓             | ✓                | ✓                |

#### Example 1: gRPC Protocol with Efficient Compression

This example demonstrates gRPC protocol selection with gzip compression, which is recommended for high-volume telemetry collection scenarios where bandwidth and protocol efficiency are important.

<figure><img src="https://1405008107-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FgmiOMzBfoNFwmKJFHMcJ%2Fuploads%2FyV5rLyHFr3asPWOg2d0b%2Fbpss_clickstack_grpc_gzip.png?alt=media&#x26;token=71ec68f3-b577-4ac8-8d0c-33ca7f2e6531" alt=""><figcaption></figcaption></figure>

#### Example 2: Logs and Metrics Only (Traces Disabled)

This example demonstrates selective telemetry type configuration, useful for organizations that want to collect logs and metrics while excluding trace data to optimize storage and processing costs.

<figure><img src="https://1405008107-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FgmiOMzBfoNFwmKJFHMcJ%2Fuploads%2F6NuUlIOIqCxNaTMz6CVc%2Fbpss_clickstack_no_traces.png?alt=media&#x26;token=408ef7d1-d649-4bc8-a134-6e74895e0f6c" alt=""><figcaption></figcaption></figure>

### Configuration Tips

#### Use Compression for Bandwidth Efficiency

* Both HTTP and gRPC protocols support compression (gzip, zstd, snappy). Enable compression to reduce bandwidth usage when sending telemetry to ClickStack, especially for high-volume scenarios.
* The ClickStack documentation shows gzip as the default compression algorithm for both protocols.

#### API Ingestion Key Authentication

* The API ingestion key must be provided as an authorization header with all OTLP communications. ClickStack validates this key for every request.
* Create separate API ingestion keys in Team Settings for different environments (development, staging, production) to maintain isolation and enable per-environment key rotation.

#### Protocol Selection Based on Infrastructure

* Use HTTP (port 4318) if your infrastructure includes proxies or firewalls that restrict gRPC traffic, as HTTP is more compatible with standard web infrastructure.
* Use gRPC (port 4317) for direct collector-to-collector communication within your internal network for better protocol efficiency.

### Troubleshooting

#### Invalid API Ingestion Key

**Symptoms:** "401 Unauthorized" or "Invalid credentials" errors when exporting telemetry to ClickStack.

**Solutions:**

1. Verify the API ingestion key is correct in ClickStack Team Settings and matches your configuration
2. Confirm the key has not expired or been revoked in ClickStack

#### Telemetry Not Appearing in ClickStack

**Symptoms:** Data is being exported (no errors in logs) but doesn't appear in ClickStack.

**Solutions:**

1. Check the hostname and port match your ClickStack OTLP endpoint configuration
2. Verify the correct telemetry types (Logs, Metrics, Traces) are enabled in the destination
3. Confirm the API ingestion key has permissions for the telemetry types you're sending

### Related Resources

* [ClickStack Getting Started Guide](https://clickhouse.com/docs/use-cases/observability/clickstack/getting-started?loc=use-case-observability)
* [ClickStack OpenTelemetry Ingestion](https://clickhouse.com/docs/use-cases/observability/clickstack/ingesting-data/opentelemetry#sending-otel-data)
* [Retry and Queuing Configuration](https://docs.bindplane.com/configuration/bindplane-otel-collector/retry-and-queueing)