Interface IMetrics
This feature allows a client to configure metric collectors.
Inherited Members
Namespace: PushTechnology.ClientInterface.Client.Features.Metrics
Assembly: Diffusion.Client.dll
Syntax
public interface IMetrics : IFeatureRemarks
Diffusion servers provide metrics which are made available in several ways:-
- Java Management Extensions (JMX) MBeans.
- Through the Diffusion Management Console.
- As endpoints for Prometheus.
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 PutSessionMetricCollectorAsync(ISessionMetricCollector) or remove RemoveSessionMetricCollectorAsync(String) a session metric collector, a session needs the CONTROL_SERVER global permission.
- To put PutTopicMetricCollectorAsync(ITopicMetricCollector) or remove RemoveTopicMetricCollectorAsync(String) a topic metric collector, a session needs the CONTROL_SERVER global permission.
- To list session metric collectors ListSessionMetricCollectorsAsync() or topic metric collectors ListTopicMetricCollectorsAsync(), a session needs the VIEW_SERVER global permission.
- To get metrics with FetchAsync(), a session needs the VIEW_SERVER global permission.
Accessing the feature
This feature may be obtained from an ISession as follows:
var metrics = session.Metrics;Added in version 6.7.
Methods
ListSessionMetricCollectorsAsync()
Retrieves the current session metric collectors.
Declaration
Task<List<ISessionMetricCollector>> ListSessionMetricCollectorsAsync()Returns
| Type | Description |
|---|---|
| Task<List<ISessionMetricCollector>> | A Task that completes when a response is received from the server. |
Remarks
If the task completes successfully, the Task result will be a list of current session metric collectors.
Exceptions
| Type | Condition |
|---|---|
| SessionSecurityException | If the calling session does not have VIEW_SERVER permission. Thrown by the returned task. |
| SessionClosedException | The calling session is closed. Thrown by the returned task. |
ListSessionMetricCollectorsAsync(CancellationToken)
Retrieves the current session metric collectors.
Declaration
Task<List<ISessionMetricCollector>> ListSessionMetricCollectorsAsync(CancellationToken cancellationToken)Parameters
| Type | Name | Description |
|---|---|---|
| CancellationToken | cancellationToken | The cancellation token used to cancel the current operation. |
Returns
| Type | Description |
|---|---|
| Task<List<ISessionMetricCollector>> | A Task that completes when a response is received from the server. |
Remarks
If the task completes successfully, the Task result will be a list of current session metric collectors.
Exceptions
| Type | Condition |
|---|---|
| SessionSecurityException | If the calling session does not have VIEW_SERVER permission. Thrown by the returned task. |
| SessionClosedException | The calling session is closed. Thrown by the returned task. |
ListTopicMetricCollectorsAsync()
Retrieves the current topic metric collectors.
Declaration
Task<List<ITopicMetricCollector>> ListTopicMetricCollectorsAsync()Returns
| Type | Description |
|---|---|
| Task<List<ITopicMetricCollector>> | A Task that completes when a response is received from the server. |
Remarks
If the task completes successfully, the Task result will be a list of current session metric collectors.
Exceptions
| Type | Condition |
|---|---|
| SessionSecurityException | If the calling session does not have VIEW_SERVER permission. Thrown by the returned task. |
| SessionClosedException | The calling session is closed. Thrown by the returned task. |
ListTopicMetricCollectorsAsync(CancellationToken)
Retrieves the current topic metric collectors.
Declaration
Task<List<ITopicMetricCollector>> ListTopicMetricCollectorsAsync(CancellationToken cancellationToken)Parameters
| Type | Name | Description |
|---|---|---|
| CancellationToken | cancellationToken | The cancellation token used to cancel the current operation. |
Returns
| Type | Description |
|---|---|
| Task<List<ITopicMetricCollector>> | A Task that completes when a response is received from the server. |
Remarks
If the task completes successfully, the Task result will be a list of current session metric collectors.
Exceptions
| Type | Condition |
|---|---|
| SessionSecurityException | If the calling session does not have VIEW_SERVER permission. Thrown by the returned task. |
| SessionClosedException | The calling session is closed. Thrown by the returned task. |
MetricsRequest()
Creates an unconfigured IMetricsRequest. The request can be invoked using FetchAsync() to retrieve metrics for the server or cluster.
Declaration
IMetricsRequest MetricsRequest()Returns
| Type | Description |
|---|---|
| IMetricsRequest | A new IMetricsRequest. |
Remarks
See IMetricsRequest for more information.
Since 6.10.
PutSessionMetricCollectorAsync(ISessionMetricCollector)
Add a session metric collector, replacing any with the same name.
Declaration
Task<object> PutSessionMetricCollectorAsync(ISessionMetricCollector collector)Parameters
| Type | Name | Description |
|---|---|---|
| ISessionMetricCollector | collector | The session metric collector. |
Returns
| Type | Description |
|---|---|
| Task<System.Object> | A Task that completes when a response is received from the server. |
Remarks
If the task completes successfully, the Task result
will be null.
Exceptions
| Type | Condition |
|---|---|
| InvalidFilterException | If the metric collector session filter is invalid. Thrown by the returned task. |
| SessionSecurityException | If the calling session does not have CONTROL_SERVER permission. Thrown by the returned task. |
| ClusterRoutingException | The operation failed due to a transient cluster error. Thrown by the returned task. |
| SessionClosedException | The calling session is closed. Thrown by the returned task. |
PutSessionMetricCollectorAsync(ISessionMetricCollector, CancellationToken)
Add a session metric collector, replacing any with the same name.
Declaration
Task<object> PutSessionMetricCollectorAsync(ISessionMetricCollector collector, CancellationToken cancellationToken)Parameters
| Type | Name | Description |
|---|---|---|
| ISessionMetricCollector | collector | The session metric collector. |
| CancellationToken | cancellationToken | The cancellation token used to cancel the current operation. |
Returns
| Type | Description |
|---|---|
| Task<System.Object> | A Task that completes when a response is received from the server. |
Remarks
If the task completes successfully, the Task result
will be null.
Exceptions
| Type | Condition |
|---|---|
| InvalidFilterException | If the metric collector session filter is invalid. Thrown by the returned task. |
| SessionSecurityException | If the calling session does not have CONTROL_SERVER permission. Thrown by the returned task. |
| ClusterRoutingException | The operation failed due to a transient cluster error. Thrown by the returned task. |
| SessionClosedException | The calling session is closed. Thrown by the returned task. |
PutTopicMetricCollectorAsync(ITopicMetricCollector)
Add a topic metric collector, replacing any with the same name.
Declaration
Task<object> PutTopicMetricCollectorAsync(ITopicMetricCollector collector)Parameters
| Type | Name | Description |
|---|---|---|
| ITopicMetricCollector | collector | The topic metric collector. |
Returns
| Type | Description |
|---|---|
| Task<System.Object> | A Task that completes when a response is received from the server. |
Remarks
A ITopicMetricCollector instance can be created using NewTopicMetricCollectorBuilder().
If the task completes successfully, the Task result
will be null.
Exceptions
| Type | Condition |
|---|---|
| SessionSecurityException | If the calling session does not have CONTROL_SERVER permission. Thrown by the returned task. |
| ClusterRoutingException | The operation failed due to a transient cluster error. Thrown by the returned task. |
| SessionClosedException | The calling session is closed. Thrown by the returned task. |
PutTopicMetricCollectorAsync(ITopicMetricCollector, CancellationToken)
Add a topic metric collector, replacing any with the same name.
Declaration
Task<object> PutTopicMetricCollectorAsync(ITopicMetricCollector collector, CancellationToken cancellationToken)Parameters
| Type | Name | Description |
|---|---|---|
| ITopicMetricCollector | collector | The topic metric collector. |
| CancellationToken | cancellationToken | The cancellation token used to cancel the current operation. |
Returns
| Type | Description |
|---|---|
| Task<System.Object> | A Task that completes when a response is received from the server. |
Remarks
A ITopicMetricCollector instance can be created using NewTopicMetricCollectorBuilder().
If the task completes successfully, the Task result
will be null.
Exceptions
| Type | Condition |
|---|---|
| SessionSecurityException | If the calling session does not have CONTROL_SERVER permission. Thrown by the returned task. |
| ClusterRoutingException | The operation failed due to a transient cluster error. Thrown by the returned task. |
| SessionClosedException | The calling session is closed. Thrown by the returned task. |
RemoveSessionMetricCollectorAsync(String)
Removes any session metric collector with the given name, if it exists.
Declaration
Task<object> RemoveSessionMetricCollectorAsync(string name)Parameters
| Type | Name | Description |
|---|---|---|
| System.String | name | The session metric collector name. |
Returns
| Type | Description |
|---|---|
| Task<System.Object> | A Task that completes when a response is received from the server. |
Remarks
If the task completes successfully, the Task result
will be null.
Exceptions
| Type | Condition |
|---|---|
| SessionSecurityException | If the calling session does not have CONTROL_SERVER permission. Thrown by the returned task. |
| ClusterRoutingException | The operation failed due to a transient cluster error. Thrown by the returned task. |
| SessionClosedException | The calling session is closed. Thrown by the returned task. |
RemoveSessionMetricCollectorAsync(String, CancellationToken)
Removes any session metric collector with the given name, if it exists.
Declaration
Task<object> RemoveSessionMetricCollectorAsync(string name, CancellationToken cancellationToken)Parameters
| Type | Name | Description |
|---|---|---|
| System.String | name | The session metric collector name. |
| CancellationToken | cancellationToken | The cancellation token used to cancel the current operation. |
Returns
| Type | Description |
|---|---|
| Task<System.Object> | A Task that completes when a response is received from the server. |
Remarks
If the task completes successfully, the Task result
will be null.
Exceptions
| Type | Condition |
|---|---|
| SessionSecurityException | If the calling session does not have CONTROL_SERVER permission. Thrown by the returned task. |
| ClusterRoutingException | The operation failed due to a transient cluster error. Thrown by the returned task. |
| SessionClosedException | The calling session is closed. Thrown by the returned task. |
RemoveTopicMetricCollectorAsync(String)
Removes any topic metric collector with the given name, if it exists.
Declaration
Task<object> RemoveTopicMetricCollectorAsync(string name)Parameters
| Type | Name | Description |
|---|---|---|
| System.String | name | The topic metric collector name. |
Returns
| Type | Description |
|---|---|
| Task<System.Object> | A Task that completes when a response is received from the server. |
Remarks
If the task completes successfully, the Task result
will be null.
Exceptions
| Type | Condition |
|---|---|
| SessionSecurityException | If the calling session does not have CONTROL_SERVER permission. Thrown by the returned task. |
| ClusterRoutingException | The operation failed due to a transient cluster error. Thrown by the returned task. |
| SessionClosedException | The calling session is closed. Thrown by the returned task. |
RemoveTopicMetricCollectorAsync(String, CancellationToken)
Removes any topic metric collector with the given name, if it exists.
Declaration
Task<object> RemoveTopicMetricCollectorAsync(string name, CancellationToken cancellationToken)Parameters
| Type | Name | Description |
|---|---|---|
| System.String | name | The topic metric collector name. |
| CancellationToken | cancellationToken | The cancellation token used to cancel the current operation. |
Returns
| Type | Description |
|---|---|
| Task<System.Object> | A Task that completes when a response is received from the server. |
Remarks
If the task completes successfully, the Task result
will be null.
Exceptions
| Type | Condition |
|---|---|
| SessionSecurityException | If the calling session does not have CONTROL_SERVER permission. Thrown by the returned task. |
| ClusterRoutingException | The operation failed due to a transient cluster error. Thrown by the returned task. |
| SessionClosedException | The calling session is closed. Thrown by the returned task. |