[lttng-tools.git] / tests / utils / lttngtest / lttngctl.py

#!/usr/bin/env python3
#
# Copyright (C) 2022 Jérémie Galarneau <jeremie.galarneau@efficios.com>
#
# SPDX-License-Identifier: GPL-2.0-only

import abc
import random
import string
import pathlib
import enum
from typing import Optional, Type, Union, List

"""
Defines an abstract interface to control LTTng tracing.

The various control concepts are defined by this module. You can use them with a
Controller to interact with a session daemon.

This interface is not comprehensive; it currently provides a subset of the
control functionality that is used by tests.
"""


def _generate_random_string(length):
    # type: (int) -> str
    return "".join(
        random.choice(string.ascii_lowercase + string.digits) for _ in range(length)
    )


class ContextType(abc.ABC):
    """Base class representing a tracing context field."""

    pass


class VpidContextType(ContextType):
    """Application's virtual process id."""

    pass


class VuidContextType(ContextType):
    """Application's virtual user id."""

    pass


class VgidContextType(ContextType):
    """Application's virtual group id."""

    pass


class JavaApplicationContextType(ContextType):
    """A java application-specific context field is a piece of state which the application provides."""

    def __init__(
        self,
        retriever_name,  # type: str
        field_name,  # type: str
    ):
        self._retriever_name = retriever_name  # type: str
        self._field_name = field_name  # type: str

    @property
    def retriever_name(self):
        # type: () -> str
        return self._retriever_name

    @property
    def field_name(self):
        # type: () -> str
        return self._field_name


@enum.unique
class TracingDomain(enum.Enum):
    """Tracing domain."""

    User = "User space tracing domain"
    Kernel = "Linux kernel tracing domain."
    Log4j = "Log4j tracing back-end."
    JUL = "Java Util Logging tracing back-end."
    Python = "Python logging module tracing back-end."

    def __repr__(self):
        return "<%s.%s>" % (self.__class__.__name__, self.name)


@enum.unique
class BufferSharingPolicy(enum.Enum):
    """Buffer sharing policy."""

    PerUID = "Per-UID buffering"
    PerPID = "Per-PID buffering"

    def __repr__(self):
        return "<%s.%s>" % (self.__class__.__name__, self.name)


class EventRule(abc.ABC):
    """Event rule base class, see LTTNG-EVENT-RULE(7)."""

    pass


class LogLevelRule:
    pass


class LogLevelRuleAsSevereAs(LogLevelRule):
    def __init__(self, level):
        # type: (int)
        self._level = level

    @property
    def level(self):
        # type: () -> int
        return self._level


class LogLevelRuleExactly(LogLevelRule):
    def __init__(self, level):
        # type: (int)
        self._level = level

    @property
    def level(self):
        # type: () -> int
        return self._level


class TracepointEventRule(EventRule):
    def __init__(
        self,
        name_pattern=None,  # type: Optional[str]
        filter_expression=None,  # type: Optional[str]
        log_level_rule=None,  # type: Optional[LogLevelRule]
        name_pattern_exclusions=None,  # type: Optional[List[str]]
    ):
        self._name_pattern = name_pattern  # type: Optional[str]
        self._filter_expression = filter_expression  # type: Optional[str]
        self._log_level_rule = log_level_rule  # type: Optional[LogLevelRule]
        self._name_pattern_exclusions = (
            name_pattern_exclusions
        )  # type: Optional[List[str]]

    @property
    def name_pattern(self):
        # type: () -> Optional[str]
        return self._name_pattern

    @property
    def filter_expression(self):
        # type: () -> Optional[str]
        return self._filter_expression

    @property
    def log_level_rule(self):
        # type: () -> Optional[LogLevelRule]
        return self._log_level_rule

    @property
    def name_pattern_exclusions(self):
        # type: () -> Optional[List[str]]
        return self._name_pattern_exclusions


class UserTracepointEventRule(TracepointEventRule):
    def __init__(
        self,
        name_pattern=None,  # type: Optional[str]
        filter_expression=None,  # type: Optional[str]
        log_level_rule=None,  # type: Optional[LogLevelRule]
        name_pattern_exclusions=None,  # type: Optional[List[str]]
    ):
        TracepointEventRule.__init__(**locals())


