[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
        pass

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

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

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


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
        pass

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


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

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


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

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


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

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


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

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


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

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


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
        pass

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

    @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."""
        pass

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

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

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

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

    @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.
        """
        pass

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

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

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

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

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

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

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

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

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

    @abc.abstractmethod
    def list_sessions(self):
        # type: () -> List[Session]
        """
        List all sessions visible to the current user.
        """
        pass
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
ef945e4d JG	207	pass
	208
	209	@property
	210	@abc.abstractmethod
ce8470c9 MJ	211	def domain(self):
ce8470c9 MJ	212	# type: () -> TracingDomain
ef945e4d JG	213	pass
	214
	215	@property
	216	@abc.abstractmethod
ce8470c9 MJ	217	def name(self):
ce8470c9 MJ	218	# type: () -> str
ef945e4d JG	219	pass
	220
	221	@abc.abstractmethod
ce8470c9 MJ	222	def add_recording_rule(self, rule) -> None:
ce8470c9 MJ	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):
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
ef945e4d JG	278	pass
	279
	280	@abc.abstractmethod
ce8470c9 MJ	281	def untrack(self, pid):
ce8470c9 MJ	282	# type: (int) -> None
ef945e4d JG	283	pass
	284
	285
	286	class VirtualProcessIDProcessAttributeTracker(ProcessAttributeTracker):
	287	@abc.abstractmethod
ce8470c9 MJ	288	def track(self, vpid):
ce8470c9 MJ	289	# type: (int) -> None
ef945e4d JG	290	pass
	291
	292	@abc.abstractmethod
ce8470c9 MJ	293	def untrack(self, vpid):
ce8470c9 MJ	294	# type: (int) -> None
ef945e4d JG	295	pass
	296
	297
	298	class UserIDProcessAttributeTracker(ProcessAttributeTracker):
	299	@abc.abstractmethod
ce8470c9 MJ	300	def track(self, uid):
ce8470c9 MJ	301	# type: (Union[int, str]) -> None
ef945e4d JG	302	pass
	303
	304	@abc.abstractmethod
ce8470c9 MJ	305	def untrack(self, uid):
ce8470c9 MJ	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):
ce8470c9 MJ	313	# type: (Union[int, str]) -> None
ef945e4d JG	314	pass
	315
	316	@abc.abstractmethod
ce8470c9 MJ	317	def untrack(self, vuid):
ce8470c9 MJ	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):
ce8470c9 MJ	325	# type: (Union[int, str]) -> None
ef945e4d JG	326	pass
	327
	328	@abc.abstractmethod
ce8470c9 MJ	329	def untrack(self, gid):
ce8470c9 MJ	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):
ce8470c9 MJ	337	# type: (Union[int, str]) -> None
ef945e4d JG	338	pass
	339
	340	@abc.abstractmethod
ce8470c9 MJ	341	def untrack(self, vgid):
ce8470c9 MJ	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():
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
ef945e4d JG	356	pass
	357
	358	@property
	359	@abc.abstractmethod
ce8470c9 MJ	360	def output(self):
ce8470c9 MJ	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):
ce8470c9 MJ	377	# type: () -> None
ef945e4d JG	378	pass
	379
	380	@abc.abstractmethod
ce8470c9 MJ	381	def stop(self):
ce8470c9 MJ	382	# type: () -> None
ef945e4d JG	383	pass
	384
	385	@abc.abstractmethod
ce8470c9 MJ	386	def destroy(self):
ce8470c9 MJ	387	# type: () -> None
ef945e4d JG	388	pass
ef945e4d JG	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):
ce8470c9 MJ	397	# type: () -> Type[ProcessIDProcessAttributeTracker]
ef945e4d JG	398	raise NotImplementedError
	399
	400	@abc.abstractproperty
ce8470c9 MJ	401	def kernel_vpid_process_attribute_tracker(self):
ce8470c9 MJ	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):
ce8470c9 MJ	414	# type: () -> Type[GroupIDProcessAttributeTracker]
ef945e4d JG	415	raise NotImplementedError
	416
	417	@abc.abstractproperty
ce8470c9 MJ	418	def kernel_vgid_process_attribute_tracker(self):
ce8470c9 MJ	419	# type: () -> Type[VirtualGroupIDProcessAttributeTracker]
ef945e4d JG	420	raise NotImplementedError
	421
	422	@abc.abstractproperty
ce8470c9 MJ	423	def user_vgid_process_attribute_tracker(self):
ce8470c9 MJ	424	# type: () -> Type[VirtualGroupIDProcessAttributeTracker]
ef945e4d JG	425	raise NotImplementedError
	426
	427	@abc.abstractproperty
ce8470c9 MJ	428	def kernel_uid_process_attribute_tracker(self):
ce8470c9 MJ	429	# type: () -> Type[UserIDProcessAttributeTracker]
ef945e4d JG	430	raise NotImplementedError
	431
	432	@abc.abstractproperty
ce8470c9 MJ	433	def kernel_vuid_process_attribute_tracker(self):
ce8470c9 MJ	434	# type: () -> Type[VirtualUserIDProcessAttributeTracker]
ef945e4d JG	435	raise NotImplementedError
	436
	437	@abc.abstractproperty
ce8470c9 MJ	438	def user_vuid_process_attribute_tracker(self):
ce8470c9 MJ	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):
ce8470c9 MJ	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):
ce8470c9 MJ	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