Session Trees

package

diffusion.features.control.metrics

Classes
  • Metrics — This feature allows a client to configure metric collectors.
class

diffusion.features.control.metrics.Metrics(session)

Bases
diffusion.internal.components.Component

This feature allows a client to configure metric collectors.

Diffusion servers provide metrics which are made available in several ways:-

  • Java Management Extensions (JMX) MBeans.
  • Through the Diffusion Management Console.
  • endpoints for Prometheus.

Metric collectors allow custom aggregation of metrics that are relevant to your application. There are no default metric collectors, only the ones that you create.

There are two types of metric collector: Session Metric Collectors and Topic Metric Collectors.

For full details regarding the configuration and operation of metric collectors see the user manual.

Session Metric Collectors

These can be configured to record metric data for a subset of all sessions, specified with a session filter.

The set of metrics recorded by each session metric collector is the same as those recorded for the whole server. For full details of session metrics, see the table in the user manual.

If the session filters of two different session metric collectors select the same session, both will record metrics for that session. It is only valid to add the metrics of different session metric collectors if their session filters select distinct sets of sessions.

You can optionally group the sessions within a collector by session properties.

Topic Metric Collectors

These can be configured to record metric data for a subset of all topics, specified with a topic selector.

You can optionally group the topics within a collector by topic type.

The set of metrics recorded by each topic metric collector is the same as those recorded for the whole server. For full details of topic metrics, see the table in the user manual.

If the topic selectors of two different topic metric collectors select the same topic, both will record metrics for that topic. It is only valid to add the metrics of different topic metric collectors if their topic selectors select distinct sets of topics.

Access control

The following access control restrictions are applied:

  • To put (put_session_metric_collector) or remove (remove_session_metric_collector) a session metric collector, a session needs the CONTROL_SERVER global permission.
  • To put (put_topic_metric_collector) or remove (remove_topic_metric_collector) a topic metric collector, a session needs the CONTROL_SERVER global permission.
  • To list session metric collectors (list_session_metric_collectors) or topic metric collectors (list_topic_metric_collectors), a session needs the VIEW_SERVER global permission.

Accessing the feature

This feature may be obtained from a Session as follows:

metrics: Metrics = session.metrics()
Attributes
  • services (ServiceLocator) — Alias for the internal session's service locator.
Methods
method
put_session_metric_collector(collector)

Add a session metric collector, replacing any with the same name.

Parameters
  • collector (SessionMetricCollector) — the session metric collector
Raises
  • InvalidSessionFilterError — if the metric collector session filter is invalid;
  • ServerDisconnectedError — if the session is disconnected.
method
list_session_metric_collectors()

Retrieves the current session metric collectors.

Returns (list of SessionMetricCollector)

a list of current session metric collectors.

Raises
  • ServerDisconnectedError — if the session is disconnected.
method
remove_session_metric_collector(name)

Removes any session metric collector with the given name, if it exists.

Parameters
  • name (str) — the session metric collector name
Raises
  • ServerDisconnectedError — if the session is disconnected.
method
put_topic_metric_collector(collector)

Add a topic metric collector, replacing any with the same name.

A TopicMetricCollector instance can be created using TopicMetricCollectorBuilder.

Parameters
  • collector (TopicMetricCollector) — the topic metric collector
Raises
  • ServerDisconnectedError — if the session is disconnected.
method
list_topic_metric_collectors()

Retrieves the current topic metric collectors.

Returns (list of TopicMetricCollector)

a list of current topic metric collectors.

Raises
  • ServerDisconnectedError — if the session is disconnected.
method
remove_topic_metric_collector(name)

Removes any topic metric collector with the given name, if it exists.

Parameters
  • name (str) — the topic metric collector name
Raises
  • ServerDisconnectedError — if the session is disconnected.
module

diffusion.features.control.metrics.session_metrics

Classes
class

diffusion.features.control.metrics.session_metrics.SessionMetricCollector(name='', exports_to_prometheus=False, maximum_groups=2147483647, removes_metrics_with_no_matches=False, session_filter=None, group_by_properties=[])

