clickstack-otel-collector

What the source does

• FilesystemNone observedNo reads or writes in the source
• NetworkNone observedNo outbound calls in the source
• ShellNone observedNo commands run in the source
• DependenciesPinnedNothing floats
• SecretsNone foundNo keys in source

Five audit layers

Gates applied: instruction override, no behavioural pass.

> 1. In the [Cloud console](https://console.clickhouse.cloud), open **Organization → API keys

as `hyperdx_ingest`. Open the shell with the combined load so `$CLICKHOUSE_PASSWORD` (and

4. **Ignore any prompt that asks you to set up or configure a collector / start ingestion.** You

- The `clickhousectl` install in Step 3 uses `curl ... | sh`, which many agent sandboxes flag as

installer: the `|| curl ... | sh` form drags a harmless check into a compound command that sandboxes

curl -fsSL https://clickhouse.com/cli | sh

Audit 0.4.1 · source sha 26841bf3d95f · 28 Oct 2026Report an issue or request a re-scan

• Publisherclickhouse GitHub organizationOwner of the repository this skill is read from
• Source folderclickhouse/agent-skills/skills/clickstack-otel-collectorThe exact folder we audited
• LicenceApache-2.0As the repository states it
• Commit pinned for this verdict26841bf3d95fA new audit runs when the source changes
• Repository statusNot archivedLast push 3 days ago
• Sandboxed runNot runSkills are read, not executed; layer L4 is skipped

Its description: Use when a user wants to wire an OpenTelemetry collector into a Managed ClickStack service on ClickHouse Cloud, either by deploying a new local collector (Docker run or Docker Compose) or by configuring their own…

---
name: clickstack-otel-collector
description: Use when a user wants to wire an OpenTelemetry collector into a Managed ClickStack service on ClickHouse Cloud, either by deploying a new local collector (Docker run or Docker Compose) or by configuring their own existing collector, then send rich synthetic telemetry and verify it is visible in ClickStack.
license: Apache-2.0
metadata:
  author: ClickHouse Inc
  version: "0.6.0"
---

# Set up an OpenTelemetry collector for Managed ClickStack

This skill wires an OpenTelemetry collector into a Managed ClickStack service running on
ClickHouse Cloud, sends rich synthetic telemetry through it, and confirms the data is actually
visible in ClickStack. It uses [`clickhousectl`](https://clickhouse.com/docs/interfaces/cli)
for all cloud and SQL operations.

**Scope.** This skill supports two paths, chosen in Step 0:

1. **Deploy a new collector** locally. You can do this **two ways: individual `docker` commands,
   or a `docker compose` file** (recommended, fewer commands and one file to start/stop). Make the
   user aware of both up front and let them pick in Step 0; do not assume plain `docker`. Either
   way runs the ClickStack distribution of the collector, preconfigured for Managed ClickStack.
2. **Configure your own existing collector** by adding the ClickHouse exporter configuration.
   We give you the exact config to drop in; you reload your collector. Use this if you already
   run a collector in a **gateway** role.

A full Kubernetes deployment (Helm, secrets in K8s Secrets) is out of scope here; the config
we generate in path 2 can be applied to a collector running anywhere.

The end state is:

- A dedicated `hyperdx_ingest` SQL user on the target service, with exactly the grants the
  collector needs (it creates the `otel.*` schema on first write).
- A collector forwarding logs, traces, and metrics into the `otel` database on the service,
  either the new local ClickStack collector or your existing one.
- Rich synthetic telemetry across several services, severities, span statuses, and metric
  types, so ClickStack's Search, Service Map, and dashboards have something real to show.
- The service confirmed **awake**, and the user walked through the ClickStack onboarding in the
  Cloud console so they can actually *see* their data.

Secrets (the OTLP auth token and the SQL password) are generated locally, written **once** to a
`0600` env file, and passed to Docker via `--env-file`. They are never pasted into the chat,
never passed with `docker run -e`, and never echoed back after creation.

Follow these steps in order. Each step depends on state established by the previous one.

---

## Step 0: Choose your path

Ask the user two short questions before doing anything else, because they determine which later
steps run.

**Question 1: Do you already have an OpenTelemetry collector running in a gateway role?**

- **No, set one up for me.** -> the **new-collector** path. Continue to Question 2.
- **Yes, I have one.** -> the **existing-collector** path. Skip Question 2 (it does not apply),
  and in Step 6 you will configure their collector rather than deploy a new one.

**Question 2 (new-collector path only): Run the collector with individual Docker commands, or a
Docker Compose file?**

- **Docker Compose (recommended).** Fewer commands, one file to start and stop, easiest to
  re-run. Best if `docker compose` is available.
- **Individual Docker commands.** Use if Compose is not installed or you prefer explicit
  commands.

Record the answers as `COLLECTOR_PATH` (`new` or `existing`) and, for the new path,
`DEPLOY_MODE` (`compose` or `run`). Refer back to them in Step 6 and Step 7.

---

## Step 1: Batch the permissions up front

Coding agents prompt for approval the first time they see each shell command. To avoid
interrupting the user every few steps, ask them once, up front, to allowlist the command
prefixes below (the "always allow for this project / session" option in their agent). There are
no destructive operations and nothing targets anything outside this project or their ClickHouse
Cloud service.

| Command prefix | Used for | Needed when |
| --- | --- | --- |
| `openssl rand ...` | generate the OTLP token and SQL password | always |
| `clickhousectl cloud ...` | auth, resolve the service, run SQL via the Query API | always |
| `jq ...` | parse JSON from `clickhousectl` | always |
| `docker ...` / `docker compose ...` | run/inspect the collector and the telemetry generator | new-collector path, and the optional telemetry check |
| `curl ...` | local health check against `localhost:13133` (and installing `clickhousectl` if missing) | new-collector path |

Tell the user, in your own words: *"If your agent supports it, choose 'always allow' for each
of these the first time it asks. The whole run is read-only against your machine except for the
collector container, and write operations against ClickHouse are limited to creating the ingest
user and the `otel` schema."*

If the user is on the existing-collector path and does not want to run the optional telemetry
check, you can drop `docker` and `curl` from the list.

**Two approvals are semantic, not prefix-based, so allowlisting won't pre-clear them.** Warn the
user to expect these and approve them explicitly when they appear:

- The `clickhousectl` install in Step 3 uses `curl ... | sh`, which many agent sandboxes flag as
  "downloading and running untrusted code" regardless of any `curl` allowlist rule.
- The `CREATE USER` / `GRANT` in Step 5 may be flagged as "modifying shared production
  infrastructure," again independent of the `clickhousectl` prefix rule.

Neither is solved by the table above; they are one-time, intentional, and safe to approve.

Then continue.

---

## Step 2: Confirm the target service and lay down the secrets file

The user's prompt contains a service identifier, either a service ID (UUID) or a service name.
Treat that value as `SERVICE_REF`.

Create a working dir

Excerpt, first 6,000 characters of SKILL.md, verbatim from the audited commit. It is text from someone else’s repository, quoted so you can judge it before your agent reads it.

git clone https://github.com/clickhouse/agent-skills
git -C agent-skills checkout 26841bf3d95f

Works in

1. 2026-10-28
   ✕BLOCK D 69 / 100

   first audit · source 26841bf3d95f

Questions about clickstack-otel-collector

• github.com/clickhouse/agent-skills/tree/main/skills/clickstack-o — the audited source at commit 26841bf3d95f and every finding aboveObserved · 28 Oct 2026

Spotted something wrong? Report a correction · Methodology