class KernelTracepointEventRule(TracepointEventRule):
    def __init__(
        self,
        name_pattern=None,  # type: Optional[str]
        filter_expression=None,  # type: Optional[str]
        log_level_rule=None,  # type: Optional[LogLevelRule]
        name_pattern_exclusions=None,  # type: Optional[List[str]]
    ):
        TracepointEventRule.__init__(**locals())


class Channel(abc.ABC):
    """
    A channel is an object which is responsible for a set of ring buffers. It is
    associated to a domain and
    """

    @staticmethod
    def _generate_name():
        # type: () -> str
        return "channel_{random_id}".format(random_id=_generate_random_string(8))

    @abc.abstractmethod
    def add_context(self, context_type):
        # type: (ContextType) -> None
        raise NotImplementedError

    @property
    @abc.abstractmethod
    def domain(self):
        # type: () -> TracingDomain
        raise NotImplementedError

    @property
    @abc.abstractmethod
    def name(self):
        # type: () -> str
        raise NotImplementedError

    @abc.abstractmethod
    def add_recording_rule(self, rule) -> None:
        # type: (Type[EventRule]) -> None
        raise NotImplementedError


class SessionOutputLocation(abc.ABC):
    pass


class LocalSessionOutputLocation(SessionOutputLocation):
    def __init__(self, trace_path):
        # type: (pathlib.Path)
        self._path = trace_path

    @property
    def path(self):
        # type: () -> pathlib.Path
        return self._path


class ProcessAttributeTracker(abc.ABC):
    """
    Process attribute tracker used to filter before the evaluation of event
    rules.

    Note that this interface is currently limited as it doesn't allow changing
    the tracking policy. For instance, it is not possible to set the tracking
    policy back to "all" once it has transitioned to "include set".
    """

    @enum.unique
    class TrackingPolicy(enum.Enum):
        INCLUDE_ALL = """
            Track all possible process attribute value of a given type (i.e. no filtering).
            This is the default state of a process attribute tracker.
            """
        EXCLUDE_ALL = "Exclude all possible process attribute values of a given type."
        INCLUDE_SET = "Track a set of specific process attribute values."

        def __repr__(self):
            return "<%s.%s>" % (self.__class__.__name__, self.name)

    def __init__(self, policy):
        # type: (TrackingPolicy)
        self._policy = policy

    @property
    def tracking_policy(self):
        # type: () -> TrackingPolicy
        return self._policy


class ProcessIDProcessAttributeTracker(ProcessAttributeTracker):
    @abc.abstractmethod
    def track(self, pid):
        # type: (int) -> None
        raise NotImplementedError

    @abc.abstractmethod
    def untrack(self, pid):
        # type: (int) -> None
        raise NotImplementedError


class VirtualProcessIDProcessAttributeTracker(ProcessAttributeTracker):
    @abc.abstractmethod
    def track(self, vpid):
        # type: (int) -> None
        raise NotImplementedError

    @abc.abstractmethod
    def untrack(self, vpid):
        # type: (int) -> None
        raise NotImplementedError


class UserIDProcessAttributeTracker(ProcessAttributeTracker):
    @abc.abstractmethod
    def track(self, uid):
        # type: (Union[int, str]) -> None
        raise NotImplementedError

    @abc.abstractmethod
    def untrack(self, uid):
        # type: (Union[int, str]) -> None
        raise NotImplementedError


class VirtualUserIDProcessAttributeTracker(ProcessAttributeTracker):
    @abc.abstractmethod
    def track(self, vuid):
        # type: (Union[int, str]) -> None
        raise NotImplementedError

    @abc.abstractmethod
    def untrack(self, vuid):
        # type: (Union[int, str]) -> None
        raise NotImplementedError


class GroupIDProcessAttributeTracker(ProcessAttributeTracker):
    @abc.abstractmethod
    def track(self, gid):
        # type: (Union[int, str]) -> None
        raise NotImplementedError

    @abc.abstractmethod
    def untrack(self, gid):
        # type: (Union[int, str]) -> None
        raise NotImplementedError


