Differential D41745 Diff 132575 cddl/contrib/opensolaris/cmd/dtrace/dtrace.1

Changeset View

Standalone View

cddl/contrib/opensolaris/cmd/dtrace/dtrace.1

.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE. .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.

.\" If applicable, add the following below this CDDL HEADER, with the .\" If applicable, add the following below this CDDL HEADER, with the

.\" fields enclosed by brackets "[]" replaced with your own identifying .\" fields enclosed by brackets "[]" replaced with your own identifying

.\" information: Portions Copyright [yyyy] [name of copyright owner] .\" information: Portions Copyright [yyyy] [name of copyright owner]

.\" .\"

.\" CDDL HEADER END .\" CDDL HEADER END

.\" .\"

.Dd February 24, 2023 .\" $FreeBSD$

.\"

.Dd September 8, 2023

.Dt DTRACE 1 .Dt DTRACE 1

.Os .Os

.Sh NAME .Sh NAME

.Nm dtrace .Nm dtrace

.Nd dynamic tracing compiler and tracing utility .Nd dynamic tracing compiler and tracing utility

.Sh SYNOPSIS .Sh SYNOPSIS

.Nm .Nm

.Op Fl 32 | Fl 64 .Op Fl 32 | Fl 64

.Op Fl aACdeFGhHlqSvVwZ .Op Fl aACdeFGhHlOqSvVwZ

.Op Fl -libxo

.Op Fl b Ar bufsz .Op Fl b Ar bufsz

.Op Fl c Ar cmd .Op Fl c Ar cmd

.Op Fl D Ar name Op Ns = Ns value .Op Fl D Ar name Op Ns = Ns value

.Op Fl I Ar path .Op Fl I Ar path

.Op Fl L Ar path .Op Fl L Ar path

.Op Fl o Ar output .Op Fl o Ar output

.Op Fl s Ar script .Op Fl s Ar script

.Op Fl U Ar name .Op Fl U Ar name

▲ Show 20 Lines • Show All 311 Lines • ▼ Show 20 Lines

Add the specified directory Add the specified directory

.Ar path .Ar path

to the search path for DTrace libraries. to the search path for DTrace libraries.

DTrace libraries are used to contain common definitions that can be used when DTrace libraries are used to contain common definitions that can be used when

writing D programs. writing D programs.

The specified The specified

.Ar path .Ar path

is added after the default library search path. is added after the default library search path.

.It Fl -libxo

markjUnsubmitted

Done

Does this line do anything?

markj: Does this line do anything?

Generate output via

.Xr libxo 3 .

This option is the same as specifying

.Sy oformat .

.It Fl m Oo Ar provider : Oc Ar module Oo Oo Ar predicate Oc Ar action Oc .It Fl m Oo Ar provider : Oc Ar module Oo Oo Ar predicate Oc Ar action Oc

Specify module name to trace or list Specify module name to trace or list

.Fl ( l .Fl ( l

option). option).

The corresponding argument can include any of the probe description forms The corresponding argument can include any of the probe description forms

.Ar provider:module .Ar provider:module

or or

.Ar module . .Ar module .

Show All 27 Lines

.Ar name .Ar name

are matched. are matched.

The The

.Fl n .Fl n

argument can be suffixed with an optional D probe clause. argument can be suffixed with an optional D probe clause.

More than one More than one

.Fl n .Fl n

option can be specified on the command line at a time. option can be specified on the command line at a time.

.It Fl O

This option causes

.Nm

to print all the aggregations upon exiting if

.Sy oformat

.Fl -libxo

are specified.

.It Fl o Ar output .It Fl o Ar output

Specify the Specify the

.Ar output .Ar output

file for the file for the

.Fl A , G , .Fl A , G ,

and and

.Fl l .Fl l

options, or for the traced data itself. options, or for the traced data itself.

▲ Show 20 Lines • Show All 219 Lines • ▼ Show 20 Lines

.It Sy libdir Ns = Ns Ar path .It Sy libdir Ns = Ns Ar path

Add a directory to the system library path. Add a directory to the system library path.

.It Sy nspec Ns = Ns Ar scalar .It Sy nspec Ns = Ns Ar scalar

