Skip to main content
Skip to main content
Edit this page

Introspection Functions

You can use functions described in this chapter to introspect ELF and DWARF for query profiling.

Note

These functions are slow and may impose security considerations.

For proper operation of introspection functions:

  • Install the clickhouse-common-static-dbg package.

  • Set the allow_introspection_functions setting to 1.

    For security reasons introspection functions are disabled by default.

ClickHouse saves profiler reports to the trace_log system table. Make sure the table and profiler are configured properly.

addressToLine​

Converts virtual memory address inside ClickHouse server process to the filename and the line number in ClickHouse source code.

If you use official ClickHouse packages, you need to install the clickhouse-common-static-dbg package.

Syntax

Arguments

  • address_of_binary_instruction (UInt64) — Address of instruction in a running process.

Returned value

  • Source code filename and the line number in this file delimited by colon. For example, /build/obj-x86_64-linux-gnu/../src/Common/ThreadPool.cpp:199, where 199 is a line number.
  • Name of a binary, if the function couldn't find the debug information.
  • Empty string, if the address is not valid.

Type: String.

Example

Enabling introspection functions:

Selecting the first string from the trace_log system table:

The trace field contains the stack trace at the moment of sampling.

Getting the source code filename and the line number for a single address:

Applying the function to the whole stack trace:

The arrayMap function allows to process each individual element of the trace array by the addressToLine function. The result of this processing you see in the trace_source_code_lines column of output.

addressToLineWithInlines​

Similar to addressToLine, but returns an Array with all inline functions. As a result of this, it is slower than addressToLine.

Note

If you use official ClickHouse packages, you need to install the clickhouse-common-static-dbg package.

Syntax

Arguments

  • address_of_binary_instruction (UInt64) — Address of instruction in a running process.

Returned value

  • An array whose first element is the source code filename and line number in the file delimited by a colon. From the second element onwards, inline functions' source code filenames, line numbers and function names are listed. If the function couldn't find the debug information, then an array with a single element equal to the name of the binary is returned, otherwise an empty array is returned if the address is not valid. Array(String).

Example

Enabling introspection functions:

Applying the function to address.

Applying the function to the whole stack trace:

The arrayJoin functions will split array to rows.

addressToSymbol​

Converts virtual memory address inside ClickHouse server process to the symbol from ClickHouse object files.

Syntax

Arguments

  • address_of_binary_instruction (UInt64) — Address of instruction in a running process.

Returned value

  • Symbol from ClickHouse object files. String.
  • Empty string, if the address is not valid. String.

Example

Enabling introspection functions:

Selecting the first string from the trace_log system table:

The trace field contains the stack trace at the moment of sampling.

Getting a symbol for a single address:

Applying the function to the whole stack trace:

The arrayMap function allows to process each individual element of the trace array by the addressToSymbols function. The result of this processing you see in the trace_symbols column of output.

demangle​

Converts a symbol that you can get using the addressToSymbol function to the C++ function name.

Syntax

Arguments

  • symbol (String) — Symbol from an object file.

Returned value

  • Name of the C++ function, or an empty string if the symbol is not valid. String.

Example

Enabling introspection functions:

Selecting the first string from the trace_log system table:

The trace field contains the stack trace at the moment of sampling.

Getting a function name for a single address:

Applying the function to the whole stack trace:

The arrayMap function allows to process each individual element of the trace array by the demangle function. The result of this processing you see in the trace_functions column of output.

tid​

Returns id of the thread, in which current Block is processed.

Syntax

Returned value

Example

Query:

Result:

logTrace​

Emits trace log message to server log for each Block.

Syntax

Arguments

  • message — Message that is emitted to server log. String.

Returned value

  • Always returns 0.

Example

Query:

Result: