文档中心MogDBMogDB StackUqbar
生态工具
文档工具
EN
v5.0

文档:v5.0

支持的版本:
最新(v5.0)

其他版本:
v3.1/
v3.0/
v2.1/
v2.0/
v1.1

gstrace

功能介绍

gstrace是MogDB提供的用来跟踪内核代码执行路径、记录内核数据结构、分析代码性能的工具。gstrace允许用户指定一个或多个模块和函数进行追踪。Trace的有限点位和数据在版本中被固化，无法动态添加和删除。

gstrace作为一款功能强大的工具，具备了在生产环境下进行追踪观测的能力，可以帮助数据库使用者导出SQL执行细节，并支持追踪分析各种模块。通过使用gstrace，数据库使用者可以全面了解系统的性能瓶颈和潜在问题，从而优化SQL代码性能，提升系统稳定性。

gstrace支持调用追踪如下模块，来提高故障诊断效率：

  • walwriter模块、 pagewriter模块和checkpointer模块；
  • 一个或多个sessions或threads；
  • 轻量级锁数据；
  • DCF模块；

img 警告：

  1. 对内核dump指定内存变量的数据用于诊断分析，不存在直接指定任意寄存器或者内存地址的行为。读取的内存地址均是在开发阶段硬编码，没有任意地读取或者修改寄存器或内存的操作。
  2. Trace点可能涉及敏感数据，收集trace信息前需要同用户协商，授权和许可后方可收集。
  3. MogDB不会在敏感信息上打点，不会TRACE和用户相关的数据。
  4. Trace仅用于诊断目的，开启trace将对性能产生一定影响，影响的大小视负载的高低，trace的模块而不同。
  5. Trace工具的权限为0700，仅限于数据库用户读、写和执行。

img 说明： 如果进程异常终止，/dev/shm/ 目录下将会有gstrace_trace_cfg_*残留，可以手动清除。

语法

gstrace [start|stop|config|dump|detailcodepath|analyze|analyze_sqltrace|dump_usess| analyze_usess|dump_lwlock|analyze_lwlock]
[-m<mask>][-p <port>][-s <BUFFER_SIZE>] [-f <DUMP_FILE>] [-o <OUTPUT_FILE>]
[-t <STEP_SIZE>][ -q <COMP_FUNC_PAIR>(,<COMP_FUNC_PAIR>)*]
[-sid <SESSION_ID>(,<SESSION_ID>)*][-tid <THREAD_ID >(,<THREAD_ID>)*][-t <session|thread> ]

参数说明

表 1 gstrace参数说明

参数 说明
start 开始记录trace。
stop 停止trace，释放存储信息的共享内存trace buffer。注意：trace buffer中已捕获trace信息会丢失。
config 显示trace的配置信息。
dump 将共享内存中的trace信息写入指定文件。若没有启动trace将报错。
detail 将dump出来的二进制文件解析成文本文件，显示trace点的线程、时间信息。
codepath 提取dump文件中的函数调用信息，按照调用栈的方式显示。
analyze 统计各个函数的执行次数、总耗时、平均耗时、最长耗时、最短耗时。
dump_lwlock 表示导出轻量级锁数据信息，采用原始二进制格式。
analyze_lwlock 表示分析并生成可阅读文件，采用文本可阅读格式。
-p PORT 指定启动trace功能的实例侦听的端口号。
-f DUMP_FILE 指定dump导出的trace文件。
-o OUTPUT_FILE 指定写入的文件。
-q COMP_FUNC_PAIR 指定哪些模块、函数需要追踪。参数不得为空。
使用语法格式及描述：
<COMP_FUNC_PAIRS> -> <COMP_FUNC_PAIR>[,<COMP_FUNC_PAIR>]*
- COMP_FUNC_PAIRS由一组及以上的模块与函数组合组成

<COMP_FUNC_PAIR> -> <COMP_NAME>.<FUNC_NAMES>
- COMP_FUNC_PAIR代表一组模块与函数组合
- COMP_NAME 代表一个模块名

