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

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.

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 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 <endpoint>/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 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://<your-instance>.clickhouse.cloud/search?chcServiceId=<service-id>&where=TraceId%20%3D%20%27{traceId}%27&whereLanguage=sql&source=<source-id>

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:

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 has the full steps for the web UI and the CLI.

Private locations

A private location 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:

OTLP_ENDPOINT=http://clickstack-collector.internal:4318
OTLP_API_KEY=<your-ingestion-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