tests/utils/lttngtest/lttngctl.py

   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
  25 def _generate_random_string(length):
  26     # type: (int) -> str
  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
  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
  66
  67     @property
  68     def retriever_name(self):
  69         # type: () -> str
  70         return self._retriever_name
  71
  72     @property
  73     def field_name(self):
  74         # type: () -> str
  75         return self._field_name
  76
  77
  78 @enum.unique
  79 class TracingDomain(enum.Enum):
  80     """Tracing domain."""
  81
  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)
  90
  91
  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
 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):
 114     def __init__(self, level):
 115         # type: (int)
 116         self._level = level
 117
 118     @property
 119     def level(self):
 120         # type: () -> int
 121         return self._level
 122
 123
 124 class LogLevelRuleExactly(LogLevelRule):
 125     def __init__(self, level):
 126         # type: (int)
 127         self._level = level
 128
 129     @property
 130     def level(self):
 131         # type: () -> int
 132         return self._level
 133
 134
 135 class TracepointEventRule(EventRule):
 136     def __init__(
 137         self,
 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]]
 142     ):
 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]]
 149
 150     @property
 151     def name_pattern(self):
 152         # type: () -> Optional[str]
 153         return self._name_pattern
 154
 155     @property
 156     def filter_expression(self):
 157         # type: () -> Optional[str]
 158         return self._filter_expression
 159
 160     @property
 161     def log_level_rule(self):
 162         # type: () -> Optional[LogLevelRule]
 163         return self._log_level_rule
 164
 165     @property
 166     def name_pattern_exclusions(self):
 167         # type: () -> Optional[List[str]]
 168         return self._name_pattern_exclusions
 169
 170
 171 class UserTracepointEventRule(TracepointEventRule):
 172     def __init__(
 173         self,
 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]]
 178     ):
 179         TracepointEventRule.__init__(**locals())
 180
 181
 182 class KernelTracepointEventRule(TracepointEventRule):
 183     def __init__(
 184         self,
 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]]
 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
 200     def _generate_name():
 201         # type: () -> str
 202         return "channel_{random_id}".format(random_id=_generate_random_string(8))
 203
 204     @abc.abstractmethod
 205     def add_context(self, context_type):
 206         # type: (ContextType) -> None
 207         pass
 208
 209     @property
 210     @abc.abstractmethod
 211     def domain(self):
 212         # type: () -> TracingDomain
 213         pass
 214
 215     @property
 216     @abc.abstractmethod
 217     def name(self):
 218         # type: () -> str
 219         pass
 220
 221     @abc.abstractmethod
 222     def add_recording_rule(self, rule) -> None:
 223         # type: (Type[EventRule]) -> None
 224         pass
 225
 226
 227 class SessionOutputLocation(abc.ABC):
 228     pass
 229
 230
 231 class LocalSessionOutputLocation(SessionOutputLocation):
 232     def __init__(self, trace_path):
 233         # type: (pathlib.Path)
 234         self._path = trace_path
 235
 236     @property
 237     def path(self):
 238         # type: () -> pathlib.Path
 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
 252     @enum.unique
 253     class TrackingPolicy(enum.Enum):
 254         INCLUDE_ALL = """
 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.
 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)
 263
 264     def __init__(self, policy):
 265         # type: (TrackingPolicy)
 266         self._policy = policy
 267
 268     @property
 269     def tracking_policy(self):
 270         # type: () -> TrackingPolicy
 271         return self._policy
 272
 273
 274 class ProcessIDProcessAttributeTracker(ProcessAttributeTracker):
 275     @abc.abstractmethod
 276     def track(self, pid):
 277         # type: (int) -> None
 278         pass
 279
 280     @abc.abstractmethod
 281     def untrack(self, pid):
 282         # type: (int) -> None
 283         pass
 284
 285
 286 class VirtualProcessIDProcessAttributeTracker(ProcessAttributeTracker):
 287     @abc.abstractmethod
 288     def track(self, vpid):
 289         # type: (int) -> None
 290         pass
 291
 292     @abc.abstractmethod
 293     def untrack(self, vpid):
 294         # type: (int) -> None
 295         pass
 296
 297
 298 class UserIDProcessAttributeTracker(ProcessAttributeTracker):
 299     @abc.abstractmethod
 300     def track(self, uid):
 301         # type: (Union[int, str]) -> None
 302         pass
 303
 304     @abc.abstractmethod
 305     def untrack(self, uid):
 306         # type: (Union[int, str]) -> None
 307         pass
 308
 309
 310 class VirtualUserIDProcessAttributeTracker(ProcessAttributeTracker):
 311     @abc.abstractmethod
 312     def track(self, vuid):
 313         # type: (Union[int, str]) -> None
 314         pass
 315
 316     @abc.abstractmethod
 317     def untrack(self, vuid):
 318         # type: (Union[int, str]) -> None
 319         pass
 320
 321
 322 class GroupIDProcessAttributeTracker(ProcessAttributeTracker):
 323     @abc.abstractmethod
 324     def track(self, gid):
 325         # type: (Union[int, str]) -> None
 326         pass
 327
 328     @abc.abstractmethod
 329     def untrack(self, gid):
 330         # type: (Union[int, str]) -> None
 331         pass
 332
 333
 334 class VirtualGroupIDProcessAttributeTracker(ProcessAttributeTracker):
 335     @abc.abstractmethod
 336     def track(self, vgid):
 337         # type: (Union[int, str]) -> None
 338         pass
 339
 340     @abc.abstractmethod
 341     def untrack(self, vgid):
 342         # type: (Union[int, str]) -> None
 343         pass
 344
 345
 346 class Session(abc.ABC):
 347     @staticmethod
 348     def _generate_name():
 349         # type: () -> str
 350         return "session_{random_id}".format(random_id=_generate_random_string(8))
 351
 352     @property
 353     @abc.abstractmethod
 354     def name(self):
 355         # type: () -> str
 356         pass
 357
 358     @property
 359     @abc.abstractmethod
 360     def output(self):
 361         # type: () -> Optional[Type[SessionOutputLocation]]
 362         pass
 363
 364     @abc.abstractmethod
 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
 372         """Add a channel with default attributes to the session."""
 373         pass
 374
 375     @abc.abstractmethod
 376     def start(self):
 377         # type: () -> None
 378         pass
 379
 380     @abc.abstractmethod
 381     def stop(self):
 382         # type: () -> None
 383         pass
 384
 385     @abc.abstractmethod
 386     def destroy(self):
 387         # type: () -> None
 388         pass
 389
 390     @abc.abstractmethod
 391     def is_active(self):
 392         # type: () -> bool
 393         pass
 394
 395     @abc.abstractmethod
 396     def rotate(self):
 397         # type: () -> None
 398         raise NotImplementedError
 399
 400     @abc.abstractproperty
 401     def kernel_pid_process_attribute_tracker(self):
 402         # type: () -> Type[ProcessIDProcessAttributeTracker]
 403         raise NotImplementedError
 404
 405     @abc.abstractproperty
 406     def kernel_vpid_process_attribute_tracker(self):
 407         # type: () -> Type[VirtualProcessIDProcessAttributeTracker]
 408         raise NotImplementedError
 409
 410     @abc.abstractproperty
 411     def user_vpid_process_attribute_tracker(
 412         self,
 413     ) -> Type[VirtualProcessIDProcessAttributeTracker]:
 414         # type: () -> Type[VirtualProcessIDProcessAttributeTracker]
 415         raise NotImplementedError
 416
 417     @abc.abstractproperty
 418     def kernel_gid_process_attribute_tracker(self):
 419         # type: () -> Type[GroupIDProcessAttributeTracker]
 420         raise NotImplementedError
 421
 422     @abc.abstractproperty
 423     def kernel_vgid_process_attribute_tracker(self):
 424         # type: () -> Type[VirtualGroupIDProcessAttributeTracker]
 425         raise NotImplementedError
 426
 427     @abc.abstractproperty
 428     def user_vgid_process_attribute_tracker(self):
 429         # type: () -> Type[VirtualGroupIDProcessAttributeTracker]
 430         raise NotImplementedError
 431
 432     @abc.abstractproperty
 433     def kernel_uid_process_attribute_tracker(self):
 434         # type: () -> Type[UserIDProcessAttributeTracker]
 435         raise NotImplementedError
 436
 437     @abc.abstractproperty
 438     def kernel_vuid_process_attribute_tracker(self):
 439         # type: () -> Type[VirtualUserIDProcessAttributeTracker]
 440         raise NotImplementedError
 441
 442     @abc.abstractproperty
 443     def user_vuid_process_attribute_tracker(self):
 444         # type: () -> Type[VirtualUserIDProcessAttributeTracker]
 445         raise NotImplementedError
 446
 447
 448 class ControlException(RuntimeError):
 449     """Base type for exceptions thrown by a controller."""
 450
 451     def __init__(self, msg):
 452         # type: (str)
 453         super().__init__(msg)
 454
 455
 456 class Controller(abc.ABC):
 457     """
 458     Interface of a top-level control interface. A control interface can be, for
 459     example, the LTTng client or a wrapper around liblttng-ctl. It is used to
 460     create and manage top-level objects of a session daemon instance.
 461     """
 462
 463     @abc.abstractmethod
 464     def create_session(self, name=None, output=None):
 465         # type: (Optional[str], Optional[SessionOutputLocation]) -> Session
 466         """
 467         Create a session with an output. Don't specify an output
 468         to create a session without an output.
 469         """
 470         pass
 471
 472     @abc.abstractmethod
 473     def start_session_by_name(self, name):
 474         # type: (str) -> None
 475         """
 476         Start a session by name.
 477         """
 478         pass
 479
 480     @abc.abstractmethod
 481     def start_session_by_glob_pattern(self, pattern):
 482         # type: (str) -> None
 483         """
 484         Start sessions whose name matches `pattern`, see GLOB(7).
 485         """
 486         pass
 487
 488     @abc.abstractmethod
 489     def start_sessions_all(self):
 490         """
 491         Start all sessions visible to the current user.
 492         """
 493         # type: () -> None
 494         pass
 495
 496     @abc.abstractmethod
 497     def stop_session_by_name(self, name):
 498         # type: (str) -> None
 499         """
 500         Stop a session by name.
 501         """
 502         pass
 503
 504     @abc.abstractmethod
 505     def stop_session_by_glob_pattern(self, pattern):
 506         # type: (str) -> None
 507         """
 508         Stop sessions whose name matches `pattern`, see GLOB(7).
 509         """
 510         pass
 511
 512     @abc.abstractmethod
 513     def stop_sessions_all(self):
 514         """
 515         Stop all sessions visible to the current user.
 516         """
 517         # type: () -> None
 518         pass
 519
 520     @abc.abstractmethod
 521     def destroy_session_by_name(self, name):
 522         # type: (str) -> None
 523         """
 524         Destroy a session by name.
 525         """
 526         pass
 527
 528     @abc.abstractmethod
 529     def destroy_session_by_glob_pattern(self, pattern):
 530         # type: (str) -> None
 531         """
 532         Destroy sessions whose name matches `pattern`, see GLOB(7).
 533         """
 534         pass
 535
 536     @abc.abstractmethod
 537     def destroy_sessions_all(self):
 538         # type: () -> None
 539         """
 540         Destroy all sessions visible to the current user.
 541         """
 542         pass
 543
 544     @abc.abstractmethod
 545     def list_sessions(self):
 546         # type: () -> List[Session]
 547         """
 548         List all sessions visible to the current user.
 549         """
 550         pass
 551
 552     @abc.abstractmethod
 553     def rotate_session_by_name(self, name, wait=True):
 554         # type: (str, bool) -> None
 555         """
 556         Rotate a session
 557         """
 558         raise NotImplementedError
 559
 560     @abc.abstractmethod
 561     def schedule_size_based_rotation(self, name, size_bytes):
 562         # type: (str, int) -> None
 563         """
 564         Schedule automatic size-based rotations.
 565         """
 566         raise NotImplementedError
 567
 568     @abc.abstractmethod
 569     def schedule_time_based_rotation(self, name, period_seconds):
 570         # type: (str, int) -> None
 571         """
 572         Schedule automatic time-based rotations.
 573         """
 574         raise NotImplementedError