FAQ.md

What is format of the URL accepted by chdig?

The simplest form is just - localhost

For a secure connections with user and password (note: passing the password on the command line is not safe), use:

chdig -u 'user:password@clickhouse-host.com/?secure=true'

A full list of supported connection options is available here.

Note: This link currently points to my fork, as some changes have not yet been accepted upstream.

Environment variables

A safer way to pass the password is via environment variables:

export CLICKHOUSE_USER='user'
export CLICKHOUSE_PASSWORD='password'
chdig -u 'clickhouse-host.com/?secure=true'
# or specify the port explicitly
chdig -u 'clickhouse-host.com:9440/?secure=true'

What is --config (CLICKHOUSE_CONFIG)?

This is standard config for ClickHouse client, i.e.

user: foo
password: bar
host: play
secure: true

See also some examples and possible advanced use cases here

What is --connection?

--connection allows you to use predefined connections, that is supported by clickhouse-client (1, 2).

Here is an example in XML format:

<clickhouse>
    <connections_credentials>
        <connection>
            <name>prod</name>
            <hostname>prod</hostname>
            <user>default</user>
            <password>secret</password>
            <!-- <secure>false</secure> -->
            <!-- <skip_verify>false</skip_verify> -->
            <!-- <ca_certificate></ca_certificate> -->
            <!-- <client_certificate></client_certificate> -->
            <!-- <client_private_key></client_private_key> -->
        </connection>
    </connections_credentials>
</clickhouse>

Or in YAML:

---
connections_credentials:
  prod:
    name: prod
    hostname: prod
    user: default
    password: secret
    # secure: false
    # skip_verify: false
    # ca_certificate:
    # client_certificate:
    # client_private_key:

And later, instead of specifying --url (with password in plain-text, which is highly not recommended), you can use chdig --connection prod.

What is flamegraph?

It is best to start with Brendan Gregg's site for a solid introduction to flamegraphs.

Below is a description of the various types of flamegraphs available in chdig:

• Real - Traces are captured at regular intervals (defined by query_profiler_real_time_period_ns/global_profiler_real_time_period_ns) for each thread, regardless of whether the thread is actively running on the CPU
• CPU - Traces are captured only when a thread is actively executing on the CPU, based on the interval specified in query_profiler_cpu_time_period_ns/global_profiler_cpu_time_period_ns
• Memory - Traces are captured after each memory_profiler_step/total_memory_profiler_step bytes are allocated by the query or server
• Live - Real-time visualization of what server is doing now from system.stack_trace

See also:

• Sampling Query Profiler

Note: for Memory chdig uses memory_profiler_step over memory_profiler_sample_probability, since the later is disabled by default

Why I see IO wait reported as zero?

• You should ensure that ClickHouse uses one of taskstat gathering methods:

  • procfs
  • netlink

• And also for linux 5.14 you should enable kernel.task_delayacct sysctl as well.

How to copy text from chdig

By default chdig is started with mouse mode enabled in terminal, you cannot copy with this mode enabled. But, terminals provide a way to disable it temporary by pressing some key (usually it is some combination of Alt, Shift or/and Ctrl), so you can find yours press them, and copy.

---

See also bugs list