<FUNC_NAMES> -> ALL|[<FUNC_NAME>[&<FUNC_NAME>]*]
- FUNC_NAMES 可由用户指定为ALL 或者一个及以上的函数名。由于FUNC_NAMES一定是与COMP_NAME组合，因此，ALL代表追踪以COMP_NAME为名的模块的所有函数；而如果用户指定的是一个及以上的函数名，则是追踪以COMP_NAME为名的模块中的这几个指定FUNC_NAME对应的函数名
- FUNC_NAME 代表一个函数
示例：
- “access.StartTransaction”：追踪一个模块及一个对应函数
- “executer.ExecutorStart&ExecInitExpr”： 追踪一个模块及多个对应函数
- “executer.ExecutorStart,tcop.PortalStart&PortalRun”： 追踪多个模块及多个对应函数
- “executer.ALL,access.ALL”：使用ALL关键字追踪所有executor和access两个模块中的全部函数
注意：如果需要追踪所有模块及函数，不使用-q参数即可。举例：gstrace start -p 8000
-sid 指定一个或多个具体需要追踪的sessions的id（此处session ids可从pg_stat_activity表中获取）。多个session id 之间使用逗号分隔，最多可指定8个。-sid不能和-tid同时使用。
-tid 指定一个或多个具体需要追踪的thread的id。多个thread id 之间使用逗号分隔，最多可指定8个。-tid不能和-sid同时使用。
-t STEP_SIZE 指定分片分析的时间跨度（秒）,可选。将生成单独的{OUTPUT_FILE}.step文件。
-m MASK 指定哪些模块、函数需要追踪，如果参数为空，则追踪添加trace接口的所有模块的所有函数。
格式：[comp…][ALL].[func…][ALL]
描述：
- comp 是模块列表，使用‘,’分隔，例如：executer,mogdb。也可以使用序号，例如：executer,2。
- func 是function列表，使用‘,’ 分隔。 例如：sql_execute_ddl, sql_execute_dcl。也可以使用序号指代模块中第几个function，例如：2。
- 设置成ALL表示所有模块或所有function被trace。
示例：
- executer,mogdb.ALL ：所有定义定义在executer和mogdb模块下的function被trace。
- executer,mogdb.sql_execute_ddl ：定义在executer 下的Function sql_execute_ddl被trace. mogdb模块被忽略，因为下面没有该function 。
- executer,mogdb.1 ：定义在模块executer和mogdb下的第一个function被trace。
ALL.1,2 ：定义在所有模块下的第一，二个function被trace。
-s BUFFER_SIZE 指定用于trace功能的共享内存大小，默认为1G。如果指定的BUFFER_SIZE小于最小值2048，系统将自动调整为最小值。如果指定的BUFFER_SIZE不是2^N^（二的N次方），则向下对齐2^N^；例如：指定BUFFER_SIZE=3072，由于2^11^<3072<2^12^，系统将调整为2048。

示例

  • 基本功能示例

    --启动trace
gstrace start -p 8000

--停止trace
gstrace stop -p 8000

--查看trace配置
gstrace config -p 8000

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

--解析dump detail信息
gstrace detail -f /data/8000.dump -o /data/8000.detail

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

--分析全局性能
gstrace analyze -f /data/8000.dump -o /data/8000.perf

--分析分片性能
gstrace analyze -f /data/8000.dump -o /data/8000.perf -t 1

  • SQL trace功能示例

    示例1：追踪全部sqltrace信息

    --1. 启动数据库，端口号为26000
gsql -d postgres -p 26000

--2. 启动TPCC模拟负载
runBenchmark.sh props.opengauss.1000w.local

--3. 启动gstrace，并指定追踪模块为sqltrace
gstrace start -p 26000 -q sqltrace.ALL

--4. 将sqltrace写入指定dump文件sqltrace.dump
gstrace dump -p 26000 -o /home/mogdbuser/sqltrace.dump

--5. 停止追踪。
gstrace stop -p 26000

