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
: int) -> str:
27 random
.choice(string
.ascii_lowercase
+ string
.digits
) for _
in range(length
)
31 class ContextType(abc
.ABC
):
32 """Base class representing a tracing context field."""
37 class VpidContextType(ContextType
):
38 """Application's virtual process id."""
43 class VuidContextType(ContextType
):
44 """Application's virtual user id."""
49 class VgidContextType(ContextType
):
50 """Application's virtual group id."""
55 class JavaApplicationContextType(ContextType
):
56 """A java application-specific context field is a piece of state which the application provides."""
58 def __init__(self
, retriever_name
: str, field_name
: str):
59 self
._retriever
_name
: str = retriever_name
60 self
._field
_name
: str = field_name
63 def retriever_name(self
) -> str:
64 return self
._retriever
_name
67 def field_name(self
) -> str:
68 return self
._field
_name
71 class TracingDomain(enum
.Enum
):
74 User
= enum
.auto(), "User space tracing domain"
75 Kernel
= enum
.auto(), "Linux kernel tracing domain."
76 Log4j
= enum
.auto(), "Log4j tracing back-end."
77 JUL
= enum
.auto(), "Java Util Logging tracing back-end."
78 Python
= enum
.auto(), "Python logging module tracing back-end."
81 class EventRule(abc
.ABC
):
82 """Event rule base class, see LTTNG-EVENT-RULE(7)."""
91 class LogLevelRuleAsSevereAs(LogLevelRule
):
92 def __init__(self
, level
: int):
96 def level(self
) -> int:
100 class LogLevelRuleExactly(LogLevelRule
):
101 def __init__(self
, level
: int):
105 def level(self
) -> int:
109 class TracepointEventRule(EventRule
):
112 name_pattern
: Optional
[str] = None,
113 filter_expression
: Optional
[str] = None,
114 log_level_rule
: Optional
[LogLevelRule
] = None,
115 name_pattern_exclusions
: Optional
[List
[str]] = None,
117 self
._name
_pattern
: Optional
[str] = name_pattern
118 self
._filter
_expression
: Optional
[str] = filter_expression
119 self
._log
_level
_rule
: Optional
[LogLevelRule
] = log_level_rule
120 self
._name
_pattern
_exclusions
: Optional
[List
[str]] = name_pattern_exclusions
123 def name_pattern(self
) -> Optional
[str]:
124 return self
._name
_pattern
127 def filter_expression(self
) -> Optional
[str]:
128 return self
._filter
_expression
131 def log_level_rule(self
) -> Optional
[LogLevelRule
]:
132 return self
._log
_level
_rule
135 def name_pattern_exclusions(self
) -> Optional
[List
[str]]:
136 return self
._name
_pattern
_exclusions
139 class UserTracepointEventRule(TracepointEventRule
):
142 name_pattern
: Optional
[str] = None,
143 filter_expression
: Optional
[str] = None,
144 log_level_rule
: Optional
[LogLevelRule
] = None,
145 name_pattern_exclusions
: Optional
[List
[str]] = None,
147 TracepointEventRule
.__init
__(**locals())
150 class KernelTracepointEventRule(TracepointEventRule
):
153 name_pattern
: Optional
[str] = None,
154 filter_expression
: Optional
[str] = None,
155 log_level_rule
: Optional
[LogLevelRule
] = None,
156 name_pattern_exclusions
: Optional
[List
[str]] = None,
158 TracepointEventRule
.__init
__(**locals())
161 class Channel(abc
.ABC
):
163 A channel is an object which is responsible for a set of ring buffers. It is
164 associated to a domain and
168 def _generate_name() -> str:
169 return "channel_{random_id}".format(random_id
=_generate_random_string(8))
172 def add_context(self
, context_type
: ContextType
) -> None:
177 def domain(self
) -> TracingDomain
:
182 def name(self
) -> str:
186 def add_recording_rule(self
, rule
: Type
[EventRule
]) -> None:
190 class SessionOutputLocation(abc
.ABC
):
194 class LocalSessionOutputLocation(SessionOutputLocation
):
195 def __init__(self
, trace_path
: pathlib
.Path
):
196 self
._path
= trace_path
199 def path(self
) -> pathlib
.Path
:
203 class ProcessAttributeTracker(abc
.ABC
):
205 Process attribute tracker used to filter before the evaluation of event
208 Note that this interface is currently limited as it doesn't allow changing
209 the tracking policy. For instance, it is not possible to set the tracking
210 policy back to "all" once it has transitioned to "include set".
213 class TrackingPolicy(enum
.Enum
):
217 Track all possible process attribute value of a given type (i.e. no filtering).
218 This is the default state of a process attribute tracker.
223 "Exclude all possible process attribute values of a given type.",
225 INCLUDE_SET
= enum
.auto(), "Track a set of specific process attribute values."
227 def __init__(self
, policy
: TrackingPolicy
):
228 self
._policy
= policy
231 def tracking_policy(self
) -> TrackingPolicy
:
235 class ProcessIDProcessAttributeTracker(ProcessAttributeTracker
):
237 def track(self
, pid
: int) -> None:
241 def untrack(self
, pid
: int) -> None:
245 class VirtualProcessIDProcessAttributeTracker(ProcessAttributeTracker
):
247 def track(self
, vpid
: int) -> None:
251 def untrack(self
, vpid
: int) -> None:
255 class UserIDProcessAttributeTracker(ProcessAttributeTracker
):
257 def track(self
, uid
: Union
[int, str]) -> None:
261 def untrack(self
, uid
: Union
[int, str]) -> None:
265 class VirtualUserIDProcessAttributeTracker(ProcessAttributeTracker
):
267 def track(self
, vuid
: Union
[int, str]) -> None:
271 def untrack(self
, vuid
: Union
[int, str]) -> None:
275 class GroupIDProcessAttributeTracker(ProcessAttributeTracker
):
277 def track(self
, gid
: Union
[int, str]) -> None:
281 def untrack(self
, gid
: Union
[int, str]) -> None:
285 class VirtualGroupIDProcessAttributeTracker(ProcessAttributeTracker
):
287 def track(self
, vgid
: Union
[int, str]) -> None:
291 def untrack(self
, vgid
: Union
[int, str]) -> None:
295 class Session(abc
.ABC
):
297 def _generate_name() -> str:
298 return "session_{random_id}".format(random_id
=_generate_random_string(8))
302 def name(self
) -> str:
307 def output(self
) -> Optional
[Type
[SessionOutputLocation
]]:
312 self
, domain
: TracingDomain
, channel_name
: Optional
[str] = None
314 """Add a channel with default attributes to the session."""
318 def start(self
) -> None:
322 def stop(self
) -> None:
326 def destroy(self
) -> None:
329 @abc.abstractproperty
330 def kernel_pid_process_attribute_tracker(
332 ) -> Type
[ProcessIDProcessAttributeTracker
]:
333 raise NotImplementedError
335 @abc.abstractproperty
336 def kernel_vpid_process_attribute_tracker(
338 ) -> Type
[VirtualProcessIDProcessAttributeTracker
]:
339 raise NotImplementedError
341 @abc.abstractproperty
342 def user_vpid_process_attribute_tracker(
344 ) -> Type
[VirtualProcessIDProcessAttributeTracker
]:
345 raise NotImplementedError
347 @abc.abstractproperty
348 def kernel_gid_process_attribute_tracker(
350 ) -> Type
[GroupIDProcessAttributeTracker
]:
351 raise NotImplementedError
353 @abc.abstractproperty
354 def kernel_vgid_process_attribute_tracker(
356 ) -> Type
[VirtualGroupIDProcessAttributeTracker
]:
357 raise NotImplementedError
359 @abc.abstractproperty
360 def user_vgid_process_attribute_tracker(
362 ) -> Type
[VirtualGroupIDProcessAttributeTracker
]:
363 raise NotImplementedError
365 @abc.abstractproperty
366 def kernel_uid_process_attribute_tracker(
368 ) -> Type
[UserIDProcessAttributeTracker
]:
369 raise NotImplementedError
371 @abc.abstractproperty
372 def kernel_vuid_process_attribute_tracker(
374 ) -> Type
[VirtualUserIDProcessAttributeTracker
]:
375 raise NotImplementedError
377 @abc.abstractproperty
378 def user_vuid_process_attribute_tracker(
380 ) -> Type
[VirtualUserIDProcessAttributeTracker
]:
381 raise NotImplementedError
384 class ControlException(RuntimeError):
385 """Base type for exceptions thrown by a controller."""
387 def __init__(self
, msg
: str):
388 super().__init
__(msg
)
391 class Controller(abc
.ABC
):
393 Interface of a top-level control interface. A control interface can be, for
394 example, the LTTng client or a wrapper around liblttng-ctl. It is used to
395 create and manage top-level objects of a session daemon instance.
400 self
, name
: Optional
[str] = None, output
: Optional
[SessionOutputLocation
] = None
403 Create a session with an output. Don't specify an output
404 to create a session without an output.