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
72 class TracingDomain(enum
.Enum
):
75 User
= "User space tracing domain"
76 Kernel
= "Linux kernel tracing domain."
77 Log4j
= "Log4j tracing back-end."
78 JUL
= "Java Util Logging tracing back-end."
79 Python
= "Python logging module tracing back-end."
82 return "<%s.%s>" % (self
.__class
__.__name
__, self
.name
)
85 class EventRule(abc
.ABC
):
86 """Event rule base class, see LTTNG-EVENT-RULE(7)."""
95 class LogLevelRuleAsSevereAs(LogLevelRule
):
96 def __init__(self
, level
: int):
100 def level(self
) -> int:
104 class LogLevelRuleExactly(LogLevelRule
):
105 def __init__(self
, level
: int):
109 def level(self
) -> int:
113 class TracepointEventRule(EventRule
):
116 name_pattern
: Optional
[str] = None,
117 filter_expression
: Optional
[str] = None,
118 log_level_rule
: Optional
[LogLevelRule
] = None,
119 name_pattern_exclusions
: Optional
[List
[str]] = None,
121 self
._name
_pattern
: Optional
[str] = name_pattern
122 self
._filter
_expression
: Optional
[str] = filter_expression
123 self
._log
_level
_rule
: Optional
[LogLevelRule
] = log_level_rule
124 self
._name
_pattern
_exclusions
: Optional
[List
[str]] = name_pattern_exclusions
127 def name_pattern(self
) -> Optional
[str]:
128 return self
._name
_pattern
131 def filter_expression(self
) -> Optional
[str]:
132 return self
._filter
_expression
135 def log_level_rule(self
) -> Optional
[LogLevelRule
]:
136 return self
._log
_level
_rule
139 def name_pattern_exclusions(self
) -> Optional
[List
[str]]:
140 return self
._name
_pattern
_exclusions
143 class UserTracepointEventRule(TracepointEventRule
):
146 name_pattern
: Optional
[str] = None,
147 filter_expression
: Optional
[str] = None,
148 log_level_rule
: Optional
[LogLevelRule
] = None,
149 name_pattern_exclusions
: Optional
[List
[str]] = None,
151 TracepointEventRule
.__init
__(**locals())
154 class KernelTracepointEventRule(TracepointEventRule
):
157 name_pattern
: Optional
[str] = None,
158 filter_expression
: Optional
[str] = None,
159 log_level_rule
: Optional
[LogLevelRule
] = None,
160 name_pattern_exclusions
: Optional
[List
[str]] = None,
162 TracepointEventRule
.__init
__(**locals())
165 class Channel(abc
.ABC
):
167 A channel is an object which is responsible for a set of ring buffers. It is
168 associated to a domain and
172 def _generate_name() -> str:
173 return "channel_{random_id}".format(random_id
=_generate_random_string(8))
176 def add_context(self
, context_type
: ContextType
) -> None:
181 def domain(self
) -> TracingDomain
:
186 def name(self
) -> str:
190 def add_recording_rule(self
, rule
: Type
[EventRule
]) -> None:
194 class SessionOutputLocation(abc
.ABC
):
198 class LocalSessionOutputLocation(SessionOutputLocation
):
199 def __init__(self
, trace_path
: pathlib
.Path
):
200 self
._path
= trace_path
203 def path(self
) -> pathlib
.Path
:
207 class ProcessAttributeTracker(abc
.ABC
):
209 Process attribute tracker used to filter before the evaluation of event
212 Note that this interface is currently limited as it doesn't allow changing
213 the tracking policy. For instance, it is not possible to set the tracking
214 policy back to "all" once it has transitioned to "include set".
218 class TrackingPolicy(enum
.Enum
):
220 Track all possible process attribute value of a given type (i.e. no filtering).
221 This is the default state of a process attribute tracker.
223 EXCLUDE_ALL
= "Exclude all possible process attribute values of a given type."
224 INCLUDE_SET
= "Track a set of specific process attribute values."
227 return "<%s.%s>" % (self
.__class
__.__name
__, self
.name
)
229 def __init__(self
, policy
: TrackingPolicy
):
230 self
._policy
= policy
233 def tracking_policy(self
) -> TrackingPolicy
:
237 class ProcessIDProcessAttributeTracker(ProcessAttributeTracker
):
239 def track(self
, pid
: int) -> None:
243 def untrack(self
, pid
: int) -> None:
247 class VirtualProcessIDProcessAttributeTracker(ProcessAttributeTracker
):
249 def track(self
, vpid
: int) -> None:
253 def untrack(self
, vpid
: int) -> None:
257 class UserIDProcessAttributeTracker(ProcessAttributeTracker
):
259 def track(self
, uid
: Union
[int, str]) -> None:
263 def untrack(self
, uid
: Union
[int, str]) -> None:
267 class VirtualUserIDProcessAttributeTracker(ProcessAttributeTracker
):
269 def track(self
, vuid
: Union
[int, str]) -> None:
273 def untrack(self
, vuid
: Union
[int, str]) -> None:
277 class GroupIDProcessAttributeTracker(ProcessAttributeTracker
):
279 def track(self
, gid
: Union
[int, str]) -> None:
283 def untrack(self
, gid
: Union
[int, str]) -> None:
287 class VirtualGroupIDProcessAttributeTracker(ProcessAttributeTracker
):
289 def track(self
, vgid
: Union
[int, str]) -> None:
293 def untrack(self
, vgid
: Union
[int, str]) -> None:
297 class Session(abc
.ABC
):
299 def _generate_name() -> str:
300 return "session_{random_id}".format(random_id
=_generate_random_string(8))
304 def name(self
) -> str:
309 def output(self
) -> Optional
[Type
[SessionOutputLocation
]]:
314 self
, domain
: TracingDomain
, channel_name
: Optional
[str] = None
316 """Add a channel with default attributes to the session."""
320 def start(self
) -> None:
324 def stop(self
) -> None:
328 def destroy(self
) -> None:
331 @abc.abstractproperty
332 def kernel_pid_process_attribute_tracker(
334 ) -> Type
[ProcessIDProcessAttributeTracker
]:
335 raise NotImplementedError
337 @abc.abstractproperty
338 def kernel_vpid_process_attribute_tracker(
340 ) -> Type
[VirtualProcessIDProcessAttributeTracker
]:
341 raise NotImplementedError
343 @abc.abstractproperty
344 def user_vpid_process_attribute_tracker(
346 ) -> Type
[VirtualProcessIDProcessAttributeTracker
]:
347 raise NotImplementedError
349 @abc.abstractproperty
350 def kernel_gid_process_attribute_tracker(
352 ) -> Type
[GroupIDProcessAttributeTracker
]:
353 raise NotImplementedError
355 @abc.abstractproperty
356 def kernel_vgid_process_attribute_tracker(
358 ) -> Type
[VirtualGroupIDProcessAttributeTracker
]:
359 raise NotImplementedError
361 @abc.abstractproperty
362 def user_vgid_process_attribute_tracker(
364 ) -> Type
[VirtualGroupIDProcessAttributeTracker
]:
365 raise NotImplementedError
367 @abc.abstractproperty
368 def kernel_uid_process_attribute_tracker(
370 ) -> Type
[UserIDProcessAttributeTracker
]:
371 raise NotImplementedError
373 @abc.abstractproperty
374 def kernel_vuid_process_attribute_tracker(
376 ) -> Type
[VirtualUserIDProcessAttributeTracker
]:
377 raise NotImplementedError
379 @abc.abstractproperty
380 def user_vuid_process_attribute_tracker(
382 ) -> Type
[VirtualUserIDProcessAttributeTracker
]:
383 raise NotImplementedError
386 class ControlException(RuntimeError):
387 """Base type for exceptions thrown by a controller."""
389 def __init__(self
, msg
: str):
390 super().__init
__(msg
)
393 class Controller(abc
.ABC
):
395 Interface of a top-level control interface. A control interface can be, for
396 example, the LTTng client or a wrapper around liblttng-ctl. It is used to
397 create and manage top-level objects of a session daemon instance.
402 self
, name
: Optional
[str] = None, output
: Optional
[SessionOutputLocation
] = None
405 Create a session with an output. Don't specify an output
406 to create a session without an output.