X-Git-Url: https://git.lttng.org/?a=blobdiff_plain;f=doc%2Fman%2Flttng-add-context.1.txt;h=8e5c2bf6403385024d1c884bf3fefd8a53bcb605;hb=dca9929532e7e1c85475ca6cb4a74b8e599cc55f;hp=529a7da26478f15891d002c29e666ad29b7bbd48;hpb=d1cff33724d92f0637853acb81d694532fb97b4b;p=lttng-tools.git diff --git a/doc/man/lttng-add-context.1.txt b/doc/man/lttng-add-context.1.txt index 529a7da26..8e5c2bf64 100644 --- a/doc/man/lttng-add-context.1.txt +++ b/doc/man/lttng-add-context.1.txt @@ -1,15 +1,17 @@ lttng-add-context(1) ==================== +:revdate: 6 May 2021 NAME ---- -lttng-add-context - Add context fields to an LTTng channel +lttng-add-context - Add context fields to be recorded by LTTng SYNOPSIS -------- -Add context fields to a channel: +Add context fields to be recorded to the event records of one or more +channels: [verse] *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *add-context* @@ -17,7 +19,7 @@ Add context fields to a channel: [option:--session='SESSION'] [option:--channel='CHANNEL'] option:--type='TYPE' [option:--type='TYPE']... -List the available context fields: +List the available context field types: [verse] *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *add-context* option:--list @@ -25,95 +27,209 @@ List the available context fields: DESCRIPTION ----------- -The `lttng add-context` command adds one or more context fields to a -channel. - -Channels are created with the linklttng:lttng-enable-channel(1) command. - -When context fields are added to a channel, all the events emitted -within this channel contain the dynamic values of those context fields. - -If the option:--session option is omitted, the current tracing session -is used. If the option:--channel option is omitted, the context fields -are added to all the selected tracing session's channels. - -Many context fields can be added to a channel at once by repeating the -option:--type option. - -perf counters are available as per-CPU (`perf:cpu:` prefix) as well as -per-thread (`perf:thread:` prefix) counters. Currently, per-CPU counters -can only be used in the Linux kernel tracing domain, while per-thread -counters can only be used in the user space tracing domain. - -Application-specific context fields can be added to a channel using the -following syntax: - +The `lttng add-context` command can: + +Without the option:--list option:: + Add one or more context fields to be recorded by LTTng to the event + records of: ++ +With the option:--session='SESSION' option::: + The tracing session named 'SESSION'. + +Without the option:--session option::: + The current tracing session (see man:lttng-concepts(7) to learn more + about the current tracing session). + +With the option:--channel='CHANNEL'::: + The channel named 'CHANNEL'. + +Without the option:--channel option::: + *All* the channels of the selected tracing session. + +With the option:--list option:: + List the available context field types. + +See man:lttng-concepts(7) to learn more about tracing sessions and +channels. + +Repeat the option:--type='TYPE' option to add more than one context +field to be recorded. 'TYPE' is one of: + +* A statically-known, or built-in context field named. + +* A perf counter name: ++ +-- +Per-CPU:: + Prefix: `perf:cpu:` ++ +Only available with the option:--kernel option. + +Per-thread:: + Prefix: `perf:thread:` ++ +Only available with the option:--userspace, option:--jul, or +option:--log4j option. +-- ++ +Add Performance Monitoring Unit (PMU) counter context fields by raw ID +with the ++perf:cpu:raw:r++__N__++:++__NAME__ (option:--kernel option) +or ++perf:thread:raw:r++__N__++:++__NAME__ (option:--userspace, +option:--jul, or option:--log4j option) types, with: ++ +-- +'N':: + A hexadecimal event descriptor which follows the man:perf-record(1) + format: a concatenation of the event number and umask value which + the manufacturer of the processor provides. ++ +The possible values for this part are processor-specific. + +'NAME':: + Custom name to identify the counter. +-- + +* An LTTng application-specific context field name: ++ +-- [verse] $app.'PROVIDER':__TYPE__ - -with: - ++ 'PROVIDER':: Provider name. 'TYPE':: Context type name. +-- ++ +Only available with the option:--jul and option:--log4j options. + +IMPORTANT: Make sure to **single-quote** 'TYPE' when you run the +`add-context` command from a shell, as `$` is a special character for +variable substitution in most shells. -NOTE: Make sure to **single-quote** the type when running the command -from a shell, as `$` is a special character for variable substitution in -most shells. +NOTE: As of LTTng{nbsp}{lttng_version}, you may :not: add context fields +to be recorded to the event records of a given channel once its tracing +session has been started (see man:lttng-start(1)) at least once. -Use the option:--list option without other arguments to list the -available context field names. +See the <> section below for usage examples. -include::common-cmd-options-head.txt[] +include::common-lttng-cmd-options-head.txt[] -Domain -~~~~~~ +Tracing domain +~~~~~~~~~~~~~~ One of: option:-j, option:--jul:: - Add context to channel in the `java.util.logging` (JUL) domain. + Add context fields to be recorded to the event records of one or + more channels of the `java.util.logging` (JUL) tracing domain. option:-k, option:--kernel:: - Add context to channel in the Linux kernel domain. + Add context fields to be recorded to the event records of one or + more channels of the Linux kernel tracing domain. option:-l, option:--log4j:: - Add context to channel in the Apache log4j domain. + Add context fields to be recorded to the event records of one or + more channels of the Apache log4j tracing domain. option:-u, option:--userspace:: - Add context to channel in the user space domain. + Add context fields to be recorded to the event records of one or + more channels of the user space tracing domain. -Target -~~~~~~ -option:-c, option:--channel='CHANNEL':: - Add context fields to a channel named 'CHANNEL' instead of adding - them to all the channels. +Recording target +~~~~~~~~~~~~~~~~ +option:-c 'CHANNEL', option:--channel='CHANNEL':: + Add context fields to be recorded to the event records of a channel + named 'CHANNEL' instead of all the channels of the selected + tracing session. -option:-s, option:--session='SESSION':: - Add context fields to a channel in the tracing session named 'SESSION' - instead of the current tracing session. +option:-s 'SESSION', option:--session='SESSION':: + Add context fields to be recorded to the event records of one or + more channels of the tracing session named 'SESSION' instead of the + current tracing session. -Context -~~~~~~~ +Context field type +~~~~~~~~~~~~~~~~~~ option:--list:: - List the available context fields. Use this option alone. + List the available context field types. ++ +You may :not: use this option with the option:--channel, +option:--session, or option:--type options. + +option:-t 'TYPE', option:--type='TYPE':: + Add a context field having the type 'TYPE' to be recorded. ++ +Repeat this option to add more than one context field. + + +include::common-lttng-cmd-help-options.txt[] + + +include::common-lttng-cmd-after-options.txt[] + -option:-t, option:--type='TYPE':: - Add context field named 'TYPE'. This option can be repeated as - many times as needed on the command-line. +[[examples]] +EXAMPLES +-------- +.List the available context field types. +==== +See the option:--list option. + +[role="term"] +---- +$ lttng add-context --list +---- +==== + +.Add a single statically-known context field to be recorded to all the Linux kernel channels of the current tracing session. +==== +[role="term"] +---- +$ lttng add-context --kernel --type=pid +---- +==== + +.Add three statically-known context fields to be recorded to a specific user space channel of a specific tracing session. +==== +See the option:--session and option:--channel options. +[role="term"] +---- +$ lttng add-context --userspace --session=my-session \ + --channel=my-channel \ + --type=vpid --type=procname --type=ip +---- +==== + +.Add a perf counter context field to be recorded to a specific Linux kernel channel of the current tracing session. +==== +See the option:--channel option. + +[role="term"] +---- +$ lttng add-context --kernel --channel=my-channel \ + --type=perf:cpu:cache-misses +---- +==== -include::common-cmd-help-options.txt[] +.Add an LTTng application-specific context field to be recorded to all the JUL channels of the current tracing session. +==== +[role="term"] +---- +$ lttng add-context --jul --type='$app.my_server:user_cnt' +---- +==== -include::common-cmd-footer.txt[] +include::common-footer.txt[] SEE ALSO -------- -linklttng:lttng(1) +man:lttng(1), +man:lttng-enable-channel(1), +man:lttng-concepts(7)