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 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:
put_session_metric_collector
async
¶
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
¶
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
¶
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
¶
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
¶
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
¶
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
instance-attribute
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
instance-attribute
class-attribute
¶
Session filter.
group_by_properties
instance-attribute
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 ¶
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 ¶
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
|
required |
Returns:
Type | Description |
---|---|
Self
|
this builder |
group_by_properties ¶
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
|
()
|
Returns:
Type | Description |
---|---|
Self
|
this builder |
remove_metrics_with_no_matches ¶
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 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
instance-attribute
class-attribute
¶
Indicates whether the collector groups by topic type. (True if grouping by topic type)
groups_by_topic_view
instance-attribute
class-attribute
¶
groups_by_topic_view: typing.Optional[bool] = pydantic.Field(default=False, alias='groups-by-topic-view.boolean')
Indicates whether the collector groups by topic view.
group_by_path_prefix_parts
instance-attribute
class-attribute
¶
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 ¶
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 ¶
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 |
group_by_topic_view ¶
Specifies whether the metric collector should group by topic view.
By default a topic metric collector does not group by topic view.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
group_by_topic_view |
bool
|
|
required |
Returns:
Type | Description |
---|---|
TopicMetricCollectorBuilder
|
This builder |
Since
6.10
export_to_prometheus ¶
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 ¶
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 ¶
create ¶
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 |
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
instance-attribute
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
instance-attribute
class-attribute
¶
Session filter.
group_by_properties
instance-attribute
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 ¶
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 ¶
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
|
required |
Returns:
Type | Description |
---|---|
Self
|
this builder |
group_by_properties ¶
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
|
()
|
Returns:
Type | Description |
---|---|
Self
|
this builder |
remove_metrics_with_no_matches ¶
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 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
instance-attribute
class-attribute
¶
Indicates whether the collector groups by topic type. (True if grouping by topic type)
groups_by_topic_view
instance-attribute
class-attribute
¶
groups_by_topic_view: typing.Optional[bool] = pydantic.Field(default=False, alias='groups-by-topic-view.boolean')
Indicates whether the collector groups by topic view.
group_by_path_prefix_parts
instance-attribute
class-attribute
¶
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 ¶
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 ¶
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 |
group_by_topic_view ¶
Specifies whether the metric collector should group by topic view.
By default a topic metric collector does not group by topic view.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
group_by_topic_view |
bool
|
|
required |
Returns:
Type | Description |
---|---|
TopicMetricCollectorBuilder
|
This builder |
Since
6.10
export_to_prometheus ¶
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 ¶
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 ¶
create ¶
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 |