Number of speculations. Number of speculations.

.It Sy nolibs .It Sy nolibs

Do not load D system libraries. Do not load D system libraries.

.It Sy quiet .It Sy quiet

Set quiet mode. Set quiet mode.

Same as the Same as the

philUnsubmitted

Done

Would you consider changing "none" to "text"? This will keep the terminology in sync with libxo.

And it allow you to pass the string directly to libxo via xo_set_options(), which means you can say:

-x oformat=json,pretty

Assuming that you are wanting all output from dtrace to be in this format, calling xo_parse_args and letting it handle the arguments will be more in line with the other commands that support libxo, so that would be my preference.

On the other you'll want to support "-o file", which should leave the normal terminal output in text and only change the output format for the output file.

I'd suggest perhaps you do want both, where "-x oformat-XXX" and --libxo XXX are identical unless the -o flag is passed, in which case you want "-x" to affect the output file and "--libxo" options to affect the terminal. Would that make sense?

phil: Would you consider changing "none" to "text"? This will keep the terminology in sync with…

domagoj.stolfa_gmail.comAuthorUnsubmitted

Done

I will make the change from "none" to "text" and use xo_set_options(), this should clean the code up quite a bit.

As for --libxo, I've been trying to "hide" libxo from dtrace(1) itself because all the changes are essentially in libdtrace so dtrace(1) itself doesn't really care what formatting library is being used, it just cares that libdtrace is somehow formatting the data in a structured way. I'm not really sure if this is the best approach, but I do feel that attempting to decouple dtrace(1) which is a DTrace consumer and libdtrace itself with new features is worthwhile in order to encourage people to build other consumers rather than just invoking dtrace(1) for convenience sake.

WDYT @markj, @phil?

domagoj.stolfa_gmail.com: I will make the change from "none" to "text" and use `xo_set_options()`, this should clean the…

philUnsubmitted

Done

I can see trying to limit the deep knowledge of libxo from the code, but I want to be able to maximize the benefits of moving to libxo. It's a balance.

And the "--libxo" argument is a bit ugly; I did it just to avoid breaking anything while giving consistent behavior. So having the same behavior under "-x oformat=XXX" makes some sense, but I'd support --libxo for consistency.

phil: I can see trying to limit the deep knowledge of libxo from the code, but I want to be able to…

domagoj.stolfa_gmail.comAuthorUnsubmitted

Done

That sounds good to me. I don't take a strong view one way or the other, so I'll add it for consistency in the next diff.

domagoj.stolfa_gmail.com: That sounds good to me. I don't take a strong view one way or the other, so I'll add it for…

.Fl q .Fl q

flag. flag.

.It Sy specsize Ns = Ns Ar size .It Sy specsize Ns = Ns Ar size

markjUnsubmitted

Done

We should xref libxo somewhere here.

markj: We should xref libxo somewhere here.

philUnsubmitted

Not Done

I have a new "libxo(7)" documentation that will contain user-oriented documentation:

https://github.com/Juniper/libxo/blob/develop/libxo/libxo.7

This will appear on my new import.

phil: I have a new "libxo(7)" documentation that will contain user-oriented documentation: https…

Size of the speculation buffer. Size of the speculation buffer.

.It Sy strsize Ns = Ns Ar size .It Sy strsize Ns = Ns Ar size

Maximum size of strings. Maximum size of strings.

.It Sy stackframes Ns = Ns Ar scalar .It Sy stackframes Ns = Ns Ar scalar

Maximum number of kernelspace stack frames to unwind when executing the Maximum number of kernelspace stack frames to unwind when executing the

.Fn stack .Fn stack

action. action.

.It Sy stackindent Ns = Ns Ar scalar .It Sy stackindent Ns = Ns Ar scalar

Number of whitespace characters to use when indenting Number of whitespace characters to use when indenting

.Fn stack .Fn stack

and and

.Fn ustack .Fn ustack

output. output.

.It Sy oformat Ns = Ns Ar format

Specify the format to use for output.

Setting

.Sy oformat

markjUnsubmitted

Done

.Sy oformat

- to text makes

+ to

