Session Trees¶
diffusion.features.control.metrics
Metrics
— This feature allows a client to configure metric collectors.
diffusion.features.control.metrics.
Metrics
(
session
)
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 theCONTROL_SERVER
global permission. - To put (
put_topic_metric_collector
) or remove (remove_topic_metric_collector
) a topic metric collector, a session needs theCONTROL_SERVER
global permission. - To list session metric collectors (
list_session_metric_collectors
) or topic metric collectors (list_topic_metric_collectors
), a session needs theVIEW_SERVER
global permission.
Accessing the feature¶
This feature may be obtained from a Session
as follows:
metrics: Metrics = session.metrics()
services
(ServiceLocator) — Alias for the internal session's service locator.
list_session_metric_collectors
(
)
(list of SessionMetricCollector) — Retrieves the current session metric collectors.list_topic_metric_collectors
(
)
(list of TopicMetricCollector) — Retrieves the current topic metric collectors.put_session_metric_collector
(
collector
)
— Add a session metric collector, replacing any with the same name.put_topic_metric_collector
(
collector
)
— Add a topic metric collector, replacing any with the same name.remove_session_metric_collector
(
name
)
— Removes any session metric collector with the given name, if it exists.remove_topic_metric_collector
(
name
)
— Removes any topic metric collector with the given name, if it exists.
put_session_metric_collector
(
collector
)
Add a session metric collector, replacing any with the same name.
collector
(SessionMetricCollector) — the session metric collector
InvalidSessionFilterError
— if the metric collector session filter is invalid;ServerDisconnectedError
— if the session is disconnected.
list_session_metric_collectors
(
)
Retrieves the current session metric collectors.
a list of current session metric collectors.
ServerDisconnectedError
— if the session is disconnected.
remove_session_metric_collector
(
name
)
Removes any session metric collector with the given name, if it exists.
name
(str) — the session metric collector name
ServerDisconnectedError
— if the session is disconnected.
put_topic_metric_collector
(
collector
)
Add a topic metric collector, replacing any with the same name.
A TopicMetricCollector
instance can be created using
TopicMetricCollectorBuilder.
collector
(TopicMetricCollector) — the topic metric collector
ServerDisconnectedError
— if the session is disconnected.
list_topic_metric_collectors
(
)
Retrieves the current topic metric collectors.
a list of current topic metric collectors.
ServerDisconnectedError
— if the session is disconnected.
remove_topic_metric_collector
(
name
)
Removes any topic metric collector with the given name, if it exists.
name
(str) — the topic metric collector name
ServerDisconnectedError
— if the session is disconnected.
diffusion.features.control.metrics.session_metrics
SessionMetricCollector
— The definition of a session metric collector.SessionMetricCollectorBuilder
— A session metric collector builder.
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=[]
)
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.
Config
(
)
Adds Serialiser support to Model.Config 'alias' defines the name of the serialiser to map to
diffusion.features.control.metrics.session_metrics.
Config
(
)
Adds Serialiser support to Model.Config 'alias' defines the name of the serialiser to map to
diffusion.features.control.metrics.session_metrics.
SessionMetricCollectorBuilder
(
*args
, **kwds
)
A session metric collector builder.
It is used to create instances of
SessionMetricCollector
that can be supplied to
Metrics.put_session_metric_collector
.
SessionMetricCollector
— The definition of a session metric collector.
__init_subclass__
(
*args
,**kwargs
)
— This method is called when a class is subclassed.create
(
name
,session_filter
)
(SessionMetricCollector) — Create a newSessionMetricCollector
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.
__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.
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=[]
)
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.
Config
(
)
Adds Serialiser support to Model.Config 'alias' defines the name of the serialiser to map to
diffusion.features.control.metrics.session_metrics.
Config
(
)
Adds Serialiser support to Model.Config 'alias' defines the name of the serialiser to map to
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.
export
(bool) — True to export metrics to Prometheus
this builder
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.
property_name
(str) — the name of the session property. SeeSession
for details of session properties
this builder
group_by_properties
(
*property_names
)
Specifies a list of session property names to group by, replacing any current list known to this builder.
property_names
— a list of session property names. SeeSession
for details of session properties
this builder
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.
remove
(bool) — True to indicate that metrics with no matches should be removed
this builder
create
(
name
, session_filter
)
→ SessionMetricCollectorCreate a new SessionMetricCollector
using the values
currently known to this builder.
name
(str) — the name of theSessionMetricCollector
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
reset
(
)
Reset the builder.
this builder
diffusion.features.control.metrics.topic_metrics
TopicMetricCollector
— The definition of a topic metric collector.TopicMetricCollectorBuilder
— A topic metric collector builder.
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
)
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.
Config
(
)
Adds Serialiser support to Model.Config 'alias' defines the name of the serialiser to map to
diffusion.features.control.metrics.topic_metrics.
Config
(
)
Adds Serialiser support to Model.Config 'alias' defines the name of the serialiser to map to
diffusion.features.control.metrics.topic_metrics.
TopicMetricCollectorBuilder
(
*args
, **kwds
)
A topic metric collector builder.
This creates instances of TopicMetricCollector
that can be supplied to
Metrics.put_topic_metric_collector.
TopicMetricCollector
— The definition of a topic metric collector.
__init_subclass__
(
*args
,**kwargs
)
— This method is called when a class is subclassed.create
(
name
,topic_selector
)
(TopicMetricCollector) — Create a newTopicMetricCollector
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.
__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.
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
)
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.
Config
(
)
Adds Serialiser support to Model.Config 'alias' defines the name of the serialiser to map to
diffusion.features.control.metrics.topic_metrics.
Config
(
)
Adds Serialiser support to Model.Config 'alias' defines the name of the serialiser to map to
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.
export
(bool) — True to export metrics to Prometheus
this builder
group_by_topic_type
(
group_by_topic_type
)
→ SelfSpecifies whether the metric collector should group by topic type.
By default a topic metric collector does not group by topic type.
group_by_topic_type
(bool) — True to indicate that the collector should group by topic type
Returns: this builder
maximum_groups
(
limit
)
→ SelfSpecify the maximum number of groups maintained by the metric collector.
By default, the number of groups is not limited.
limit
(PositiveInt) — The maximum number of groups maintained by the metric collector.
Returns: this builder
group_by_path_prefix_parts
(
parts
)
→ SelfSpecifies 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.
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
reset
(
)
Reset the builder.
this Builder
create
(
name
, topic_selector
)
Create a new TopicMetricCollector
using the values
currently known to this builder.
name
(str) — the name of the TopicMetricCollectortopic_selector
(str) — the selector pattern that specifies the topics for which metrics are to be collected
a new TopicMetricCollector with all of the current settings of this builder