The Metrics Facet

11 min read

The Metrics facet provides convenient access to metrics for the Ice runtime and select Ice services. The metrics provided by this facet include the number of threads currently running and their state, the number of connections, information on invocations and dispatch, as well as connection establishment and endpoint name resolution.

Metrics Terminology

metric: an "analytical measurement intended to quantify the state of a system", recorded by the Ice runtime, such as bytes sent over a connection.
metric name: the name of the metric, such as "number of connections".
metrics map: a collection of metrics objects.
metrics view: a collection of metrics maps. A view contains metrics maps of different types (e.g., connections and threads). Several metrics views can be configured with different purposes. For example, you can have a "debug" metrics view to get detailed metrics of each of the instrumented objects in the Ice communicator. This view can be enabled from time to time for debugging purposes but it's disabled most of the time. You could also have a more coarse-grained metrics view to collect data at a higher level, such as the amount of bytes received and sent by all the connections from the communicator. This metrics view can be enabled all the time.

Metrics Types

Metrics are specified as Slice classes defined in the Ice/Metrics.ice Slice file. All the metrics types are defined in the IceMX module.

The base class is IceMX::Metrics:

Slice

class Metrics
{
    string id;
    long total = 0;
    int current = 0;
    long totalLifetime = 0;
    int failures = 0;
}

A metrics object is an instance of IceMX::Metrics and represents metrics of one or more instrumented objects. An instrumented object can be anything that supports instrumentation. The Ice runtime supports instrumentation of the following objects and activities:

Threads
Connections
Invocations
Dispatches
Connection establishment
Endpoint resolution

The id of a metric identifies the instrumented object(s). The total and current members specify the total and current number of instrumented objects created since the creation of the Ice communicator, respectively. The totalLifetime member is the sum of the lifetime of each instrumented object and failures is the number of failures that have occurred for the metrics object(s).

Failures are specified using a separate IceMX::MetricsFailures structure:

Slice

struct MetricsFailures
{
    string id;
    StringIntDict failures;
}

The failures dictionary provides the count of each type of failure for a metric identified by id. Failures are dependent on the instrumented objects. For example, failures for Ice connections are represented with the name of the exception that caused the connection to fail (e.g., Ice::ConnectionLostException or Ice::TimeoutException).

A metrics map is simply defined as a sequence of IceMX::Metrics objects, and a metrics view is defined as a dictionary of metrics map:

Slice

sequence<Metrics> MetricsMap;
dictionary<string, MetricsMap> MetricsView;

The key for the metrics view dictionary is a string that identifies the metrics map. The Ice runtime supports the following metrics maps:

Metrics map name	Slice class	Description
Connection	`IceMX::ConnectionMetrics`	Connection metrics.
Thread	`IceMX::ThreadMetrics`	Thread metrics. The Ice runtime instruments threads for the communicator's thread pools as well as threads used internally.
Invocation	`IceMX::InvocationMetrics`	Client-side proxy invocation metrics.
Dispatch	`IceMX::DispatchMetrics`	Server-side dispatch metrics.
EndpointLookup	`IceMX::Metrics`	Endpoint lookup metrics. For tcp, ssl and udp endpoints, this corresponds to the DNS lookups made to resolve the host names in endpoints.
ConnectionEstablishment	`IceMX::Metrics`	Connection establishment metrics.

A metrics map can also contain sub-metrics maps. An example is the Invocation metrics map, which provides a Remote sub-metrics map to record metrics associated with remote invocations. The Slice class for remote invocation metrics is IceMX::Metrics.

The `MetricsAdmin` Interface

The Slice interface IceMX::MetricsAdmin allows you to retrieve the metrics associated with the Ice communicator:

Slice

module IceMX
{
    exception UnknownMetricsView {}

    interface MetricsAdmin
    {
        Ice::StringSeq getMetricsViewNames(out Ice::StringSeq disableViews);

        void enableMetricsView(string name)
            throws UnknownMetricsView;

        void disableMetricsView(string name)
            throws UnknownMetricsView;

        MetricsView getMetricsView(string view, out long timestamp)
            throws UnknownMetricsView;

        MetricsFailuresSeq getMapMetricsFailures(string view, string map)
            throws UnknownMetricsView;

        MetricsFailures getMetricsFailures(string view, string map, string id)
            throws UnknownMetricsView;
    }
}

The getMetricsViewName operation retrieves the names of the configured enabled and disabled views. The enableMetricsView and disableMetricsView operations allow you to enable and disable a specific view. Calling those operations is equivalent to setting the view Disabled property to 1 or 0.The getMetricsView operation returns the metrics for the given view. The getMapMetricsFailures and getMetricsFailures operations retrieve the metrics failures for a given map or metrics id.