{"Entry":{"collection":"guc","key":"timing_clock_source","name":"timing_clock_source","aliases":[],"metadata":{"baseline":false,"boot_human":"Not specified","boot_val":null,"category":"Resource Usage / Time","category_zh":"","changed_in":[],"changes":[{"documentation_changed":false,"fields":{},"from":"18","status":"added","to":"19"}],"content_hash":"faa7e1cc96ab9fc107308a6aedfe1e621b161f2c10a8421750f96e26e648f1ac","context":"","default_changed_in":[],"default_history":[{"from":"19","to":"19","value":"auto"}],"editorial":{"advice":{"olap":"Use representative scans, prefetch, and spill phases. Increase concurrency or worker capacity only while throughput rises without unacceptable CPU overhead, memory pressure, or storage saturation.","oltp":"Benchmark with the production storage stack and concurrency. Optimize tail latency and queue depth, not only average throughput, and retain capacity for WAL, checkpoints, and foreground reads.","small":"Prefer auto or the upstream worker limits. Validate with pg_test_timing or I/O statistics as applicable; a larger pool on a small node can add context switching without useful parallelism."},"mechanism":["PostgreSQL describes timing_clock_source as follows: “Controls the clock source used for collecting timing measurements.” It can be changed at run time only by a superuser or a role with an appropriate SET grant. The atlas measures it in PG19 Beta 3; boot_val is the compiled or initialized baseline, not proof of a running cluster's effective setting.","auto selects a supported x86-64 Time-Stamp Counter when appropriate and otherwise uses the operating-system monotonic clock; system forces the OS clock and tsc requests CPU instructions such as RDTSC/RDTSCP. The faster source lowers EXPLAIN ANALYZE measurement overhead, but emulated or unstable TSC behavior can be slower or invalid.","Read it together with track_io_timing, track_wal_io_timing, log_executor_stats, compute_query_id. Check SHOW and pg_settings on the target server, verify the source and pending_restart fields, and compare workload, logs, and resource metrics before and after any change."],"pitfalls":["Treating the measured boot_val for timing_clock_source as proof of the effective value on an initialized or managed cluster.","Applying a change as though it were immediate while pg_settings reports superuser context.","Changing this setting in isolation without checking the linked limits, observability, and rollback path.","Depending on beta behavior in production without retesting the PostgreSQL 19 final release."],"references":[{"title":"PostgreSQL 19 Beta 4: timing_clock_source","url":"https://www.postgresql.org/docs/19/runtime-config-resource.html#GUC-TIMING-CLOCK-SOURCE"},{"title":"PostgreSQL 19 release notes","url":"https://www.postgresql.org/docs/19/release-19.html"}],"related":["track_io_timing","track_wal_io_timing","log_executor_stats","compute_query_id"],"summary":"timing_clock_source — Controls the clock source used for collecting timing measurements. Observed in PG19 Beta 4; its last measured boot default is auto in PG19 Beta 4, with superuser context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA."},"enumvals":[],"first_version":"19","group":"Resource Usage","group_slug":"resource","imported_at":"2026-09-27T17:57:32.168855+08:00","intro_commit":{"authored_at":"2026-04-07T12:48:07-04:00","discussion":["https://postgr.es/m/20200612232810.f46nbqkdhbutzqdg@alap3.anarazel.de"],"hash":"294520c44487ecaade7a6ea8781b973f9ed03909","subject":"instrumentation: Use Time-Stamp Counter on x86-64 to lower overhead","url":"https://git.postgresql.org/gitweb/?p=postgresql.git;a=commit;h=294520c44487ecaade7a6ea8781b973f9ed03909"},"key":"timing_clock_source","last_version":"20","max_val":"","min_val":"","name":"timing_clock_source","position":415,"present_in":["19","20"],"short_desc":"Selects the method for making timing measurements using the OS or specialized CPU instructions.","short_desc_zh":"","source_rev":"english-manuals:6750c880720b8717e8f26205393941f51cfea63cbb91d2a27a68e24cd38bb7e7","unit":"","vartype":"enum"}},"Definition":{"Collection":"guc","Key":"timing_clock_source","SourceDatabase":"center","Version":"20","SourceTable":"guc","SourceKey":"timing_clock_source","SourceRevision":"english-manuals:6750c880720b8717e8f26205393941f51cfea63cbb91d2a27a68e24cd38bb7e7","Facts":{"boot_val":null,"category":"Timing","context":"","description":"Selects the method for making timing measurements using the OS or specialized CPU instructions. Possible values are: auto (automatically chooses TSC clock source on supported x86-64 CPUs, otherwise uses the OS system clock) system (measures timing using the OS system clock) tsc (measures timing with a CPU instruction, e.g. using RDTSC/RDTSCP on x86-64) The default is auto. Only superusers can change this setting. Changing the setting during query execution is not recommended and may cause interval timings to jump significantly or produce negative values. If enabled, the TSC clock source, named after the Time-Stamp Counter on x86-64, will use specialized CPU instructions when measuring time intervals. This lowers timing overhead compared to reading the OS system clock, and reduces the measurement error on top of the actual runtime, for example with EXPLAIN ANALYZE. On x86-64 CPUs the TSC clock source utilizes the RDTSC instruction for EXPLAIN ANALYZE. For timings that require higher precision the RDTSCP instruction is used, which avoids inaccuracies due to CPU instruction re-ordering. Use of the TSC clock source is not supported on older x86-64 CPUs and other architectures, and is not advised on systems that utilize an emulated TSC, as it is likely slower than the system clock source. To help decide which clock source to use you can run the pg_test_timing utility to check TSC availability, and perform timing measurements.","doc":{"anchor":"GUC-TIMING-CLOCK-SOURCE","file":"runtime-config-resource.html","lang":"en","sha256":"ea0a5d7b8e66421d046db778b5fd97f6b61f6e0c6d784a5df79583500a5e1497","slug":"devel"},"documented":true,"enumvals":[],"extra_desc":"","lang":"en","max_val":null,"metadata_version":"","min_val":null,"name":"timing_clock_source","short_desc":"","source":"english-manual","unit":"","vartype":"enum"},"ManualEvidence":{"doc":{"anchor":"GUC-TIMING-CLOCK-SOURCE","file":"runtime-config-resource.html","lang":"en","sha256":"ea0a5d7b8e66421d046db778b5fd97f6b61f6e0c6d784a5df79583500a5e1497","slug":"devel"}},"MeasuredEvidence":{"metadata_version":""}},"Text":{"Collection":"guc","Key":"timing_clock_source","SourceDatabase":"pgweb","Version":"20","Locale":"zh-Hans","Title":"timing_clock_source","Summary":"","BodyHTML":"\u003cp\u003e选择使用操作系统或专用 CPU 指令进行计时测量的方法。可能的值有：\u003c/p\u003e\u003cdiv\u003e\u003cul\u003e\u003cli\u003e\u003cp\u003e\u003ccode\u003eauto\u003c/code\u003e（在受支持的 x86-64 CPU 上自动选择 TSC 时钟源，否则使用操作系统时钟）\u003c/p\u003e\u003c/li\u003e\u003cli\u003e\u003cp\u003e\u003ccode\u003esystem\u003c/code\u003e（使用操作系统时钟进行计时测量）\u003c/p\u003e\u003c/li\u003e\u003cli\u003e\u003cp\u003e\u003ccode\u003etsc\u003c/code\u003e（使用 CPU 指令进行计时，例如在 x86-64 上使用 \u003ccode\u003eRDTSC\u003c/code\u003e/\u003ccode\u003eRDTSCP\u003c/code\u003e）\u003c/p\u003e\u003c/li\u003e\u003c/ul\u003e\u003c/div\u003e\u003cp\u003e默认值为\u003ccode\u003eauto\u003c/code\u003e。只有超级用户可以更改此设置。不建议在查询执行期间更改该设置，因为这可能会导致间隔计时出现明显跳变，或者产生负值。\u003c/p\u003e\u003cp\u003e 如果启用，名为 TSC 的时钟源会在测量时间间隔时使用专门的 CPU 指令；它的名字来自 x86-64 上的时间戳计数器（Time-Stamp Counter）。与读取操作系统时钟相比，这可以降低计时开销，并减少叠加在实际运行时间之上的测量误差，例如在 \u003ccode\u003eEXPLAIN ANALYZE\u003c/code\u003e 中。\u003c/p\u003e\u003cp\u003e在 x86-64 CPU 上，TSC 时钟源会在 \u003ccode\u003eEXPLAIN ANALYZE\u003c/code\u003e 中使用 \u003ccode\u003eRDTSC\u003c/code\u003e 指令。对于需要更高精度的计时，会使用 \u003ccode\u003eRDTSCP\u003c/code\u003e 指令，以避免由于 CPU 指令重排序造成的不准确。较旧的 x86-64 CPU 和其他架构不支持使用 TSC 时钟源，而且在使用模拟 TSC 的系统上也不建议这样做，因为它很可能比系统时钟源更慢。\u003c/p\u003e\u003cp\u003e为了帮助决定应使用哪种时钟源，你可以运行\u003ca href=\"/docs/devel/pgtesttiming.html\" title=\"pg_test_timing\" rel=\"nofollow\"\u003e\u003cspan\u003e\u003cspan\u003epg_test_timing\u003c/span\u003e\u003c/span\u003e\u003c/a\u003e工具来检查 TSC 可用性并执行计时测量。\u003c/p\u003e","SourceRevision":"2026-09-11@29c86d9","ContentHash":"7ce32c25abb639b96c35f8dbcab97ff979f85683c131ca131ae0b27f25f0e2f5","Payload":{"carried_from":"19","carry_reason":"手册不含 pg_settings 事实，沿用 19","doc_html":"\u003cp\u003e选择使用操作系统或专用 CPU 指令进行计时测量的方法。可能的值有：\u003c/p\u003e\u003cdiv class=\"itemizedlist\"\u003e\u003cul\u003e\u003cli\u003e\u003cp\u003e\u003ccode class=\"literal\"\u003eauto\u003c/code\u003e（在受支持的 x86-64 CPU 上自动选择 TSC 时钟源，否则使用操作系统时钟）\u003c/p\u003e\u003c/li\u003e\u003cli\u003e\u003cp\u003e\u003ccode class=\"literal\"\u003esystem\u003c/code\u003e（使用操作系统时钟进行计时测量）\u003c/p\u003e\u003c/li\u003e\u003cli\u003e\u003cp\u003e\u003ccode class=\"literal\"\u003etsc\u003c/code\u003e（使用 CPU 指令进行计时，例如在 x86-64 上使用 \u003ccode class=\"command\"\u003eRDTSC\u003c/code\u003e/\u003ccode class=\"command\"\u003eRDTSCP\u003c/code\u003e）\u003c/p\u003e\u003c/li\u003e\u003c/ul\u003e\u003c/div\u003e\u003cp\u003e默认值为\u003ccode class=\"literal\"\u003eauto\u003c/code\u003e。只有超级用户可以更改此设置。不建议在查询执行期间更改该设置，因为这可能会导致间隔计时出现明显跳变，或者产生负值。\u003c/p\u003e\u003cp\u003e 如果启用，名为 TSC 的时钟源会在测量时间间隔时使用专门的 CPU 指令；它的名字来自 x86-64 上的时间戳计数器（Time-Stamp Counter）。与读取操作系统时钟相比，这可以降低计时开销，并减少叠加在实际运行时间之上的测量误差，例如在 \u003ccode class=\"command\"\u003eEXPLAIN ANALYZE\u003c/code\u003e 中。\u003c/p\u003e\u003cp\u003e在 x86-64 CPU 上，TSC 时钟源会在 \u003ccode class=\"command\"\u003eEXPLAIN ANALYZE\u003c/code\u003e 中使用 \u003ccode class=\"command\"\u003eRDTSC\u003c/code\u003e 指令。对于需要更高精度的计时，会使用 \u003ccode class=\"command\"\u003eRDTSCP\u003c/code\u003e 指令，以避免由于 CPU 指令重排序造成的不准确。较旧的 x86-64 CPU 和其他架构不支持使用 TSC 时钟源，而且在使用模拟 TSC 的系统上也不建议这样做，因为它很可能比系统时钟源更慢。\u003c/p\u003e\u003cp\u003e为了帮助决定应使用哪种时钟源，你可以运行\u003ca href=\"/docs/devel/pgtesttiming.html\" title=\"pg_test_timing\"\u003e\u003cspan class=\"refentrytitle\"\u003e\u003cspan class=\"application\"\u003epg_test_timing\u003c/span\u003e\u003c/span\u003e\u003c/a\u003e工具来检查 TSC 可用性并执行计时测量。\u003c/p\u003e","doc_same_as":""}},"RequestedLocale":"zh-Hans","Fallback":false,"Versions":["19","20"],"Locales":["en","zh-Hans"],"Signatures":null,"Spellings":null,"SQLState":null,"Evidence":null}