Commit | Line | Data |
---|---|---|
ef945e4d JG |
1 | #!/usr/bin/env python3 |
2 | # | |
3 | # Copyright (C) 2022 Jérémie Galarneau <jeremie.galarneau@efficios.com> | |
4 | # | |
5 | # SPDX-License-Identifier: GPL-2.0-only | |
6 | ||
7 | import abc | |
8 | import random | |
9 | import string | |
10 | import pathlib | |
11 | import enum | |
12 | from typing import Optional, Type, Union, List | |
13 | ||
14 | """ | |
15 | Defines an abstract interface to control LTTng tracing. | |
16 | ||
17 | The various control concepts are defined by this module. You can use them with a | |
18 | Controller to interact with a session daemon. | |
19 | ||
20 | This interface is not comprehensive; it currently provides a subset of the | |
21 | control functionality that is used by tests. | |
22 | """ | |
23 | ||
24 | ||
ce8470c9 MJ |
25 | def _generate_random_string(length): |
26 | # type: (int) -> str | |
ef945e4d JG |
27 | return "".join( |
28 | random.choice(string.ascii_lowercase + string.digits) for _ in range(length) | |
29 | ) | |
30 | ||
31 | ||
32 | class ContextType(abc.ABC): | |
33 | """Base class representing a tracing context field.""" | |
34 | ||
35 | pass | |
36 | ||
37 | ||
38 | class VpidContextType(ContextType): | |
39 | """Application's virtual process id.""" | |
40 | ||
41 | pass | |
42 | ||
43 | ||
44 | class VuidContextType(ContextType): | |
45 | """Application's virtual user id.""" | |
46 | ||
47 | pass | |
48 | ||
49 | ||
50 | class VgidContextType(ContextType): | |
51 | """Application's virtual group id.""" | |
52 | ||
53 | pass | |
54 | ||
55 | ||
56 | class JavaApplicationContextType(ContextType): | |
57 | """A java application-specific context field is a piece of state which the application provides.""" | |
58 | ||
ce8470c9 MJ |
59 | def __init__( |
60 | self, | |
61 | retriever_name, # type: str | |
62 | field_name, # type: str | |
63 | ): | |
64 | self._retriever_name = retriever_name # type: str | |
65 | self._field_name = field_name # type: str | |
ef945e4d JG |
66 | |
67 | @property | |
ce8470c9 MJ |
68 | def retriever_name(self): |
69 | # type: () -> str | |
ef945e4d JG |
70 | return self._retriever_name |
71 | ||
72 | @property | |
ce8470c9 MJ |
73 | def field_name(self): |
74 | # type: () -> str | |
ef945e4d JG |
75 | return self._field_name |
76 | ||
77 | ||
544d8425 | 78 | @enum.unique |
ef945e4d JG |
79 | class TracingDomain(enum.Enum): |
80 | """Tracing domain.""" | |
81 | ||
544d8425 MJ |
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." | |
87 | ||
88 | def __repr__(self): | |
89 | return "<%s.%s>" % (self.__class__.__name__, self.name) | |
ef945e4d JG |
90 | |
91 | ||
a631186c JG |
92 | @enum.unique |
93 | class BufferSharingPolicy(enum.Enum): | |
94 | """Buffer sharing policy.""" | |
95 | ||
96 | PerUID = "Per-UID buffering" | |
97 | PerPID = "Per-PID buffering" | |
98 | ||
99 | def __repr__(self): | |
100 | return "<%s.%s>" % (self.__class__.__name__, self.name) | |
101 | ||
102 | ||
ef945e4d JG |
103 | class EventRule(abc.ABC): |
104 | """Event rule base class, see LTTNG-EVENT-RULE(7).""" | |
105 | ||
106 | pass | |
107 | ||
108 | ||
109 | class LogLevelRule: | |
110 | pass | |
111 | ||
112 | ||
113 | class LogLevelRuleAsSevereAs(LogLevelRule): | |
ce8470c9 MJ |
114 | def __init__(self, level): |
115 | # type: (int) | |
ef945e4d JG |
116 | self._level = level |
117 | ||
118 | @property | |
ce8470c9 MJ |
119 | def level(self): |
120 | # type: () -> int | |
ef945e4d JG |
121 | return self._level |
122 | ||
123 | ||
124 | class LogLevelRuleExactly(LogLevelRule): | |
ce8470c9 MJ |
125 | def __init__(self, level): |
126 | # type: (int) | |
ef945e4d JG |
127 | self._level = level |
128 | ||
129 | @property | |
ce8470c9 MJ |
130 | def level(self): |
131 | # type: () -> int | |
ef945e4d JG |
132 | return self._level |
133 | ||
134 | ||
135 | class TracepointEventRule(EventRule): | |
136 | def __init__( | |
137 | self, | |
ce8470c9 MJ |
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]] | |
ef945e4d | 142 | ): |
ce8470c9 MJ |
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]] | |
ef945e4d JG |
149 | |
150 | @property | |
ce8470c9 MJ |
151 | def name_pattern(self): |
152 | # type: () -> Optional[str] | |
ef945e4d JG |
153 | return self._name_pattern |
154 | ||
155 | @property | |
ce8470c9 MJ |
156 | def filter_expression(self): |
157 | # type: () -> Optional[str] | |
ef945e4d JG |
158 | return self._filter_expression |
159 | ||
160 | @property | |
ce8470c9 MJ |
161 | def log_level_rule(self): |
162 | # type: () -> Optional[LogLevelRule] | |
ef945e4d JG |
163 | return self._log_level_rule |
164 | ||
165 | @property | |
ce8470c9 MJ |
166 | def name_pattern_exclusions(self): |
167 | # type: () -> Optional[List[str]] | |
ef945e4d JG |
168 | return self._name_pattern_exclusions |
169 | ||
170 | ||
171 | class UserTracepointEventRule(TracepointEventRule): | |
172 | def __init__( | |
173 | self, | |
ce8470c9 MJ |
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]] | |
ef945e4d JG |
178 | ): |
179 | TracepointEventRule.__init__(**locals()) | |
180 | ||
181 | ||
182 | class KernelTracepointEventRule(TracepointEventRule): | |
183 | def __init__( | |
184 | self, | |
ce8470c9 MJ |
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]] | |
ef945e4d JG |
189 | ): |
190 | TracepointEventRule.__init__(**locals()) | |
191 | ||
192 | ||
193 | class Channel(abc.ABC): | |
194 | """ | |
195 | A channel is an object which is responsible for a set of ring buffers. It is | |
196 | associated to a domain and | |
197 | """ | |
198 | ||
199 | @staticmethod | |
ce8470c9 MJ |
200 | def _generate_name(): |
201 | # type: () -> str | |
ef945e4d JG |
202 | return "channel_{random_id}".format(random_id=_generate_random_string(8)) |
203 | ||
204 | @abc.abstractmethod | |
ce8470c9 MJ |
205 | def add_context(self, context_type): |
206 | # type: (ContextType) -> None | |
ef945e4d JG |
207 | pass |
208 | ||
209 | @property | |
210 | @abc.abstractmethod | |
ce8470c9 MJ |
211 | def domain(self): |
212 | # type: () -> TracingDomain | |
ef945e4d JG |
213 | pass |
214 | ||
215 | @property | |
216 | @abc.abstractmethod | |
ce8470c9 MJ |
217 | def name(self): |
218 | # type: () -> str | |
ef945e4d JG |
219 | pass |
220 | ||
221 | @abc.abstractmethod | |
ce8470c9 MJ |
222 | def add_recording_rule(self, rule) -> None: |
223 | # type: (Type[EventRule]) -> None | |
ef945e4d JG |
224 | pass |
225 | ||
226 | ||
227 | class SessionOutputLocation(abc.ABC): | |
228 | pass | |
229 | ||
230 | ||
231 | class LocalSessionOutputLocation(SessionOutputLocation): | |
ce8470c9 MJ |
232 | def __init__(self, trace_path): |
233 | # type: (pathlib.Path) | |
ef945e4d JG |
234 | self._path = trace_path |
235 | ||
236 | @property | |
ce8470c9 MJ |
237 | def path(self): |
238 | # type: () -> pathlib.Path | |
ef945e4d JG |
239 | return self._path |
240 | ||
241 | ||
242 | class ProcessAttributeTracker(abc.ABC): | |
243 | """ | |
244 | Process attribute tracker used to filter before the evaluation of event | |
245 | rules. | |
246 | ||
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". | |
250 | """ | |
251 | ||
544d8425 | 252 | @enum.unique |
ef945e4d | 253 | class TrackingPolicy(enum.Enum): |
544d8425 | 254 | INCLUDE_ALL = """ |
ef945e4d JG |
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. | |
544d8425 MJ |
257 | """ |
258 | EXCLUDE_ALL = "Exclude all possible process attribute values of a given type." | |
259 | INCLUDE_SET = "Track a set of specific process attribute values." | |
260 | ||
261 | def __repr__(self): | |
262 | return "<%s.%s>" % (self.__class__.__name__, self.name) | |
ef945e4d | 263 | |
ce8470c9 MJ |
264 | def __init__(self, policy): |
265 | # type: (TrackingPolicy) | |
ef945e4d JG |
266 | self._policy = policy |
267 | ||
268 | @property | |
ce8470c9 MJ |
269 | def tracking_policy(self): |
270 | # type: () -> TrackingPolicy | |
ef945e4d JG |
271 | return self._policy |
272 | ||
273 | ||
274 | class ProcessIDProcessAttributeTracker(ProcessAttributeTracker): | |
275 | @abc.abstractmethod | |
ce8470c9 MJ |
276 | def track(self, pid): |
277 | # type: (int) -> None | |
ef945e4d JG |
278 | pass |
279 | ||
280 | @abc.abstractmethod | |
ce8470c9 MJ |
281 | def untrack(self, pid): |
282 | # type: (int) -> None | |
ef945e4d JG |
283 | pass |
284 | ||
285 | ||
286 | class VirtualProcessIDProcessAttributeTracker(ProcessAttributeTracker): | |
287 | @abc.abstractmethod | |
ce8470c9 MJ |
288 | def track(self, vpid): |
289 | # type: (int) -> None | |
ef945e4d JG |
290 | pass |
291 | ||
292 | @abc.abstractmethod | |
ce8470c9 MJ |
293 | def untrack(self, vpid): |
294 | # type: (int) -> None | |
ef945e4d JG |
295 | pass |
296 | ||
297 | ||
298 | class UserIDProcessAttributeTracker(ProcessAttributeTracker): | |
299 | @abc.abstractmethod | |
ce8470c9 MJ |
300 | def track(self, uid): |
301 | # type: (Union[int, str]) -> None | |
ef945e4d JG |
302 | pass |
303 | ||
304 | @abc.abstractmethod | |
ce8470c9 MJ |
305 | def untrack(self, uid): |
306 | # type: (Union[int, str]) -> None | |
ef945e4d JG |
307 | pass |
308 | ||
309 | ||
310 | class VirtualUserIDProcessAttributeTracker(ProcessAttributeTracker): | |
311 | @abc.abstractmethod | |
ce8470c9 MJ |
312 | def track(self, vuid): |
313 | # type: (Union[int, str]) -> None | |
ef945e4d JG |
314 | pass |
315 | ||
316 | @abc.abstractmethod | |
ce8470c9 MJ |
317 | def untrack(self, vuid): |
318 | # type: (Union[int, str]) -> None | |
ef945e4d JG |
319 | pass |
320 | ||
321 | ||
322 | class GroupIDProcessAttributeTracker(ProcessAttributeTracker): | |
323 | @abc.abstractmethod | |
ce8470c9 MJ |
324 | def track(self, gid): |
325 | # type: (Union[int, str]) -> None | |
ef945e4d JG |
326 | pass |
327 | ||
328 | @abc.abstractmethod | |
ce8470c9 MJ |
329 | def untrack(self, gid): |
330 | # type: (Union[int, str]) -> None | |
ef945e4d JG |
331 | pass |
332 | ||
333 | ||
334 | class VirtualGroupIDProcessAttributeTracker(ProcessAttributeTracker): | |
335 | @abc.abstractmethod | |
ce8470c9 MJ |
336 | def track(self, vgid): |
337 | # type: (Union[int, str]) -> None | |
ef945e4d JG |
338 | pass |
339 | ||
340 | @abc.abstractmethod | |
ce8470c9 MJ |
341 | def untrack(self, vgid): |
342 | # type: (Union[int, str]) -> None | |
ef945e4d JG |
343 | pass |
344 | ||
345 | ||
346 | class Session(abc.ABC): | |
347 | @staticmethod | |
ce8470c9 MJ |
348 | def _generate_name(): |
349 | # type: () -> str | |
ef945e4d JG |
350 | return "session_{random_id}".format(random_id=_generate_random_string(8)) |
351 | ||
352 | @property | |
353 | @abc.abstractmethod | |
ce8470c9 MJ |
354 | def name(self): |
355 | # type: () -> str | |
ef945e4d JG |
356 | pass |
357 | ||
358 | @property | |
359 | @abc.abstractmethod | |
ce8470c9 MJ |
360 | def output(self): |
361 | # type: () -> Optional[Type[SessionOutputLocation]] | |
ef945e4d JG |
362 | pass |
363 | ||
364 | @abc.abstractmethod | |
a631186c JG |
365 | def add_channel( |
366 | self, | |
367 | domain, | |
368 | channel_name=None, | |
369 | buffer_sharing_policy=BufferSharingPolicy.PerUID, | |
370 | ): | |
371 | # type: (TracingDomain, Optional[str], BufferSharingPolicy) -> Channel | |
ef945e4d JG |
372 | """Add a channel with default attributes to the session.""" |
373 | pass | |
374 | ||
375 | @abc.abstractmethod | |
ce8470c9 MJ |
376 | def start(self): |
377 | # type: () -> None | |
ef945e4d JG |
378 | pass |
379 | ||
380 | @abc.abstractmethod | |
ce8470c9 MJ |
381 | def stop(self): |
382 | # type: () -> None | |
ef945e4d JG |
383 | pass |
384 | ||
385 | @abc.abstractmethod | |
ce8470c9 MJ |
386 | def destroy(self): |
387 | # type: () -> None | |
ef945e4d JG |
388 | pass |
389 | ||
b9780062 JG |
390 | @abc.abstractmethod |
391 | def is_active(self): | |
392 | # type: () -> bool | |
393 | pass | |
394 | ||
ef945e4d | 395 | @abc.abstractproperty |
ce8470c9 MJ |
396 | def kernel_pid_process_attribute_tracker(self): |
397 | # type: () -> Type[ProcessIDProcessAttributeTracker] | |
ef945e4d JG |
398 | raise NotImplementedError |
399 | ||
400 | @abc.abstractproperty | |
ce8470c9 MJ |
401 | def kernel_vpid_process_attribute_tracker(self): |
402 | # type: () -> Type[VirtualProcessIDProcessAttributeTracker] | |
ef945e4d JG |
403 | raise NotImplementedError |
404 | ||
405 | @abc.abstractproperty | |
406 | def user_vpid_process_attribute_tracker( | |
407 | self, | |
408 | ) -> Type[VirtualProcessIDProcessAttributeTracker]: | |
ce8470c9 | 409 | # type: () -> Type[VirtualProcessIDProcessAttributeTracker] |
ef945e4d JG |
410 | raise NotImplementedError |
411 | ||
412 | @abc.abstractproperty | |
ce8470c9 MJ |
413 | def kernel_gid_process_attribute_tracker(self): |
414 | # type: () -> Type[GroupIDProcessAttributeTracker] | |
ef945e4d JG |
415 | raise NotImplementedError |
416 | ||
417 | @abc.abstractproperty | |
ce8470c9 MJ |
418 | def kernel_vgid_process_attribute_tracker(self): |
419 | # type: () -> Type[VirtualGroupIDProcessAttributeTracker] | |
ef945e4d JG |
420 | raise NotImplementedError |
421 | ||
422 | @abc.abstractproperty | |
ce8470c9 MJ |
423 | def user_vgid_process_attribute_tracker(self): |
424 | # type: () -> Type[VirtualGroupIDProcessAttributeTracker] | |
ef945e4d JG |
425 | raise NotImplementedError |
426 | ||
427 | @abc.abstractproperty | |
ce8470c9 MJ |
428 | def kernel_uid_process_attribute_tracker(self): |
429 | # type: () -> Type[UserIDProcessAttributeTracker] | |
ef945e4d JG |
430 | raise NotImplementedError |
431 | ||
432 | @abc.abstractproperty | |
ce8470c9 MJ |
433 | def kernel_vuid_process_attribute_tracker(self): |
434 | # type: () -> Type[VirtualUserIDProcessAttributeTracker] | |
ef945e4d JG |
435 | raise NotImplementedError |
436 | ||
437 | @abc.abstractproperty | |
ce8470c9 MJ |
438 | def user_vuid_process_attribute_tracker(self): |
439 | # type: () -> Type[VirtualUserIDProcessAttributeTracker] | |
ef945e4d JG |
440 | raise NotImplementedError |
441 | ||
442 | ||
443 | class ControlException(RuntimeError): | |
444 | """Base type for exceptions thrown by a controller.""" | |
445 | ||
ce8470c9 MJ |
446 | def __init__(self, msg): |
447 | # type: (str) | |
ef945e4d JG |
448 | super().__init__(msg) |
449 | ||
450 | ||
451 | class Controller(abc.ABC): | |
452 | """ | |
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. | |
456 | """ | |
457 | ||
458 | @abc.abstractmethod | |
ce8470c9 MJ |
459 | def create_session(self, name=None, output=None): |
460 | # type: (Optional[str], Optional[SessionOutputLocation]) -> Session | |
ef945e4d JG |
461 | """ |
462 | Create a session with an output. Don't specify an output | |
463 | to create a session without an output. | |
464 | """ | |
465 | pass | |
b9780062 JG |
466 | |
467 | @abc.abstractmethod | |
468 | def start_session_by_name(self, name): | |
469 | # type: (str) -> None | |
470 | """ | |
471 | Start a session by name. | |
472 | """ | |
473 | pass | |
474 | ||
475 | @abc.abstractmethod | |
476 | def start_session_by_glob_pattern(self, pattern): | |
477 | # type: (str) -> None | |
478 | """ | |
479 | Start sessions whose name matches `pattern`, see GLOB(7). | |
480 | """ | |
481 | pass | |
482 | ||
483 | @abc.abstractmethod | |
484 | def start_sessions_all(self): | |
485 | """ | |
486 | Start all sessions visible to the current user. | |
487 | """ | |
488 | # type: () -> None | |
489 | pass | |
490 | ||
491 | @abc.abstractmethod | |
492 | def stop_session_by_name(self, name): | |
493 | # type: (str) -> None | |
494 | """ | |
495 | Stop a session by name. | |
496 | """ | |
497 | pass | |
498 | ||
499 | @abc.abstractmethod | |
500 | def stop_session_by_glob_pattern(self, pattern): | |
501 | # type: (str) -> None | |
502 | """ | |
503 | Stop sessions whose name matches `pattern`, see GLOB(7). | |
504 | """ | |
505 | pass | |
506 | ||
507 | @abc.abstractmethod | |
508 | def stop_sessions_all(self): | |
509 | """ | |
510 | Stop all sessions visible to the current user. | |
511 | """ | |
512 | # type: () -> None | |
513 | pass | |
514 | ||
515 | @abc.abstractmethod | |
516 | def destroy_session_by_name(self, name): | |
517 | # type: (str) -> None | |
518 | """ | |
519 | Destroy a session by name. | |
520 | """ | |
521 | pass | |
522 | ||
523 | @abc.abstractmethod | |
524 | def destroy_session_by_glob_pattern(self, pattern): | |
525 | # type: (str) -> None | |
526 | """ | |
527 | Destroy sessions whose name matches `pattern`, see GLOB(7). | |
528 | """ | |
529 | pass | |
530 | ||
531 | @abc.abstractmethod | |
532 | def destroy_sessions_all(self): | |
533 | # type: () -> None | |
534 | """ | |
535 | Destroy all sessions visible to the current user. | |
536 | """ | |
537 | pass | |
538 | ||
539 | @abc.abstractmethod | |
540 | def list_sessions(self): | |
541 | # type: () -> List[Session] | |
542 | """ | |
543 | List all sessions visible to the current user. | |
544 | """ | |
545 | pass |