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 : IFeature
Remarks

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

Metric Alerts

Metric alerts allow users to react to changes in system metrics, such as memory usage, by defining conditions under which notifications are triggered.

Metric alerts are defined using a domain-specific language (DSL) to specify the conditions for triggering alerts. Users can create alerts based on various metrics available in Diffusion, such as JVM memory usage, and define thresholds for these metrics. When a metric crosses the specified threshold, the alert is triggered, resulting in the creation or update of a corresponding Diffusion topic. This topic will contain a JSON representation of the metric data that caused the alert to trigger.

Users interact with metric alerts through API methods in this class, which allow adding, removing, and listing alerts. Listing alerts requires the VIEW_SERVER global permission, while adding or removing alerts requires the CONTROL_SERVER global permission.

Topic creation is done using the principal of the session that created the alert, and so inherits the permissions of that session.

Metric Alert Specifications

The DSL for metric alerts specifies the metric from which the alert is to be created and the topic to which the alert is published. Additionally, it may contain conditionals to control when the alert is published, and control the specification of the topic and which server the alert will appear for.

Here is a typical example of an alert specification: 

select os_system_load_average
into topic /metrics/</serverName>/os_system_load_average
where value > 5

This statement creates an alert on the 'os_system_load_average' metric, triggering when its value exceeds 5. The path of the notification topic depends on the name of the server which triggered the alert; a value in a topic path surrounded by angle brackets indicates a JSON pointer to a value in the alert data. If the server name is 'diffusion_0', the topic path will be '/metrics/diffusion_0/os_system_load_average'.

The full syntax of the specification language is as follows: 

SELECT metric_name [ FROM_SERVER server_name ]
    INTO_TOPIC topic_path
    [ WITH_PROPERTIES { property_name: property_value[, ...] } ]
    [ WHERE condition ]
    [ DISABLE_UNTIL condition ]

metric_name:
A string representing the name of the metric to be monitored.


FROM_SERVER server_name (optional):
A string identifying the specific server from which to monitor the
metric. If omitted, defaults to monitoring on all servers in the cluster.


INTO_TOPIC topic_path:
The topic path where alert notifications are sent. The path may include
values from the event JSON using JSON pointers enclosed in angle
brackets.


WITH_PROPERTIES { property_name: property_value[, ...] } (optional):
A set of key-value pairs defining additional properties for the topic.
Specified using standard Diffusion topic property names. See
ITopicSpecification.


WHERE condition (optional):
A logical expression that defines the triggering condition for the alert.
Supports logical operators ('and', 'or') and comparisons. Dimensional
data may be compared using the dimensions object, for
example 
where dimensions = { name: 'foo'}


DISABLE_UNTIL condition (optional):
A logical expression specifying conditions under which the alert is
temporarily disabled after being triggered. The alert is re-enabled once
these conditions are met.

Accessing the feature

This feature may be obtained from an ISession as follows: 

var metrics = session.Metrics;

Added in version 6.7.

Methods

ListMetricAlertsAsync()

List all metric alerts that have been created.

Declaration
Task<List<IMetricAlert>> ListMetricAlertsAsync()
Returns
Type Description
System.Threading.Tasks.Task<System.Collections.Generic.List<IMetricAlert>>

A Task that completes when a response is received from the server, returning a list of metric alerts sorted by their creation order.
Remarks

Since 6.12.

Exceptions
Type Condition
SessionSecurityException

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.

ListMetricAlertsAsync(CancellationToken)

List all metric alerts that have been created.

Declaration
Task<List<IMetricAlert>> ListMetricAlertsAsync(CancellationToken cancellationToken)
Parameters
Type Name Description
System.Threading.CancellationToken cancellationToken

The cancellation token used to cancel the current operation.
Returns
Type Description
System.Threading.Tasks.Task<System.Collections.Generic.List<IMetricAlert>>

A Task that completes when a response is received from the server, returning a list of metric alerts sorted by their creation order.
Remarks

Since 6.12.

Exceptions
Type Condition
SessionSecurityException

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.

ListSessionMetricCollectorsAsync()

Retrieves the current session metric collectors.

Declaration
Task<List<ISessionMetricCollector>> ListSessionMetricCollectorsAsync()
Returns
Type Description
System.Threading.Tasks.Task<System.Collections.Generic.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
System.Threading.CancellationToken cancellationToken

