gstrace

Function

gstrace is used to trace the kernel code execution path, record the kernel data structure, and analyze code performance. The limited trace points and data are fixed in the version and cannot be dynamically added or deleted.

WARNING

The data of the memory variable specified by the kernel dump is used for diagnosis and analysis. There is no behavior of directly specifying any register or memory address. The read memory addresses are hard-coded in the development phase, and no register or memory is read or modified randomly.
Trace points may involve sensitive data. Before collecting trace information, you need to negotiate with the customer and obtain authorization and permission.
openGauss does not dot sensitive information, and therefore does not trace user-related data.
The trace function is used only for diagnosis. Enabling the trace function affects the performance. The impact varies depending on the load and the trace module.
The permission of the Trace tool is 0700, which indicates read, write, and execution by database users only.

NOTE

If the process is stopped abnormally, the gstrace_trace_cfg_* file will exist in the /dev/shm directory. You can manually delete the file.

Syntax

gstrace [start|stop|config|dump|detailcodepath|analyze] [-p <port>][-s <BUFFER_SIZE>] [-f <DUMP_FILE>] [-o <OUTPUT_FILE>] [-t <STEP_SIZE>]

Parameter Description

Table 1 gs_trace parameters

Parameter	Description
start	Starts to record trace information.
stop	Stops the trace process and releases the shared memory trace buffer for storing information. Note: The trace information captured in the trace buffer will be lost.
config	Displays trace configuration information.
dump	Writes trace information in the shared memory to a specified file. If the trace is not started, an error is reported.
detail	Parses the dump binary file into a text file and displays the thread and time information of the trace point.
codepath	Extracts the function call information from the dump file and displays the information in the call stack mode.
analyze	Collects statistics on the number of execution times, total duration, average duration, maximum duration, and minimum duration of each function.
-p PORT	Specifies the listening port number of an instance on which the trace function is enabled.
-f DUMP_FILE	Specifies the trace file exported by dump.
-o OUTPUT_FILE	Specifies the file to be written.
-t STEP_SIZE	Time span for fragment analysis, in seconds. This parameter is optional. A separate {OUTPUT_FILE}.step file will be generated.
-m MASK	Specifies the modules and functions to be traced. If the parameter is left blank, all functions of all modules to which the trace interface is added are traced. Format: [comp...] [ALL]. [func...] [ALL] Description: comp indicates the module list, which is separated by commas (,), for example, executer,kernel. You can also use a sequence number, for example, executer,2. func indicates a function list, which is separated by commas (,). for example, sql_execute_ddl, sql_execute_dcl. You can also use a sequence number to indicate the sequence of a function in a module, for example, 2. The value ALL indicates that all modules or functions are traced. Example: executer,kernel.ALL: All functions defined in the executer and kernel modules are traced. executer,kernel.sql_execute_ddl: The function sql_execute_ddl defined under executer is traced. The kernel module is ignored because it does not have the function. executer,kernel.1: The first function in the executer and kernel modules is traced. ALL.1,2: The first and second functions in all modules are traced.
-s BUFFER_SIZE	Specifies the size of the shared memory used for the trace function. The default value is 1 GB. If the specified value of BUFFER_SIZE is less than the minimum value 2048, the system automatically adjusts the value to the minimum value. If the value specified by BUFFER_SIZE is not 2^N (2 to the power of N), 2^N is aligned downwards. For example, if BUFFER_SIZE is set to 3072, the system changes the value to 2048 because 2^11 < 3072 < 2^12.

Example

Start the trace function.
```
gstrace start -p 8000
```
Stop the trace function.
```
gstrace stop -p 8000
```
Check the trace configuration information.
```
gstrace config -p 8000
```

dump trace

gstrace dump -p 8000 -o /data/8000.dump

Parse dump details.

gstrace detail -f /data/8000.dump -o /data/8000.detail

Parse dump codepath.

gstrace codepath -f /data/8000.dump -o /data/8000.codepath

Analyze global performance.

gstrace analyze -f /data/8000.dump -o /data/8000.perf

Analyze fragment performance.

gstrace analyze -f /data/8000.dump -o /data/8000.perf -t 1