class VirtualGroupIDProcessAttributeTracker(ProcessAttributeTracker):
    @abc.abstractmethod
    def track(self, vgid):
        # type: (Union[int, str]) -> None
        raise NotImplementedError

    @abc.abstractmethod
    def untrack(self, vgid):
        # type: (Union[int, str]) -> None
        raise NotImplementedError


class Session(abc.ABC):
    @staticmethod
    def _generate_name():
        # type: () -> str
        return "session_{random_id}".format(random_id=_generate_random_string(8))

    @property
    @abc.abstractmethod
    def name(self):
        # type: () -> str
        raise NotImplementedError

    @property
    @abc.abstractmethod
    def output(self):
        # type: () -> Optional[Type[SessionOutputLocation]]
        raise NotImplementedError

    @abc.abstractmethod
    def add_channel(
        self,
        domain,
        channel_name=None,
        buffer_sharing_policy=BufferSharingPolicy.PerUID,
    ):
        # type: (TracingDomain, Optional[str], BufferSharingPolicy) -> Channel
        """Add a channel with default attributes to the session."""
        raise NotImplementedError

    @abc.abstractmethod
    def start(self):
        # type: () -> None
        raise NotImplementedError

    @abc.abstractmethod
    def stop(self):
        # type: () -> None
        raise NotImplementedError

    @abc.abstractmethod
    def destroy(self):
        # type: () -> None
        raise NotImplementedError

    @abc.abstractmethod
    def is_active(self):
        # type: () -> bool
        raise NotImplementedError

    @abc.abstractmethod
    def rotate(self):
        # type: () -> None
        raise NotImplementedError

    @abc.abstractproperty
    def kernel_pid_process_attribute_tracker(self):
        # type: () -> Type[ProcessIDProcessAttributeTracker]
        raise NotImplementedError

    @abc.abstractproperty
    def kernel_vpid_process_attribute_tracker(self):
        # type: () -> Type[VirtualProcessIDProcessAttributeTracker]
        raise NotImplementedError

    @abc.abstractproperty
    def user_vpid_process_attribute_tracker(
        self,
    ) -> Type[VirtualProcessIDProcessAttributeTracker]:
        # type: () -> Type[VirtualProcessIDProcessAttributeTracker]
        raise NotImplementedError

    @abc.abstractproperty
    def kernel_gid_process_attribute_tracker(self):
        # type: () -> Type[GroupIDProcessAttributeTracker]
        raise NotImplementedError

    @abc.abstractproperty
    def kernel_vgid_process_attribute_tracker(self):
        # type: () -> Type[VirtualGroupIDProcessAttributeTracker]
        raise NotImplementedError

    @abc.abstractproperty
    def user_vgid_process_attribute_tracker(self):
        # type: () -> Type[VirtualGroupIDProcessAttributeTracker]
        raise NotImplementedError

    @abc.abstractproperty
    def kernel_uid_process_attribute_tracker(self):
        # type: () -> Type[UserIDProcessAttributeTracker]
        raise NotImplementedError

    @abc.abstractproperty
    def kernel_vuid_process_attribute_tracker(self):
        # type: () -> Type[VirtualUserIDProcessAttributeTracker]
        raise NotImplementedError

    @abc.abstractproperty
    def user_vuid_process_attribute_tracker(self):
        # type: () -> Type[VirtualUserIDProcessAttributeTracker]
        raise NotImplementedError


class ControlException(RuntimeError):
    """Base type for exceptions thrown by a controller."""

    def __init__(self, msg):
        # type: (str)
        super().__init__(msg)