The cancellation token used to cancel the current operation.
Returns
Type Description
System.Threading.Tasks.Task<System.Collections.Generic.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
System.Threading.Tasks.Task<System.Collections.Generic.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
System.Threading.CancellationToken cancellationToken

The cancellation token used to cancel the current operation.
Returns
Type Description
System.Threading.Tasks.Task<System.Collections.Generic.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
System.Threading.Tasks.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.
System.Threading.CancellationToken cancellationToken

The cancellation token used to cancel the current operation.
Returns
Type Description
System.Threading.Tasks.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
System.Threading.Tasks.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.
System.Threading.CancellationToken cancellationToken

The cancellation token used to cancel the current operation.
Returns
Type Description
System.Threading.Tasks.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.

RemoveMetricAlertAsync(String)

Removes a named metric alert if it exists.

Declaration
Task<object> RemoveMetricAlertAsync(string name)
Parameters
Type Name Description
System.String name

The name of the metric alert.
Returns
Type Description
System.Threading.Tasks.Task<System.Object>

A Task that completes when a response is received from the server.
Remarks

If the named alert does not exist, the Task will complete successfully.

Since 6.12.

Exceptions
Type Condition
System.ArgumentNullException

The given name is null.
SessionSecurityException

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.

RemoveMetricAlertAsync(String, CancellationToken)

Removes a named metric alert if it exists.

Declaration
Task<object> RemoveMetricAlertAsync(string name, CancellationToken cancellationToken)
Parameters
Type Name Description
System.String name

The name of the metric alert.
System.Threading.CancellationToken cancellationToken

The cancellation token used to cancel the current operation.
Returns
Type Description
System.Threading.Tasks.Task<System.Object>

A Task that completes when a response is received from the server.
Remarks

If the named alert does not exist, the Task will complete successfully.

Since 6.12.

Exceptions
Type Condition
System.ArgumentNullException

The given name is null.
SessionSecurityException

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
System.Threading.Tasks.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.
System.Threading.CancellationToken cancellationToken

The cancellation token used to cancel the current operation.
Returns
Type Description
System.Threading.Tasks.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
System.Threading.Tasks.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.
System.Threading.CancellationToken cancellationToken

The cancellation token used to cancel the current operation.
Returns
Type Description
System.Threading.Tasks.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.

SetMetricAlertAsync(String, String)

Set or update a metric alert with a given name and specification.

Declaration
Task<object> SetMetricAlertAsync(string name, string specification)
Parameters
Type Name Description
System.String name

The name of the metric alert. This name is used to uniquely identify the alert.
System.String specification

The specification of the metric alert. This defines the conditions under which the alert is triggered and the actions to be taken.
Returns
Type Description
System.Threading.Tasks.Task<System.Object>

A Task that completes when a response is received from the server. If the operation is successful, the task completes normally.
Remarks

This method creates or updates a metric alert. If an alert with the specified name already exists, it will be overwritten with the new specification.

Since 6.12.

Exceptions
Type Condition
System.ArgumentNullException

The given name or specification is null.
System.ArgumentException

If name is an empty string.
InvalidFilterException

The specification is invalid. Thrown by the returned task.
SessionSecurityException

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.

SetMetricAlertAsync(String, String, CancellationToken)

Set or update a metric alert with a given name and specification.

Declaration
Task<object> SetMetricAlertAsync(string name, string specification, CancellationToken cancellationToken)
Parameters
Type Name Description
System.String name

The name of the metric alert. This name is used to uniquely identify the alert.
System.String specification

The specification of the metric alert. This defines the conditions under which the alert is triggered and the actions to be taken.
System.Threading.CancellationToken cancellationToken

The cancellation token used to cancel the current operation.
Returns
Type Description
System.Threading.Tasks.Task<System.Object>

A Task that completes when a response is received from the server. If the operation is successful, the task completes normally.
Remarks

This method creates or updates a metric alert. If an alert with the specified name already exists, it will be overwritten with the new specification.

Since 6.12.

Exceptions
Type Condition
System.ArgumentNullException

The given name or specification is null.
System.ArgumentException

If name is an empty string.
InvalidFilterException

The specification is invalid. Thrown by the returned task.
SessionSecurityException

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.