3 # Copyright (C) 2022 Jérémie Galarneau <jeremie.galarneau@efficios.com>
5 # SPDX-License-Identifier: GPL-2.0-only
12 from typing
import Optional
, Type
, Union
, List
15 Defines an abstract interface to control LTTng tracing.
17 The various control concepts are defined by this module. You can use them with a
18 Controller to interact with a session daemon.
20 This interface is not comprehensive; it currently provides a subset of the
21 control functionality that is used by tests.
25 def _generate_random_string(length
):
28 random
.choice(string
.ascii_lowercase
+ string
.digits
) for _
in range(length
)
32 class ContextType(abc
.ABC
):
33 """Base class representing a tracing context field."""
38 class VpidContextType(ContextType
):
39 """Application's virtual process id."""
44 class VuidContextType(ContextType
):
45 """Application's virtual user id."""
50 class VgidContextType(ContextType
):
51 """Application's virtual group id."""
56 class JavaApplicationContextType(ContextType
):
57 """A java application-specific context field is a piece of state which the application provides."""
61 retriever_name
, # type: str
62 field_name
, # type: str
64 self
._retriever
_name
= retriever_name
# type: str
65 self
._field
_name
= field_name
# type: str
68 def retriever_name(self
):
70 return self
._retriever
_name
75 return self
._field
_name
79 class TracingDomain(enum
.Enum
):
82 User
= "User space tracing domain"
83 Kernel
= "Linux kernel tracing domain."
84 Log4j
= "Log4j tracing back-end."
85 JUL
= "Java Util Logging tracing back-end."
86 Python
= "Python logging module tracing back-end."
89 return "<%s.%s>" % (self
.__class
__.__name
__, self
.name
)
93 class BufferSharingPolicy(enum
.Enum
):
94 """Buffer sharing policy."""
96 PerUID
= "Per-UID buffering"
97 PerPID
= "Per-PID buffering"
100 return "<%s.%s>" % (self
.__class
__.__name
__, self
.name
)
103 class EventRule(abc
.ABC
):
104 """Event rule base class, see LTTNG-EVENT-RULE(7)."""
113 class LogLevelRuleAsSevereAs(LogLevelRule
):
114 def __init__(self
, level
):
124 class LogLevelRuleExactly(LogLevelRule
):
125 def __init__(self
, level
):
135 class TracepointEventRule(EventRule
):
138 name_pattern
=None, # type: Optional[str]
139 filter_expression
=None, # type: Optional[str]
140 log_level_rule
=None, # type: Optional[LogLevelRule]
141 name_pattern_exclusions
=None, # type: Optional[List[str]]
143 self
._name
_pattern
= name_pattern
# type: Optional[str]
144 self
._filter
_expression
= filter_expression
# type: Optional[str]
145 self
._log
_level
_rule
= log_level_rule
# type: Optional[LogLevelRule]
146 self
._name
_pattern
_exclusions
= (
147 name_pattern_exclusions
148 ) # type: Optional[List[str]]
151 def name_pattern(self
):
152 # type: () -> Optional[str]
153 return self
._name
_pattern
156 def filter_expression(self
):
157 # type: () -> Optional[str]
158 return self
._filter
_expression
161 def log_level_rule(self
):
162 # type: () -> Optional[LogLevelRule]
163 return self
._log
_level
_rule
166 def name_pattern_exclusions(self
):
167 # type: () -> Optional[List[str]]
168 return self
._name
_pattern
_exclusions
171 class UserTracepointEventRule(TracepointEventRule
):
174 name_pattern
=None, # type: Optional[str]
175 filter_expression
=None, # type: Optional[str]
176 log_level_rule
=None, # type: Optional[LogLevelRule]
177 name_pattern_exclusions
=None, # type: Optional[List[str]]
179 TracepointEventRule
.__init
__(**locals())
182 class KernelTracepointEventRule(TracepointEventRule
):
185 name_pattern
=None, # type: Optional[str]
186 filter_expression
=None, # type: Optional[str]
187 log_level_rule
=None, # type: Optional[LogLevelRule]
188 name_pattern_exclusions
=None, # type: Optional[List[str]]
190 TracepointEventRule
.__init
__(**locals())
193 class Channel(abc
.ABC
):
195 A channel is an object which is responsible for a set of ring buffers. It is
196 associated to a domain and
200 def _generate_name():
202 return "channel_{random_id}".format(random_id
=_generate_random_string(8))
205 def add_context(self
, context_type
):
206 # type: (ContextType) -> None
212 # type: () -> TracingDomain
222 def add_recording_rule(self
, rule
) -> None:
223 # type: (Type[EventRule]) -> None
227 class SessionOutputLocation(abc
.ABC
):
231 class LocalSessionOutputLocation(SessionOutputLocation
):
232 def __init__(self
, trace_path
):
233 # type: (pathlib.Path)
234 self
._path
= trace_path
238 # type: () -> pathlib.Path
242 class ProcessAttributeTracker(abc
.ABC
):
244 Process attribute tracker used to filter before the evaluation of event
247 Note that this interface is currently limited as it doesn't allow changing
248 the tracking policy. For instance, it is not possible to set the tracking
249 policy back to "all" once it has transitioned to "include set".
253 class TrackingPolicy(enum
.Enum
):
255 Track all possible process attribute value of a given type (i.e. no filtering).
256 This is the default state of a process attribute tracker.
258 EXCLUDE_ALL
= "Exclude all possible process attribute values of a given type."
259 INCLUDE_SET
= "Track a set of specific process attribute values."
262 return "<%s.%s>" % (self
.__class
__.__name
__, self
.name
)
264 def __init__(self
, policy
):
265 # type: (TrackingPolicy)
266 self
._policy
= policy
269 def tracking_policy(self
):
270 # type: () -> TrackingPolicy
274 class ProcessIDProcessAttributeTracker(ProcessAttributeTracker
):
276 def track(self
, pid
):
277 # type: (int) -> None
281 def untrack(self
, pid
):
282 # type: (int) -> None
286 class VirtualProcessIDProcessAttributeTracker(ProcessAttributeTracker
):
288 def track(self
, vpid
):
289 # type: (int) -> None
293 def untrack(self
, vpid
):
294 # type: (int) -> None
298 class UserIDProcessAttributeTracker(ProcessAttributeTracker
):
300 def track(self
, uid
):
301 # type: (Union[int, str]) -> None
305 def untrack(self
, uid
):
306 # type: (Union[int, str]) -> None
310 class VirtualUserIDProcessAttributeTracker(ProcessAttributeTracker
):
312 def track(self
, vuid
):
313 # type: (Union[int, str]) -> None
317 def untrack(self
, vuid
):
318 # type: (Union[int, str]) -> None
322 class GroupIDProcessAttributeTracker(ProcessAttributeTracker
):
324 def track(self
, gid
):
325 # type: (Union[int, str]) -> None
329 def untrack(self
, gid
):
330 # type: (Union[int, str]) -> None
334 class VirtualGroupIDProcessAttributeTracker(ProcessAttributeTracker
):
336 def track(self
, vgid
):
337 # type: (Union[int, str]) -> None
341 def untrack(self
, vgid
):
342 # type: (Union[int, str]) -> None
346 class Session(abc
.ABC
):
348 def _generate_name():
350 return "session_{random_id}".format(random_id
=_generate_random_string(8))
361 # type: () -> Optional[Type[SessionOutputLocation]]
369 buffer_sharing_policy
=BufferSharingPolicy
.PerUID
,
371 # type: (TracingDomain, Optional[str], BufferSharingPolicy) -> Channel
372 """Add a channel with default attributes to the session."""
395 @abc.abstractproperty
396 def kernel_pid_process_attribute_tracker(self
):
397 # type: () -> Type[ProcessIDProcessAttributeTracker]
398 raise NotImplementedError
400 @abc.abstractproperty
401 def kernel_vpid_process_attribute_tracker(self
):
402 # type: () -> Type[VirtualProcessIDProcessAttributeTracker]
403 raise NotImplementedError
405 @abc.abstractproperty
406 def user_vpid_process_attribute_tracker(
408 ) -> Type
[VirtualProcessIDProcessAttributeTracker
]:
409 # type: () -> Type[VirtualProcessIDProcessAttributeTracker]
410 raise NotImplementedError
412 @abc.abstractproperty
413 def kernel_gid_process_attribute_tracker(self
):
414 # type: () -> Type[GroupIDProcessAttributeTracker]
415 raise NotImplementedError
417 @abc.abstractproperty
418 def kernel_vgid_process_attribute_tracker(self
):
419 # type: () -> Type[VirtualGroupIDProcessAttributeTracker]
420 raise NotImplementedError
422 @abc.abstractproperty
423 def user_vgid_process_attribute_tracker(self
):
424 # type: () -> Type[VirtualGroupIDProcessAttributeTracker]
425 raise NotImplementedError
427 @abc.abstractproperty
428 def kernel_uid_process_attribute_tracker(self
):
429 # type: () -> Type[UserIDProcessAttributeTracker]
430 raise NotImplementedError
432 @abc.abstractproperty
433 def kernel_vuid_process_attribute_tracker(self
):
434 # type: () -> Type[VirtualUserIDProcessAttributeTracker]
435 raise NotImplementedError
437 @abc.abstractproperty
438 def user_vuid_process_attribute_tracker(self
):
439 # type: () -> Type[VirtualUserIDProcessAttributeTracker]
440 raise NotImplementedError
443 class ControlException(RuntimeError):
444 """Base type for exceptions thrown by a controller."""
446 def __init__(self
, msg
):
448 super().__init
__(msg
)
451 class Controller(abc
.ABC
):
453 Interface of a top-level control interface. A control interface can be, for
454 example, the LTTng client or a wrapper around liblttng-ctl. It is used to
455 create and manage top-level objects of a session daemon instance.
459 def create_session(self
, name
=None, output
=None):
460 # type: (Optional[str], Optional[SessionOutputLocation]) -> Session
462 Create a session with an output. Don't specify an output
463 to create a session without an output.
468 def start_session_by_name(self
, name
):
469 # type: (str) -> None
471 Start a session by name.
476 def start_session_by_glob_pattern(self
, pattern
):
477 # type: (str) -> None
479 Start sessions whose name matches `pattern`, see GLOB(7).
484 def start_sessions_all(self
):
486 Start all sessions visible to the current user.
492 def stop_session_by_name(self
, name
):
493 # type: (str) -> None
495 Stop a session by name.
500 def stop_session_by_glob_pattern(self
, pattern
):
501 # type: (str) -> None
503 Stop sessions whose name matches `pattern`, see GLOB(7).
508 def stop_sessions_all(self
):
510 Stop all sessions visible to the current user.
516 def destroy_session_by_name(self
, name
):
517 # type: (str) -> None
519 Destroy a session by name.
524 def destroy_session_by_glob_pattern(self
, pattern
):
525 # type: (str) -> None
527 Destroy sessions whose name matches `pattern`, see GLOB(7).
532 def destroy_sessions_all(self
):
535 Destroy all sessions visible to the current user.
540 def list_sessions(self
):
541 # type: () -> List[Session]
543 List all sessions visible to the current user.