io.mats3.intercept.micrometer

Class MatsMicrometerInterceptor

java.lang.Object

io.mats3.intercept.micrometer.MatsMicrometerInterceptor

All Implemented Interfaces:

MatsInitiateInterceptor, MatsInterceptable.MatsMetricsInterceptor, MatsStageInterceptor

public class MatsMicrometerInterceptor
extends java.lang.Object
implements MatsInterceptable.MatsMetricsInterceptor, MatsInitiateInterceptor, MatsStageInterceptor

An interceptor that instruments a MatsFactory with metrics using the (Spring) Micrometer framework. If you provide a MeterRegistry, it will employ this to create the metrics on, otherwise it employs the Metrics.globalRegistry.

Note: This interceptor (Micrometer Metrics) has special support in JmsMatsFactory: If present on the classpath, it is automatically installed using the install(MatsInterceptableMatsFactory) install method. This implies that it employs the Micrometer 'globalRegistry' - and 'includeAllTags' will be false. If you rather want to supply a specific registry, then install a different instance using the install(MatsInterceptableMatsFactory, MeterRegistry, boolean) method - the JmsMatsFactory will then remove the automatically installed, since it implements the special marker-interface MatsInterceptable.MatsMetricsInterceptor of which there can only be one instance installed. (In a Spring context where the MatsFactory is created for you using an annotation, you are still able to do this during early phases of Spring initialization: E.g. inject a reference to the MatsInterceptable (the MatsFactory) and just install the new instance. This is possible since the Micrometer meters are lazily created when initiations are performed and Mats Stages receives messages. The decision of which tags are in use is therefore not needed until right before the service becomes operational, that is, performs inits and receives messages.)

Note the argument 'includeAllTags' on the second install(..) method: If this is true, then tags will be added to the meters which will give higher semantic resolution and more information, but which might result in a quite substantial number of time series - if you have a popular Mats endpoint with many stages targeted by many other services (thus getting many differing 'from', 'initiatingAppName' and 'initiatorId'), you may get a "cardinality explosion", in particular if you also configure histograms. It is thus false by default, i.e. when using the first install(..) method.
Which extra tags are omitted in which situations when 'includeAllTags' is false:

• Received (incoming message): "from" (from which stage) for initial stage, "initiatingAppName" and "initiatorId".
• Stage execution: "initiatingAppName" and "initiatorId".
• Stage outgoing messages: "to" (to which stage) for REPLY-messages (as that will have same cardinality as 'from'), "initiatingAppName" and "initiatorId".

You may set 'includeAllTags' to true, and then use a MeterFilter to tweak the tags with more precision than this all-or-nothing approach, e.g. include "initiatingAppName" and "initiatorId" for specific endpoints or stages.

Notice the class MatsMicrometerInterceptor.SuggestedTimingHistogramsMeterFilter, which configures the timing-specific metrics with hopefully relevant histograms. You may apply this as such:
Metrics.globalRegistry.config().meterFilter(new SuggestedTimingHistogramsMeterFilter());
.. or you may apply any other distribution or histogram configuration using the MeterFilter logic of Micrometer.

See Also:

MatsMicrometerInterceptor.SuggestedTimingHistogramsMeterFilter

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	MatsMicrometerInterceptor.SuggestedTimingHistogramsMeterFilter A MeterFilter that applies a hopefully reasonable histogram to all timing meters.

Nested classes/interfaces inherited from interface io.mats3.api.intercept.MatsInitiateInterceptor

MatsInitiateInterceptor.InitiateCompletedContext, MatsInitiateInterceptor.InitiateInterceptContext, MatsInitiateInterceptor.InitiateInterceptOutgoingMessagesContext, MatsInitiateInterceptor.InitiateInterceptUserLambdaContext, MatsInitiateInterceptor.InitiateStartedContext, MatsInitiateInterceptor.MatsInitiateInterceptOutgoingMessages, MatsInitiateInterceptor.MatsInitiateInterceptUserLambda

Nested classes/interfaces inherited from interface io.mats3.api.intercept.MatsStageInterceptor

