com.pushtechnology.diffusion.client.features.control.Metrics Maven / Gradle / Ivy
/*******************************************************************************
* Copyright (c) 2023 DiffusionData Ltd., All Rights Reserved.
*
* Use is subject to license terms.
*
* NOTICE: All information contained herein is, and remains the
* property of Push Technology. The intellectual and technical
* concepts contained herein are proprietary to Push Technology and
* may be covered by U.S. and Foreign Patents, patents in process, and
* are protected by trade secret or copyright law.
*******************************************************************************/
package com.pushtechnology.diffusion.client.features.control;
import java.util.List;
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.CompletionException;
import com.pushtechnology.diffusion.client.Diffusion;
import com.pushtechnology.diffusion.client.features.ClusterRoutingException;
import com.pushtechnology.diffusion.client.features.InvalidFilterException;
import com.pushtechnology.diffusion.client.session.Feature;
import com.pushtechnology.diffusion.client.session.PermissionsException;
import com.pushtechnology.diffusion.client.session.Session;
import com.pushtechnology.diffusion.client.session.SessionClosedException;
import com.pushtechnology.diffusion.client.types.GlobalPermission;
/**
* 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:
*
* - To {@link #putSessionMetricCollector put} or
* {@link #removeSessionMetricCollector remove} a session metric collector, a
* session needs the {@link GlobalPermission#CONTROL_SERVER CONTROL_SERVER}
* global permission.
*
- To {@link #putTopicMetricCollector put} or
* {@link #removeTopicMetricCollector remove} a topic metric collector, a
* session needs the {@link GlobalPermission#CONTROL_SERVER CONTROL_SERVER}
* global permission.
*
- To list {@link #listSessionMetricCollectors session metric collectors} or
* {@link #listTopicMetricCollectors topic metric collectors}, a session needs
* the {@link GlobalPermission#VIEW_SERVER VIEW_SERVER} global permission.
*
*
* Accessing the feature
*
* This feature may be obtained from a {@link Session session} as follows:
*
*
* Metrics metrics = session.feature(Metrics.class);
*
*
* @author DiffusionData Limited
*
* @since 6.7
*/
public interface Metrics extends Feature {
/**
* The common base interface for metric collectors.
*/
interface MetricCollector {
/**
* Returns the name of the metric collector.
*
* @return the name of the metric collector
*/
String getName();
/**
* Indicates whether the metric collector exports to Prometheus.
*
* @return true if exporting to Prometheus
*/
boolean exportsToPrometheus();
/**
* Limit the number of groups maintained by this metric collector.
*
* Session metric collectors can
* {@link SessionMetricCollector#getGroupByProperties() group metrics by
* property}. Topic metric collectors can
* {@link TopicMetricCollector#groupsByTopicType() group metrics by
* topic type}. This property places an upper limit on the number of
* groups that will be maintained for the metric collector.
*
*
For example,
* if a session metric collector groups by {@code $SessionId} and
* maximumGroups is 10, then metrics will only be collected for the
* first 10 sessions.
*
* @return the maximum number of sub-groups maintained by this metric
* collector
* @since 6.8
*/
int maximumGroups();
}
/**
* Common interface for metric collector builders.
*
* @since 6.8
* @param type of concrete Builder
*/
interface Builder> {
/**
* Reset the builder.
*
* @return this Builder
*/
B reset();
/**
* Specifies whether the metric collector should export metrics to
* Prometheus or not.
*
* By default, metrics are not exported to Prometheus.
*
* @param export true to export metrics to Prometheus
*
* @return this builder
*/
B exportToPrometheus(boolean export);
/**
* Set the maximum number of groups maintained by the metric collector.
*
* By default, the number of groups is not limited.
*
* @param limit a positive integer
* @return the maximum number of groups
* @see MetricCollector#maximumGroups()
* @since 6.8
*/
B maximumGroups(int limit);
}
/**
* 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.
*/
interface SessionMetricCollector extends MetricCollector {
/**
* Returns the session filter.
*
* @return the session filter
*/
String getSessionFilter();
/**
* Returns the list of properties to group by.
*
* @return list of properties to group by
*/
List getGroupByProperties();
/**
* Indicates whether metrics with no matches should be removed.
*
* @return true if metrics with no matches should be removed
*/
boolean removesMetricsWithNoMatches();
/**
* A session metric collector builder.
*
* A builder of this type may be created using
* {@link Diffusion#newSessionMetricCollectorBuilder
* newSessionMetricCollectorBuilder} and used to create instances of
* {@link SessionMetricCollector} that can be supplied to
* {@link Metrics#putSessionMetricCollector putSessionMetricCollector}.
*/
interface Builder extends Metrics.Builder {
/**
* 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.
*
* @param propertyName the name of the session property. See
* {@link Session} for details of session properties
*
* @return this builder
*/
Builder groupByProperty(String propertyName);
/**
* Specifies a list of session property names to group by, replacing
* any current list known to this builder.
*
* @param propertyNames a list of session property names. See
* {@link Session} for details of session properties
*
* @return this builder
*/
Builder groupByProperties(List propertyNames);
/**
* 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.
*
* @param remove true to indicate that metrics with no matches
* should be removed
*
* @return this builder
*/
Builder removeMetricsWithNoMatches(boolean remove);
/**
* Create a new {@link SessionMetricCollector} using the values
* currently known to this builder.
*
* @param name the name of the {@link SessionMetricCollector}
*
* @param sessionFilter the session filter indicating the sessions
* this collector should apply to. The format of a session
* property filter is documented in {@link Session}
*
* @return a new {@link SessionMetricCollector} with all of the
* current settings of this builder
*/
SessionMetricCollector create(String name, String sessionFilter);
}
}
/**
* 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.
*/
interface TopicMetricCollector extends MetricCollector {
/**
* Returns the topic selector.
*
* @return topic selector
*/
String getTopicSelector();
/**
* Indicates whether the collector groups by topic type.
*
* @return true if grouping by topic type
*/
boolean groupsByTopicType();
/**
* Indicates whether the collector groups by topic view.
*
* @return true if grouping by topic view
* @since 6.9
*/
boolean groupsByTopicView();
/**
* Returns the number of leading parts of the topic path to group by.
*
* @return the number of leading parts of the topic path to group by, or
* 0 if the collector does not group by path prefix
* @since 6.8
*/
int groupByPathPrefixParts();
/**
* A topic metric collector builder.
*
* A builder of this type may be created using
* {@link Diffusion#newTopicMetricCollectorBuilder
* newTopicMetricCollectorBuilder} and used to create instances of
* {@link TopicMetricCollector} that can be supplied to
* {@link Metrics#putTopicMetricCollector putTopicMetricCollector}.
*/
interface Builder extends Metrics.Builder {
/**
* Specifies whether the metric collector should group by topic
* type.
*
* By default a topic metric collector does not group by topic type.
*
* @param groupByTopicType true to indicate that the collector
* should group by topic type
*
* @return this builder
*/
Builder groupByTopicType(boolean groupByTopicType);
/**
* Specifies the number of leading parts of the topic path the
* metric collector should use to group results.
*
*
* 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.
*
* @param parts the number of leading parts of the topic path to
* group by; set to 0 to disable grouping by path
* @return this builder
* @since 6.8
*/
Builder groupByPathPrefixParts(int parts);
/**
* Specifies whether the metric collector should group by topic view.
*
* By default a topic metric collector does not group by topic view.
*
* @param groupByTopicView true to indicate that the collector should group by topic view
* @return this builder
* @since 6.9
*/
Builder groupByTopicView(boolean groupByTopicView);
/**
* Create a new {@link TopicMetricCollector} using the values
* currently known to this builder.
*
* @param name the name of the {@link TopicMetricCollector}
*
* @param topicSelector the selector pattern that specifies the
* topics for which metrics are to be collected
*
* @return a new {@link TopicMetricCollector} with all of the
* current settings of this builder
* @throws IllegalArgumentException if this builder has been
* configured using {@link #groupByPathPrefixParts(int)} and
* a negative number of parts
*/
TopicMetricCollector create(String name, String topicSelector);
}
}
/**
* Add a session metric collector, replacing any with the same name.
*
* @param collector the session metric collector
*
* @return 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 {@link CompletionException}. Common reasons for failure, listed
* by the exception reported as the
* {@link CompletionException#getCause() cause}, include:
*
*
* - {@link InvalidFilterException} – if the metric
* collector session filter is invalid;
*
- {@link PermissionsException} – if the calling
* session does not have {@link GlobalPermission#CONTROL_SERVER
* CONTROL_SERVER} permission;
*
- {@link ClusterRoutingException} – if the operation
* failed due to a transient cluster error;
*
- {@link SessionClosedException} – if the session is
* closed.
*
*/
CompletableFuture putSessionMetricCollector(
SessionMetricCollector collector);
/**
* Retrieves the current session metric collectors.
*
* @return 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 {@link CompletionException}. Common reasons for failure, listed
* by the exception reported as the
* {@link CompletionException#getCause() cause}, include:
*
*
* - {@link PermissionsException} – if the calling
* session does not have {@link GlobalPermission#VIEW_SERVER
* VIEW_SERVER} permission;
*
- {@link SessionClosedException} – if the session is
* closed.
*
*/
CompletableFuture>
listSessionMetricCollectors();
/**
* Removes any session metric collector with the given name, if it exists.
*
* @param name the session metric collector name
*
* @return 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 {@link CompletionException}. Common reasons for failure, listed
* by the exception reported as the
* {@link CompletionException#getCause() cause}, include:
*
*
* - {@link PermissionsException} – if the calling
* session does not have {@link GlobalPermission#CONTROL_SERVER
* CONTROL_SERVER} permission;
*
- {@link ClusterRoutingException} – if the operation
* failed due to a transient cluster error;
*
- {@link SessionClosedException} – if the session is
* closed.
*
*/
CompletableFuture removeSessionMetricCollector(String name);
/**
* Add a topic metric collector, replacing any with the same name.
*
* A {@link TopicMetricCollector} instance can be created using
* {@link Diffusion#newTopicMetricCollectorBuilder
* newTopicMetricCollectorBuilder}.
*
* @param collector the topic metric collector
*
* @return 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 {@link CompletionException}. Common reasons for failure, listed
* by the exception reported as the
* {@link CompletionException#getCause() cause}, include:
*
*
* - {@link PermissionsException} – if the calling
* session does not have {@link GlobalPermission#CONTROL_SERVER
* CONTROL_SERVER} permission;
*
- {@link ClusterRoutingException} – if the operation
* failed due to a transient cluster error;
*
- {@link SessionClosedException} – if the session is
* closed.
*
*/
CompletableFuture putTopicMetricCollector(
TopicMetricCollector collector);
/**
* Retrieves the current topic metric collectors.
*
* @return 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 {@link CompletionException}. Common reasons for failure, listed
* by the exception reported as the
* {@link CompletionException#getCause() cause}, include:
*
*
* - {@link PermissionsException} – if the calling
* session does not have {@link GlobalPermission#VIEW_SERVER
* VIEW_SERVER} permission;
*
- {@link SessionClosedException} – if the session is
* closed.
*
*/
CompletableFuture> listTopicMetricCollectors();
/**
* Removes any topic metric collector with the given name, if it exists.
*
* @param name the topic metric collector name
*
* @return 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 {@link CompletionException}. Common reasons for failure, listed
* by the exception reported as the
* {@link CompletionException#getCause() cause}, include:
*
*
* - {@link PermissionsException} – if the calling
* session does not have {@link GlobalPermission#CONTROL_SERVER
* CONTROL_SERVER} permission;
*
- {@link ClusterRoutingException} – if the operation
* failed due to a transient cluster error;
*
- {@link SessionClosedException} – if the session is
* closed.
*
*/
CompletableFuture removeTopicMetricCollector(String name);
}