class Controller(abc.ABC):
    """
    Interface of a top-level control interface. A control interface can be, for
    example, the LTTng client or a wrapper around liblttng-ctl. It is used to
    create and manage top-level objects of a session daemon instance.
    """

    @abc.abstractmethod
    def create_session(self, name=None, output=None):
        # type: (Optional[str], Optional[SessionOutputLocation]) -> Session
        """
        Create a session with an output. Don't specify an output
        to create a session without an output.
        """
        raise NotImplementedError

    @abc.abstractmethod
    def start_session_by_name(self, name):
        # type: (str) -> None
        """
        Start a session by name.
        """
        raise NotImplementedError

    @abc.abstractmethod
    def start_session_by_glob_pattern(self, pattern):
        # type: (str) -> None
        """
        Start sessions whose name matches `pattern`, see GLOB(7).
        """
        raise NotImplementedError

    @abc.abstractmethod
    def start_sessions_all(self):
        """
        Start all sessions visible to the current user.
        """
        # type: () -> None
        raise NotImplementedError

    @abc.abstractmethod
    def stop_session_by_name(self, name):
        # type: (str) -> None
        """
        Stop a session by name.
        """
        raise NotImplementedError

    @abc.abstractmethod
    def stop_session_by_glob_pattern(self, pattern):
        # type: (str) -> None
        """
        Stop sessions whose name matches `pattern`, see GLOB(7).
        """
        raise NotImplementedError

    @abc.abstractmethod
    def stop_sessions_all(self):
        """
        Stop all sessions visible to the current user.
        """
        # type: () -> None
        raise NotImplementedError

    @abc.abstractmethod
    def destroy_session_by_name(self, name):
        # type: (str) -> None
        """
        Destroy a session by name.
        """
        raise NotImplementedError

    @abc.abstractmethod
    def destroy_session_by_glob_pattern(self, pattern):
        # type: (str) -> None
        """
        Destroy sessions whose name matches `pattern`, see GLOB(7).
        """
        raise NotImplementedError

    @abc.abstractmethod
    def destroy_sessions_all(self):
        # type: () -> None
        """
        Destroy all sessions visible to the current user.
        """
        raise NotImplementedError

    @abc.abstractmethod
    def list_sessions(self):
        # type: () -> List[Session]
        """
        List all sessions visible to the current user.
        """
        raise NotImplementedError

    @abc.abstractmethod
    def rotate_session_by_name(self, name, wait=True):
        # type: (str, bool) -> None
        """
        Rotate a session
        """
        raise NotImplementedError

    @abc.abstractmethod
    def schedule_size_based_rotation(self, name, size_bytes):
        # type: (str, int) -> None
        """
        Schedule automatic size-based rotations.
        """
        raise NotImplementedError

    @abc.abstractmethod
    def schedule_time_based_rotation(self, name, period_seconds):
        # type: (str, int) -> None
        """
        Schedule automatic time-based rotations.
        """
        raise NotImplementedError
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):
ce8470c9 MJ	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
ef945e4d JG	67	@property
ce8470c9 MJ	68	def retriever_name(self):
ce8470c9 MJ	69	# type: () -> str
ef945e4d JG	70	return self._retriever_name
	71
	72	@property
ce8470c9 MJ	73	def field_name(self):
ce8470c9 MJ	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
ef945e4d JG	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):
ce8470c9 MJ	115	# type: (int)
ef945e4d JG	116	self._level = level
	117
	118	@property
ce8470c9 MJ	119	def level(self):
ce8470c9 MJ	120	# type: () -> int
ef945e4d JG	121	return self._level
	122
	123
	124	class LogLevelRuleExactly(LogLevelRule):
ce8470c9 MJ	125	def __init__(self, level):
ce8470c9 MJ	126	# type: (int)
ef945e4d JG	127	self._level = level
	128
	129	@property
ce8470c9 MJ	130	def level(self):
ce8470c9 MJ	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
ef945e4d JG	150	@property
ce8470c9 MJ	151	def name_pattern(self):
ce8470c9 MJ	152	# type: () -> Optional[str]
ef945e4d JG	153	return self._name_pattern
	154
	155	@property
ce8470c9 MJ	156	def filter_expression(self):
ce8470c9 MJ	157	# type: () -> Optional[str]
ef945e4d JG	158	return self._filter_expression
	159
	160	@property