--6. 解析dump信息，并输出到指定文件sqltrace.txt
gstrace analyze_sqltrace -f /home/mogdbuser/sqltrace.dump -o /home/mogdbuser/sqltrace.txt

--7. 解析dump信息，并将解析内容按session id分别生成文件，并输出到指定文件路径
gstrace analyze_sqltrace -f /home/mogdbuser/sqltrace.dump -o /home/mogdbuser/sqltracebysession/ -t session

--8. 解析dump信息，并将解析内容按thread id分别生成文件，并输出到指定文件路径
gstrace analyze_sqltrace -f /home/mogdbuser/sqltrace.dump -o /home/mogdbuser/sqltracebysession/ -t thread

    示例1：解析结果文件内容

    img

    示例2：只追踪指定session信息

    --1. 启动数据库，端口号为26000
gsql -d postgres -p 26000

--2. 获取当前的某session id
gsql -c "select pg_current_sessionid();"

--3. 启动gstrace，并指定追踪模块为sqltrace，及前一步获取的session id，记为session_num
gstrace start -p 26000 -q sqltrace.ALL -sid session_num

--4. 将sqltrace写入指定dump文件sqltrace.dump
gstrace dump -p 26000 -o /home/mogdbuser/sqltrace.dump

--5. 停止trace
gstrace stop -p 26000

--6. 解析dump信息，并输出到指定文件sqltrace.txt
gstrace analyze_sqltrace -f /home/mogdbuser/sqltrace.dump -o /home/mogdbuser/sqltrace.txt

    示例2：解析结果文件内容

    img

    示例3：只追踪指定thread信息

    --1. 启动数据库，端口号为26000
gsql -d postgres -p 26000

--2. 执行sql语句
create table t_trace_thread(i int);
insert into t_trace_thread select generate_series(1,100000000);

--3. 查询上一步执行的sql的thread id
select lwtid from pg_thread_wait_status where query_id in (select query_id from pg_stat_activity where query='insert into t_trace_thread select generate_series(1,100000000);');

--4. 启动gstrace，并指定追踪模块为sqltrace，及前一步获取的thread id，记为thread_num
gstrace start -p 26000 -q sqltrace.ALL -tid thread_num

--5. 将sqltrace写入指定dump文件sqltrace.dump
gstrace dump -p 26000 -o /home/mogdbuser/sqltrace.dump

--6. 停止追踪
gstrace stop -p 26000

--7. 解析dump信息，并输出到指定文件sqltrace.txt
gstrace analyze_sqltrace -f /home/mogdbuser/sqltrace.dump -o /home/mogdbuser/sqltrace.txt

    示例3：解析结果文件内容

    img

  • 导出并分析轻量级锁数据

    --1. 启动数据库
gsql -d postgres -p 26000
  
--2. 导出获得二进制lwlock文件
gstrace dump_lwlock -p 5549 -o /home/mogdbuser/dump_lwlock.bin
  
--3. 创建可阅读json版本lwlock信息文件
gstrace analyze_lwlock -f /home/mogdbuser/dump_lwlock.bin -o /home/mogdbuser/analyze_lwlock.json
  
--4. 阅读分析json版本信息文件

  • 调用追踪DCF模块

    --1. 按DCF配置三个节点，node1(主),node2,node3
