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."""
374 @abc.abstractproperty
375 def kernel_pid_process_attribute_tracker(self
):
376 # type: () -> Type[ProcessIDProcessAttributeTracker]
377 raise NotImplementedError
379 @abc.abstractproperty
380 def kernel_vpid_process_attribute_tracker(self
):
381 # type: () -> Type[VirtualProcessIDProcessAttributeTracker]
382 raise NotImplementedError
384 @abc.abstractproperty
385 def user_vpid_process_attribute_tracker(
387 ) -> Type
[VirtualProcessIDProcessAttributeTracker
]:
388 # type: () -> Type[VirtualProcessIDProcessAttributeTracker]
389 raise NotImplementedError
391 @abc.abstractproperty
392 def kernel_gid_process_attribute_tracker(self
):
393 # type: () -> Type[GroupIDProcessAttributeTracker]
394 raise NotImplementedError
396 @abc.abstractproperty
397 def kernel_vgid_process_attribute_tracker(self
):
398 # type: () -> Type[VirtualGroupIDProcessAttributeTracker]
399 raise NotImplementedError
401 @abc.abstractproperty
402 def user_vgid_process_attribute_tracker(self
):
403 # type: () -> Type[VirtualGroupIDProcessAttributeTracker]
404 raise NotImplementedError
406 @abc.abstractproperty
407 def kernel_uid_process_attribute_tracker(self
):
408 # type: () -> Type[UserIDProcessAttributeTracker]
409 raise NotImplementedError
411 @abc.abstractproperty
412 def kernel_vuid_process_attribute_tracker(self
):
413 # type: () -> Type[VirtualUserIDProcessAttributeTracker]
414 raise NotImplementedError
416 @abc.abstractproperty
417 def user_vuid_process_attribute_tracker(self
):
418 # type: () -> Type[VirtualUserIDProcessAttributeTracker]
419 raise NotImplementedError
422 class ControlException(RuntimeError):
423 """Base type for exceptions thrown by a controller."""
425 def __init__(self
, msg
):
427 super().__init
__(msg
)
430 class Controller(abc
.ABC
):
432 Interface of a top-level control interface. A control interface can be, for
433 example, the LTTng client or a wrapper around liblttng-ctl. It is used to
434 create and manage top-level objects of a session daemon instance.
438 def create_session(self
, name
=None, output
=None):
439 # type: (Optional[str], Optional[SessionOutputLocation]) -> Session
441 Create a session with an output. Don't specify an output
442 to create a session without an output.