+ .Ql text

+ makes

.Nm

use regular human-readable output.

markj:

.Ql text

makes

markjUnsubmitted

Done

This is just the default behaviour, right?

markj: This is just the default behaviour, right?

.Nm

use regular human-readable output which is its default behavior.

The options passed to

.Sy oformat

are directly forwarded to

markjUnsubmitted

Done

The acronyms should be capitalized, or quoted if you're referring to them as libxo options.

markj: The acronyms should be capitalized, or quoted if you're referring to them as libxo options.

.Xr libxo 3 .

markjUnsubmitted

Done

Some of the supported formatters include json, xml and html.

- Note that specifying this option will cause

+ Note that this option will cause

.Nm

to not produce any output unless printing functions are explicitly called

markj:

Some of the supported formatters include

.Ql json ,

markjUnsubmitted

Done

Note that specifying this option will cause

.Nm

- to not produce any output unless printing functions are explicitly called

+ to not produce any output unless printing functions are explicitly called,

or the

markj:

.Ql xml

and

.Ql html .

Note that this option will cause

.Nm

to not produce any output unless printing functions are explicitly called,

or the

.Fl O

flag is specified.

For more information see

.Sx STRUCTURED OUTPUT .

.It Sy statusrate Ns = Ns Ar time .It Sy statusrate Ns = Ns Ar time

Rate of status checking. Rate of status checking.

.It Sy switchrate Ns = Ns Ar time .It Sy switchrate Ns = Ns Ar time

Rate of buffer switching. Rate of buffer switching.

.It Sy syslibdir Ns = Ns Ar path .It Sy syslibdir Ns = Ns Ar path

Path to system libraries. Path to system libraries.

Defaults to Defaults to

.Pa /usr/lib/dtrace . .Pa /usr/lib/dtrace .

▲ Show 20 Lines • Show All 110 Lines • ▼ Show 20 Lines

files files

.Fl ( s .Fl ( s

option) or on the command line option) or on the command line

.Fl ( P , m , f , n , .Fl ( P , m , f , n ,

or or

.Fl i .Fl i

options) contain descriptions that do not match any known probes. options) contain descriptions that do not match any known probes.

.El .El

.Sh STRUCTURED OUTPUT

.Nm

supports structured output using

.Xr libxo 3 .

The output will always have a top-level object called

markjUnsubmitted

Done

.Xr libxo 3 .

- The structure of the output is always going to have a top-level object called

+ The output will always have a top-level object called

"dtrace", followed by a list of objects "probes".

markj:

.Dq dtrace ,

markjUnsubmitted

Done

Please use the .Ql or .Dq macros for quoted words.

markj: Please use the .Ql or .Dq macros for quoted words.

followed by a list of objects

markjUnsubmitted

Done

"dtrace", followed by a list of objects "probes".

- Each of the probe objects is going to have a timestamp which is generated at

+ Each of the probe objects will have a timestamp which is generated at

output time rather than probe firing time, the CPU identifier which the probe

markj:

.Dq probes .

markjUnsubmitted

Done

"an identifier for the CPU on which the probe was executed"

markj: "an identifier for the CPU on which the probe was executed"

Each of the probe objects will to have a timestamp which is generated at

markjUnsubmitted

Done

What is "it"?

markj: What is "it"?

markjUnsubmitted

Done

output time rather than probe firing time, the CPU identifier which the probe

- was executed on and its full specification:

+ was executed on, and its full specification:

.Bd -literal

markj:

output time rather than probe firing time, an identifier for the CPU on

which the probe was executed, and the probe's full specification:

.Bd -literal

{

"dtrace": {

"probes": [

{

"timestamp": ...,

"cpu": ...,

"id": ...,

"provider": ...,

"module": ...,

"function": ...,

"name": ...,

markjUnsubmitted

Done

"output": [

- ... (script specific)

+ ... (script-specific output)

]

}

]

markj:

"output": [

... (script-specific output)

]

}

]

}

<?xml version="1.0"?>

markjUnsubmitted

Done

- ... (script specific)

+ ... (script-specific output)

</output>

markj:

... (script-specific output)

</output>

</probes>

</dtrace>

