Options
All
  • Public
  • Public/Protected
  • All
Menu

Interface Metrics

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

Accessing the feature

This feature may be obtained from a session as follows:

const metrics = session.metrics;
author

DiffusionData Limited

since

6.7

Hierarchy

  • Metrics

Index

Methods

Methods

listMetricAlerts

  • List all metric alerts that have been created.

    since

    6.12

    Returns Promise<MetricAlert[]>

    a Promise that resolves when a response is received from the server, returning a list of metric alerts sorted by their creation order.

        If the task fails, the Promise will reject with an Error. Common
    reasons for failure, listed by the exception, include:

    <ul>
    <li>{@link ClusterRoutingException} &ndash; if the operation
    failed due to a transient cluster error;
    <li>{@link PermissionsException} &ndash; if the calling session
    does not have CONTROL_SERVER permission;
    <li>{@link SessionClosedException} &ndash; if the session is
    closed.
    </ul>

listSessionMetricCollectors

  • Retrieves the current session metric collectors.

    Returns Promise<SessionMetricCollectorList>

    a Promise that completes when a response is received from the server.

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

    Otherwise, the Promise will reject with an Error. Common reasons for failure include:

    • if the calling session does not have VIEW_SERVER permission;
    • if the session is closed.

listTopicMetricCollectors

  • Retrieves the current topic metric collectors.

    Returns Promise<TopicMetricCollectorList>

    a Promise that completes when a response is received from the server.

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

    Otherwise, the Promise will reject with an Error. Common reasons for failure include:

    • if the calling session does not have VIEW_SERVER permission;
    • if the session is closed.

metricsRequest

putSessionMetricCollector

  • Add a session metric collector, replacing any with the same name.

    A SessionMetricCollector instance can be created using newSessionMetricCollectorBuilder.

    Parameters

    Returns Promise<any>

    a Promise that resolves when a response is received from the server.

    If the task completes successfully, the 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 Promise will reject with an Error. Common reasons for failure include:

    • if the metric collector session filter is invalid;
    • if the calling session does not have CONTROL_SERVER permission;
    • if the operation failed due to a transient cluster error;
    • if the session is closed.
    • NullValueError – if the collector is null or undefined

putTopicMetricCollector

  • Add a topic metric collector, replacing any with the same name.

    A TopicMetricCollector instance can be created using newTopicMetricCollectorBuilder.

    Parameters

    Returns Promise<any>

    a Promise that resolves when a response is received from the server.

    If the task completes successfully, the 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 Promise will reject with an Error. Common reasons for failure include:

    • if the metric collector session filter is invalid;
    • if the calling session does not have CONTROL_SERVER permission;
    • if the operation failed due to a transient cluster error;
    • if the session is closed.
    • NullValueError – if the collector is null or undefined

removeMetricAlert

  • removeMetricAlert(name: string): Promise<void>

  • Remove a named metric alert if it exists.

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

    since

    6.12

    Parameters

    • name: string

      the name of the metric alert

    Returns Promise<void>

    a Promise that resolves when a response is received from the server.

        If the task fails, the Promise will reject with an Error. Common
    reasons for failure, listed by the exception, include:

    <ul>
    <li>{@link ClusterRoutingException} &ndash; if the operation
    failed due to a transient cluster error;
    <li>{@link PermissionsException} &ndash; if the calling session
    does not have CONTROL_SERVER permission;
    <li>{@link SessionClosedException} &ndash; if the session is
    closed.
    </ul>

removeSessionMetricCollector

  • removeSessionMetricCollector(name: string): Promise<any>

  • Removes any session metric collector with the given name, if it exists.

    Parameters

    • name: string

      the session metric collector name

    Returns Promise<any>

    a Promise that resolves when a response is received from the server.

    If the task completes successfully, the 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 Promise will reject with an Error. Common reasons for failure include:

    • if the calling session does not have CONTROL_SERVER permission;
    • if the operation failed due to a transient cluster error;
    • if the session is closed.
    • NullValueError – if the name is null or undefined

removeTopicMetricCollector

  • removeTopicMetricCollector(name: string): Promise<any>

  • Removes any topic metric collector with the given name, if it exists.

    Parameters

    • name: string

      the topic metric collector name

    Returns Promise<any>

    a Promise that resolves when a response is received from the server.

    If the task completes successfully, the 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 Promise will reject with an Error. Common reasons for failure include:

    • if the calling session does not have CONTROL_SERVER permission;
    • if the operation failed due to a transient cluster error;
    • if the session is closed.
    • NullValueError – if the collector is null or undefined

setMetricAlert

  • setMetricAlert(name: string, specification: string): Promise<void>

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

    since

    6.12

    Parameters

    • name: string

      the name of the metric alert. This name is used to uniquely identify the alert.

    • specification: string

      the specification of the metric alert. This defines the conditions under which the alert is triggered and the actions to be taken.

    Returns Promise<void>

    a Promise that resolves when a response is received from the server. If the operation is successful, the Promise resolves normally.

        If the task fails, the Promise will reject with an Error. Common
    reasons for failure, listed by the exception, include:

    <ul>
    <li>{@link ScriptException} &ndash; if {@code specification} is
        invalid;
    <li>{@link ClusterRoutingException} &ndash; if the operation
        failed due to a transient cluster error;
    <li>{@link PermissionsException} &ndash; if the calling session
        does not have CONTROL_SERVER permission;
    <li>{@link SessionClosedException} &ndash; if the session is
        closed;
    </ul>