lsst.dax.apdb.monitor.MonService Class Reference

Inheritance diagram for lsst.dax.apdb.monitor.MonService:

Public Member Functions
None	set_filters (self, Iterable[str] rules)
Iterable[MonHandler]	handlers (self)
None	add_handler (self, MonHandler handler)
None	remove_handler (self, MonHandler handler)
Iterator[None]	context_tags (self, _TagsType tags)

Protected Member Functions
None	_add_record (self, *, str agent_name, str record_name, Mapping[str, Any] values, Mapping[str, str|int]|None tags=None, float|None timestamp=None)
None	_default_init (self)
_TagsType|None	_add_context_tags (self, _TagsType tags)

Static Protected Attributes
list	_handlers = []
_TagsType	_context_tags = None
list	_filters = []
bool	_initialized = False

Detailed Description

Class implementing monitoring service functionality.

Notes
-----
This is a singleton class which serves all client agents in an application.
It accepts records from agents, filters it based on a set of configured
rules and forwards them to one or more configured handlers. By default
there are no handlers defined which means that all records are discarded.
Default set of filtering rules is empty which accepts all agent names.

To produce a useful output from this service one has to add at least one
handler using `add_handler` method (e.g. `LoggingMonHandler` instance).
The `set_filters` methods can be used to specify the set of filtering
rules.

Definition at line 193 of file monitor.py.

Member Function Documentation

_add_context_tags()

_TagsType | None lsst.dax.apdb.monitor.MonService._add_context_tags ( self, _TagsType tags )

protected

Extend the tag context with new tags, overriding any tags that may
already exist in a current context.

Definition at line 361 of file monitor.py.

    def _add_context_tags(self, tags: _TagsType) -> _TagsType | None:
        """Extend the tag context with new tags, overriding any tags that may
        already exist in a current context.
        """
        old_tags = self._context_tags
        if not self._context_tags:
            self._context_tags = tags
        else:
            all_tags = dict(self._context_tags)
            all_tags.update(tags)
            self._context_tags = all_tags
        return old_tags
 

_add_record()

None lsst.dax.apdb.monitor.MonService._add_record ( self, * , str agent_name, str record_name, Mapping[str, Any] values, Mapping[str, str | int] | None tags = None, float | None timestamp = None )

protected

Add one monitoring record, this method is for use by agents only.

Definition at line 259 of file monitor.py.

    ) -> None:
        """Add one monitoring record, this method is for use by agents only."""
        if not self._initialized:
            try:
                self._default_init()
                self._initialized = True
            except Exception as exc:
                # Complain but continue.
                message = f"Error in configuration of monitoring service: {exc}"
                # Stack level does not really matter.
                warnings.warn(message, stacklevel=3)
        if self._handlers:
            accept: bool | None = None
            # Check every filter, accept if none makes any decision.
            for filter in self._filters:
                accept = filter.accept(agent_name)
                if accept is False:
                    return
                if accept is True:
                    break
            if timestamp is None:
                timestamp = time.time()
            if tags is None:
                tags = self._context_tags or {}
            else:
                if self._context_tags:
                    all_tags = dict(self._context_tags)
                    all_tags.update(tags)
                    tags = all_tags
            for handler in self._handlers:
                handler.handle(record_name, timestamp, tags, values, agent_name)
 

_default_init()

None lsst.dax.apdb.monitor.MonService._default_init ( self )

protected

Perform default initialization of the service.

Definition at line 299 of file monitor.py.

    def _default_init(self) -> None:
        """Perform default initialization of the service."""
        if env := os.environ.get(_CONFIG_ENV):
            # Configuration is specified as colon-separated list of key:value
            # pairs or simple values. Simple values are treated as filters
            # (see set_filters for syntax). key-values pairs pairs specify
            # handlers, for now the only supported handler is logging, it
            # is specified as "logging:<logger-name>[:<level>]".
            filters = []
            handlers: list[MonHandler] = []
            for item in env.split(","):
                pieces = item.split(":")
                if len(pieces) in (2, 3) and pieces[0] == "logging":
                    logger_name = pieces[1]
                    if len(pieces) == 3:
                        level_name = pieces[2]
                        level = logging.getLevelNamesMapping().get(level_name.upper())
                        if level is None:
                            raise ValueError(
                                f"Unknown logging level name {level_name!r} in {_CONFIG_ENV}={env!r}"
                            )
                    else:
                        level = logging.INFO
                    handlers.append(LoggingMonHandler(logger_name, level))
                elif len(pieces) == 1:
                    filters.extend(pieces)
                else:
                    raise ValueError(f"Unexpected format of item {item!r} in {_CONFIG_ENV}={env!r}")
            for handler in handlers:
                self.add_handler(handler)
            self.set_filters(filters)
 

add_handler()

None lsst.dax.apdb.monitor.MonService.add_handler	(		self,
		MonHandler	handler )

Add one monitoring handler.

Parameters
----------
handler : `MonHandler`
    Handler instance.

