Skip to content

Security and Privacy

Click-Dog reads telemetry from ClickHouse in readonly=2 mode, but the data it exports can still be sensitive. Query literals may contain credentials, email addresses, account identifiers, or other personal data. Query-log enrichment can also include users, client hosts and addresses, tables, and databases.

Choose a query-text posture

filters.query_text_mode is the final query-text boundary shared by scheduled native spans, query-log backfill, OTLP, and Splunk HEC:

filters:
  query_text_mode: normalized_only # raw | redacted | normalized_only | none
  • raw is the compatibility default and exports original statements subject to length limits.
  • redacted requires redact_queries rules. Statements that match no rule are omitted; they are never exported raw as a fallback.
  • normalized_only removes raw statements and retains a bounded, literal-stripped ClickHouse normalized preview only when safely available.
  • none removes raw and normalized query text while retaining identifiers, hashes, tables, timings, status, and resource attributes.
  • All three drop exception messages, which quote the failing statement, and keep exception codes.

Use normalized_only or none for privacy-sensitive production environments. Normalization support is capability-probed; when it is unavailable, normalized_only omits query text instead of weakening the policy. Normalized text remains explicitly labeled and is never emitted as db.statement.

All three privacy-restricting modes also drop URI-bearing pass-through span attributes that contain a ClickHouse HTTP query parameter. HTTP GET requests can otherwise carry a second, URL-encoded copy of the raw statement in attributes such as http.url, http.target, url.full, url.query, or a vendor-specific URL/URI attribute. The scrubber is scoped by attribute name; SQL string literals and non-URI metadata are not interpreted as request URIs. The whole unsafe URI value is removed rather than partially rewriting a possibly malformed URI. URI values without a query parameter remain available.

Existing configs with redact_queries and no mode migrate to fail-closed redacted and emit a migration warning. This preserves the privacy intent but is deliberately stricter than the legacy behavior: statements that match no rule used to pass through raw and are now omitted. Make the mode explicit during the next config edit.

When normalized_only is selected, click-dog warns if query-log enrichment is disabled for scheduled/native spans and warns at startup if the ClickHouse capability probe cannot provide normalized query fields. In both cases text is omitted rather than falling back to raw SQL.

Protect data in transit and at rest

Enable TLS for ClickHouse and OTLP connections, and use HTTPS for Splunk HEC. The defaults permit plaintext ClickHouse and OTLP connections for local compatibility, so production configs should opt in deliberately. Treat backend retention, access controls, and index permissions as part of the same privacy boundary; Click-Dog cannot retract data a sink has already accepted.

Query-text mode does not remove other potentially identifying attributes such as query_log.user, query_log.client_hostname, query_log.client_address, or log_comment.*. Disable query-log enrichment when it is not needed, avoid putting secrets in log_comment, and use user/IP filters where appropriate. It also does not attempt to recognize arbitrary custom attributes that an instrumentation library may use to duplicate SQL. Avoid adding raw statements under custom attribute names; the supported raw carriers are db.statement, query-log query, and URI query parameters.

Query analysis and trace drilldown keep their stricter report contract. Setting query-text mode to raw does not cause those reports to begin emitting raw SQL. Query-analysis baseline artifacts are stricter still: they contain no raw or normalized SQL, dimension values, config paths, or endpoints. They store exact normalized hashes and aggregate performance/failure metrics, and replace effective user-filter values with a one-way fingerprint. Baselines are written atomically with mode 0600, but they remain operational artifacts: retain and share them under the same access controls as reports and traces. Reports written with --output carry mode 0600 on every run, including over a file that already exists, and a symlink at the output path is replaced rather than written through — but the mode only protects the file click-dog writes, so copies, backups, and anything that ingests it need the same care.

Explicit analyze queries --notify delivery has a separate, smaller privacy boundary. Both the webhook and Datadog Event Management destinations receive only analysis.notification.v1: the window and schema identities; total/new severity counts; stable condition keys; analyzer, family, and exact decimal normalized-query-hash identifiers; and explicit truncation counts. The shared DTO excludes SQL/query previews, user/client/host dimensions, finding prose and evidence, paths, endpoints, configuration, and credentials. The renderer cannot recover those omitted fields from the DTO. Notifications are bounded to 20 conditions and 10 hashes per condition; retain the protected local report for full evidence.

Treat webhook URLs, Datadog API keys, and Datadog application keys as secrets. Prefer environment expansion or the mutually exclusive *_file fields, keep file permissions narrow, and use HTTPS destinations. Delivery errors omit configured URLs, response bodies, and credentials; redirects are rejected so credentials cannot be forwarded to a redirected host. datadog_events.site is trusted operator configuration: set it only to the site hostname for your Datadog organization.

See Filtering, Span Attributes, and Configuration for the full field and attribute contracts.