MatsStageInterceptor.MatsStageInterceptOutgoingMessages, MatsStageInterceptor.MatsStageInterceptUserLambda, MatsStageInterceptor.StageCommonContext, MatsStageInterceptor.StageCompletedContext, MatsStageInterceptor.StageInterceptContext, MatsStageInterceptor.StageInterceptOutgoingMessageContext, MatsStageInterceptor.StageInterceptUserLambdaContext, MatsStageInterceptor.StagePreprocessAndDeserializeErrorContext, MatsStageInterceptor.StageReceivedContext

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	LOG_PREFIX
static int	MAX_NUMBER_OF_METRICS This is a cardinality-explosion-avoidance limit in case of wrongly used initiatorIds.
static java.lang.String	MEASURE_EXEC_OP_PREFIX
static java.lang.String	QUANTITY_EXEC_OUT_DESC
static java.lang.String	QUANTITY_EXEC_OUT_NAME
static java.lang.String	SIZE_OUT_ENVELOPE_DESC
static java.lang.String	SIZE_OUT_ENVELOPE_NAME
static java.lang.String	SIZE_OUT_WIRE_DESC
static java.lang.String	SIZE_OUT_WIRE_NAME
static java.lang.String	TAG_APP_NAME
static java.lang.String	TAG_APP_VERSION
static java.lang.String	TAG_EXEC
static java.lang.String	TAG_FROM
static java.lang.String	TAG_INITIATING_APP_NAME
static java.lang.String	TAG_INITIATOR_ID
static java.lang.String	TAG_INITIATOR_NAME
static java.lang.String	TAG_STAGE_ID
static java.lang.String	TAG_STAGE_INDEX
static java.lang.String	TAG_TO
static java.lang.String	TAG_TYPE
static java.lang.String	TIMER_EXEC_DB_COMMIT_DESC
static java.lang.String	TIMER_EXEC_DB_COMMIT_NAME
static java.lang.String	TIMER_EXEC_MSGSYS_COMMIT_DESC
static java.lang.String	TIMER_EXEC_MSGSYS_COMMIT_NAME
static java.lang.String	TIMER_EXEC_OPS_PREFIX
static java.lang.String	TIMER_EXEC_OUT_DESC
static java.lang.String	TIMER_EXEC_OUT_NAME
static java.lang.String	TIMER_EXEC_TOTAL_DESC
static java.lang.String	TIMER_EXEC_TOTAL_NAME
static java.lang.String	TIMER_EXEC_USER_LAMBDA_DESC
static java.lang.String	TIMER_EXEC_USER_LAMBDA_NAME
static java.lang.String	TIMER_IN_TOTAL_DESC
static java.lang.String	TIMER_IN_TOTAL_NAME
static java.lang.String	TIMER_OUT_MSGSYS_SEND_DESC
static java.lang.String	TIMER_OUT_MSGSYS_SEND_NAME
static java.lang.String	TIMER_OUT_TOTAL_DESC
static java.lang.String	TIMER_OUT_TOTAL_NAME
static java.lang.String	UNIT_BYTES

Fields inherited from interface io.mats3.api.intercept.MatsInterceptable.MatsMetricsInterceptor

INITIATOR_ID_WHEN_NO_OUTGOING_MESSAGES

Method Summary

Modifier and Type	Method and Description
void	initiateCompleted(MatsInitiateInterceptor.InitiateCompletedContext ctx)
static MatsMicrometerInterceptor	install(MatsInterceptableMatsFactory matsInterceptableMatsFactory) Creates a MatsMicrometerInterceptor employing the provided globalRegistry, and installs it as a singleton on the provided MatsInterceptableMatsFactory
static MatsMicrometerInterceptor	install(MatsInterceptableMatsFactory matsInterceptableMatsFactory, io.micrometer.core.instrument.MeterRegistry meterRegistry, boolean includeAllTags) Creates a MatsMicrometerInterceptor employing the provided MeterRegistry, and installs it as a singleton on the provided MatsInterceptableMatsFactory
void	stageCompleted(MatsStageInterceptor.StageCompletedContext ctx) Invoked after the stage is fully completed, outgoing messages sent, db and messaging system committed.
void	stageReceived(MatsStageInterceptor.StageReceivedContext ctx) Invoked right after message have been received, preprocessed and deserialized, before invoking the user lambda.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface io.mats3.api.intercept.MatsInitiateInterceptor

