PostgreSQL：文档：17：27.5. 动态跟踪

支持版本：当前 (17) / 16 / 15 / 14 / 13 / 12

开发版本：devel

不支持的版本：11 / 10 / 9.6 / 9.5 / 9.4 / 9.3 / 9.2 / 9.1 / 9.0 / 8.4 / 8.3 / 8.2

27.5. 动态跟踪
上一步	向上	第 27 章. 监控数据库活动	主页	下一步

27.5. 动态跟踪 #

27.5.1. 为动态跟踪编译
27.5.2. 内置探针
27.5.3. 使用探针
27.5.4. 定义新的探针

PostgreSQL 提供支持数据库服务器动态跟踪的功能。这允许在代码中的特定点调用外部工具，从而跟踪执行。

源代码中已插入了许多探针或跟踪点。这些探针旨在供数据库开发人员和管理员使用。默认情况下，探针不会编译到 PostgreSQL 中；用户需要明确告诉配置脚本使探针可用。

目前，支持 DTrace 工具，该工具在撰写本文时可在 Solaris、macOS、FreeBSD、NetBSD 和 Oracle Linux 上使用。用于 Linux 的 SystemTap 项目提供了 DTrace 等效项，也可以使用。理论上可以通过更改 src/include/utils/probes.h 中宏的定义来支持其他动态跟踪工具。

27.5.1. 为动态跟踪编译 #

默认情况下，探针不可用，因此您需要明确告诉配置脚本在 PostgreSQL 中使探针可用。要包含 DTrace 支持，请在配置时指定 --enable-dtrace。有关更多信息，请参见第 17.3.3.6 节。

27.5.2. 内置探针 #

源代码中提供了许多标准探针，如表 27.49 所示；表 27.50 显示了探针中使用的类型。当然可以添加更多探针以增强 PostgreSQL 的可观察性。

表 27.49. 内置 DTrace 探针