--a. 分别在三个节点上安装数据库
--b. 配置白名单：在pg_hba.conf里添加白名单,示例如下：
host all all 172.20.10.6/32
host all all 172.20.10.7/32
host all all 172.20.10.8/32
--c.分别在三个节点的postgresql.conf配置文件里添加如下内容配置DCF参数，例如：
--节点1：
port=21000
dcf_node_id = 1
dcf_ssl=off
dcf_data_path = '/opengauss/data/dcf_data'
dcf_log_path= '/opengauss/data/dcf_log'
dcf_config='[{"stream_id":1,"node_id":1,"ip":"172.20.10.6","port":21000,"role":"LEADER"},{"stream_id":1,"node_id":2,"ip":"172.20.10.7","port":21000,"role":"FOLLOWER"},{"stream_id":1,"node_id":3,"ip":"172.20.10.8","port":21000,"role":"FOLLOWER"}]'
replconninfo1 = 'localhost=172.20.10.6 localport=21001 localheartbeatport=21005 remotehost=172.20.10.7 remoteport=21001 remoteheartbeatport=21005'
replconninfo2 = 'localhost=172.20.10.6 localport=21001 localheartbeatport=21005 remotehost=172.20.10.8 remoteport=21001 remoteheartbeatport=21005'
--节点2：
port=21000
dcf_node_id = 2
dcf_ssl=off
dcf_data_path = '/opengauss/data/dcf_data'
dcf_log_path= '/opengauss/data/dcf_log'
dcf_config='[{"stream_id":1,"node_id":1,"ip":"172.20.10.6","port":21000,"role":"LEADER"},{"stream_id":1,"node_id":2,"ip":"172.20.10.7","port":21000,"role":"FOLLOWER"},{"stream_id":1,"node_id":3,"ip":"172.20.10.8","port":21000,"role":"FOLLOWER"}]'
replconninfo1 = 'localhost=172.20.10.7 localport=21001 localheartbeatport=21005 remotehost=172.20.10.6 remoteport=21001 remoteheartbeatport=21005'
replconninfo2 = 'localhost=172.20.10.7 localport=21001 localheartbeatport=21005 remotehost=172.20.10.8 remoteport=21001 remoteheartbeatport=21005'
--节点3：
port=21000
dcf_node_id = 3
dcf_ssl=off
dcf_data_path = '/opengauss/data/dcf_data'
dcf_log_path= '/opengauss/data/dcf_log'
dcf_config='[{"stream_id":1,"node_id":1,"ip":"172.20.10.6","port":21000,"role":"LEADER"},{"stream_id":1,"node_id":2,"ip":"172.20.10.7","port":21000,"role":"FOLLOWER"},{"stream_id":1,"node_id":3,"ip":"172.20.10.8","port":21000,"role":"FOLLOWER"}]'
replconninfo1 = 'localhost=172.20.10.8 localport=21001 localheartbeatport=21005 remotehost=172.20.10.7 remoteport=21001 remoteheartbeatport=21005'
replconninfo2 = 'localhost=172.20.10.8 localport=21001 localheartbeatport=21005 remotehost=172.20.10.6 remoteport=21001 remoteheartbeatport=21005'

--2. 设置GUC参数enable_dcf = on，启动数据库
set enable_dcf = on
gsql -d postgres -p 26000

--3. 三个node分别启动gstrace，指定追踪dcf模块的所有函数。
gstrace start -p port1_num -q dcf.ALL -f dump_file_1
gstrace start -p port2_num -q dcf.ALL -f dump_file_2
gstrace start -p port3_num -q dcf.ALL -f dump_file_3

--4. 执行会调用DCF功能模块的相关操作，例如数据库主备切换。
gs_ctl switchover -D $PGDATA2

--5. 停止追踪
gstrace stop -p port 1 _num
gstrace stop -p port 2 _num
gstrace stop -p port 3 _num

--6. 解析dump detail信息
gstrace detail -f dump_file1 -o detail_file
gstrace detail -f dump_file2 -o detail_file
gstrace detail -f dump_file3 -o detail_file

--7. 解析dump codepath信息
gstrace codepath -f dump1_file -o codepath_file
gstrace codepath -f dump2_file -o codepath_file
gstrace codepath -f dump3_file -o codepath_file

--8. 解析dump analyze信息
gstrace analyze -f dump1_file -o analyze_file
gstrace analyze -f dump2_file -o analyze_file
gstrace analyze -f dump3_file -o analyze_file

    • dump detail解析结果文件内容

      node 1

      img

      node 2

      img

      node 3

      img

    • dump codepath解析结果文件内容

      node 1

      img

      node 2

      img

      node 3

      img

    • dump analyze解析结果文件内容

      node 1

      img

      node 2

      img

      node 3

      img

首页

反馈
Copyright © 2011-2025 www.enmotech.com All rights reserved.