Package com.pushtechnology.diffusion.client.features.control

Interface Metrics

All Superinterfaces:
Feature
public interface Metrics extends Feature
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.
  • 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 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/</server>/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
     TopicSpecification.

 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 a session as follows: 

 Metrics metrics = session.feature(Metrics.class);
Since:
6.7
Author:
DiffusionData Limited

  • Method Details

    • putSessionMetricCollector

      CompletableFuture<?> putSessionMetricCollector(Metrics.SessionMetricCollector collector)
      Add a session metric collector, replacing any with the same name.
      Parameters:
      collector - the session metric collector
      Returns:
      a CompletableFuture that completes when a response is received from the server.

      If the task completes successfully, the CompletableFuture result will be null. The result type is any rather than Void to provide forward compatibility with future iterations of this API that may provide a non-null result with a more specific result type.

      Otherwise, the CompletableFuture will complete exceptionally with a CompletionException. Common reasons for failure, listed by the exception reported as the cause, include:

    • listSessionMetricCollectors

      CompletableFuture<List<Metrics.SessionMetricCollector>> listSessionMetricCollectors()
      Retrieves the current session metric collectors.
      Returns:
      a CompletableFuture that completes when a response is received from the server.

      If the task completes successfully, the CompletableFuture result will be a list of current session metric collectors.

      Otherwise, the CompletableFuture will complete exceptionally with a CompletionException. Common reasons for failure, listed by the exception reported as the cause, include:

    • removeSessionMetricCollector

      CompletableFuture<?> removeSessionMetricCollector(String name)
      Removes any session metric collector with the given name, if it exists.
      Parameters:
      name - the session metric collector name
      Returns:
      a CompletableFuture that completes when a response is received from the server.

      If the task completes successfully, the CompletableFuture result will be null. The result type is any rather than Void to provide forward compatibility with future iterations of this API that may provide a non-null result with a more specific result type.

      Otherwise, the CompletableFuture will complete exceptionally with a CompletionException. Common reasons for failure, listed by the exception reported as the cause, include:

    • putTopicMetricCollector

      CompletableFuture<?> putTopicMetricCollector(Metrics.TopicMetricCollector collector)
      Add a topic metric collector, replacing any with the same name.

      A Metrics.TopicMetricCollector instance can be created using newTopicMetricCollectorBuilder.

      Parameters:
      collector - the topic metric collector
      Returns:
      a CompletableFuture that completes when a response is received from the server.

      If the task completes successfully, the CompletableFuture result will be null. The result type is any rather than Void to provide forward compatibility with future iterations of this API that may provide a non-null result with a more specific result type.

      Otherwise, the CompletableFuture will complete exceptionally with a CompletionException. Common reasons for failure, listed by the exception reported as the cause, include:

    • listTopicMetricCollectors

      CompletableFuture<List<Metrics.TopicMetricCollector>> listTopicMetricCollectors()
      Retrieves the current topic metric collectors.
      Returns:
      a CompletableFuture that completes when a response is received from the server.

      If the task completes successfully, the CompletableFuture result will be a list of current topic metric collectors.

      Otherwise, the CompletableFuture will complete exceptionally with a CompletionException. Common reasons for failure, listed by the exception reported as the cause, include:

    • removeTopicMetricCollector

      CompletableFuture<?> removeTopicMetricCollector(String name)
      Removes any topic metric collector with the given name, if it exists.
      Parameters:
      name - the topic metric collector name
      Returns:
      a CompletableFuture that completes when a response is received from the server.

      If the task completes successfully, the CompletableFuture result will be null. The result type is any rather than Void to provide forward compatibility with future iterations of this API that may provide a non-null result with a more specific result type.

      Otherwise, the CompletableFuture will complete exceptionally with a CompletionException. Common reasons for failure, listed by the exception reported as the cause, include:

    • metricsRequest

      Metrics.MetricsRequest metricsRequest()
      Creates an unconfigured Metrics.MetricsRequest. The request can be invoked using Metrics.MetricsRequest.fetch() to retrieve metrics for the server or cluster.

      See Metrics.MetricsRequest for more information.

      Returns:
      a new Metrics.MetricsRequest
      Since:
      6.10

    • setMetricAlert

      CompletableFuture<?> setMetricAlert(String name, String specification)
      Set or update a metric alert with a given name and specification.

      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.

      Parameters:
      name - the name of the metric alert. This name is used to uniquely identify the alert.
      specification - the specification of the metric alert. This defines the conditions under which the alert is triggered and the actions to be taken.
      Returns:
      a CompletableFuture that completes when a response is received from the server. If the operation is successful, the future completes normally.

      If the task fails, the CompletableFuture will complete exceptionally with a CompletionException. Common reasons for failure, listed by the exception reported as the cause, include:

      Since:
      6.12

    • listMetricAlerts

      CompletableFuture<List<Metrics.MetricAlert>> listMetricAlerts()
      List all metric alerts that have been created.
      Returns:
      a CompletableFuture that completes when a response is received from the server, returning a list of metric alerts sorted by their creation order.

      If the task fails, the CompletableFuture will complete exceptionally with a CompletionException. Common reasons for failure, listed by the exception reported as the cause, include:

      Since:
      6.12

    • removeMetricAlert

      CompletableFuture<?> removeMetricAlert(String name)
      Remove a named metric alert if it exists.

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

      Parameters:
      name - the name of the metric alert
      Returns:
      a CompletableFuture that completes when a response is received from the server.

      If the task fails, the CompletableFuture will complete exceptionally with a CompletionException. Common reasons for failure, listed by the exception reported as the cause, include:

      Since:
      6.12