Dynamic Tracing docs
Enclose new trace.sgml file as discussed on -docs.
This includes some heavily rewritten words and mostly verbatim programs
from http://blogs.sun.com/robertlor/entry/user_level_dtrace_probes_in,
as invited to do by Josh Berkus and Robert Lor on 27 Nov in private
correspondence prior to my post on -docs. There is substantial
additional material as well as genericisation so it is suitable for
inclusion in general docs.
This includes refactoring of some of the trace related GUC docs from
config.sgml, so its all in the one place.
SGML is clean apart from two xrefs that don't work properly:
openjade:config.sgml:4412:23:X: reference to non-existent ID
"TRACE-CONFIG-DEVELOPER"
openjade:wal.sgml:292:31:X: reference to non-existent ID "GUC-WAL-DEBUG"
openjade:/usr/share/sgml/docbook/dsssl-stylesheets/html/dblink.dsl:203:1:E: XRef LinkEnd to missing ID 'TRACE-CONFIG-DEVELOPER'
openjade:/usr/share/sgml/docbook/dsssl-stylesheets/html/dblink.dsl:203:1:E: XRef LinkEnd to missing ID 'GUC-WAL-DEBUG'
Quick fixes?
(I haven't proof-read the resulting .html as a result of the above
error, but seems like y'all would want to see this anyway).
--
Simon Riggs
EnterpriseDB http://www.enterprisedb.com
Attachments:
tracedocs.patchtext/x-patch; charset=UTF-8; name=tracedocs.patchDownload
Index: doc/src/sgml/config.sgml
===================================================================
RCS file: /projects/cvsroot/pgsql/doc/src/sgml/config.sgml,v
retrieving revision 1.96
diff -c -r1.96 config.sgml
*** doc/src/sgml/config.sgml 21 Nov 2006 01:23:37 -0000 1.96
--- doc/src/sgml/config.sgml 1 Dec 2006 22:47:32 -0000
***************
*** 4400,4411 ****
<para>
The following parameters are intended for work on the
! <productname>PostgreSQL</productname> source, and in some cases
to assist with recovery of severely damaged databases. There
should be no reason to use them in a production database setup.
As such, they have been excluded from the sample
! <filename>postgresql.conf</> file. Note that many of these
! parameters require special source compilation flags to work at all.
</para>
<variablelist>
--- 4400,4415 ----
<para>
The following parameters are intended for work on the
! <productname>PostgreSQL</productname> source specifically
to assist with recovery of severely damaged databases. There
should be no reason to use them in a production database setup.
As such, they have been excluded from the sample
! <filename>postgresql.conf</> file.
! </para>
!
! <para>
! Additional parameters used for tracing server behaviour are discussed
! in the trace chapter.
</para>
<variablelist>
***************
*** 4423,4449 ****
</listitem>
</varlistentry>
- <varlistentry id="guc-debug-assertions" xreflabel="debug_assertions">
- <term><varname>debug_assertions</varname> (<type>boolean</type>)</term>
- <indexterm>
- <primary><varname>debug_assertions</> configuration parameter</primary>
- </indexterm>
- <listitem>
- <para>
- Turns on various assertion checks. This is a debugging aid. If
- you are experiencing strange problems or crashes you might want
- to turn this on, as it might expose programming mistakes. To use
- this parameter, the macro <symbol>USE_ASSERT_CHECKING</symbol>
- must be defined when <productname>PostgreSQL</productname> is
- built (accomplished by the <command>configure</command> option
- <option>--enable-cassert</option>). Note that
- <varname>debug_assertions</varname> defaults to <literal>on</>
- if <productname>PostgreSQL</productname> has been built with
- assertions enabled.
- </para>
- </listitem>
- </varlistentry>
-
<varlistentry id="guc-ignore-system-indexes" xreflabel="ignore_system_indexes">
<term><varname>ignore_system_indexes</varname> (<type>boolean</type>)</term>
<indexterm>
--- 4427,4432 ----
***************
*** 4459,4560 ****
</listitem>
</varlistentry>
- <varlistentry id="guc-post-auth-delay" xreflabel="post_auth_delay">
- <term><varname>post_auth_delay</varname> (<type>integer</type>)</term>
- <indexterm>
- <primary><varname>post_auth_delay</> configuration parameter</primary>
- </indexterm>
- <listitem>
- <para>
- If nonzero, a delay of this many seconds occurs when a new
- server process is started, after it conducts the
- authentication procedure. This is intended to give an
- opportunity to attach to the server process with a debugger.
- This parameter cannot be changed after session start.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="guc-pre-auth-delay" xreflabel="pre_auth_delay">
- <term><varname>pre_auth_delay</varname> (<type>integer</type>)</term>
- <indexterm>
- <primary><varname>pre_auth_delay</> configuration parameter</primary>
- </indexterm>
- <listitem>
- <para>
- If nonzero, a delay of this many seconds occurs just after a
- new server process is forked, before it conducts the
- authentication procedure. This is intended to give an
- opportunity to attach to the server process with a debugger to
- trace down misbehavior in authentication.
- This parameter can only be set in the <filename>postgresql.conf</>
- file or on the server command line.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="guc-trace-notify" xreflabel="trace_notify">
- <term><varname>trace_notify</varname> (<type>boolean</type>)</term>
- <indexterm>
- <primary><varname>trace_notify</> configuration parameter</primary>
- </indexterm>
- <listitem>
- <para>
- Generates a great amount of debugging output for the
- <command>LISTEN</command> and <command>NOTIFY</command>
- commands. <xref linkend="guc-client-min-messages"> or
- <xref linkend="guc-log-min-messages"> must be
- <literal>DEBUG1</literal> or lower to send this output to the
- client or server log, respectively.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="guc-trace-sort" xreflabel="trace_sort">
- <term><varname>trace_sort</varname> (<type>boolean</type>)</term>
- <indexterm>
- <primary><varname>trace_sort</> configuration parameter</primary>
- </indexterm>
- <listitem>
- <para>
- If on, emit information about resource usage during sort operations.
- This parameter is only available if the <symbol>TRACE_SORT</symbol> macro
- was defined when <productname>PostgreSQL</productname> was compiled.
- (However, <symbol>TRACE_SORT</symbol> is currently defined by default.)
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><varname>trace_locks</varname> (<type>boolean</type>)</term>
- <term><varname>trace_lwlocks</varname> (<type>boolean</type>)</term>
- <term><varname>trace_userlocks</varname> (<type>boolean</type>)</term>
- <term><varname>trace_lock_oidmin</varname> (<type>boolean</type>)</term>
- <term><varname>trace_lock_table</varname> (<type>boolean</type>)</term>
- <term><varname>debug_deadlocks</varname> (<type>boolean</type>)</term>
- <term><varname>log_btree_build_stats</varname> (<type>boolean</type>)</term>
- <listitem>
- <para>
- Various other code tracing and debugging options.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="guc-wal-debug" xreflabel="wal_debug">
- <term><varname>wal_debug</varname> (<type>boolean</type>)</term>
- <indexterm>
- <primary><varname>wal_debug</> configuration parameter</primary>
- </indexterm>
- <listitem>
- <para>
- If on, emit WAL-related debugging output. This parameter is
- only available if the <symbol>WAL_DEBUG</symbol> macro was
- defined when <productname>PostgreSQL</productname> was
- compiled.
- </para>
- </listitem>
- </varlistentry>
-
<varlistentry id="guc-zero-damaged-pages" xreflabel="zero_damaged_pages">
<term><varname>zero_damaged_pages</varname> (<type>boolean</type>)</term>
<indexterm>
--- 4442,4447 ----
Simon Riggs wrote:
This includes refactoring of some of the trace related GUC docs from
config.sgml, so its all in the one place.
I would rather like to keep all configuration parameters in one place.
--
Peter Eisentraut
http://developer.postgresql.org/~petere/
"Simon Riggs" <simon@2ndquadrant.com> writes:
This includes refactoring of some of the trace related GUC docs from
config.sgml, so its all in the one place.
Why exactly is that a good idea? Since DTrace is Solaris-only, this
almost seems like an attempt to hide non-Solaris-specific information
where people won't look for it. Moreover, the point of config.sgml
is to describe all the configuration parameters in one place. We do not
need to have people second-guessing that decision for random subsets
of the parameters.
regards, tom lane
Simon Riggs a écrit :
Enclose new trace.sgml file as discussed on -docs.
This includes some heavily rewritten words and mostly verbatim programs
from http://blogs.sun.com/robertlor/entry/user_level_dtrace_probes_in,
as invited to do by Josh Berkus and Robert Lor on 27 Nov in private
correspondence prior to my post on -docs. There is substantial
additional material as well as genericisation so it is suitable for
inclusion in general docs.This includes refactoring of some of the trace related GUC docs from
config.sgml, so its all in the one place.SGML is clean apart from two xrefs that don't work properly:
openjade:config.sgml:4412:23:X: reference to non-existent ID
"TRACE-CONFIG-DEVELOPER"
openjade:wal.sgml:292:31:X: reference to non-existent ID "GUC-WAL-DEBUG"
openjade:/usr/share/sgml/docbook/dsssl-stylesheets/html/dblink.dsl:203:1:E: XRef LinkEnd to missing ID 'TRACE-CONFIG-DEVELOPER'
openjade:/usr/share/sgml/docbook/dsssl-stylesheets/html/dblink.dsl:203:1:E: XRef LinkEnd to missing ID 'GUC-WAL-DEBUG'
Don't you need to lowercase them ? at least guc-wal-config exists in
config.sgml, but in lowercase only.
grep -ir shows nothing about a TRACE-CONFIG-DEVELOPER ID. In
config.sgml, there is a runtime-config-developer but I don't know if
this is the one you're searching for.
Regards.
--
Guillaume.
<!-- http://abs.traduc.org/
http://lfs.traduc.org/
http://docs.postgresqlfr.org/ -->
On Dec 1, 2006, at 6:56 PM, Tom Lane wrote:
"Simon Riggs" <simon@2ndquadrant.com> writes:
This includes refactoring of some of the trace related GUC docs from
config.sgml, so its all in the one place.Why exactly is that a good idea? Since DTrace is Solaris-only, this
almost seems like an attempt to hide non-Solaris-specific information
where people won't look for it. Moreover, the point of config.sgml
is to describe all the configuration parameters in one place. We
do not
need to have people second-guessing that decision for random subsets
of the parameters.
There is high likelihood that DTrace will be present in FreeBSD 7.0
and Mac OS 10.5. So, 3 of the support platforms would make use of it.
// Theo Schlossnagle
// CTO -- http://www.omniti.com/~jesus/
// OmniTI Computer Consulting, Inc. -- http://www.omniti.com/
"Simon Riggs" <simon@2ndquadrant.com> writes:
Enclose new trace.sgml file as discussed on -docs.
After some thought I decided it's probably best to stick this into
monitoring.sgml for now. If it gets big enough to deserve its own
chapter we can think about where else to put it.
Committed with some rewording and SGML fixes.
regards, tom lane
On Sat, 2006-12-02 at 01:02 +0100, Guillaume Lelarge wrote:
Simon Riggs a écrit :
Enclose new trace.sgml file as discussed on -docs.
This includes some heavily rewritten words and mostly verbatim programs
from http://blogs.sun.com/robertlor/entry/user_level_dtrace_probes_in,
as invited to do by Josh Berkus and Robert Lor on 27 Nov in private
correspondence prior to my post on -docs. There is substantial
additional material as well as genericisation so it is suitable for
inclusion in general docs.This includes refactoring of some of the trace related GUC docs from
config.sgml, so its all in the one place.SGML is clean apart from two xrefs that don't work properly:
openjade:config.sgml:4412:23:X: reference to non-existent ID
"TRACE-CONFIG-DEVELOPER"
openjade:wal.sgml:292:31:X: reference to non-existent ID "GUC-WAL-DEBUG"
openjade:/usr/share/sgml/docbook/dsssl-stylesheets/html/dblink.dsl:203:1:E: XRef LinkEnd to missing ID 'TRACE-CONFIG-DEVELOPER'
openjade:/usr/share/sgml/docbook/dsssl-stylesheets/html/dblink.dsl:203:1:E: XRef LinkEnd to missing ID 'GUC-WAL-DEBUG'Don't you need to lowercase them ? at least guc-wal-config exists in
config.sgml, but in lowercase only.grep -ir shows nothing about a TRACE-CONFIG-DEVELOPER ID. In
config.sgml, there is a runtime-config-developer but I don't know if
this is the one you're searching for.
They are lower case.
--
Simon Riggs
EnterpriseDB http://www.enterprisedb.com
On Fri, 2006-12-01 at 18:56 -0500, Tom Lane wrote:
"Simon Riggs" <simon@2ndquadrant.com> writes:
This includes refactoring of some of the trace related GUC docs from
config.sgml, so its all in the one place.Why exactly is that a good idea?
All of the trace options that require code edits to enable them are in
one place now. No need to re-invent what is already there.
Since DTrace is Solaris-only, this
almost seems like an attempt to hide non-Solaris-specific information
where people won't look for it.
The chapter is about Trace generally. DTrace isn't the only way of
getting trace information out of the server, so why would it have it's
own private chapter?
Moreover, the point of config.sgml
is to describe all the configuration parameters in one place. We do not
need to have people second-guessing that decision for random subsets
of the parameters.
I had split the Developer options into 2, which was a neat split. There
are tracing parameters and recovery/other parameters. So the split was
neither random, nor hidden - there was a clear xref to them from the
config.sgml. (That was one of the causes of the SGML errors, note).
The trace related parameters are significantly different from other
parameters, since they do not always work.
--
Simon Riggs
EnterpriseDB http://www.enterprisedb.com
On Fri, 2006-12-01 at 19:44 -0500, Tom Lane wrote:
"Simon Riggs" <simon@2ndquadrant.com> writes:
Enclose new trace.sgml file as discussed on -docs.
After some thought I decided it's probably best to stick this into
monitoring.sgml for now. If it gets big enough to deserve its own
chapter we can think about where else to put it.Committed with some rewording and SGML fixes.
Thanks. Like the changes to "Built-In" rather than Well-Known and few
other wording changes.
--
Simon Riggs
EnterpriseDB http://www.enterprisedb.com
On Fri, 2006-12-01 at 19:44 -0500, Tom Lane wrote:
"Simon Riggs" <simon@2ndquadrant.com> writes:
Enclose new trace.sgml file as discussed on -docs.
Committed with some rewording and SGML fixes.
Looks like you removed this line
@commit["Abort"] = count();
which means you should also remove this line from the output:
Abort 1
(So, both, or neither).
Robert's example defined this section of code
postgresql$1:::transaction-abort
{
@abort["Abort"] = count();
}
which would be otherwise unused, so I added the two lines to the final
section and program output. So the program as submitted was slightly
different to Robert's published example by covering both commits and
aborts.
--
Simon Riggs
EnterpriseDB http://www.enterprisedb.com
Also, it is probably too late to add something of this magnitude this
close to wrapping the tarball, but I might be mistaken.
---------------------------------------------------------------------------
Tom Lane wrote:
"Simon Riggs" <simon@2ndquadrant.com> writes:
This includes refactoring of some of the trace related GUC docs from
config.sgml, so its all in the one place.Why exactly is that a good idea? Since DTrace is Solaris-only, this
almost seems like an attempt to hide non-Solaris-specific information
where people won't look for it. Moreover, the point of config.sgml
is to describe all the configuration parameters in one place. We do not
need to have people second-guessing that decision for random subsets
of the parameters.regards, tom lane
---------------------------(end of broadcast)---------------------------
TIP 7: You can help support the PostgreSQL project by donating at
--
Bruce Momjian bruce@momjian.us
EnterpriseDB http://www.enterprisedb.com
+ If your life is a hard drive, Christ can be your backup. +
Oh, seems like Tom got it into CVS. Good.
---------------------------------------------------------------------------
Simon Riggs wrote:
Enclose new trace.sgml file as discussed on -docs.
This includes some heavily rewritten words and mostly verbatim programs
from http://blogs.sun.com/robertlor/entry/user_level_dtrace_probes_in,
as invited to do by Josh Berkus and Robert Lor on 27 Nov in private
correspondence prior to my post on -docs. There is substantial
additional material as well as genericisation so it is suitable for
inclusion in general docs.This includes refactoring of some of the trace related GUC docs from
config.sgml, so its all in the one place.SGML is clean apart from two xrefs that don't work properly:
openjade:config.sgml:4412:23:X: reference to non-existent ID
"TRACE-CONFIG-DEVELOPER"
openjade:wal.sgml:292:31:X: reference to non-existent ID "GUC-WAL-DEBUG"
openjade:/usr/share/sgml/docbook/dsssl-stylesheets/html/dblink.dsl:203:1:E: XRef LinkEnd to missing ID 'TRACE-CONFIG-DEVELOPER'
openjade:/usr/share/sgml/docbook/dsssl-stylesheets/html/dblink.dsl:203:1:E: XRef LinkEnd to missing ID 'GUC-WAL-DEBUG'Quick fixes?
(I haven't proof-read the resulting .html as a result of the above
error, but seems like y'all would want to see this anyway).--
Simon Riggs
EnterpriseDB http://www.enterprisedb.com
[ Attachment, skipping... ]
[ Attachment, skipping... ]
---------------------------(end of broadcast)---------------------------
TIP 5: don't forget to increase your free space map settings
--
Bruce Momjian bruce@momjian.us
EnterpriseDB http://www.enterprisedb.com
+ If your life is a hard drive, Christ can be your backup. +
Simon Riggs wrote:
Enclose new trace.sgml file as discussed on -docs.
I have a question here, regarding this:
To include DTrace support in a 64-bit binary, specify --enable-dtrace
and DTRACEFLAGS="-64" to configure.
The dtrace documentation says that dtrace automatically picks the right
build environment. Something is wrong here. Either the dtrace
documentation or ours.
--
Peter Eisentraut
http://developer.postgresql.org/~petere/
On Sat, 2006-12-02 at 09:43 +0100, Peter Eisentraut wrote:
Simon Riggs wrote:
Enclose new trace.sgml file as discussed on -docs.
I have a question here, regarding this:
To include DTrace support in a 64-bit binary, specify --enable-dtrace
and DTRACEFLAGS="-64" to configure.The dtrace documentation says that dtrace automatically picks the right
build environment. Something is wrong here. Either the dtrace
documentation or ours.
I didn't presume to question Robert's technical notes
http://blogs.sun.com/robertlor/entry/user_level_dtrace_probes_in
Robert, Can you throw any light on this? Or do you have any further
comments on the docs?
http://developer.postgresql.org/pgdocs/postgres/dynamic-trace.html
--
Simon Riggs
EnterpriseDB http://www.enterprisedb.com
Simon Riggs napsal(a):
On Sat, 2006-12-02 at 09:43 +0100, Peter Eisentraut wrote:
Simon Riggs wrote:
Enclose new trace.sgml file as discussed on -docs.
I have a question here, regarding this:
To include DTrace support in a 64-bit binary, specify --enable-dtrace
and DTRACEFLAGS="-64" to configure.The dtrace documentation says that dtrace automatically picks the right
build environment. Something is wrong here. Either the dtrace
documentation or ours.I didn't presume to question Robert's technical notes
http://blogs.sun.com/robertlor/entry/user_level_dtrace_probes_inRobert, Can you throw any light on this? Or do you have any further
comments on the docs?
http://developer.postgresql.org/pgdocs/postgres/dynamic-trace.html
I'm not dtrace guru, but I think that main reason for 64-bit flag is
that dtrace generates header file/code for probes during preprocessing
time and it don't know nothing about compiler switch. The probe code/
data structure is different on 32/64-bit.
However, if you run dtrace script that dtrace detects automatically
"build environment" (if binary is 32 or 64bits).
Robert, please correct me if I wrong.
Zdenek
Simon Riggs wrote On 12/02/06 06:50,:
Robert, Can you throw any light on this? Or do you have any further
comments on the docs?
http://developer.postgresql.org/pgdocs/postgres/dynamic-trace.html
Here is what the dtrace man page says about the -32 and -64 flags:
The D compiler produces programs using the native data
model of the operating system kernel. You can use the
isainfo -b command to determine the current operating
system data model. If the -32 option is specified,
dtrace forces the D compiler to compile a D program
using the 32-bit data model. If the -64 option is speci-
fied, dtrace forces the D compiler to compile a D pro-
gram using the 64-bit data model. These options are typ-
ically not required as dtrace selects the native data
model as the default. The data model affects the sizes
of integer types and other language properties. D pro-
grams compiled for either data model can be executed on
both 32-bit and 64-bit kernels. The -32 and -64 options
also determine the ELF file format (ELF32 or ELF64) pro-
duced by the -G option.
In my testing on the 64 bit Solaris kernel building a 64-bit Postgres
binary, if DTRACEFLAGS="-64" is not passed to the configure script,
compilation will fail when dtrace is invoked. Based on my observation,
dtrace will default to 32-bit, but for 64-bit you have to be explicit
with DTRACEFLAGS="-64"
Simon, thanks for you help with the doc patch!
Regards,
-Robert