名称	参数	描述
`transaction-start`	`(LocalTransactionId)`	在开始新的事务时触发的探针。arg0 是事务 ID。
`transaction-commit`	`(LocalTransactionId)`	事务成功完成时触发的探针。arg0 是事务 ID。
`transaction-abort`	`(LocalTransactionId)`	事务不成功完成时触发的探针。arg0 是事务 ID。
`query-start`	`(const char *)`	在开始处理查询时触发的探针。arg0 是查询字符串。
`query-done`	`(const char *)`	在完成查询处理时触发的探针。arg0 是查询字符串。
`query-parse-start`	`(const char *)`	在开始解析查询时触发的探针。arg0 是查询字符串。
`query-parse-done`	`(const char *)`	在完成查询解析时触发的探针。arg0 是查询字符串。
`query-rewrite-start`	`(const char *)`	在开始重写查询时触发的探针。arg0 是查询字符串。
`query-rewrite-done`	`(const char *)`	在完成查询重写时触发的探针。arg0 是查询字符串。
`query-plan-start`	`()`	在开始规划查询时触发的探针。
`query-plan-done`	`()`	在完成查询规划时触发的探针。
`query-execute-start`	`()`	在开始执行查询时触发的探针。
`query-execute-done`	`()`	在完成查询执行时触发的探针。
`statement-status`	`(const char *)`	每当服务器进程更新其 `pg_stat_activity`.`status` 时触发的探针。arg0 是新的状态字符串。
`checkpoint-start`	`(int)`	在开始检查点时触发的探针。arg0 包含用于区分不同检查点类型的位标志，例如关闭、立即或强制。
`checkpoint-done`	`(int, int, int, int, int)`	在完成检查点时触发的探针。（接下来列出的探针在检查点处理过程中按顺序触发。）arg0 是写入的缓冲区数量。arg1 是缓冲区的总数。arg2、arg3 和 arg4 分别包含添加、删除和回收的 WAL 文件数量。
`clog-checkpoint-start`	`(bool)`	在开始检查点的 CLOG 部分时触发的探针。arg0 对于正常检查点为真，对于关闭检查点为假。
`clog-checkpoint-done`	`(bool)`	在完成检查点的 CLOG 部分时触发的探针。arg0 的含义与 `clog-checkpoint-start` 相同。
`subtrans-checkpoint-start`	`(bool)`	在开始检查点的 SUBTRANS 部分时触发的探针。arg0 对于正常检查点为真，对于关闭检查点为假。
`subtrans-checkpoint-done`	`(bool)`	在完成检查点的 SUBTRANS 部分时触发的探针。arg0 的含义与 `subtrans-checkpoint-start` 相同。
`multixact-checkpoint-start`	`(bool)`	在开始检查点的 MultiXact 部分时触发的探针。arg0 对于正常检查点为真，对于关闭检查点为假。
`multixact-checkpoint-done`	`(bool)`	在完成检查点的 MultiXact 部分时触发的探针。arg0 的含义与 `multixact-checkpoint-start` 相同。
`buffer-checkpoint-start`	`(int)`	在开始检查点的缓冲区写入部分时触发的探针。arg0 包含用于区分不同检查点类型的位标志，例如关闭、立即或强制。
`buffer-sync-start`	`(int, int)`	在我们在检查点期间开始写入脏缓冲区（在识别出必须写入的缓冲区后）时触发的探针。arg0 是缓冲区的总数。arg1 是当前脏的并且需要写入的缓冲区数量。
`buffer-sync-written`	`(int)`	在检查点期间写入每个缓冲区后触发的探针。arg0 是缓冲区的 ID 号。
`buffer-sync-done`	`(int, int, int)`	在所有脏缓冲区都已写入后触发的探针。arg0 是缓冲区的总数。arg1 是检查点进程实际写入的缓冲区数量。arg2 是预计要写入的缓冲区数量（`buffer-sync-start` 的 arg1）；任何差异都反映了检查点期间其他进程刷新缓冲区的情况。
`buffer-checkpoint-sync-start`	`()`	在将脏缓冲区写入内核后，但在开始发出 fsync 请求之前触发的探针。
`buffer-checkpoint-done`	`()`	在将缓冲区同步到磁盘完成后触发的探针。
`twophase-checkpoint-start`	`()`	在开始检查点的两阶段部分时触发的探针。
`twophase-checkpoint-done`	`()`	在完成检查点的两阶段部分时触发的探针。
`buffer-extend-start`	`(ForkNumber, BlockNumber, Oid, Oid, Oid, int, unsigned int)`	在关系扩展开始时触发的探针。arg0 包含要扩展的分支。arg1、arg2 和 arg3 包含标识关系的表空间、数据库和关系 OID。arg4 是创建本地缓冲区临时关系的后端 ID，或 `INVALID_PROC_NUMBER` (-1) 用于共享缓冲区。arg5 是调用者希望扩展的块数。
`buffer-extend-done`	`(ForkNumber, BlockNumber, Oid, Oid, Oid, int, unsigned int, BlockNumber)`	在关系扩展完成时触发的探针。arg0 包含要扩展的分支。arg1、arg2 和 arg3 包含标识关系的表空间、数据库和关系 OID。arg4 是创建本地缓冲区临时关系的后端 ID，或 `INVALID_PROC_NUMBER` (-1) 用于共享缓冲区。arg5 是关系扩展的块数，这可能小于 `buffer-extend-start` 中的块数，因为资源限制。arg6 包含第一个新块的 BlockNumber。
`buffer-read-start`	`(ForkNumber, BlockNumber, Oid, Oid, Oid, int)`	在开始缓冲区读取时触发的探针。arg0 和 arg1 包含页面的分支和块号。arg2、arg3 和 arg4 包含标识关系的表空间、数据库和关系 OID。arg5 是创建本地缓冲区临时关系的后端 ID，或 `INVALID_PROC_NUMBER` (-1) 用于共享缓冲区。
`buffer-read-done`	`(ForkNumber, BlockNumber, Oid, Oid, Oid, int, bool)`	在缓冲区读取完成后触发的探针。arg0 和 arg1 包含页面的分支和块号。arg2、arg3 和 arg4 包含标识关系的表空间、数据库和关系 OID。arg5 是创建本地缓冲区临时关系的后端 ID，或 `INVALID_PROC_NUMBER` (-1) 用于共享缓冲区。arg6 如果缓冲区在池中找到，则为真，否则为假。
`buffer-flush-start`	`(ForkNumber, BlockNumber, Oid, Oid, Oid)`	在为共享缓冲区发出任何写入请求之前触发的探针。arg0 和 arg1 包含页面的分支和块号。arg2、arg3 和 arg4 包含标识关系的表空间、数据库和关系 OID。
`buffer-flush-done`	`(ForkNumber, BlockNumber, Oid, Oid, Oid)`	在写入请求完成后触发的探针。（请注意，这仅反映了将数据传递给内核所需的时间；通常还没有真正写入磁盘。）参数与 `buffer-flush-start` 相同。
`wal-buffer-write-dirty-start`	`()`	当服务器进程开始写入脏 WAL 缓冲区，因为没有更多 WAL 缓冲区空间可用时触发的探针。（如果经常发生这种情况，则意味着 wal_buffers 太小。）
`wal-buffer-write-dirty-done`	`()`	在完成脏 WAL 缓冲区写入时触发的探针。
`wal-insert`	`(unsigned char, unsigned char)`	在插入 WAL 记录时触发的探针。arg0 是记录的资源管理器 (rmid)。arg1 包含信息标志。
`wal-switch`	`()`	在请求 WAL 段切换时触发的探针。
`smgr-md-read-start`	`(ForkNumber, BlockNumber, Oid, Oid, Oid, int)`	在开始从关系中读取块时触发的探针。arg0 和 arg1 包含页面的分叉号和块号。arg2、arg3 和 arg4 包含标识关系的表空间、数据库和关系 OID。arg5 是为本地缓冲区创建临时关系的后端 ID，或 `INVALID_PROC_NUMBER` (-1) 用于共享缓冲区。
`smgr-md-read-done`	`(ForkNumber, BlockNumber, Oid, Oid, Oid, int, int, int)`	在完成块读取时触发的探针。arg0 和 arg1 包含页面的分叉号和块号。arg2、arg3 和 arg4 包含标识关系的表空间、数据库和关系 OID。arg5 是为本地缓冲区创建临时关系的后端 ID，或 `INVALID_PROC_NUMBER` (-1) 用于共享缓冲区。arg6 是实际读取的字节数，而 arg7 是请求的字节数（如果它们不同，则表示短读取）。
`smgr-md-write-start`	`(ForkNumber, BlockNumber, Oid, Oid, Oid, int)`	在开始将块写入关系时触发的探针。arg0 和 arg1 包含页面的分叉号和块号。arg2、arg3 和 arg4 包含标识关系的表空间、数据库和关系 OID。arg5 是为本地缓冲区创建临时关系的后端 ID，或 `INVALID_PROC_NUMBER` (-1) 用于共享缓冲区。
`smgr-md-write-done`	`(ForkNumber, BlockNumber, Oid, Oid, Oid, int, int, int)`	在完成块写入时触发的探针。arg0 和 arg1 包含页面的分叉号和块号。arg2、arg3 和 arg4 包含标识关系的表空间、数据库和关系 OID。arg5 是为本地缓冲区创建临时关系的后端 ID，或 `INVALID_PROC_NUMBER` (-1) 用于共享缓冲区。arg6 是实际写入的字节数，而 arg7 是请求的字节数（如果它们不同，则表示短写入）。
`sort-start`	`(int, bool, int, int, bool, int)`	在开始排序操作时触发的探针。arg0 指示堆、索引或数据排序。arg1 对于唯一值强制执行为真。arg2 是键列数。arg3 是允许的工作内存大小（千字节）。arg4 如果需要对排序结果进行随机访问，则为真。arg5 表示 `0` 时为串行，`1` 时为并行工作器，`2` 时为并行领导者。
`sort-done`	`(bool, long)`	在排序完成时触发的探针。arg0 对于外部排序为真，对于内部排序为假。arg1 是外部排序使用的磁盘块数，或内部排序使用的内存大小（千字节）。
`lwlock-acquire`	`(char *, LWLockMode)`	在获取 LWLock 时触发的探针。arg0 是 LWLock 的区段。arg1 是请求的锁定模式，可以是排他或共享。
`lwlock-release`	`(char *)`	在释放 LWLock 时触发的探针（但请注意，任何已释放的等待者尚未被唤醒）。arg0 是 LWLock 的区段。
`lwlock-wait-start`	`(char *, LWLockMode)`	当 LWLock 立即不可用且服务器进程已开始等待锁定变为可用时触发的探针。arg0 是 LWLock 的区段。arg1 是请求的锁定模式，可以是排他或共享。
`lwlock-wait-done`	`(char *, LWLockMode)`	在服务器进程从其等待 LWLock 的状态中释放出来时触发的探针（它尚未实际拥有锁定）。arg0 是 LWLock 的区段。arg1 是请求的锁定模式，可以是排他或共享。
`lwlock-condacquire`	`(char *, LWLockMode)`	当调用者指定不等待时，LWLock 成功获取时触发的探针。arg0 是 LWLock 的区段。arg1 是请求的锁定模式，可以是排他或共享。
`lwlock-condacquire-fail`	`(char *, LWLockMode)`	当调用者指定不等待时，LWLock 未成功获取时触发的探针。arg0 是 LWLock 的区段。arg1 是请求的锁定模式，可以是排他或共享。
`lock-wait-start`	`(unsigned int, unsigned int, unsigned int, unsigned int, unsigned int, LOCKMODE)`	当请求重量级锁（lmgr 锁）开始等待，因为锁不可用时触发的探针。arg0 到 arg3 是标识被锁定的对象的标记字段。arg4 指示被锁定的对象的类型。arg5 指示请求的锁定类型。
`lock-wait-done`	`(unsigned int, unsigned int, unsigned int, unsigned int, unsigned int, LOCKMODE)`	当请求重量级锁（lmgr 锁）完成等待（即，已获取锁）时触发的探针。参数与 `lock-wait-start` 相同。
`deadlock-found`	`()`	当死锁检测器发现死锁时触发的探针。

