The Metrics Facet

The Metrics facet provides the metrics of the Ice runtime and of the Glacier2 and IceStorm services. The Ice runtime metrics cover threads and their state, connections, invocations, dispatches, connection establishment, and endpoint resolution.

Metrics Terminology

• metric: a measurement that the Ice runtime records, such as the number of bytes sent over a connection.
• instrumented object: what the Ice runtime measures: a thread, a connection, an invocation, a dispatch, a connection establishment, or an endpoint lookup.
• metrics object: the metrics of one or more instrumented objects, such as all the invocations of the sayHello operation.
• metrics map: the metrics objects of one kind of instrumented object, keyed by their id, such as the Connection map, which by default holds one metrics object per connection.
• metrics view: a named set of metrics maps that you configure and enable together; see Configuring Metrics Views.

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:

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

The fields of Metrics are:

• id: the ID of the metrics object, built from the attributes named by the map's GroupBy property.
• total: the number of instrumented objects that the metrics object has observed since its creation.
• current: the number of instrumented objects it observes now.
• totalLifetime: the sum, in microseconds, of the lifetimes of the instrumented objects it no longer observes.
• failures: the number of failures that have occurred for these instrumented objects.

Each IceMX::MetricsFailures structure counts the failures of one metrics object:

struct MetricsFailures
{
    string id;
    StringIntDict failures;
}

• id: the ID of the metrics object.
• failures: the number of failures of each kind, keyed by the type ID of the exception that caused them, such as ::Ice::ConnectionLostException for a connection.

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:

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:

An invocation on a proxy results in one or more child invocations: a remote invocation each time Ice sends the request over a connection, or a collocated invocation each time Ice dispatches it directly to a collocated object adapter. An invocation that Ice retries has several child invocations. The Invocation map records them in two sub-maps, stored in each IceMX::InvocationMetrics object:

• Remote, in the remotes field: IceMX::RemoteMetrics objects for the remote invocations.
• Collocated, in the collocated field: IceMX::CollocatedMetrics objects for the collocated invocations.

Both classes derive from IceMX::ChildInvocationMetrics.

The classes derived from IceMX::Metrics add the following fields:

The MetricsAdmin Interface

The Metrics facet implements the Slice interface IceMX::MetricsAdmin, whose operations return the metrics of a view and the failures recorded by a map or by a metrics object, and enable or disable a view. Enabling or disabling a view has the same effect as setting its Disabled property to 0 or 1.

// It's nullptr when the facet is not enabled
auto metricsAdmin = communicator->findAdminFacet<IceMX::MetricsAdmin>("Metrics");

if (communicator.findAdminFacet("Metrics") is IceMX.MetricsAdmin metricsAdmin)
{
    ...
}
// else, the facet is not enabled

com.zeroc.Ice.Object obj = communicator.findAdminFacet("Metrics");
if (obj != null) { // It's null when the facet is not enabled
    var metricsAdmin = (com.zeroc.IceMX.MetricsAdmin)obj;
    ...
}

Configuring Metrics Views

The Metrics facet records metrics only for the views you configure with IceMX Metrics properties. For example, the following configuration enables the Metrics facet and defines a view named Debug that records invocation and dispatch metrics grouped by operation:

Ice.Admin.Endpoints=tcp -h localhost -p 10002
Ice.Admin.InstanceName=MyServer
IceMX.Metrics.Debug.Map.Invocation.GroupBy=operation
IceMX.Metrics.Debug.Map.Invocation.Map.Remote.GroupBy=id
IceMX.Metrics.Debug.Map.Invocation.Map.Collocated.GroupBy=id
IceMX.Metrics.Debug.Map.Dispatch.GroupBy=operation

You can also update the IceMX.* properties at run time through the Properties facet: the Metrics facet then creates, updates, or removes the corresponding views and maps. A map that you reconfigure and a view that you disable lose the metrics they recorded.

Metrics Attributes

The GroupBy, Accept and Reject properties are specified using attributes that are specific to each metrics map. The tables below describe the attributes supported by the Ice runtime's metrics maps, grouped by what they describe.

Attributes of Every Map

All maps support these attributes:

Endpoint Attributes

The Connection, Dispatch, Remote, ConnectionEstablishment, and EndpointLookup maps support these attributes:

Connection Attributes

The Connection, Dispatch, and Remote maps support these attributes:

Request Attributes

The Dispatch and Invocation maps support these attributes:

The Dispatch, Remote, and Collocated maps support the requestId attribute: the request ID of the dispatch or invocation; 0 for a oneway request.

Attributes of a Single Map

The parent Attribute

The value of the parent attribute depends on the map:

Grouping Examples

The GroupBy property sets the level of detail of a map:

• GroupBy=parent groups the metrics by object adapter or communicator. For instance, the following configuration groups all the metrics this way and does not monitor any metrics for the Ice.Admin object adapter:

  Properties

  IceMX.Metrics.MyView.GroupBy=parent
  IceMX.Metrics.MyView.Reject.parent=Ice\.Admin   # Escape the dot in Ice.Admin

• GroupBy=none records all the statistics of a map in a single metrics object, for the whole communicator:

  Properties

  IceMX.Metrics.MyView.GroupBy=none

• GroupBy=id records the statistics of a map in one metrics object per id. Each map computes id from its instrumented object; for example, the id of a dispatch is the target identity followed by the operation name:

  Properties

  IceMX.Metrics.MyView.GroupBy=id

See Also

• IceMX.Metrics.*
• Glacier2 Metrics
• IceStorm Metrics
• Using the admin Object