Definition at line 336 of file monitor.py.

    def add_handler(self, handler: MonHandler) -> None:
        """Add one monitoring handler.
 
        Parameters
        ----------
        handler : `MonHandler`
            Handler instance.
        """
        # Manually adding handler means default initialization should be
        # skipped.
        self._initialized = True
        if handler not in self._handlers:
            self._handlers.append(handler)
 

context_tags()

Iterator[None] lsst.dax.apdb.monitor.MonService.context_tags	(		self,
		_TagsType	tags )

Context manager that adds a set of tags to all records created
inside the context.

Typically clients will be using `MonAgent.context_tags`, which forwards
to this method.

Definition at line 375 of file monitor.py.

    def context_tags(self, tags: _TagsType) -> Iterator[None]:
        """Context manager that adds a set of tags to all records created
        inside the context.
 
        Typically clients will be using `MonAgent.context_tags`, which forwards
        to this method.
        """
        old_context = self._add_context_tags(tags)
        try:
            yield
        finally:
            # Restore old context.
            self._context_tags = old_context
 
 

handlers()

Iterable[MonHandler] lsst.dax.apdb.monitor.MonService.handlers

(

self

)

Set of handlers defined currently.

Definition at line 332 of file monitor.py.

    def handlers(self) -> Iterable[MonHandler]:
        """Set of handlers defined currently."""
        return self._handlers
 

remove_handler()

None lsst.dax.apdb.monitor.MonService.remove_handler	(		self,
		MonHandler	handler )

Remove a monitoring handler.

Parameters
----------
handler : `MonHandler`
    Handler instance.

Definition at line 350 of file monitor.py.

    def remove_handler(self, handler: MonHandler) -> None:
        """Remove a monitoring handler.
 
        Parameters
        ----------
        handler : `MonHandler`
            Handler instance.
        """
        if handler in self._handlers:
            self._handlers.remove(handler)
 

set_filters()

None lsst.dax.apdb.monitor.MonService.set_filters	(		self,
		Iterable[str]	rules )

Define a sequence of rules for filtering of the agent names.

Parameters
----------
rules : `~collections.abc.Iterable` [`str`]
    Ordered collection of rules.  Each string specifies filtering rule
    for a single name, or catch-all rule.  The rule consist of the
    agent name prefixed by minus or optional plus sign. Catch-all rule
    uses name "any". If the rule starts with minus sign then matching
    agent will be rejected. Otherwise matching agent is accepted.

Notes
-----
The catch-all rule (`-any`, `+any`, or `any`) can be specified in any
location in the sequence but it is always applied last. E.g.
`["-any", "+agent1"]` behaves the same as `["+agent1", "-any"]`.
If the set of rues does not include catch-all rule, filtering behaves
as if it is added implicitly as `+any`.

Filtering code evaluates each rule in order. First rule that matches
the agent name wins. Agent names are matched literally, wildcards are
not supported and there are no parent/child relations between agent
names (e.g `lsst.dax.apdb` and `lsst.dax.apdb.sql` are treated as
independent names).

Definition at line 222 of file monitor.py.

    def set_filters(self, rules: Iterable[str]) -> None:
        """Define a sequence of rules for filtering of the agent names.
 
        Parameters
        ----------
        rules : `~collections.abc.Iterable` [`str`]
            Ordered collection of rules.  Each string specifies filtering rule
            for a single name, or catch-all rule.  The rule consist of the
            agent name prefixed by minus or optional plus sign. Catch-all rule
            uses name "any". If the rule starts with minus sign then matching
            agent will be rejected. Otherwise matching agent is accepted.
 
        Notes
        -----
        The catch-all rule (`-any`, `+any`, or `any`) can be specified in any
        location in the sequence but it is always applied last. E.g.
        `["-any", "+agent1"]` behaves the same as `["+agent1", "-any"]`.
        If the set of rues does not include catch-all rule, filtering behaves
        as if it is added implicitly as `+any`.
 
        Filtering code evaluates each rule in order. First rule that matches
        the agent name wins. Agent names are matched literally, wildcards are
        not supported and there are no parent/child relations between agent
        names (e.g `lsst.dax.apdb` and `lsst.dax.apdb.sql` are treated as
        independent names).
        """
        match_all: MonFilter | None = None
        self._filters = []
        for rule in rules:
            mon_filter = MonFilter(rule)
            if mon_filter.is_match_all():
                match_all = mon_filter
            else:
                self._filters.append(mon_filter)
        if match_all:
            self._filters.append(match_all)
 

Member Data Documentation

_context_tags

_TagsType lsst.dax.apdb.monitor.MonService._context_tags = None

staticprotected

Definition at line 213 of file monitor.py.

_filters

list lsst.dax.apdb.monitor.MonService._filters = []

staticprotected

Definition at line 216 of file monitor.py.

_handlers

list lsst.dax.apdb.monitor.MonService._handlers = []

staticprotected

Definition at line 210 of file monitor.py.

_initialized

bool lsst.dax.apdb.monitor.MonService._initialized = False

staticprotected

Definition at line 219 of file monitor.py.

---

The documentation for this class was generated from the following file:

• /j/snowflake/release/lsstsw/stack/lsst-scipipe-12.1.0/Linux/dax_apdb/gb88ae4c679+7dec8f19df/python/lsst/dax/apdb/monitor.py