/
lttng-enable-event.1.txt
950 lines (791 loc) · 29.8 KB
/
lttng-enable-event.1.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
lttng-enable-event(1)
=====================
:revdate: 14 June 2021
NAME
----
lttng-enable-event - Create or enable LTTng recording event rules
SYNOPSIS
--------
Create or enable one or more recording event rules to match Linux kernel
tracepoint or system call events:
[verse]
*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-event* option:--kernel [option:--tracepoint | option:--syscall]
(option:--all | 'NAME'[,'NAME']...) [option:--filter='EXPR']
[option:--session='SESSION'] [option:--channel='CHANNEL']
Create or enable a recording event rule to match Linux kernel events
created from a dynamic instrumentation point:
[verse]
*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-event* option:--kernel
(option:--probe='LOC' | option:--function='LOC' | option:--userspace-probe='LOC') 'RECORDNAME'
[option:--session='SESSION'] [option:--channel='CHANNEL']
Create or enable one or more recording event rules to match
user space tracepoint events:
[verse]
*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-event* option:--userspace [option:--tracepoint]
(option:--all | 'NAME'[,'NAME']...) [option:--exclude='XNAME'[,'XNAME']...]
[option:--loglevel='LOGLEVEL' | option:--loglevel-only='LOGLEVEL'] [option:--filter='EXPR']
[option:--session='SESSION'] [option:--channel='CHANNEL']
Create or enable one or more recording event rules to match
Java/Python logging events:
[verse]
*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-event* (option:--jul | option:--log4j | option:--python)
[option:--tracepoint] (option:--all | 'NAME'[,'NAME']...)
[option:--loglevel='LOGLEVEL' | option:--loglevel-only='LOGLEVEL'] [option:--filter='EXPR']
[option:--session='SESSION'] [option:--channel='CHANNEL']
DESCRIPTION
-----------
The `lttng enable-event` command does one of:
* Create one or more recording event rules.
* Enable one or more disabled recording event rules.
+
See the ``<<enable,Enable a disabled recording event rule>>'' section
below.
See man:lttng-concepts(7) to learn more about instrumentation points,
events, recording event rules, and event records.
The recording event rule(s) to create or enable belong to:
With the option:--session='SESSION' option::
The recording session named 'SESSION'.
Without the option:--session option::
The current recording session (see man:lttng-concepts(7) to learn
more about the current recording session).
With the option:--channel='CHANNEL' option::
The channel named 'CHANNEL'.
Without the option:--channel option::
The channel named `channel0`.
+
If there's already a channel for the selected recording session and
domain which isn't named `channel0`, the `enable-event` command fails.
Otherwise, it automatically creates it.
See the ``<<examples,EXAMPLES>>'' section below for usage examples.
List the recording event rules of a specific recording session
and/or channel with the man:lttng-list(1) and man:lttng-status(1)
commands.
Disable an enabled recording event rule with the
man:lttng-disable-event(1) command.
Overview of recording event rule conditions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
For LTTng to emit and record an event{nbsp}__E__,{nbsp}__E__ must
satisfy *all* the conditions of a recording event rule{nbsp}__ER__, that
is:
Explicit conditions::
You set the following conditions when you create or
enable{nbsp}__ER__ with the `enable-event` command:
+
--
* The instrumentation point type from which LTTng creates{nbsp}__E__
has a specific type.
+
See the ``<<inst-point-type-cond,Instrumentation point type
condition>>'' section below.
* A pattern matches the name of{nbsp}__E__ while another pattern
doesn't.
+
See the ``<<event-name-cond,Event name condition>>'' section below.
* The log level of the instrumentation point from which LTTng
creates{nbsp}__E__ is at least as severe as some value, or is exactly
some value.
+
See the ``<<inst-point-log-level-cond,Instrumentation point log level
condition>>'' section below.
* The fields of the payload of{nbsp}__E__ and the current context fields
satisfy a filter expression.
+
See the ``<<filter-cond,Event payload and context filter condition>>''
section below.
--
Implicit conditions::
+
--
* _ER_ itself is enabled.
+
A recording event rule is enabled on creation.
+
Enable a disabled recording event rule with the `enable-event` command.
* The channel to which{nbsp}__ER__ is attached is enabled.
+
A channel is enabled on creation.
+
Enable a disabled channel with the man:lttng-enable-channel(1) command.
* The recording session of{nbsp}__ER__ is active (started).
+
A recording session is inactive (stopped) on creation.
+
Start an inactive recording session with the man:lttng-start(1) command.
* The process for which LTTng creates{nbsp}__E__ is allowed to record
events.
+
All processes are allowed to record events on recording session
creation.
+
Use the man:lttng-track(1) and man:lttng-untrack(1) commands to select
which processes are allowed to record events based on specific process
attributes.
--
The dedicated command-line options of most conditions are optional: if
you don't specify the option, the associated condition is always
satisfied.
[[inst-point-type-cond]]
Instrumentation point type condition
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
An event{nbsp}__E__ satisfies the instrumentation point type condition
of a recording event rule if the instrumentation point from which LTTng
creates{nbsp}__E__ is:
For the Linux kernel tracing domain (option:--kernel option)::
With the option:--tracepoint option or without any other instrumentation point type option:::
An LTTng kernel tracepoint, that is, a statically defined point
in the source code of the kernel image or of a kernel module
with LTTng kernel tracer macros.
+
As of LTTng{nbsp}{lttng_version}, this is the default instrumentation
point type of the Linux kernel tracing domain, but this may change in
the future.
+
List the available Linux kernel tracepoints with `lttng list --kernel`.
See man:lttng-list(1) to learn more.
With the option:--syscall option:::
The entry and exit of a Linux kernel system call.
+
List the available Linux kernel system call instrumentation points with
`lttng list --kernel --syscall`. See man:lttng-list(1) to learn more.
With the option:--probe option:::
A Linux kprobe, that is, a single probe dynamically placed in
the compiled kernel code.
+
The argument of the option:--probe option is the location of the
kprobe to insert, either a symbol or a
memory address, while 'RECORDNAME' is the name of the record
of{nbsp}__E__ (see the ``<<er-name,Event record name>>'' section below).
+
The payload of a Linux kprobe event is empty.
With the option:--userspace-probe option:::
A Linux user space probe, that is, a single probe dynamically
placed at the entry of a compiled user space application/library
function through the kernel.
+
The argument of the option:--userspace-probe option is the location
of the user space probe to insert, one of:
+
--
* A path and symbol (ELF method).
* A path, provider name, and probe name (SystemTap User-level Statically
Defined Tracing (USDT) method; a DTrace-style marker).
+
As of LTTng{nbsp}{lttng_version}, LTTng only supports USDT probes which
are :not: reference-counted.
--
+
'RECORDNAME' is the name of the record of{nbsp}__E__ (see the
``<<er-name,Event record name>>'' section below).
+
The payload of a Linux user space probe event is empty.
With the option:--function option:::
A Linux kretprobe, that is, two probes dynamically placed at the
entry and exit of a function in the compiled kernel code.
+
The argument of the option:--function option is the location of the
Linux kretprobe to insert, either a symbol or
a memory address, while 'RECORDNAME' is the name of the record
of{nbsp}__E__ (see the ``<<er-name,Event record name>>'' section below).
+
The payload of a Linux kretprobe event is empty.
For the user space tracing domain (option:--userspace option)::
With or without the option:--tracepoint option:::
An LTTng user space tracepoint, that is, a statically defined
point in the source code of a C/$$C++$$ application/library with
LTTng user space tracer macros.
+
As of LTTng{nbsp}{lttng_version}, this is the default and sole
instrumentation point type of the user space tracing domain, but this
may change in the future.
+
List the available user space tracepoints with `lttng list --userspace`.
See man:lttng-list(1) to learn more.
For the `java.util.logging` (option:--jul option), Apache log4j (option:--log4j option), and Python (option:--python option) tracing domains::
With or without the option:--tracepoint option:::
A logging statement.
+
As of LTTng{nbsp}{lttng_version}, this is the default and sole
instrumentation point type of the `java.util.logging`, Apache log4j, and
Python tracing domains, but this may change in the future.
+
List the available Java and Python loggers with `lttng list --jul`,
`lttng list --log4j`, and `lttng list --python`. See man:lttng-list(1)
to learn more.
[[event-name-cond]]
Event name condition
~~~~~~~~~~~~~~~~~~~~
An event{nbsp}__E__ satisfies the event name condition of a recording
event rule{nbsp}__ER__ if the two following statements are true:
* You specify the option:--all option or, depending on the
instrumentation type condition (see the
``<<inst-point-type-cond,Instrumentation point type condition>>''
section above) of{nbsp}__ER__, 'NAME' matches:
+
--
LTTng tracepoint::
The full name of the tracepoint from which LTTng creates{nbsp}__E__.
+
Note that the full name of a user space tracepoint is
__PROVIDER__++:++__NAME__, where __PROVIDER__ is the tracepoint provider
name and __NAME__ is the tracepoint name.
Logging statement::
The name of the Java or Python logger from which LTTng
creates{nbsp}__E__.
Linux system call::
The name of the system call, without any `sys_` prefix, from which
LTTng creates{nbsp}__E__.
--
* You don't specify the option:--exclude=__XNAME__[++,++__XNAME__]...
option or, depending on the instrumentation type condition
of{nbsp}__ER__, none of the 'XNAME' arguments matches the full name of
the user space tracepoint from which LTTng creates{nbsp}__E__.
+
The option:--exclude option is only available with the option:--userspace
option.
This condition is only meaningful for the LTTng tracepoint, logging
statement, and Linux system call instrumentation point types: it's
always satisfied for the other types.
In all cases, 'NAME' and 'XNAME' are globbing patterns: the `*`
character means ``match anything''. To match a literal `*` character,
use :escwc:. To match a literal `,` character, use
:esccomma:.
IMPORTANT: Make sure to **single-quote** 'NAME' and 'XNAME' when they
contain the `*` character and when you run the `enable-event` command
from a shell.
With the LTTng tracepoint, logging statement, and Linux system call
instrumentation point types, the `enable-event` command creates or
enables one independent recording event rule per 'NAME' argument
(non-option, comma-separated). With the option:--all option, the
`enable-event` command creates or enables a single recording event rule.
[[inst-point-log-level-cond]]
Instrumentation point log level condition
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
An event{nbsp}__E__ satisfies the instrumentation point log level
condition of a recording event rule if either:
* The option:--loglevel and option:--loglevel-only options are
missing.
* The log level of the LTTng user space tracepoint or logging statement
which creates{nbsp}__E__ is:
With the option:--loglevel='LOGLEVEL' option::
At least as severe as 'LOGLEVEL'.
With the option:--loglevel-only='LOGLEVEL' option::
Exactly 'LOGLEVEL'.
This condition is only meaningful for the LTTng user space tracepoint
and logging statement instrumentation point types: it's always satisfied
for other types.
The available values of 'LOGLEVEL' are, depending on the tracing domain,
from the most to the least severe:
User space (option:--userspace option)::
+
* `EMERG` (0)
* `ALERT` (1)
* `CRIT` (2)
* `ERR` (3)
* `WARNING` (4)
* `NOTICE` (5)
* `INFO` (6)
* `DEBUG_SYSTEM` (7)
* `DEBUG_PROGRAM` (8)
* `DEBUG_PROCESS` (9)
* `DEBUG_MODULE` (10)
* `DEBUG_UNIT` (11)
* `DEBUG_FUNCTION` (12)
* `DEBUG_LINE` (13)
* `DEBUG` (14)
`java.util.logging` (option:--jul option)::
+
* `OFF` (`INT32_MAX`)
* `SEVERE` (1000)
* `WARNING` (900)
* `INFO` (800)
* `CONFIG` (700)
* `FINE` (500)
* `FINER` (400)
* `FINEST` (300)
* `ALL` (`INT32_MIN`)
Apache log4j (option:--log4j option)::
+
* `OFF` (`INT32_MAX`)
* `FATAL` (50000)
* `ERROR` (40000)
* `WARN` (30000)
* `INFO` (20000)
* `DEBUG` (10000)
* `TRACE` (5000)
* `ALL` (`INT32_MIN`)
Python (option:--python option)::
+
* `CRITICAL` (50)
* `ERROR` (40)
* `WARNING` (30)
* `INFO` (20)
* `DEBUG` (10)
* `NOTSET` (0)
[[filter-cond]]
Event payload and context filter condition
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
An event{nbsp}__E__ satisfies the event payload and context filter
condition of a recording event rule if the option:--filter='EXPR'
option is missing or if 'EXPR' is _true_.
This condition is only meaningful for the LTTng tracepoint and Linux
system call instrumentation point types: it's always satisfied for other
types.
'EXPR' can contain references to the payload fields of{nbsp}__E__ and
to the current context fields.
IMPORTANT: Make sure to **single-quote** 'EXPR' when you run the
`enable-event` command from a shell, as filter expressions typically
include characters having a special meaning for most shells.
The expected syntax of 'EXPR' is similar to the syntax of a
C{nbsp}language conditional expression (an expression which an `if`
statement can evaluate), but there are a few differences:
* A _NAME_ expression identifies an event payload field named
_NAME_ (a C{nbsp}identifier).
+
Use the C{nbsp}language dot and square bracket notations to access
nested structure and array/sequence fields. You can only use a constant,
positive integer number within square brackets. If the index is out of
bounds, 'EXPR' is _false_.
+
The value of an enumeration field is an integer.
+
When a field expression doesn't exist, 'EXPR' is _false_.
+
Examples: `my_field`, `target_cpu`, `seq[7]`, `msg.user[1].data[2][17]`.
* A ++$ctx.++__TYPE__ expression identifies the statically-known context
field having the type _TYPE_ (a C{nbsp}identifier).
+
List the available statically-known context field names with the
man:lttng-add-context(1) command.
+
When a field expression doesn't exist, 'EXPR' is _false_.
+
Examples: `$ctx.prio`, `$ctx.preemptible`,
`$ctx.perf:cpu:stalled-cycles-frontend`.
* A ++$app.++__PROVIDER__++:++__TYPE__ expression identifies the
application-specific context field having the type _TYPE_ (a
C{nbsp}identifier) from the provider _PROVIDER_ (a C{nbsp}identifier).
+
When a field expression doesn't exist, 'EXPR' is _false_.
+
Example: `$app.server:cur_user`.
* Compare strings, either string fields or string literals
(double-quoted), with the `==` and `!=` operators.
+
When comparing to a string literal, the `*` character means ``match
anything''. To match a literal `*` character, use :escwc:.
+
Examples: `my_field == "user34"`, `my_field == my_other_field`,
`my_field == "192.168.*"`.
* The precedence table of the operators which are supported in 'EXPR'
is as follows. In this table, the highest precedence is{nbsp}1:
+
[options="header"]
|===
|Precedence |Operator |Description |Associativity
|1 |`-` |Unary minus |Right-to-left
|1 |`+` |Unary plus |Right-to-left
|1 |`!` |Logical NOT |Right-to-left
|1 |`~` |Bitwise NOT |Right-to-left
|2 |`<<` |Bitwise left shift |Left-to-right
|2 |`>>` |Bitwise right shift |Left-to-right
|3 |`&` |Bitwise AND |Left-to-right
|4 |`^` |Bitwise XOR |Left-to-right
|5 |`\|` |Bitwise OR |Left-to-right
|6 |`<` |Less than |Left-to-right
|6 |`<=` |Less than or equal to |Left-to-right
|6 |`>` |Greater than |Left-to-right
|6 |`>=` |Greater than or equal to |Left-to-right
|7 |`==` |Equal to |Left-to-right
|7 |`!=` |Not equal to |Left-to-right
|8 |`&&` |Logical AND |Left-to-right
|9 |`\|\|` |Logical OR |Left-to-right
|===
+
Parentheses are supported to bypass the default order.
+
IMPORTANT: Unlike the C{nbsp}language, the bitwise AND and OR operators
(`&` and `|`) in 'EXPR' take precedence over relational operators (`<`,
`<=`, `>`, `>=`, `==`, and `!=`). This means the expression `2 & 2 == 2`
is _true_ while the equivalent C{nbsp}expression is _false_.
+
The arithmetic operators are :not: supported.
+
LTTng first casts all integer constants and fields to signed 64-bit
integers. The representation of negative integers is two's complement.
This means that, for example, the signed 8-bit integer field 0xff (-1)
becomes 0xffffffffffffffff (still -1) once casted.
+
Before a bitwise operator is applied, LTTng casts all its operands to
unsigned 64-bit integers, and then casts the result back to a signed
64-bit integer. For the bitwise NOT operator, it's the equivalent of
this C{nbsp}expression:
+
[source,c]
----
(int64_t) ~((uint64_t) val)
----
+
For the binary bitwise operators, it's the equivalent of those
C{nbsp}expressions:
+
[source,c]
----
(int64_t) ((uint64_t) lhs >> (uint64_t) rhs)
(int64_t) ((uint64_t) lhs << (uint64_t) rhs)
(int64_t) ((uint64_t) lhs & (uint64_t) rhs)
(int64_t) ((uint64_t) lhs ^ (uint64_t) rhs)
(int64_t) ((uint64_t) lhs | (uint64_t) rhs)
----
+
If the right-hand side of a bitwise shift operator (`<<` and `>>`) is
not in the [0,{nbsp}63] range, then 'EXPR' is _false_.
[NOTE]
====
Use the man:lttng-track(1) and man:lttng-untrack(1) commands to allow or
disallow processes to record LTTng events based on their attributes
instead of using equivalent statically-known context fields in 'EXPR'
like `$ctx.pid`.
The former method is much more efficient.
====
'EXPR' examples:
----------------------------
msg_id == 23 && size >= 2048
----------------------------
-------------------------------------------------
$ctx.procname == "lttng*" && (!flag || poel < 34)
-------------------------------------------------
---------------------------------------------------------
$app.my_provider:my_context == 17.34e9 || some_enum >= 14
---------------------------------------------------------
---------------------------------------
$ctx.cpu_id == 2 && filename != "*.log"
---------------------------------------
------------------------------------------------
eax_reg & 0xff7 == 0x240 && x[4] >> 12 <= 0x1234
------------------------------------------------
[[er-name]]
Event record name
~~~~~~~~~~~~~~~~~
When LTTng records an event{nbsp}__E__, the resulting event record has a
name which depends on the instrumentation point type condition (see the
``<<inst-point-type-cond,Instrumentation point type condition>>''
section above) of the recording event rule which matched{nbsp}__E__:
LTTng tracepoint (option:--kernel/option:--userspace and option:--tracepoint options)::
Full name of the tracepoint from which LTTng creates{nbsp}__E__.
+
Note that the full name of a user space tracepoint is
__PROVIDER__++:++__NAME__, where __PROVIDER__ is the tracepoint provider
name and __NAME__ is the tracepoint name.
`java.util.logging` logging statement (option:--jul and option:--tracepoint options)::
`lttng_jul:event`
+
Such an event record has a string field `logger_name` which contains the
name of the `java.util.logging` logger from which LTTng
creates{nbsp}__E__.
Apache log4j logging statement (option:--log4j and option:--tracepoint options)::
`lttng_log4j:event`
+
Such an event record has a string field `logger_name` which contains the
name of the Apache log4j logger from which LTTng creates{nbsp}__E__.
Python logging statement (option:--python and option:--tracepoint options)::
`lttng_python:event`
+
Such an event record has a string field `logger_name` which contains the
name of the Python logger from which LTTng creates{nbsp}__E__.
Linux system call (option:--kernel and option:--syscall options)::
Entry:::
++syscall_entry_++__NAME__, where _NAME_ is the name of the
system call from which LTTng creates{nbsp}__E__, without any
`sys_` prefix.
Exit:::
++syscall_exit_++__NAME__, where _NAME_ is the name of the
system call from which LTTng creates{nbsp}__E__, without any
`sys_` prefix.
Linux kprobe (option:--kernel and option:--probe options)::
Linux user space probe (option:--kernel and option:--userspace-probe options)::
'RECORDNAME' (first non-option argument).
Linux kretprobe (option:--kernel and option:--function options)::
Entry:::
__RECORDNAME__++_entry++
Exit:::
__RECORDNAME__++_exit++
[[enable]]
Enable a disabled recording event rule
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The `enable-event` command can enable a disabled recording event rule,
as listed in the output of the man:lttng-list(1) command.
You may enable a disabled recording event rule regardless of the
activity (started or stopped) of its recording session (see
man:lttng-start(1) and man:lttng-stop(1)).
To enable a disabled recording event rule, run the `enable-event`
command with the exact same options and arguments that you used to
create it. In particular, with the option:--filter='EXPR' option, 'EXPR'
must be the exact same string as the one you used on creation.
include::common-lttng-cmd-options-head.txt[]
Tracing domain
~~~~~~~~~~~~~~
One of:
option:-j, option:--jul::
Create or enable recording event rules in the `java.util.logging`
(JUL) tracing domain.
option:-k, option:--kernel::
Create or enable recording event rules in the Linux kernel tracing
domain.
option:-l, option:--log4j::
Create or enable recording event rules in the Apache log4j tracing
domain.
option:-p, option:--python::
Create or enable recording event rules in the Python tracing domain.
option:-u, option:--userspace::
Create or enable recording event rules in the user space tracing
domain.
Recording target
~~~~~~~~~~~~~~~~
option:-c 'CHANNEL', option:--channel='CHANNEL'::
Create or enable recording event rules attached to the channel named
'CHANNEL' instead of `channel0`.
option:-s 'SESSION', option:--session='SESSION'::
Create or enable recording event rules in the recording session
named 'SESSION' instead of the current recording session.
Instrumentation point type condition
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
See the ``<<inst-point-type-cond,Instrumentation point type
condition>>'' section above.
At most one of:
option:--function='LOC'::
Only match Linux kretprobe events.
+
Only available with the option:--kernel option.
+
'LOC' is one of:
+
--
* A function address (`0x` hexadecimal prefix supported).
* A function symbol name.
* A function symbol name and an offset
(__SYMBOL__++pass:[+]++__OFFSET__ format).
--
+
You must specify the event record name with 'RECORDNAME'. See the
``<<er-name,Event record name>>'' section above to learn more.
option:--probe='LOC'::
Only match Linux kprobe events.
+
Only available with the option:--kernel option.
+
'LOC' is one of:
+
--
* An address (`0x` hexadecimal prefix supported).
* A symbol name.
* A symbol name and an offset (__SYMBOL__++pass:[+]++__OFFSET__ format).
--
+
You must specify the event record name with 'RECORDNAME'. See the
``<<er-name,Event record name>>'' section above to learn more.
option:--userspace-probe='LOC'::
Only match Linux user space probe events.
+
Only available with the option:--kernel option.
+
'LOC' is one of:
+
--
\[++elf:++]__PATH__++:++__SYMBOL__::
Probe an available symbol within a user space application or
library.
+
--
'PATH'::
Application or library path.
+
One of:
+
* An absolute path.
* A relative path.
* The name of an application as found in the directories listed in the
`PATH` environment variable.
'SYMBOL'::
Symbol name of the function of which to instrument the entry.
+
'SYMBOL' can be any defined code symbol in the output of the man:nm(1)
command, including with its nloption:--dynamic option, which lists
dynamic symbols.
--
+
As of LTTng{nbsp}{lttng_version}, not specifying `elf:` is equivalent to
specifying it, but this default may change in the future.
+
Examples:
+
* `--userspace-probe=/usr/lib/libc.so.6:malloc`
* `--userspace-probe=./myapp:createUser`
* `--userspace-probe=elf:httpd:ap_run_open_htaccess`
++sdt:++__PATH__++:++__PROVIDER__++:++__NAME__::
Use a SystemTap User-level Statically Defined Tracing (USDT) probe
within a user space application or library.
+
--
'PATH'::
Application or library path.
+
This can be:
+
* An absolute path.
* A relative path.
* The name of an application as found in the directories listed in the
`PATH` environment variable.
'PROVIDER'::
'NAME'::
USDT provider and probe names.
+
For example, with the following USDT probe:
+
[source,c]
----
DTRACE_PROBE2("server", "accept_request",
request_id, ip_addr);
----
+
The provider/probe name pair is `server:accept_request`.
--
+
Example: `--userspace-probe=sdt:./build/server:server:accept_request`
--
+
You must specify the event record name with 'RECORDNAME'. See the
``<<er-name,Event record name>>'' section above to learn more.
option:--syscall::
Only match Linux system call events.
+
Only available with the option:--kernel option.
option:--tracepoint::
Only match:
+
With the option:--kernel or option:--userspace option:::
LTTng tracepoint events.
With the option:--jul, option:--log4j, or option:--python option:::
Logging events.
With the option:--kernel, not specifying any of the instrumentation
point type options is equivalent to specifying the option:--tracepoint
option, but this default may change in the future.
With the option:--userspace, option:--jul, option:--log4j, and
option:--python options, not specifying the option:--tracepoint option
is equivalent to specifying it, but this default may change in the
future.
Event name condition
~~~~~~~~~~~~~~~~~~~~
See the ``<<event-name-cond,Event name condition>>'' section above.
option:-a, option:--all::
Equivalent to a single 'NAME' argument (LTTng tracepoint or logger
name) set to `*` (match anything).
+
You may :not: use this option with a 'NAME' argument.
option:-x 'XNAME'[,'XNAME']..., option:--exclude='XNAME'[,'XNAME']...::
Only match events of which none of the 'XNAME' arguments
matches the full name of the LTTng user space tracepoint.
+
Only available with the option:--userspace option.
+
'XNAME' is a globbing pattern: the `*` character means ``match
anything''. To match a literal `*` character, use :escwc:. To match
a literal `,` character, use :esccomma:.
Instrumentation point log level condition
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
See the ``<<inst-point-log-level-cond,Instrumentation point log level
condition>>'' section above.
At most one of:
option:--loglevel='LOGLEVEL'::
Only match events of which the log level of the LTTng tracepoint or
logging statement is at least as severe as 'LOGLEVEL'.
option:--loglevel-only='LOGLEVEL'::
Only match events of which the log level of the LTTng tracepoint or
logging statement is exactly 'LOGLEVEL'.
The instrumentation point log level options above are :not: available
with the option:--kernel option.
Event payload and context filter condition
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
See the ``<<filter-cond,Event payload and context filter condition>>''
section above.
option:-f 'EXPR', option:--filter='EXPR'::
Only match events of which 'EXPR', which can contain references to
event payload and current context fields, is _true_.
+
This option is only available with the option:--tracepoint or
option:--syscall option.
include::common-lttng-cmd-help-options.txt[]
include::common-lttng-cmd-after-options.txt[]
[[examples]]
EXAMPLES
--------
.Create a recording event rule which matches all Linux system call events (current recording session, default channel).
====
See the option:--all and option:--syscall options.
[role="term"]
----
$ lttng enable-event --kernel --all --syscall
----
====
.Create a recording event rule which matches user space tracepoint events named specifically (current recording session, default channel).
====
The recording event rule below matches all user space tracepoint events
of which the name starts with `my_provider:msg`.
[role="term"]
----
$ lttng enable-event --userspace 'my_provider:msg*'
----
====
.Create three recording event rules which match Python logging events named specifically (current recording session, default channel).
====
[role="term"]
----
$ lttng enable-event --python server3,ui.window,user-mgmt
----
====
.Create a recording event rule which matches Apache log4j logging events with a specific log level range (current recording session, specific channel).
====
See the option:--channel, option:--all, and option:--loglevel options.
[role="term"]
----
$ lttng enable-event --log4j --channel=my-loggers \
--all --loglevel=INFO
----
====
.Create a recording event rule which matches specific Linux kprobe events (current recording session, default channel).
====
The recording event rule below matches the entry of `usb_disconnect()`
Linux kernel function calls. The records of such events are named `usbd`
(see the ``<<er-name,Event record name>>'' section above).
See the option:--probe option.
[role="term"]
----
$ lttng enable-event --kernel --probe=usb_disconnect usbd
----
====
.Create a recording event rule which matches Linux kernel tracepoint events which satisfy an event payload and context filter (specific recording session, default channel).
====
See the option:--session and option:--filter options.
[role="term"]
----
$ lttng enable-event --kernel --session=my-session 'sched_*' \
--filter='$ctx.preemptible && comm != "systemd*"'
----
====
.Enable two Linux kernel tracepoint recording event rules (current recording session, specific channel).
====
See the option:--channel option.
[role="term"]
----
$ lttng enable-event --kernel --channel=tva ja,wendy
----
====
include::common-footer.txt[]
SEE ALSO
--------
man:lttng(1),
man:lttng-disable-event(1),
man:lttng-enable-channel(1),
man:lttng-list(1),
man:lttng-start(1),
man:lttng-track(1),
man:lttng-concepts(7)