ce8470c9 MJ	161	def log_level_rule(self):
ce8470c9 MJ	162	# type: () -> Optional[LogLevelRule]
ef945e4d JG	163	return self._log_level_rule
	164
	165	@property
ce8470c9 MJ	166	def name_pattern_exclusions(self):
ce8470c9 MJ	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():
ce8470c9 MJ	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):
ce8470c9 MJ	206	# type: (ContextType) -> None
fe3442d8	207	raise NotImplementedError
ef945e4d JG	208
	209	@property
	210	@abc.abstractmethod
ce8470c9 MJ	211	def domain(self):
ce8470c9 MJ	212	# type: () -> TracingDomain
fe3442d8	213	raise NotImplementedError
ef945e4d JG	214
	215	@property
	216	@abc.abstractmethod
ce8470c9 MJ	217	def name(self):
ce8470c9 MJ	218	# type: () -> str
fe3442d8	219	raise NotImplementedError
ef945e4d JG	220
ef945e4d JG	221	@abc.abstractmethod
ce8470c9 MJ	222	def add_recording_rule(self, rule) -> None:
ce8470c9 MJ	223	# type: (Type[EventRule]) -> None
fe3442d8	224	raise NotImplementedError
ef945e4d JG	225
	226
	227	class SessionOutputLocation(abc.ABC):
	228	pass
	229
	230
	231	class LocalSessionOutputLocation(SessionOutputLocation):
ce8470c9 MJ	232	def __init__(self, trace_path):
ce8470c9 MJ	233	# type: (pathlib.Path)
ef945e4d JG	234	self._path = trace_path
	235
	236	@property
ce8470c9 MJ	237	def path(self):
ce8470c9 MJ	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).
ef945e4d JG	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):
ce8470c9 MJ	265	# type: (TrackingPolicy)
ef945e4d JG	266	self._policy = policy
	267
	268	@property
ce8470c9 MJ	269	def tracking_policy(self):
ce8470c9 MJ	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):
ce8470c9 MJ	277	# type: (int) -> None
fe3442d8	278	raise NotImplementedError
ef945e4d JG	279
ef945e4d JG	280	@abc.abstractmethod
ce8470c9 MJ	281	def untrack(self, pid):
ce8470c9 MJ	282	# type: (int) -> None
fe3442d8	283	raise NotImplementedError
ef945e4d JG	284
	285
	286	class VirtualProcessIDProcessAttributeTracker(ProcessAttributeTracker):
	287	@abc.abstractmethod
ce8470c9 MJ	288	def track(self, vpid):
ce8470c9 MJ	289	# type: (int) -> None
fe3442d8	290	raise NotImplementedError
ef945e4d JG	291
ef945e4d JG	292	@abc.abstractmethod
ce8470c9 MJ	293	def untrack(self, vpid):
ce8470c9 MJ	294	# type: (int) -> None
fe3442d8	295	raise NotImplementedError
ef945e4d JG	296
	297
	298	class UserIDProcessAttributeTracker(ProcessAttributeTracker):
	299	@abc.abstractmethod
ce8470c9 MJ	300	def track(self, uid):
ce8470c9 MJ	301	# type: (Union[int, str]) -> None
fe3442d8	302	raise NotImplementedError
ef945e4d JG	303
ef945e4d JG	304	@abc.abstractmethod
ce8470c9 MJ	305	def untrack(self, uid):
ce8470c9 MJ	306	# type: (Union[int, str]) -> None
fe3442d8	307	raise NotImplementedError
ef945e4d JG	308
	309
	310	class VirtualUserIDProcessAttributeTracker(ProcessAttributeTracker):
	311	@abc.abstractmethod
ce8470c9 MJ	312	def track(self, vuid):
ce8470c9 MJ	313	# type: (Union[int, str]) -> None
fe3442d8	314	raise NotImplementedError
ef945e4d JG	315
ef945e4d JG	316	@abc.abstractmethod
ce8470c9 MJ	317	def untrack(self, vuid):
ce8470c9 MJ	318	# type: (Union[int, str]) -> None
fe3442d8	319	raise NotImplementedError
ef945e4d JG	320
	321
	322	class GroupIDProcessAttributeTracker(ProcessAttributeTracker):
	323	@abc.abstractmethod