Bases
diffusion.features.control.metrics.collector.MetricCollector diffusion.internal.serialisers.pydantic.MarshalledModel diffusion.internal.utils.Model pydantic.main.BaseModel pydantic.utils.Representation

The definition of a session metric collector.

These can be configured to record metric data for a subset of all sessions, specified with a session filter.

Classes
  • Config — Adds Serialiser support to Model.Config 'alias' defines the name of the serialiser to map to
  • Config — Adds Serialiser support to Model.Config 'alias' defines the name of the serialiser to map to
class
Config()
Bases
diffusion.internal.serialisers.pydantic.MarshalledModel.Config diffusion.internal.utils.Model.Config

Adds Serialiser support to Model.Config 'alias' defines the name of the serialiser to map to

class
diffusion.features.control.metrics.session_metrics.Config()
Bases
diffusion.features.control.metrics.session_metrics.SessionMetricCollector.Config diffusion.features.control.metrics.session_metrics.Config diffusion.features.control.metrics.collector.Config diffusion.features.control.metrics.collector.Config diffusion.internal.serialisers.pydantic.Config diffusion.internal.serialisers.pydantic.MarshalledModel.Config diffusion.internal.serialisers.pydantic.Config diffusion.internal.utils.Config diffusion.internal.utils.Model.Config pydantic.config.BaseConfig

Adds Serialiser support to Model.Config 'alias' defines the name of the serialiser to map to

class

diffusion.features.control.metrics.session_metrics.SessionMetricCollectorBuilder(*args, **kwds)

Bases
diffusion.internal.utils.SessionMetricCollectorBuilderBase typing.Generic

A session metric collector builder.

It is used to create instances of SessionMetricCollector that can be supplied to Metrics.put_session_metric_collector.

Classes
Methods
  • __init_subclass__(*args, **kwargs) — This method is called when a class is subclassed.
  • create(name, session_filter) (SessionMetricCollector) — Create a new SessionMetricCollector using the values currently known to this builder.
  • export_to_prometheus(export) (Self) — Specifies whether the metric collector should export metrics to Prometheus or not.
  • group_by_properties(*property_names) (Self) — Specifies a list of session property names to group by, replacing any current list known to this builder.
  • group_by_property(property_name) (Self) — Adds the name of a session property to group by to the list known to this builder.
  • remove_metrics_with_no_matches(remove) (Self) — Specifies whether the metric collector should remove any metrics that have no matches.
  • reset() (SessionMetricCollectorBuilder) — Reset the builder.
classmethod
__init_subclass__(*args, **kwargs)

This method is called when a class is subclassed.

The default implementation does nothing. It may be overridden to extend subclasses.

class

diffusion.features.control.metrics.session_metrics.SessionMetricCollector(name='', exports_to_prometheus=False, maximum_groups=2147483647, removes_metrics_with_no_matches=False, session_filter=None, group_by_properties=[])

Bases
diffusion.features.control.metrics.collector.MetricCollector diffusion.internal.serialisers.pydantic.MarshalledModel diffusion.internal.utils.Model pydantic.main.BaseModel pydantic.utils.Representation

The definition of a session metric collector.

These can be configured to record metric data for a subset of all sessions, specified with a session filter.

Classes
  • Config — Adds Serialiser support to Model.Config 'alias' defines the name of the serialiser to map to
  • Config — Adds Serialiser support to Model.Config 'alias' defines the name of the serialiser to map to
class
Config()
Bases
diffusion.internal.serialisers.pydantic.MarshalledModel.Config diffusion.internal.utils.Model.Config

Adds Serialiser support to Model.Config 'alias' defines the name of the serialiser to map to

class
diffusion.features.control.metrics.session_metrics.Config()
Bases
diffusion.features.control.metrics.session_metrics.SessionMetricCollector.Config diffusion.features.control.metrics.session_metrics.Config diffusion.features.control.metrics.collector.Config diffusion.features.control.metrics.collector.Config diffusion.internal.serialisers.pydantic.Config diffusion.internal.serialisers.pydantic.MarshalledModel.Config diffusion.internal.serialisers.pydantic.Config diffusion.internal.utils.Config diffusion.internal.utils.Model.Config pydantic.config.BaseConfig

