X-Git-Url: https://git.lttng.org/?a=blobdiff_plain;f=doc%2Fman%2Flttng-add-context.1.txt;h=8e5c2bf6403385024d1c884bf3fefd8a53bcb605;hb=dca9929532e7e1c85475ca6cb4a74b8e599cc55f;hp=512bdf154963472dff910c3dfa91ac78bf22108c;hpb=484b2a0cbefcf0c7072622a5a411ea5ed849da28;p=lttng-tools.git diff --git a/doc/man/lttng-add-context.1.txt b/doc/man/lttng-add-context.1.txt index 512bdf154..8e5c2bf64 100644 --- a/doc/man/lttng-add-context.1.txt +++ b/doc/man/lttng-add-context.1.txt @@ -1,6 +1,6 @@ lttng-add-context(1) ==================== -:revdate: 8 April 2021 +:revdate: 6 May 2021 NAME @@ -10,8 +10,8 @@ lttng-add-context - Add context fields to be recorded by LTTng SYNOPSIS -------- -Add context fields to be recorded to the LTTng event records of -one or more channels: +Add context fields to be recorded to the event records of one or more +channels: [verse] *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *add-context* @@ -27,80 +27,95 @@ List the available context field types: DESCRIPTION ----------- -The `lttng add-context` command adds one or more context fields to be -recorded to the event records of a given channel, or of all the channels -of a selected tracing session, by LTTng. +The `lttng add-context` command can: -See man:lttng-enable-channel(1) to learn more about LTTng channels. +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). -When you use the `add-context` command to add context fields for a given -channel, all the event records which LTTng writes to a sub-buffer of -that channel contain the dynamic values of those context fields. +With the option:--channel='CHANNEL'::: + The channel named 'CHANNEL'. -Without the option:--session option, the `add-context` command selects -the current tracing session (see man:lttng-create(1) and -man:lttng-set-session(1) to learn more about the current tracing -session). +Without the option:--channel option::: + *All* the channels of the selected tracing session. -Without the option:--channel option, LTTng adds context fields to be -recorded to the event records of *all* the channels of the selected -tracing session. +With the option:--list option:: + List the available context field types. -Repeat the option:--type option to add more than one context field to be -recorded. +See man:lttng-concepts(7) to learn more about tracing sessions and +channels. -perf counter context fields are available: +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:`. + Prefix: `perf:cpu:` + -Only available for Linux kernel (option:--kernel option) channels. +Only available with the option:--kernel option. Per-thread:: - Prefix: `perf:thread:`. + Prefix: `perf:thread:` + -Only available for user application/library (option:--userspace, -option:--jul, and option:--log4j options) channels. - -Add PMU counter context fields by raw ID with the -++perf:cpu:raw:r++__N__++:++__NAME__ (Linux kernel tracing domain) or -++perf:thread:raw:r++__N__++:++__NAME__ (user space tracing domain) -types, with: - +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 field are processor-specific. +The possible values for this part are processor-specific. 'NAME':: - Custom name to easily recognize the counter. - -Add an application-specific context field with the following syntax: + Custom name to identify the counter. +-- +* An LTTng application-specific context field name: ++ +-- [verse] $app.'PROVIDER':__TYPE__ - ++ 'PROVIDER':: Provider name. 'TYPE':: Context type name. +-- ++ +Only available with the option:--jul and option:--log4j options. -NOTE: Make sure to **single-quote** the argument of the option:--type -option when you run the `add-context` command from a shell, as `$` is a -special character for variable substitution in most shells. +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. -List the available context field types with the option:--list option and -without other arguments. +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. -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. +See the <> section below for usage examples. -include::common-cmd-options-head.txt[] +include::common-lttng-cmd-options-head.txt[] Tracing domain @@ -151,14 +166,70 @@ option:-t 'TYPE', option:--type='TYPE':: Repeat this option to add more than one context field. -include::common-cmd-help-options.txt[] +include::common-lttng-cmd-help-options.txt[] + + +include::common-lttng-cmd-after-options.txt[] + + +[[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 +---- +==== + +.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 -------- man:lttng(1), man:lttng-enable-channel(1), -man:lttng-set-session(1) +man:lttng-concepts(7)