gstrace

Function

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

WARNING:
The specified memory variables dumped from the kernel are used only for diagnosis and analysis. Registers or memory addresses will not be randomly and directly specified. The read memory addresses are hard-coded in the development, 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 point on sensitive information or 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 that only database users can read, write, and execute the trace tool.

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. A separate {OUTPUT_FILE}.step file will be generated.
stop	Stops tracing and releases the shared memory trace buffer. Note: This will cause the traced information in the trace buffer to be lost. A separate {OUTPUT_FILE}.step file will be generated.
config	Displays trace configuration information. A separate {OUTPUT_FILE}.step file will be generated.
dump	Writes the traced information frm the shared memory to a specified file. If the tracing is not started, an error message will be displayed. A separate {OUTPUT_FILE}.step file will be generated.
detail	Parses the dumped binary file to a text file, so that traced threads and time information are displayed. A separate {OUTPUT_FILE}.step file will be generated.
codepath	Extracts the function calling information from the dumped file and displays the information in the call stack mode. A separate {OUTPUT_FILE}.step file will be generated.
analyze	Collects statistics on the number of execution times, total duration, average duration, maximum duration, and minimum duration of each function. A separate {OUTPUT_FILE}.step file will be generated.
-p PORT	Specifies the listening port number of an instance on which the trace function is enabled. A separate {OUTPUT_FILE}.step file will be generated.
-f DUMP_FILE	Specifies the trace file to be dumped. A separate {OUTPUT_FILE}.step file will be generated.
-o OUTPUT_FILE	Specifies the file to be written. A separate {OUTPUT_FILE}.step file will be generated.
-t STEP_SIZE	Specifies the time span for segment 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. This parameter can't be left blank. Format: <COMP_FUNC_PAIR> [,<COMP_FUNC_PAIR>]* Description: <COMP_FUNC_PAIR> -> <COMP_NAME>.<FUNC_NAME> COMP_FUNC_PAIR indicates one or more pair of module and function. COMP_NAME indicates a module by name. <FUNC_NAMES> -> ALL\|[<FUNC_NAME>[&<FUNC_NAME>]] FUNC_NAMES* could be ALL or specific function names. The value ALL indicates all the functions in this module will be traced. Or one or more functions could be specified, which is separated by &. For example, sql_execute_ddl&sql_execute_dcl. Examples: access.StartTransaction: The function StartTransaction in module access is traced. executer.ExecutorStart&ExecInitExpr: The ExecutorStart and ExecInitExpr functions defined in the executer are traced. executer.ExecutorStart,tcop.PortalStart&PortalRun: The function ExecutorStart in the executer and PortalStart&PortalRun functions in modules tcop are traced. executer.ALL,access.ALL: All functions in modules executer and access 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. A separate {OUTPUT_FILE}.step file will be generated.

Example

Start the tracing.
```
gstrace start -p 8000
```
Stop the tracing.
```
gstrace stop -p 8000
```
Check the configurations for tracing.
```
gstrace config -p 8000
```

dump trace

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

Parses dumped details.

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

Parse dumped codepath.

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

Analyze the global performance.

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

Analyze the segment performance.

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