--- title: 'Connect ClickStack / HyperDX' description: 'Send Yorker check telemetry to ClickStack (HyperDX on ClickHouse): open source, self-hosted, or Managed ClickStack in ClickHouse Cloud.' section: 'Guides' canonical_url: 'https://yorkermonitoring.com/docs/guides/connect-clickstack' --- # Connect ClickStack / HyperDX Yorker exports every check run as standard OTLP to a backend you choose. This guide covers connecting that export to ClickStack, the ClickHouse observability stack with HyperDX as its UI. Once connected, your synthetic results sit next to your application traces, logs and metrics, and you can install the pre-built Yorker dashboards. Connecting a backend is optional. Yorker stores and displays check results, screenshots and alerts whether or not you configure one. ## What you need | | Open source ClickStack | Managed ClickStack (ClickHouse Cloud) | |---|---|---| | **OTLP endpoint** | Your ClickStack OTel collector, HTTP port `4318` | An OTel collector you run that writes to your ClickHouse Cloud service, HTTP port `4318` | | **Credential** | The **Ingestion API Key** from HyperDX under **Team Settings > API Keys** | The `OTLP_AUTH_TOKEN` you set on the collector, if you set one | Two things apply to both: - **Use the HTTP port, not gRPC.** Yorker sends OTLP over HTTP with JSON bodies. Point it at `4318` (or whatever fronts it), not `4317`. - **Hosted locations need a public endpoint.** Telemetry for checks on Yorker-hosted locations is sent from Yorker's servers, so the collector must be reachable from the internet over a public hostname or IP. `localhost`, private IP ranges and hostnames that resolve to them are rejected. If your collector must stay inside your network, see [Private locations](#private-locations). Managed ClickStack does not come with a hosted OTLP endpoint. You run the collector yourself, and ClickHouse recommends the ClickStack distribution of it. Their [collector guide](https://clickhouse.com/docs/use-cases/observability/clickstack/ingesting-data/otel-collector) covers deployment. The collector is unauthenticated unless you set `OTLP_AUTH_TOKEN`, so set one before exposing it publicly, and put TLS in front of it. ## Connect in the web UI 1. Open **Settings** and find **Telemetry (OTLP)**. 2. In **OTLP Endpoint**, enter the base URL of your collector, for example `https://otel.example.com` or `https://otel.example.com:4318`. 3. In **OTLP API Key**, paste your Ingestion API Key (open source) or your `OTLP_AUTH_TOKEN` (managed). Paste the key on its own, with no `Bearer` prefix. Leave the field empty if your collector has no authentication. 4. Click **Test connection**. **Test connection** sends one test metric (`synthetics.connection.test`) to `/v1/metrics`. If the collector accepts it, the endpoint and key are saved and you do not need to click **Save Changes** for these fields. If it fails, nothing is saved. From then on, every check run exports to that endpoint. ### Endpoint format Enter the base URL only. Yorker appends `/v1/traces`, `/v1/metrics` and `/v1/logs` itself. If you paste a URL that already ends in one of those, the suffix is removed. A path prefix is kept, so a collector behind a reverse proxy at `https://proxy.example.com/otel` works. The URL must use `http://` or `https://` and cannot contain a username, password, query string or fragment. Redirects are not followed. ### How the key is sent The **OTLP API Key** value is sent exactly as entered in the `Authorization` header of every OTLP request. ClickStack expects the ingestion key on its own in that header, which is why you paste it without a prefix. If you front the collector with a gateway that needs a different or additional header, add it under **Custom OTLP Headers**. A custom header named `Authorization` replaces the OTLP API Key value. ## Check that data is arriving Run a check (or wait for the next scheduled run), then open HyperDX and search your **Logs** source for the service name `synthetics`. Every signal Yorker emits carries `service.name = synthetics` plus attributes that identify the check, location and run, such as `synthetics.check.name` and `synthetics.location.name`. You should see a `synthetics.check.completed` or `synthetics.check.failed` log event for each run. Browser checks also produce a `synthetics.check.run` trace and metrics. See [OpenTelemetry](/docs/concepts/opentelemetry) for the full list of metrics, events and attributes. ## Link from Yorker back to HyperDX Set a **Trace URL Template** so that the request waterfall and alerts in Yorker link straight to the matching trace in HyperDX. 1. In HyperDX, open **Search** and select your **Traces** source. 2. Copy the URL from your browser. 3. In Yorker, under **Settings > Telemetry (OTLP) > Trace URL Template**, pick the **ClickStack / HyperDX** preset and replace the placeholder values with the ones from the URL you copied. Keep `{traceId}` where the trace ID goes. For Managed ClickStack the result looks like this: ``` https://.clickhouse.cloud/search?chcServiceId=&where=TraceId%20%3D%20%27{traceId}%27&whereLanguage=sql&source= ``` The URL must include both the `source` and `chcServiceId` parameters. On open source ClickStack there is no `chcServiceId`; use your HyperDX URL with the same `where` and `source` parameters. ## Install the dashboards Yorker ships eight pre-built dashboards for ClickStack. Installing them uses the HyperDX dashboard API, which takes different credentials from OTLP ingest: | | Dashboard API credential | |---|---| | **Open source ClickStack** | Your **Personal API Access Key** from **Team Settings > API Keys**. This is a different key from the Ingestion API Key. The API is served by the HyperDX app, on port `8000` by default. | | **Managed ClickStack** | A ClickHouse Cloud API key (key ID and secret), plus your organization ID and service ID. | The dashboards read from Traces, Logs and Metrics sources in HyperDX, so make sure all three exist first. In the web UI these go under **Settings > Telemetry (OTLP) > Dashboard Provisioning**. For open source ClickStack the web UI needs the HyperDX API on an `https://` URL; the CLI has no such requirement. [Install Dashboards](/docs/guides/install-dashboards) has the full steps for the web UI and the CLI. ## Private locations A [private location](/docs/guides/private-locations) agent sends its OTLP signals directly from inside your network, so it can reach a collector that has no public address. Set the endpoint and key on the agent: ```bash OTLP_ENDPOINT=http://clickstack-collector.internal:4318 OTLP_API_KEY= ``` `OTLP_API_KEY` is sent as the `Authorization` header in the same way as the setting in the web UI. The agent's direct export covers the raw metrics and traces for runs at that location. Events that Yorker produces after a run, such as `synthetics.check.completed`, anomaly signals and SLO signals, are still sent from Yorker to the endpoint in **Settings > Telemetry (OTLP)**. To receive those, that endpoint needs to be publicly reachable. ## Troubleshooting | Symptom | Likely cause | |---|---| | `OTLP endpoint returned HTTP 401` or `403` | Wrong key, or the Personal API Access Key was used where the Ingestion API Key belongs. Also check that the key was pasted without a `Bearer` prefix. | | `OTLP endpoint returned HTTP 404` | The URL points at the HyperDX app (port `8080` or `8000`) or at ClickHouse itself, not at the collector's OTLP HTTP port. | | `Connection failed` | The collector is unreachable from the internet, the port is closed, the endpoint is the gRPC port `4317`, or the endpoint redirects. | | `URLs pointing to private/reserved IP addresses are not allowed` | The hostname resolves to a private or loopback address. Expose the collector publicly, or use a private location. | | Test passes but dashboards are empty | The dashboards have not been installed, or a Traces, Logs or Metrics source is missing in HyperDX. See [Install Dashboards](/docs/guides/install-dashboards#prerequisites-data-sources). |