ce8470c9 MJ	324	def track(self, gid):
ce8470c9 MJ	325	# type: (Union[int, str]) -> None
fe3442d8	326	raise NotImplementedError
ef945e4d JG	327
ef945e4d JG	328	@abc.abstractmethod
ce8470c9 MJ	329	def untrack(self, gid):
ce8470c9 MJ	330	# type: (Union[int, str]) -> None
fe3442d8	331	raise NotImplementedError
ef945e4d JG	332
	333
	334	class VirtualGroupIDProcessAttributeTracker(ProcessAttributeTracker):
	335	@abc.abstractmethod
ce8470c9 MJ	336	def track(self, vgid):
ce8470c9 MJ	337	# type: (Union[int, str]) -> None
fe3442d8	338	raise NotImplementedError
ef945e4d JG	339
ef945e4d JG	340	@abc.abstractmethod
ce8470c9 MJ	341	def untrack(self, vgid):
ce8470c9 MJ	342	# type: (Union[int, str]) -> None
fe3442d8	343	raise NotImplementedError
ef945e4d JG	344
	345
	346	class Session(abc.ABC):
	347	@staticmethod
ce8470c9 MJ	348	def _generate_name():
ce8470c9 MJ	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):
ce8470c9 MJ	355	# type: () -> str
fe3442d8	356	raise NotImplementedError
ef945e4d JG	357
	358	@property
	359	@abc.abstractmethod
ce8470c9 MJ	360	def output(self):
ce8470c9 MJ	361	# type: () -> Optional[Type[SessionOutputLocation]]
fe3442d8	362	raise NotImplementedError
ef945e4d JG	363
ef945e4d JG	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	372	"""Add a channel with default attributes to the session."""
fe3442d8	373	raise NotImplementedError
ef945e4d JG	374
ef945e4d JG	375	@abc.abstractmethod
ce8470c9 MJ	376	def start(self):
ce8470c9 MJ	377	# type: () -> None
fe3442d8	378	raise NotImplementedError
ef945e4d JG	379
ef945e4d JG	380	@abc.abstractmethod
ce8470c9 MJ	381	def stop(self):
ce8470c9 MJ	382	# type: () -> None
fe3442d8	383	raise NotImplementedError
ef945e4d JG	384
ef945e4d JG	385	@abc.abstractmethod
ce8470c9 MJ	386	def destroy(self):
ce8470c9 MJ	387	# type: () -> None
fe3442d8	388	raise NotImplementedError
ef945e4d	389
b9780062 JG	390	@abc.abstractmethod
	391	def is_active(self):
	392	# type: () -> bool
fe3442d8	393	raise NotImplementedError
b9780062	394
a8cac44b JG	395	@abc.abstractmethod
	396	def rotate(self):
	397	# type: () -> None
	398	raise NotImplementedError
	399
ef945e4d	400	@abc.abstractproperty
ce8470c9 MJ	401	def kernel_pid_process_attribute_tracker(self):
ce8470c9 MJ	402	# type: () -> Type[ProcessIDProcessAttributeTracker]
ef945e4d JG	403	raise NotImplementedError
	404
	405	@abc.abstractproperty
ce8470c9 MJ	406	def kernel_vpid_process_attribute_tracker(self):
ce8470c9 MJ	407	# type: () -> Type[VirtualProcessIDProcessAttributeTracker]
ef945e4d JG	408	raise NotImplementedError
	409
	410	@abc.abstractproperty
	411	def user_vpid_process_attribute_tracker(
	412	self,
	413	) -> Type[VirtualProcessIDProcessAttributeTracker]:
ce8470c9	414	# type: () -> Type[VirtualProcessIDProcessAttributeTracker]
ef945e4d JG	415	raise NotImplementedError
	416
	417	@abc.abstractproperty
ce8470c9 MJ	418	def kernel_gid_process_attribute_tracker(self):
ce8470c9 MJ	419	# type: () -> Type[GroupIDProcessAttributeTracker]
ef945e4d JG	420	raise NotImplementedError
	421
	422	@abc.abstractproperty
