Metrics

diffusion.features.control.metrics

Metrics

Bases: 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

put_session_metric_collector async

put_session_metric_collector(collector: SessionMetricCollector) -> None

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

Parameters:

Name	Type	Description	Default
collector	SessionMetricCollector	the session metric collector	required

Raises:

Type	Description
InvalidSessionFilterError	if the metric collector session filter is invalid;
ServerDisconnectedError	if the session is disconnected.

list_session_metric_collectors async

list_session_metric_collectors() -> typing.List[SessionMetricCollector]

Retrieves the current session metric collectors.

Returns:

Type	Description
typing.List[SessionMetricCollector]	a list of current session metric collectors.

Raises:

Type	Description
ServerDisconnectedError	if the session is disconnected.

remove_session_metric_collector async

remove_session_metric_collector(name: str) -> None

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

Parameters:

Name	Type	Description	Default
name	str	the session metric collector name	required

Raises:

Type	Description
ServerDisconnectedError	if the session is disconnected.

put_topic_metric_collector async

put_topic_metric_collector(collector: TopicMetricCollector) -> None

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

A TopicMetricCollector instance can be created using TopicMetricCollectorBuilder.

Parameters:

Name	Type	Description	Default
collector	TopicMetricCollector	the topic metric collector	required

Raises:

Type	Description
ServerDisconnectedError	if the session is disconnected.

list_topic_metric_collectors async

list_topic_metric_collectors() -> typing.List[TopicMetricCollector]

Retrieves the current topic metric collectors.

Returns:

Type	Description
typing.List[TopicMetricCollector]	a list of current topic metric collectors.

Raises:

Type	Description
ServerDisconnectedError	if the session is disconnected.

remove_topic_metric_collector async

remove_topic_metric_collector(name: str) -> None

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

Parameters:

Name	Type	Description	Default
name	str	the topic metric collector name	required

Raises:

Type	Description
ServerDisconnectedError	if the session is disconnected.

session_metrics

SessionMetricCollector

Bases: MetricCollector

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.

removes_metrics_with_no_matches class-attribute

removes_metrics_with_no_matches: typing.Optional[bool] = pydantic.Field(default=False, alias='removes-metrics-with-no-matches.boolean')

True if metrics with no matches should be removed.

session_filter class-attribute

session_filter: typing.Optional[pydantic.StrictStr] = None

Session filter.

group_by_properties class-attribute

group_by_properties: typing.List[pydantic.StrictStr] = pydantic.Field(default=[], alias='session-property-keys')

List of properties to group by.

SessionMetricCollectorBuilder

Bases: BuilderBase[SessionMetricCollector]

A session metric collector builder.

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

export_to_prometheus

export_to_prometheus(export: bool) -> Self

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

The default is that metrics are not exported to Prometheus.

Parameters:

Name	Type	Description	Default
export	bool	True to export metrics to Prometheus	required

Returns:

Type	Description
Self	this builder

group_by_property

group_by_property(property_name: str) -> Self

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:

Name	Type	Description	Default
property_name	str	the name of the session property. See Session for details of session properties	required

Returns:

Type	Description
Self	this builder

group_by_properties

group_by_properties(*property_names: str) -> Self

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

Parameters:

Name	Type	Description	Default
*property_names	str	a list of session property names. See Session for details of session properties	()

Returns:

Type	Description
Self	this builder

remove_metrics_with_no_matches

remove_metrics_with_no_matches(remove: bool) -> Self

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:

Name	Type	Description	Default
remove	bool	True to indicate that metrics with no matches should be removed	required

Returns:

Type	Description
Self	this builder

create

create(name: str, session_filter: str) -> SessionMetricCollector

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

Parameters:

Name	Type	Description	Default
name	str	the name of the SessionMetricCollector	required
session_filter	str	the session filter indicating the sessions this collector should apply to. The format of a session property filter is documented in Session	required

Returns:

Type	Description
SessionMetricCollector	a new SessionMetricCollector with all of the current settings of this builder

topic_metrics

TopicMetricCollector

Bases: MetricCollector

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.

groups_by_topic_type class-attribute

groups_by_topic_type: bool = pydantic.Field(default=False, alias='groups-by-topic-type.boolean')

Indicates whether the collector groups by topic type. (True if grouping by topic type)

group_by_path_prefix_parts class-attribute

group_by_path_prefix_parts: pydantic.NonNegativeInt = 0

The number of leading parts of the topic path to group by.

TopicMetricCollectorBuilder

Bases: BuilderBase[TopicMetricCollector]

A topic metric collector builder.

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

group_by_topic_type

group_by_topic_type(group_by_topic_type: bool) -> Self

Specifies whether the metric collector should group by topic type.

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

Parameters:

Name	Type	Description	Default
group_by_topic_type	bool	True to indicate that the collector should group by topic type	required

Returns:

Type	Description
Self	this builder

group_by_path_prefix_parts

group_by_path_prefix_parts(parts: pydantic.NonNegativeInt) -> 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:

Name	Type	Description	Default
parts	pydantic.NonNegativeInt	The number of leading parts of the topic path to group by. Set to 0 to disable grouping by path.	required

Returns:

Type	Description
Self	this builder

export_to_prometheus

export_to_prometheus(export: bool) -> Self

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

The default is that metrics are not exported to Prometheus.

Parameters:

Name	Type	Description	Default
export	bool	True to export metrics to Prometheus	required

Returns:

Type	Description
Self	this builder