Adds Serialiser support to Model.Config 'alias' defines the name of the serialiser to map to

method
export_to_prometheus(export)

Specifies whether the metric collector should export metrics to Prometheus or not.

The default is that metrics are not exported to Prometheus.

Parameters
  • export (bool) — True to export metrics to Prometheus
Returns (Self)

this builder

method
group_by_property(property_name)

Adds the name of a session property to group by to the list known to this builder.

By default a builder will initially have no session properties to group by set.

Parameters
  • property_name (str) — the name of the session property. See Session for details of session properties
Returns (Self)

this builder

method
group_by_properties(*property_names)

Specifies a list of session property names to group by, replacing any current list known to this builder.

Parameters
  • property_names — a list of session property names. See Session for details of session properties
Returns (Self)

this builder

method
remove_metrics_with_no_matches(remove)

Specifies whether the metric collector should remove any metrics that have no matches.

The default is that the metric collector will not remove metrics with no matches.

Parameters
  • remove (bool) — True to indicate that metrics with no matches should be removed
Returns (Self)

this builder

method
create(name, session_filter) → SessionMetricCollector

Create a new SessionMetricCollector using the values currently known to this builder.

Parameters
  • name (str) — the name of the SessionMetricCollector
  • session_filter (str) — the session filter indicating the sessions this collector should apply to. The format of a session property filter is documented in {@link Session}

Returns: a new SessionMetricCollector with all of the current settings of this builder

method
reset()

Reset the builder.

Returns (SessionMetricCollectorBuilder)

this builder

module

diffusion.features.control.metrics.topic_metrics

Classes
class

diffusion.features.control.metrics.topic_metrics.TopicMetricCollector(name='', exports_to_prometheus=False, maximum_groups=2147483647, topic_selector=None, groups_by_topic_type=False, group_by_path_prefix_parts=0)

Bases
diffusion.features.control.metrics.collector.MetricCollector diffusion.internal.serialisers.pydantic.MarshalledModel diffusion.internal.utils.Model pydantic.main.BaseModel pydantic.utils.Representation

The definition of a topic metric collector.

These can be configured to record metric data for a subset of all topics, specified with a topic selector.

Classes
  • Config — Adds Serialiser support to Model.Config 'alias' defines the name of the serialiser to map to
  • Config — Adds Serialiser support to Model.Config 'alias' defines the name of the serialiser to map to
class
Config()
Bases
diffusion.internal.serialisers.pydantic.MarshalledModel.Config diffusion.internal.utils.Model.Config

Adds Serialiser support to Model.Config 'alias' defines the name of the serialiser to map to

class
diffusion.features.control.metrics.topic_metrics.Config()
Bases
diffusion.features.control.metrics.topic_metrics.TopicMetricCollector.Config diffusion.features.control.metrics.topic_metrics.Config diffusion.features.control.metrics.collector.Config diffusion.features.control.metrics.collector.Config diffusion.internal.serialisers.pydantic.Config diffusion.internal.serialisers.pydantic.MarshalledModel.Config diffusion.internal.serialisers.pydantic.Config diffusion.internal.utils.Config diffusion.internal.utils.Model.Config pydantic.config.BaseConfig

Adds Serialiser support to Model.Config 'alias' defines the name of the serialiser to map to

class

diffusion.features.control.metrics.topic_metrics.TopicMetricCollectorBuilder(*args, **kwds)

Bases
diffusion.internal.utils.TopicMetricCollectorBuilderBase typing.Generic

A topic metric collector builder.

This creates instances of TopicMetricCollector that can be supplied to Metrics.put_topic_metric_collector.

