Re: 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

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(at)2ndquadrant(dot)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(at)2ndquadrant(dot)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(at)2ndquadrant(dot)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(at)2ndquadrant(dot)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(at)2ndquadrant(dot)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(at)2ndquadrant(dot)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(at)2ndquadrant(dot)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
>
> http://www.postgresql.org/about/donate

--
Bruce Momjian bruce(at)momjian(dot)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(at)momjian(dot)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_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
>

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