maximum_groups

maximum_groups(limit: pydantic.PositiveInt) -> Self

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

By default, the number of groups is not limited.

Parameters:

Name	Type	Description	Default
limit	pydantic.PositiveInt	The maximum number of groups maintained by the metric collector.	required

Returns:

Type	Description
Self	this builder

reset

reset() -> TopicMetricCollectorBuilder

Reset the builder.

Returns:

Type	Description
TopicMetricCollectorBuilder	this Builder

create

create(name: str, topic_selector: str) -> TopicMetricCollector

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

Parameters:

Name	Type	Description	Default
name	str	the name of the TopicMetricCollector	required
topic_selector	str	the selector pattern that specifies the topics for which metrics are to be collected	required

Returns:

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

collector

MetricCollector

Bases: MarshalledModel

The common base interface for metric collectors.

name class-attribute

name: str = pydantic.Field(default='', min_length=1, alias='metric-collector-name')

The name of the metric collector.

exports_to_prometheus class-attribute

exports_to_prometheus: bool = pydantic.Field(default=False, alias='exports-to-prometheus.boolean')

Indicates whether the metric collector exports to Prometheus.

diffusion.features.control.metrics.session_metrics

SessionMetricCollector

Bases: MetricCollector

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.

removes_metrics_with_no_matches class-attribute

removes_metrics_with_no_matches: typing.Optional[bool] = pydantic.Field(default=False, alias='removes-metrics-with-no-matches.boolean')

True if metrics with no matches should be removed.

session_filter class-attribute

session_filter: typing.Optional[pydantic.StrictStr] = None

Session filter.

group_by_properties class-attribute

group_by_properties: typing.List[pydantic.StrictStr] = pydantic.Field(default=[], alias='session-property-keys')

List of properties to group by.

SessionMetricCollectorBuilder

Bases: BuilderBase[SessionMetricCollector]

A session metric collector builder.

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

export_to_prometheus

export_to_prometheus(export: bool) -> Self

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

The default is that metrics are not exported to Prometheus.

Parameters:

Name	Type	Description	Default
export	bool	True to export metrics to Prometheus	required

Returns:

Type	Description
Self	this builder

group_by_property

group_by_property(property_name: str) -> Self

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:

Name	Type	Description	Default
property_name	str	the name of the session property. See Session for details of session properties	required

Returns:

Type	Description
Self	this builder

group_by_properties

group_by_properties(*property_names: str) -> Self

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

Parameters:

Name	Type	Description	Default
*property_names	str	a list of session property names. See Session for details of session properties	()

Returns:

Type	Description
Self	this builder

remove_metrics_with_no_matches

remove_metrics_with_no_matches(remove: bool) -> Self

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:

Name	Type	Description	Default
remove	bool	True to indicate that metrics with no matches should be removed	required

Returns:

Type	Description
Self	this builder

create

create(name: str, session_filter: str) -> SessionMetricCollector

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

Parameters:

Name	Type	Description	Default
name	str	the name of the SessionMetricCollector	required
session_filter	str	the session filter indicating the sessions this collector should apply to. The format of a session property filter is documented in Session	required

Returns:

Type	Description
SessionMetricCollector	a new SessionMetricCollector with all of the current settings of this builder

diffusion.features.control.metrics.topic_metrics

TopicMetricCollector

Bases: MetricCollector

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.

groups_by_topic_type class-attribute

groups_by_topic_type: bool = pydantic.Field(default=False, alias='groups-by-topic-type.boolean')

Indicates whether the collector groups by topic type. (True if grouping by topic type)

group_by_path_prefix_parts class-attribute

group_by_path_prefix_parts: pydantic.NonNegativeInt = 0

The number of leading parts of the topic path to group by.

TopicMetricCollectorBuilder

Bases: BuilderBase[TopicMetricCollector]

A topic metric collector builder.

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

group_by_topic_type

group_by_topic_type(group_by_topic_type: bool) -> Self

Specifies whether the metric collector should group by topic type.

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

Parameters:

Name	Type	Description	Default
group_by_topic_type	bool	True to indicate that the collector should group by topic type	required

Returns:

Type	Description
Self	this builder

group_by_path_prefix_parts

group_by_path_prefix_parts(parts: pydantic.NonNegativeInt) -> 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:

Name	Type	Description	Default
parts	pydantic.NonNegativeInt	The number of leading parts of the topic path to group by. Set to 0 to disable grouping by path.	required

Returns:

Type	Description
Self	this builder

export_to_prometheus

export_to_prometheus(export: bool) -> Self

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

The default is that metrics are not exported to Prometheus.

Parameters:

Name	Type	Description	Default
export	bool	True to export metrics to Prometheus	required

Returns:

Type	Description
Self	this builder

maximum_groups

maximum_groups(limit: pydantic.PositiveInt) -> Self

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

By default, the number of groups is not limited.

Parameters:

Name	Type	Description	Default
limit	pydantic.PositiveInt	The maximum number of groups maintained by the metric collector.	required

Returns:

Type	Description
Self	this builder

reset

reset() -> TopicMetricCollectorBuilder

Reset the builder.

Returns:

Type	Description
TopicMetricCollectorBuilder	this Builder

create

create(name: str, topic_selector: str) -> TopicMetricCollector

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

Parameters:

Name	Type	Description	Default
name	str	the name of the TopicMetricCollector	required
topic_selector	str	the selector pattern that specifies the topics for which metrics are to be collected	required

Returns:

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