.Ed

markjUnsubmitted

Done

</dtrace>

.Ed

.Pp

- It is also possible to see XML output take the following form if some

+ It is also possible for XML output to take the following form if some

of the fields are empty (in this example, module and function values

markj:

.Pp

It is also possible for XML output to take the following form if some

of the fields are empty (in this example, module and function values

are absent):

.Bd -literal

<?xml version="1.0"?>

...

...

markjUnsubmitted

Done

- ... (script specific)

+ ... (script-specific output)

</output>

markj:

... (script-specific output)

</output>

</probes>

</dtrace>

.Ed

.Pp

Similarly,

.Sy oformat

can be used to generate HTML:

.Bd -literal

markjUnsubmitted

Done

- <div class="data" data-tag="... (script specific)">...</div>

+ <div class="data" data-tag="... (script-specific)">...</div>

</div>

markj:

</div>

.Ed

.Pp

Unlike JSON and XML, the

.Dq output

array is not present.

markjUnsubmitted

Done

data-tag is associated with each of the keys.

.Pp

- The "output" array's contents depend on the probes' actions and are

+ The "output" array's contents depend on the probes' actions and is

explained below.

markj:

Instead, data is simply formatted into a div of class

.Dq data

and a data-tag is associated with each of the keys.

.Pp

markjUnsubmitted

Done

"applies for all output formats."

markj: "applies for all output formats."

The

.Dq output

array's contents depend on the probes' actions and is explained below.

The examples here are presented in JSON form as opposed to XML or HTML,

however the conversion explained above applies for all output formats.

.Pp

Any scalar output, such as output produced by the

.Fn trace

action is of form:

.Bd -literal

{

"value": ...

}

markjUnsubmitted

Done

.Fn printf

- action begins with an object containing the evaluated message of the

+ action begins with an object containing the formatted output of the

.Fn printf

markj:

.Ed

.Pp

The

markjUnsubmitted

Done

action.

- Every consecutive object contains the value of each of the arguments to

+ Subsequent objects contain the value of each of the arguments to

.Fn printf

markj:

.Fn printf

action begins with an object containing the formatted output of the

.Fn printf

action.

Subsequent objects contains the value of each of the arguments to

.Fn printf

in its raw form as if the

.Fn trace

action was used instead.

.Fn printf

statement which contains no arguments other than the message will only have

one object following the message object and its value will always be 0.

This is an artefact of the implementation and can safely be ignored.

.Bd -literal

# dtrace --libxo json,pretty -n 'BEGIN { printf("... %Y, ..", walltimestamp); }'

{

"message": "... 2023 Sep 7 16:49:02, .."

markjUnsubmitted

Done

This example should include the corresponding printf() statement.

markj: This example should include the corresponding printf() statement.

{

"value": 1694105342633402400

markjUnsubmitted

Done

"for a given key."

markj: "for a given key."

{

...

}

.Ed

.Pp

Scalar aggregations are aggregations which produce a single value for a given

key.

These aggregations include

markjUnsubmitted

Done

.Fn sum .

- Each one of them is represented with the key containing their name being

+ Each one of them is represented by the key containing their name being

present.

I think you can remove "being present".

markj: I think you can remove "being present".

.Fn count ,

.Fn min ,

.Fn max ,

.Fn stddev

and

.Fn sum .

Each one of them is represented by the key containing their name.

For example, the output of a

.Fn stddev

aggregation will contain a key

.Dq stddev

inside an

.Dq aggregation-data

object:

.Bd -literal

{

"aggregation-data": [

{

"keys": [

...

"stddev": ...

}

"aggregation-name": ...

}

markjUnsubmitted

Done

This sentence and the previous sentence are saying more or less the same thing.

markj: This sentence and the previous sentence are saying more or less the same thing.

.Ed

.Pp

The

.Dq keys

field remains consistent across all aggregations, however

.Fn quantize ,

.Fn lquantize

and

.Fn llquantize

need to be treated differently.

.Sy oformat

will create a new array of objects called

.Dq buckets .

Each of the objects contains a

.Dq value

and a

.Dq count

field which are

the left-hand side and the right-hand side of human-readable

.Nm

output respectively.

The full object has the following format:

.Bd -literal

{

"aggregation-data": [

...

{

"keys": [

...

"buckets": [

{

"value": 32,

"count": 0

{

"value": 64,

"count": 17

...

]

"aggregation-name": ...

}

.Ed

.Pp

Similar to scalar aggregations, named scalar actions such as

.Fn mod ,

.Fn umod ,

.Fn usym ,

.Fn tracemem

and

.Fn printm

will output an object with the key being equal to the

name of the action.

For example,

.Fn printm

output would produce the following object:

.Bd -literal

{

"printm": "0x4054171100"

}

.Ed

.Pp

markjUnsubmitted

Done

Including the D source would be helpful here.

markj: Including the D source would be helpful here.

.Fn sym

is slightly different.

While it will create a

.Dq sym

field which contains its value, in some cases it will also create additional

fields

.Dq object ,

.Dq name

and

.Dq offset :

.Bd -literal

# dtrace -x oformat=json,pretty -On 'BEGIN { sym((uintptr_t)&`prison0); }'

{

"sym": "kernel`prison0",

"object": "kernel",

"name": "prison0"

}

# dtrace --libxo json,pretty -On 'BEGIN { sym((uintptr_t)curthread); }'

{

"sym": "0xfffffe00c18d2000",

"offset": "0xfffffe00c18d2000"

}

.Ed

.Pp

.Fn stack

and

.Fn ustack

actions unroll each of the stack frames into its own object in an array.

The only real difference between them is that the

.Fn stack

action will produce a list called

.Dq stack-frames

while

.Fn ustack

will produce one called

.Dq ustack-frames .

The following is an example of their

.Sy oformat

output:

.Bd -literal

{

"stack-frames": [

{

"symbol": "dtrace.ko`dtrace_dof_create+0x35",

"module": "dtrace.ko",

"name": "dtrace_dof_create",

"offset": "0x35"

{

"symbol": "dtrace.ko`dtrace_ioctl+0x81c",

"module": "dtrace.ko",

"name": "dtrace_ioctl",

"offset": "0x81c"

...

]

}

{

"ustack-frames": [

{

"symbol": "libc.so.7`ioctl+0xa",

"module": "libc.so.7",

"name": "ioctl",

"offset": "0xa"

{

"symbol": "libdtrace.so.2`dtrace_go+0xf3",

"module": "libdtrace.so.2",

"name": "dtrace_go",

"offset": "0xf3"

...

]

}

.Ed

.Pp

The

.Fn print

action produces a

.Dq type

list in the following form:

.Bd -literal

{

"type": [

{

"object-name": "kernel",

"name": "struct thread",

"ctfid": 2372

{

"member-name": "td_lock",

"name": "struct mtx *volatile",

"ctfid": 2035,

"value": "0xffffffff82158440"

...

}

.Ed

.Pp

If the type is invalid, a

.Dq warning

object will be produced containing the diagnostic message as well as two

possible optional fields:

.Dq type-identifier

which contains the CTF identifier of the type and

.Dq size containing the size of an integer, enum or float.

The fields generated will depend on the kind of error that was encountered

while processing the trace data.

.Pp

Finally,

.Sy oformat

provides a special pseudo-probe to represent drops.

.Nm

polls for various kinds of drops

.Sy oformat

will produce output similar to the following in order to represent drops:

.Bd -literal

{

"cpu": -1,

"id": -1,

"provider": "dtrace",

"module": "INTERNAL",

"function": "INTERNAL",

"name": "DROP",

"timestamp": ...,

"count": ...,

"total": ...,

"kind": 2,

"msg": "... dynamic variable drops\n"

}

.Ed

.Sh OPERANDS .Sh OPERANDS

You can specify zero or more additional arguments on the You can specify zero or more additional arguments on the

.Nm .Nm

command line to define a set of macro variables and so forth). command line to define a set of macro variables and so forth).

The additional arguments can be used in D programs specified using the The additional arguments can be used in D programs specified using the

.Fl s .Fl s

option or on the command line. option or on the command line.

.Sh FILES .Sh FILES

Show All 35 Lines