initiateStarted

Methods inherited from interface io.mats3.api.intercept.MatsStageInterceptor

stageCompletedNextDirect, stagePreprocessAndDeserializeError

Field Detail

LOG_PREFIX

public static final java.lang.String LOG_PREFIX

See Also:

Constant Field Values

TIMER_EXEC_TOTAL_NAME

public static final java.lang.String TIMER_EXEC_TOTAL_NAME

See Also:

Constant Field Values

TIMER_EXEC_TOTAL_DESC

public static final java.lang.String TIMER_EXEC_TOTAL_DESC

See Also:

Constant Field Values

TIMER_EXEC_USER_LAMBDA_NAME

public static final java.lang.String TIMER_EXEC_USER_LAMBDA_NAME

See Also:

Constant Field Values

TIMER_EXEC_USER_LAMBDA_DESC

public static final java.lang.String TIMER_EXEC_USER_LAMBDA_DESC

See Also:

Constant Field Values

TIMER_EXEC_OUT_NAME

public static final java.lang.String TIMER_EXEC_OUT_NAME

See Also:

Constant Field Values

TIMER_EXEC_OUT_DESC

public static final java.lang.String TIMER_EXEC_OUT_DESC

See Also:

Constant Field Values

QUANTITY_EXEC_OUT_NAME

public static final java.lang.String QUANTITY_EXEC_OUT_NAME

See Also:

Constant Field Values

QUANTITY_EXEC_OUT_DESC

public static final java.lang.String QUANTITY_EXEC_OUT_DESC

See Also:

Constant Field Values

TIMER_EXEC_DB_COMMIT_NAME

public static final java.lang.String TIMER_EXEC_DB_COMMIT_NAME

See Also:

Constant Field Values

TIMER_EXEC_DB_COMMIT_DESC

public static final java.lang.String TIMER_EXEC_DB_COMMIT_DESC

See Also:

Constant Field Values

TIMER_EXEC_MSGSYS_COMMIT_NAME

public static final java.lang.String TIMER_EXEC_MSGSYS_COMMIT_NAME

See Also:

Constant Field Values

TIMER_EXEC_MSGSYS_COMMIT_DESC

public static final java.lang.String TIMER_EXEC_MSGSYS_COMMIT_DESC

See Also:

Constant Field Values

TIMER_EXEC_OPS_PREFIX

public static final java.lang.String TIMER_EXEC_OPS_PREFIX

See Also:

Constant Field Values

MEASURE_EXEC_OP_PREFIX

public static final java.lang.String MEASURE_EXEC_OP_PREFIX

See Also:

Constant Field Values

TIMER_IN_TOTAL_NAME

public static final java.lang.String TIMER_IN_TOTAL_NAME

See Also:

Constant Field Values

TIMER_IN_TOTAL_DESC

public static final java.lang.String TIMER_IN_TOTAL_DESC

See Also:

Constant Field Values

TIMER_OUT_TOTAL_NAME

public static final java.lang.String TIMER_OUT_TOTAL_NAME

See Also:

Constant Field Values

TIMER_OUT_TOTAL_DESC

public static final java.lang.String TIMER_OUT_TOTAL_DESC

See Also:

Constant Field Values

TIMER_OUT_MSGSYS_SEND_NAME

public static final java.lang.String TIMER_OUT_MSGSYS_SEND_NAME

See Also:

Constant Field Values

TIMER_OUT_MSGSYS_SEND_DESC

public static final java.lang.String TIMER_OUT_MSGSYS_SEND_DESC

See Also:

Constant Field Values

SIZE_OUT_ENVELOPE_NAME

public static final java.lang.String SIZE_OUT_ENVELOPE_NAME

See Also:

Constant Field Values

SIZE_OUT_ENVELOPE_DESC

public static final java.lang.String SIZE_OUT_ENVELOPE_DESC

See Also:

Constant Field Values

SIZE_OUT_WIRE_NAME

public static final java.lang.String SIZE_OUT_WIRE_NAME

See Also:

Constant Field Values

SIZE_OUT_WIRE_DESC

public static final java.lang.String SIZE_OUT_WIRE_DESC