表 27.50. 探针参数中使用的定义类型

类型	定义
`LocalTransactionId`	`unsigned int`
`LWLockMode`	`int`
`LOCKMODE`	`int`
`BlockNumber`	`unsigned int`
`Oid`	`unsigned int`
`ForkNumber`	`int`
`bool`	`unsigned char`

27.5.3. 使用探针 #

下面的示例显示了用于分析系统中事务计数的 DTrace 脚本，作为在性能测试之前和之后对 pg_stat_database 进行快照的替代方法

#!/usr/sbin/dtrace -qs

postgresql$1:::transaction-start
{
      @start["Start"] = count();
      self->ts  = timestamp;
}

postgresql$1:::transaction-abort
{
      @abort["Abort"] = count();
}

postgresql$1:::transaction-commit
/self->ts/
{
      @commit["Commit"] = count();
      @time["Total time (ns)"] = sum(timestamp - self->ts);
      self->ts=0;
}

执行后，示例 D 脚本会给出如下输出

# ./txn_count.d `pgrep -n postgres` or ./txn_count.d <PID>
^C

Start                                          71
Commit                                         70
Total time (ns)                        2312105013

注意

SystemTap 使用与 DTrace 不同的跟踪脚本表示法，即使底层跟踪点是兼容的。需要注意的一点是，在编写本文时，SystemTap 脚本必须使用双下划线代替连字符来引用探针名称。预计将在未来的 SystemTap 版本中修复此问题。

