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
)
92 class EventRule(abc
.ABC
):
93 """Event rule base class, see LTTNG-EVENT-RULE(7)."""
102 class LogLevelRuleAsSevereAs(LogLevelRule
):
103 def __init__(self
, level
):
113 class LogLevelRuleExactly(LogLevelRule
):
114 def __init__(self
, level
):
124 class TracepointEventRule(EventRule
):
127 name_pattern
=None, # type: Optional[str]
128 filter_expression
=None, # type: Optional[str]
129 log_level_rule
=None, # type: Optional[LogLevelRule]
130 name_pattern_exclusions
=None, # type: Optional[List[str]]
132 self
._name
_pattern
= name_pattern
# type: Optional[str]
133 self
._filter
_expression
= filter_expression
# type: Optional[str]
134 self
._log
_level
_rule
= log_level_rule
# type: Optional[LogLevelRule]
135 self
._name
_pattern
_exclusions
= (
136 name_pattern_exclusions
137 ) # type: Optional[List[str]]
140 def name_pattern(self
):
141 # type: () -> Optional[str]
142 return self
._name
_pattern
145 def filter_expression(self
):
146 # type: () -> Optional[str]
147 return self
._filter
_expression
150 def log_level_rule(self
):
151 # type: () -> Optional[LogLevelRule]
152 return self
._log
_level
_rule
155 def name_pattern_exclusions(self
):
156 # type: () -> Optional[List[str]]
157 return self
._name
_pattern
_exclusions
160 class UserTracepointEventRule(TracepointEventRule
):
163 name_pattern
=None, # type: Optional[str]
164 filter_expression
=None, # type: Optional[str]
165 log_level_rule
=None, # type: Optional[LogLevelRule]
166 name_pattern_exclusions
=None, # type: Optional[List[str]]
168 TracepointEventRule
.__init
__(**locals())
171 class KernelTracepointEventRule(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 Channel(abc
.ABC
):
184 A channel is an object which is responsible for a set of ring buffers. It is
185 associated to a domain and
189 def _generate_name():
191 return "channel_{random_id}".format(random_id
=_generate_random_string(8))
194 def add_context(self
, context_type
):
195 # type: (ContextType) -> None
201 # type: () -> TracingDomain
211 def add_recording_rule(self
, rule
) -> None:
212 # type: (Type[EventRule]) -> None
216 class SessionOutputLocation(abc
.ABC
):
220 class LocalSessionOutputLocation(SessionOutputLocation
):
221 def __init__(self
, trace_path
):
222 # type: (pathlib.Path)
223 self
._path
= trace_path
227 # type: () -> pathlib.Path
231 class ProcessAttributeTracker(abc
.ABC
):
233 Process attribute tracker used to filter before the evaluation of event
236 Note that this interface is currently limited as it doesn't allow changing
237 the tracking policy. For instance, it is not possible to set the tracking
238 policy back to "all" once it has transitioned to "include set".
242 class TrackingPolicy(enum
.Enum
):
244 Track all possible process attribute value of a given type (i.e. no filtering).
245 This is the default state of a process attribute tracker.
247 EXCLUDE_ALL
= "Exclude all possible process attribute values of a given type."
248 INCLUDE_SET
= "Track a set of specific process attribute values."
251 return "<%s.%s>" % (self
.__class
__.__name
__, self
.name
)
253 def __init__(self
, policy
):
254 # type: (TrackingPolicy)
255 self
._policy
= policy
258 def tracking_policy(self
):
259 # type: () -> TrackingPolicy
263 class ProcessIDProcessAttributeTracker(ProcessAttributeTracker
):
265 def track(self
, pid
):
266 # type: (int) -> None
270 def untrack(self
, pid
):
271 # type: (int) -> None
275 class VirtualProcessIDProcessAttributeTracker(ProcessAttributeTracker
):
277 def track(self
, vpid
):
278 # type: (int) -> None
282 def untrack(self
, vpid
):
283 # type: (int) -> None
287 class UserIDProcessAttributeTracker(ProcessAttributeTracker
):
289 def track(self
, uid
):
290 # type: (Union[int, str]) -> None
294 def untrack(self
, uid
):
295 # type: (Union[int, str]) -> None
299 class VirtualUserIDProcessAttributeTracker(ProcessAttributeTracker
):
301 def track(self
, vuid
):
302 # type: (Union[int, str]) -> None
306 def untrack(self
, vuid
):
307 # type: (Union[int, str]) -> None
311 class GroupIDProcessAttributeTracker(ProcessAttributeTracker
):
313 def track(self
, gid
):
314 # type: (Union[int, str]) -> None
318 def untrack(self
, gid
):
319 # type: (Union[int, str]) -> None
323 class VirtualGroupIDProcessAttributeTracker(ProcessAttributeTracker
):
325 def track(self
, vgid
):
326 # type: (Union[int, str]) -> None
330 def untrack(self
, vgid
):
331 # type: (Union[int, str]) -> None
335 class Session(abc
.ABC
):
337 def _generate_name():
339 return "session_{random_id}".format(random_id
=_generate_random_string(8))
350 # type: () -> Optional[Type[SessionOutputLocation]]
354 def add_channel(self
, domain
, channel_name
=None):
355 # type: (TracingDomain, Optional[str]) -> Channel
356 """Add a channel with default attributes to the session."""
379 @abc.abstractproperty
380 def kernel_pid_process_attribute_tracker(self
):
381 # type: () -> Type[ProcessIDProcessAttributeTracker]
382 raise NotImplementedError
384 @abc.abstractproperty
385 def kernel_vpid_process_attribute_tracker(self
):
386 # type: () -> Type[VirtualProcessIDProcessAttributeTracker]
387 raise NotImplementedError
389 @abc.abstractproperty
390 def user_vpid_process_attribute_tracker(
392 ) -> Type
[VirtualProcessIDProcessAttributeTracker
]:
393 # type: () -> Type[VirtualProcessIDProcessAttributeTracker]
394 raise NotImplementedError
396 @abc.abstractproperty
397 def kernel_gid_process_attribute_tracker(self
):
398 # type: () -> Type[GroupIDProcessAttributeTracker]
399 raise NotImplementedError
401 @abc.abstractproperty
402 def kernel_vgid_process_attribute_tracker(self
):
403 # type: () -> Type[VirtualGroupIDProcessAttributeTracker]
404 raise NotImplementedError
406 @abc.abstractproperty
407 def user_vgid_process_attribute_tracker(self
):
408 # type: () -> Type[VirtualGroupIDProcessAttributeTracker]
409 raise NotImplementedError
411 @abc.abstractproperty
412 def kernel_uid_process_attribute_tracker(self
):
413 # type: () -> Type[UserIDProcessAttributeTracker]
414 raise NotImplementedError
416 @abc.abstractproperty
417 def kernel_vuid_process_attribute_tracker(self
):
418 # type: () -> Type[VirtualUserIDProcessAttributeTracker]
419 raise NotImplementedError
421 @abc.abstractproperty
422 def user_vuid_process_attribute_tracker(self
):
423 # type: () -> Type[VirtualUserIDProcessAttributeTracker]
424 raise NotImplementedError
427 class ControlException(RuntimeError):
428 """Base type for exceptions thrown by a controller."""
430 def __init__(self
, msg
):
432 super().__init
__(msg
)
435 class Controller(abc
.ABC
):
437 Interface of a top-level control interface. A control interface can be, for
438 example, the LTTng client or a wrapper around liblttng-ctl. It is used to
439 create and manage top-level objects of a session daemon instance.
443 def create_session(self
, name
=None, output
=None):
444 # type: (Optional[str], Optional[SessionOutputLocation]) -> Session
446 Create a session with an output. Don't specify an output
447 to create a session without an output.
452 def start_session_by_name(self
, name
):
453 # type: (str) -> None
455 Start a session by name.
460 def start_session_by_glob_pattern(self
, pattern
):
461 # type: (str) -> None
463 Start sessions whose name matches `pattern`, see GLOB(7).
468 def start_sessions_all(self
):
470 Start all sessions visible to the current user.
476 def stop_session_by_name(self
, name
):
477 # type: (str) -> None
479 Stop a session by name.
484 def stop_session_by_glob_pattern(self
, pattern
):
485 # type: (str) -> None
487 Stop sessions whose name matches `pattern`, see GLOB(7).
492 def stop_sessions_all(self
):
494 Stop all sessions visible to the current user.
500 def destroy_session_by_name(self
, name
):
501 # type: (str) -> None
503 Destroy a session by name.
508 def destroy_session_by_glob_pattern(self
, pattern
):
509 # type: (str) -> None
511 Destroy sessions whose name matches `pattern`, see GLOB(7).
516 def destroy_sessions_all(self
):
519 Destroy all sessions visible to the current user.
524 def list_sessions(self
):
525 # type: () -> List[Session]
527 List all sessions visible to the current user.