See Also:

Constant Field Values

TAG_APP_NAME

public static final java.lang.String TAG_APP_NAME

See Also:

Constant Field Values

TAG_APP_VERSION

public static final java.lang.String TAG_APP_VERSION

See Also:

Constant Field Values

TAG_EXEC

public static final java.lang.String TAG_EXEC

See Also:

Constant Field Values

TAG_TYPE

public static final java.lang.String TAG_TYPE

See Also:

Constant Field Values

TAG_INITIATING_APP_NAME

public static final java.lang.String TAG_INITIATING_APP_NAME

See Also:

Constant Field Values

TAG_INITIATOR_NAME

public static final java.lang.String TAG_INITIATOR_NAME

See Also:

Constant Field Values

TAG_INITIATOR_ID

public static final java.lang.String TAG_INITIATOR_ID

See Also:

Constant Field Values

TAG_STAGE_ID

public static final java.lang.String TAG_STAGE_ID

See Also:

Constant Field Values

TAG_STAGE_INDEX

public static final java.lang.String TAG_STAGE_INDEX

See Also:

Constant Field Values

TAG_FROM

public static final java.lang.String TAG_FROM

See Also:

Constant Field Values

TAG_TO

public static final java.lang.String TAG_TO

See Also:

Constant Field Values

UNIT_BYTES

public static final java.lang.String UNIT_BYTES

See Also:

Constant Field Values

MAX_NUMBER_OF_METRICS

public static final int MAX_NUMBER_OF_METRICS

This is a cardinality-explosion-avoidance limit in case of wrongly used initiatorIds. These are not supposed to be dynamic, but there is nothing hindering a user from creating a new initiatorId per initiation. Thus, if we go above a certain number of such entries, we stop adding.

Value is 200.

See Also:

Constant Field Values

Method Detail

install

public static MatsMicrometerInterceptor install(MatsInterceptableMatsFactory matsInterceptableMatsFactory,
                                                io.micrometer.core.instrument.MeterRegistry meterRegistry,
                                                boolean includeAllTags)

Creates a MatsMicrometerInterceptor employing the provided MeterRegistry, and installs it as a singleton on the provided MatsInterceptableMatsFactory

Parameters:

matsInterceptableMatsFactory - the MatsInterceptable to install on (probably a MatsFactory.

meterRegistry - the Micrometer MeterRegistry to create meters on.

includeAllTags - whether all tags should be included (which may easily result in very many time series) or not.

Returns:

the MatsMicrometerInterceptor instance which was installed as singleton.

install

public static MatsMicrometerInterceptor install(MatsInterceptableMatsFactory matsInterceptableMatsFactory)

Creates a MatsMicrometerInterceptor employing the provided globalRegistry, and installs it as a singleton on the provided MatsInterceptableMatsFactory

Parameters:

matsInterceptableMatsFactory - the MatsInterceptable to install on (probably a MatsFactory.

Returns:

the MatsMicrometerInterceptor instance which was installed as singleton.

initiateCompleted

public void initiateCompleted(MatsInitiateInterceptor.InitiateCompletedContext ctx)

Specified by:

initiateCompleted in interface MatsInitiateInterceptor

stageReceived

public void stageReceived(MatsStageInterceptor.StageReceivedContext ctx)

Description copied from interface: MatsStageInterceptor

Invoked right after message have been received, preprocessed and deserialized, before invoking the user lambda. (If any error occurs during preprocess or deserialization, then MatsStageInterceptor.stagePreprocessAndDeserializeError(StagePreprocessAndDeserializeErrorContext) is invoked instead).

Specified by:

stageReceived in interface MatsStageInterceptor

stageCompleted

public void stageCompleted(MatsStageInterceptor.StageCompletedContext ctx)

Description copied from interface: MatsStageInterceptor

Invoked after the stage is fully completed, outgoing messages sent, db and messaging system committed. You cannot anymore modify any outgoing messages etc - for this, implement MatsStageInterceptor.MatsStageInterceptOutgoingMessages.

Specified by:

stageCompleted in interface MatsStageInterceptor

See Also:

MatsStageInterceptor.stageCompletedNextDirect(StageCompletedContext)