ce8470c9 MJ	423	def kernel_vgid_process_attribute_tracker(self):
ce8470c9 MJ	424	# type: () -> Type[VirtualGroupIDProcessAttributeTracker]
ef945e4d JG	425	raise NotImplementedError
	426
	427	@abc.abstractproperty
ce8470c9 MJ	428	def user_vgid_process_attribute_tracker(self):
ce8470c9 MJ	429	# type: () -> Type[VirtualGroupIDProcessAttributeTracker]
ef945e4d JG	430	raise NotImplementedError
	431
	432	@abc.abstractproperty
ce8470c9 MJ	433	def kernel_uid_process_attribute_tracker(self):
ce8470c9 MJ	434	# type: () -> Type[UserIDProcessAttributeTracker]
ef945e4d JG	435	raise NotImplementedError
	436
	437	@abc.abstractproperty
ce8470c9 MJ	438	def kernel_vuid_process_attribute_tracker(self):
ce8470c9 MJ	439	# type: () -> Type[VirtualUserIDProcessAttributeTracker]
ef945e4d JG	440	raise NotImplementedError
	441
	442	@abc.abstractproperty
ce8470c9 MJ	443	def user_vuid_process_attribute_tracker(self):
ce8470c9 MJ	444	# type: () -> Type[VirtualUserIDProcessAttributeTracker]
ef945e4d JG	445	raise NotImplementedError
	446
	447
	448	class ControlException(RuntimeError):
	449	"""Base type for exceptions thrown by a controller."""
	450
ce8470c9 MJ	451	def __init__(self, msg):
ce8470c9 MJ	452	# type: (str)
ef945e4d JG	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
ce8470c9 MJ	464	def create_session(self, name=None, output=None):
ce8470c9 MJ	465	# type: (Optional[str], Optional[SessionOutputLocation]) -> Session
ef945e4d JG	466	"""
	467	Create a session with an output. Don't specify an output
	468	to create a session without an output.
	469	"""
fe3442d8	470	raise NotImplementedError
b9780062 JG	471
	472	@abc.abstractmethod
	473	def start_session_by_name(self, name):
	474	# type: (str) -> None
	475	"""
	476	Start a session by name.
	477	"""
fe3442d8	478	raise NotImplementedError
b9780062 JG	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	"""
fe3442d8	486	raise NotImplementedError
b9780062 JG	487
	488	@abc.abstractmethod
	489	def start_sessions_all(self):
	490	"""
	491	Start all sessions visible to the current user.
	492	"""
	493	# type: () -> None
fe3442d8	494	raise NotImplementedError
b9780062 JG	495
	496	@abc.abstractmethod
	497	def stop_session_by_name(self, name):
	498	# type: (str) -> None
	499	"""
	500	Stop a session by name.
	501	"""
fe3442d8	502	raise NotImplementedError
b9780062 JG	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	"""
fe3442d8	510	raise NotImplementedError
b9780062 JG	511
	512	@abc.abstractmethod
	513	def stop_sessions_all(self):
	514	"""
	515	Stop all sessions visible to the current user.
	516	"""
	517	# type: () -> None
fe3442d8	518	raise NotImplementedError
b9780062 JG	519
	520	@abc.abstractmethod
	521	def destroy_session_by_name(self, name):
	522	# type: (str) -> None
	523	"""
	524	Destroy a session by name.
	525	"""
fe3442d8	526	raise NotImplementedError
b9780062 JG	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	"""
fe3442d8	534	raise NotImplementedError
b9780062 JG	535
	536	@abc.abstractmethod
	537	def destroy_sessions_all(self):
	538	# type: () -> None
	539	"""
	540	Destroy all sessions visible to the current user.
	541	"""
fe3442d8	542	raise NotImplementedError
b9780062 JG	543
	544	@abc.abstractmethod
	545	def list_sessions(self):
	546	# type: () -> List[Session]
	547	"""
	548	List all sessions visible to the current user.
	549	"""
fe3442d8	550	raise NotImplementedError
a8cac44b JG	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