Classes
Methods
  • __init_subclass__(*args, **kwargs) — This method is called when a class is subclassed.
  • create(name, topic_selector) (TopicMetricCollector) — Create a new TopicMetricCollector using the values currently known to this builder.
  • export_to_prometheus(export) (Self) — Specifies whether the metric collector should export metrics to Prometheus or not.
  • group_by_path_prefix_parts(parts) (Self) — Specifies the number of leading parts of the topic path the metric collector should use to group results. Since 6.8.
  • group_by_topic_type(group_by_topic_type) (Self) — Specifies whether the metric collector should group by topic type.
  • maximum_groups(limit) (Self) — Specify the maximum number of groups maintained by the metric collector.
  • reset() (TopicMetricCollectorBuilder) — Reset the builder.
classmethod
__init_subclass__(*args, **kwargs)

This method is called when a class is subclassed.

The default implementation does nothing. It may be overridden to extend subclasses.

class

diffusion.features.control.metrics.topic_metrics.TopicMetricCollector(name='', exports_to_prometheus=False, maximum_groups=2147483647, topic_selector=None, groups_by_topic_type=False, group_by_path_prefix_parts=0)

Bases
diffusion.features.control.metrics.collector.MetricCollector diffusion.internal.serialisers.pydantic.MarshalledModel diffusion.internal.utils.Model pydantic.main.BaseModel pydantic.utils.Representation

The definition of a topic metric collector.

These can be configured to record metric data for a subset of all topics, specified with a topic selector.

Classes
  • Config — Adds Serialiser support to Model.Config 'alias' defines the name of the serialiser to map to
  • Config — Adds Serialiser support to Model.Config 'alias' defines the name of the serialiser to map to
class
Config()
Bases
diffusion.internal.serialisers.pydantic.MarshalledModel.Config diffusion.internal.utils.Model.Config

Adds Serialiser support to Model.Config 'alias' defines the name of the serialiser to map to

class
diffusion.features.control.metrics.topic_metrics.Config()
Bases
diffusion.features.control.metrics.topic_metrics.TopicMetricCollector.Config diffusion.features.control.metrics.topic_metrics.Config diffusion.features.control.metrics.collector.Config diffusion.features.control.metrics.collector.Config diffusion.internal.serialisers.pydantic.Config diffusion.internal.serialisers.pydantic.MarshalledModel.Config diffusion.internal.serialisers.pydantic.Config diffusion.internal.utils.Config diffusion.internal.utils.Model.Config pydantic.config.BaseConfig

Adds Serialiser support to Model.Config 'alias' defines the name of the serialiser to map to

method
export_to_prometheus(export)

Specifies whether the metric collector should export metrics to Prometheus or not.

The default is that metrics are not exported to Prometheus.

Parameters
  • export (bool) — True to export metrics to Prometheus
Returns (Self)

this builder

method
group_by_topic_type(group_by_topic_type) → Self

Specifies whether the metric collector should group by topic type.

By default a topic metric collector does not group by topic type.

Parameters
  • group_by_topic_type (bool) — True to indicate that the collector should group by topic type

Returns: this builder

method
maximum_groups(limit) → Self

Specify the maximum number of groups maintained by the metric collector.

By default, the number of groups is not limited.

Parameters
  • limit (PositiveInt) — The maximum number of groups maintained by the metric collector.

Returns: this builder

method
group_by_path_prefix_parts(parts) → Self

Specifies the number of leading parts of the topic path the metric collector should use to group results. Since 6.8.

By default a topic metric collector does not group by the topic path prefix. If a positive number of parts is specified, it will enable grouping.

Parameters
  • parts (NonNegativeInt) — The number of leading parts of the topic path to group by. Set to 0 to disable grouping by path.

Returns: this builder

method
reset()

Reset the builder.

Returns (TopicMetricCollectorBuilder)

this Builder

method
create(name, topic_selector)

Create a new TopicMetricCollector using the values currently known to this builder.

Parameters
  • name (str) — the name of the TopicMetricCollector
  • topic_selector (str) — the selector pattern that specifies the topics for which metrics are to be collected
Returns (TopicMetricCollector)

a new TopicMetricCollector with all of the current settings of this builder