您应该记住，DTrace 脚本需要仔细编写和调试，否则收集到的跟踪信息可能毫无意义。在大多数发现问题的情况下，是检测工具存在错误，而不是底层系统。在讨论使用动态跟踪发现的信息时，请确保包含用于允许也检查和讨论该脚本的脚本。

27.5.4. 定义新的探针 #

可以在开发人员希望的任何地方在代码中定义新的探针，但这将需要重新编译。以下是插入新探针的步骤

确定探针名称和要通过探针提供的数据
将探针定义添加到 src/backend/utils/probes.d
如果包含探针点的模块（s）中不存在 pg_trace.h，则包含它，并在源代码中的所需位置插入 TRACE_POSTGRESQL 探针宏
重新编译并验证新探针是否可用

示例： 以下是如何添加探针以通过事务 ID 跟踪所有新事务的示例。

确定探针将被命名为 transaction-start 并且需要一个类型为 LocalTransactionId 的参数
将探针定义添加到 src/backend/utils/probes.d
```
probe transaction__start(LocalTransactionId);
```
注意探针名称中使用了双下划线。在使用探针的 DTrace 脚本中，双下划线需要替换为连字符，因此 transaction-start 是要为用户记录的名称。
在编译时，transaction__start 被转换为名为 TRACE_POSTGRESQL_TRANSACTION_START 的宏（注意这里的下划线是单一的），它可以通过包含 pg_trace.h 来使用。将宏调用添加到源代码中的适当位置。在这种情况下，它看起来像这样
```
TRACE_POSTGRESQL_TRANSACTION_START(vxid.localTransactionId);
```

重新编译并运行新二进制文件后，通过执行以下 DTrace 命令来检查您新添加的探针是否可用。您应该看到类似的输出

# dtrace -ln transaction-start
   ID    PROVIDER          MODULE           FUNCTION NAME
18705 postgresql49878     postgres     StartTransactionCommand transaction-start
18755 postgresql49877     postgres     StartTransactionCommand transaction-start
18805 postgresql49876     postgres     StartTransactionCommand transaction-start
18855 postgresql49875     postgres     StartTransactionCommand transaction-start
18986 postgresql49873     postgres     StartTransactionCommand transaction-start

在将跟踪宏添加到 C 代码时，需要注意一些事项

您应该注意，为探针参数指定的的数据类型必须与宏中使用的变量的数据类型匹配。否则，您将收到编译错误。
在大多数平台上，如果 PostgreSQL 是使用 --enable-dtrace 构建的，则跟踪宏的参数将在控制流过宏时进行评估，即使没有进行跟踪。如果您只是报告几个局部变量的值，这通常不值得担心。但是，请注意将昂贵的函数调用放入参数中。如果您需要这样做，请考虑使用检查来保护宏，以查看跟踪是否实际启用
```
if (TRACE_POSTGRESQL_TRANSACTION_START_ENABLED())
    TRACE_POSTGRESQL_TRANSACTION_START(some_function(...));
```
每个跟踪宏都有一个相应的 ENABLED 宏。

上一步	向上	下一步
27.4. 进度报告	主页	27.6. 监控磁盘使用情况

提交更正

如果您在文档中发现任何不正确的内容，与您对特定功能的体验不符，或者需要进一步说明，请使用此表格报告文档问题。