Documentation for a newer release is available. View Latest
Esta página no está disponible actualmente en Español. Si lo necesita, póngase en contacto con el servicio de asistencia de Icon (correo electrónico)

Metrics

Payment Metrics

Payment metrics are produced when a payment has finished. They are a counter of finished payments, the duration of the end-to-end payment, and if configured, the duration of the payments critical path and its time spent waiting.

Each metric is also labelled, see the Labels section for more information.

Available Metrics

Payments Finished

The metric ipf_businessmetrics_payments_finished_total represents a count of finished payments. A payment is determined to be finished when its global state is terminal, which is achieved by querying the ODS database for the set of terminal global states.

The terminal states are cached to avoid having to query ODS for each payment.

End to End Payment Duration

The metric ipf_businessmetrics_payments_duration_seconds represents the duration of finished payments, as three separate metrics.

Metric Description

ipf_businessmetrics_payments_duration_seconds_count

The total number of durations produced. There will be one per finished payment. If five payments finish, this counter will be five.

ipf_businessmetrics_payments_duration_seconds_max

The largest payment duration (in seconds).

ipf_businessmetrics_payments_duration_seconds_sum

The sum of all payment durations (in seconds).

These metrics allow you to determine the mean payment duration, e.g.

\$"ipf_businessmetrics_payments_duration_seconds_sum" / "ipf_businessmetrics_payments_duration_seconds_count"\$

Critical Path Duration

The metric ipf_businessmetrics_payments_criticalpath_duration_seconds represents the time payments spent in the configured critical path. The critical path is defined by a start and end state, and may be different between different payment types. This metric is only produced if the finished payment went through both the start and end states.

The metrics processor will first look at the incoming events and attempt to calculate the critical path duration from those events that are labelled CRITICAL_PATH_START, and CRITICAL_PATH_END. If the duration cannot be determined, and legacy configuration exists (see below), the configuration will be used to calculate the critical path duration. If neither approach succeeds, the metric is not published.

The CRITICAL_PATH_START, and CRITICAL_PATH_END labels may appear in events across flows for a unit of work. There must be an end matching each start.

It’s possible for a unit of work to start and finish many critical paths. In this case the critical path duration is the sum. If smaller critical paths occur within a larger critical path, the larger critical path is used.

The critical path duration is defined as three separate metrics.

Metric Description

ipf_businessmetrics_payments_criticalpath_duration_seconds_count

The total number of durations produced. There will be one per finished payment that went through a critical path. If five payments finish, and three went through a critical path, this counter will be three.

ipf_businessmetrics_payments_criticalpath_duration_seconds_max

The largest critical path duration (in seconds).

ipf_businessmetrics_payments_criticalpath_duration_seconds_sum

The sum of all critical path durations (in seconds).

These metrics allow you to determine the mean critical path duration, e.g.

\$"ipf_businessmetrics_payments_criticalpath_duration_seconds_sum" / "ipf_businessmetrics_payments_criticalpath_duration_seconds_count"\$

Critical Path Configuration - Deprecated

This configuration is deprecated, and exists only for backward compatibility. It will be unsupported in a future release.
This configuration is not required if payment flows produce events with labels indicating the critical path start and end.

The Critical Path configuration defines any number of payment-type-mappings that specify how to calculate the Critical Path Duration for a given payment type.

ipf.business-metrics-processor.payment-metrics.payment-duration {
  critical-path {
    critical-path-states-by-payment-type = [
      {
        paymentType = "Debtor CT"
        start-state = "Validating"
        end-state   = "Instructing"
      }
    ]
  }
}

The above configuration will only calculate the critical path duration of Debtor CT payment types. The Duration is calculated by taking the difference between the timestamp of the Process Flow Event with status.globalStatus=Validating and the timestamp of the Process Flow Event with status.globalStatus=Instructing

Waiting Duration

The waiting duration metrics indicate how long payments spend in pre-defined waiting states

The metric ipf_businessmetrics_payments_waiting_duration_seconds represents the time payments spent in pre-defined waiting states. This is typically the time the IPF payment flows spend waiting on external systems, such as those provided by the client bank, e.g. when the payment flow makes a call to a banks system to perform some part of the payment processing.

The waiting states are defined on states or events in payment flows. When the Metrics Processor receives events (which includes a new resulting state) that contains the label WAITING_DURATION, it calculates the time spent in the resulting state and sums with all other waiting states. If a payment comprises many flows, the sum of all waiting states across flows is the total waiting duration.

If the incoming events are not labelled, and legacy configuration exists (see below), the configuration will be used to calculate the total waiting duration. If neither approach succeeds, the metric is not published

Example

A payment is processed by a single flow that can be in states [A, B, C, D, E] where B is considered a waiting state. The time that the payment flow transitions from A to B (entering B) is the start time, and the time that the payment flow transitions from B to C (leaving B) is the end time. The difference between the start and end time is the waiting duration.

A payment may be processed by many flows, each with many possible waiting states. The payments waiting duration is the sum of time it spent in all waiting states.

This metric is only produced if the finished payment actually spent time waiting, and like the other duration metrics, is defined as three separate metrics.

Metric Description

ipf_businessmetrics_payments_waiting_duration_seconds_count

The total number of durations produced. There will be one per finished payment that spent a non-zero time waiting. If five payments finish, and three spent time waiting, this counter will be three.

ipf_businessmetrics_payments_waiting_duration_seconds_max

The largest waiting duration (in seconds).

ipf_businessmetrics_payments_waiting_duration_seconds_sum

The sum of all waiting durations (in seconds).

These metrics allow you to determine the mean waiting duration, e.g. "ipf_businessmetrics_payments_waiting_duration_seconds_sum" / "ipf_businessmetrics_payments_waiting_duration_seconds_count"

Waiting Duration Configuration - Deprecated

This configuration is deprecated, and exists only for backward compatibility. It will be unsupported in a future release.
This configuration is not required if payment flows produce events with labels indicating the waiting states.

The Waiting Duration configuration defines a list of statuses per flow that are considered as a waiting statuses. These statuses match against the Resulting Status and Originating Status of two Process Flow Events that are ingested for a given Flow.

ipf.business-metrics-processor.payment-metrics.payment-duration {
  waiting {
    waiting-states-by-flow = [
      {
        flow-name = "PaymentExecutionFlowV1"
        states = [ "Checking Bank System A", "Checking Bank System B" ]
      }
    ]
  }
}

Given the above configuration, the waiting states for PaymentExecutionFlowV1 are Checking Bank System A and Checking Bank System B. This means that for a payment from this flow, the waiting duration is the sum of the following two Durations:

  • The Duration between the timestamp of the Process Flow Event with status.resultingStatus=Checking Bank System A and the timestamp of the Process Flow Event with status.originatingStatus=Checking Bank System A

  • The Duration between the timestamp of the Process Flow Event with status.resultingStatus=Checking Bank System B and the timestamp of the Process Flow Event with status.originatingStatus=Checking Bank System B

Labels

Labels are applied to all the produced payment metrics, and they can be used to drill down into those metrics, e.g. The count of all finished payments that are Completed vs Cancelled, or a count of all finished payments that went via the CSM RT1.

Default Label Values

In most cases a default label value of "Unknown" is applied to any payment metric label where that label value cannot be determined for that payment.

This can occur when the source for the label value is never received, e.g. there’s no Csm PDS object for the payment, or when configuration is missing for a specific label, e.g. currency mapping configuration.

Payment metrics will be labelled with the following…​

Label Description

csm

The CSM of the payment

Mapped from a Csm PDS object that is produced for a payment.

currency

The currency of the payment

Mapped when currency mappings are configured, and the configured source PDS object is produced by a payment.

direction

The direction of the payment.

Mapped when direction mappings are configured, and the payment produces a PaymentType PDS object.

htm

A flag that indicates if a payment went through Human Task Manager

Always present with a default of "No", and only "Yes" when payments produce an event that is deemed to be an HTM event.

paymentType

The type of the payment

Mapped from a PaymentType PDS object that is produced for a payment.

state

The final global state of the payment.

localInstrument

The local instrument that facilitates the transfer of funds.

Mapped when local instrument mappings are configured, and the configured source PDS object is produced by a payment.

clientChannel

The client payment initiation channel used for a payment.

Mapped when client channel mappings are configured, and the configured source PDS object is produced by a payment.

errorCode

The most recent error code for a given unit of work.

Always present with a default of "None" when there are no error codes for the unit of work.

identityComparison

The most recent identity comparison result performed for the unit of work

Mapped when identity comparison mappings are configured, and the configured source PDS object containing a boolean true/false, match/no-match value is produced by a payment.

Always present with the default of "NotExecuted" if no comparisons were performed.

processingEntity

The processing entity for the unit of work

Always present with the default of "None" if there is no known processing entity

configurable propagated supporting context keys

Only present if the configured keys are available in the captured context.

By default, only ipf_version_selection key is configured to be added as a label.

An example of a metric with labels is ipf_businessmetrics_payments_finished_total{csm="SIP",currency="CHF",direction="Outbound",htm="No",paymentType="IP SIC Outbound",localInstrument="ACTR",clientChannel="EBNKG",state="Cancelled",errorCode="RJ01"}.

Each distinct value for a label produces a new distinct metric, e.g. the above example is a count of all Cancelled payments. An alternative metric may be ipf_businessmetrics_payments_finished_total{csm="SIP",currency="CHF",direction="Outbound",htm="No",paymentType="IP SIC Outbound",localInstrument="ACTR",clientChannel="EBNKG",state="Completed",errorCode="None"} which is a count of all Completed payments.

Given there may be up to seven different labels, and assuming each could have at-least two distinct values, in theory, the total number of distinct metrics could be quite large.

In practice the number of metrics may be fewer than expected because there is a relationship between some labels, e.g. the direction is mapped from the payment type, or perhaps the currency is missing in most cases for Cancelled payments

Processing Entity

If the processing entity for a unit of work is known when producing payment metrics, the metrics will be labelled with {processingEntity="ENTITY_1"}. If the processing entity is unknown for the unit of work, the payment metrics will be labelled with {processingEntity="None"}.

This label is always present on payment metrics.

CSM

Applied to metrics when a finished payment has produced a Csm PDS object, e.g. {csm="RT1"}

Payment Type

Applied to metrics when a finished payment has produced a PaymentType PDS object, e.g. {paymentType="Debtor CT"}

State

The value for state is the last global state for the finished payment, e.g. {state="Completed"}

Currency

Applied to metrics when a currency mapping is configured, and the configured source PDS object is produced by a payment, otherwise the value is "Unknown".

The currency label value can be sourced from any client-specific PDS object, but, only one currency mapping may be configured. An example currency mapping configuration could be…​

ipf.business-metrics-processor.payment-metrics.labels {
  currency {
      pdsType = ClientSpecificType
      path = "amt.pmtAmt.ccy"
  }
}

Given a ClientSpecificType PDS object with the content…​

{
  "amt": {
    "pmtAmt": {
      "ccy": "EUR"
    }
  }
}

All metrics for payments that produce the configured PDS object will be labelled with {currency="EUR"}.

If the configured target field of the PDS object is null, the label is applied to the metric as "Unknown".

Direction

Applied to metrics when the payment’s type is known, and a direction mapping is configured for the payment type.

An example direction mapping configuration could be…​

ipf.business-metrics-processor.payment-metrics.labels {
  direction {
    payment-type-mappings = [
      {
        label = "Outbound"
        payment-types = [ "DebtorCT1", "DebtorCT2" ]
      }
      {
        label = "Inbound"
        payment-types = [ "CreditorCT" ]
      }
      {
        label = "AnythingYouLike"
        payment-types = [ "DebtorCT3" ]
      }
    ]
  }
}

When a payment is determined to have finished, and the payment type is known to be "DebtorCT1", all metrics for that payment would be labelled with {direction="Outbound"}. If the payment type is "CreditorCT", then the label is {direction="Inbound"}.

The payment types defined in configuration are case-insensitive, e.g. "debtorct1" matches the payment type "DebtorCT1".

HTM

Defaults to {htm="No"}, and will be set to {htm="Yes"} for a payments metrics if that payment saw an event that is deemed to be an HTM event.

A payment is considered to have been through HTM if one or more events contain the label HTM. Payment flows may produce events with this label, but HTM produces its events with the label by default.

HTM Configuration - Deprecated
The following configuration is deprecated, and exists only for backward compatibility. It will be unsupported in a future release.

An example HTM configuration is…​

ipf.business-metrics-processor.payment-metrics.labels {
  htm {
    events = [ "Task Registration Successful", "Task Registration Failed" ]
  }
}

If a finished payment produced an event with the name "Task Registration Successful", then it is considered to have been through Human Task Manager, and the metric is labelled with {htm="Yes"}.

If the finished payment did not produce an event with one of those names, then the default {htm="No"} is applied.

The configured event names are case-insensitive and whitespace-insensitive, e.g. "taskregistrationsuccessful" matches "Task Registration Successful".

Local Instrument

The localInstrument label value can be sourced from any client-specific PDS object, but, only one local instrument mapping may be configured. An example local instrument mapping configuration is…​

ipf.business-metrics-processor.payment-metrics.labels {
  local-instrument {
      pdsType = ClientSpecificType
      path = "prcgInstrs.lclInstrm.prtry"
  }
}

Given a ClientSpecificType PDS object with the content…​

{
  "prcgInstrs": {
    "lclInstrm": {
      "prtry": "ACTR"
    }
  }
}

All metrics for the payment will be labelled with {localInstrument="ACTR"}.

If the configured target field of the PDS object is null, the label is applied to the metric as "Unknown".

Identity Comparison

The identityComparison value is one of Passed|Failed|NotExecuted and is based on the most recent identity comparison result for the unit of work.

The value is NotExecuted under the following scenarios:

  • There are no identity comparison results for the unit of work

  • There is an identity comparison result, but the label is not configured

  • There is an identity comparison result, but the target path in the PDS content is not valid

The identity comparison result must be within a custom PDS object, and the content must contain a boolean field indicating the result of the comparison.When the value is true, the label value is Passed, and when the value is false, the label value is Failed.

The comparison result can be within any custom PDS object, and that boolean field is mapped from its content via configuration, e.g.

ipf.business-metrics-processor.payment-metrics.labels {
  identity-comparison {
      pds-type = ClientSpecificPds
      path = "comparisonResult.result"
  }
}

Given a ClientSpecificType PDS with the following content…​

{
  "comparisonResult": {
    "result": true
  }
}

Then all metrics for the payment will be labelled with {identityComparison="Passed"}.

It’s called identity comparison here which aligns with the IPF naming of the identity comparison service, but clients can name their variable on their Grafana dashboard as creditor comparison.
Example
businessmetrics_payments_finished_total{
    identityComparison="NotExecuted|Passed|Failed"
}

Client Channel

The clientChannel label value can be sourced from any client-specific PDS object, but, only one client channel mapping may be configured. An example client channel mapping configuration is…​

ipf.business-metrics-processor.payment-metrics.labels {
  client-channel {
      pdsType = ClientSpecificType
      path = "instrMsg.cstmCrdTrfInitn.chanl"
  }
}

Given a ClientSpecificType PDS object with the content…​

{
  "instrMsg": {
    "cstmCrdTrfInitn": {
      "chanl": "EBNKG"
    }
  }
}

All metrics for the payment will be labelled with {clientChannel="EBNKG"}.

If the configured target field of the PDS object is null, the label is applied to the metric as "Unknown".

Error Code

The errorCode value is sourced from the originalReasonCode field within a process flow event, and it is the most recent value for a unit of work if it sees more than one error.

If there is no error code on any of the events for a unit of work then there is no error, and the label value is "None".

An example of this label is {errorCode="E37:00001}, or {errorCode="None"}.

A note on client PDS path configuration

It is possible to configure your PDS object path to navigate to fields contained within a List. The Metrics Processor will always try to use the first element in that list to obtain the value from your desired field.

This client PDS object path configuration may apply to Currency, Local Instrument, Client Channel, and Identity Comparison label configurations.

For example, if you configure:

ipf.business-metrics-processor.payment-metrics.labels {
  client-channel {
      pdsType = ClientSpecificType
      path = "instrMsg.cstmCrdTrfInitn.chanl"
  }
}

Given a ClientSpecificType PDS object with the content…​

{
  "instrMsg": {
    "cstmCrdTrfInitn": [
      {
        "chanl": "EBNKG"
      },
      {
        "chanl": "GKNBE"
      }
    ]
  }
}

Then all metrics for the payment will be labelled with {clientChannel="EBNKG"}.

If the PDS Object contains an empty List then all metrics for the payment will be labelled with {clientChannel="UNKNOWN"}.

Configured Propagated Supporting Context Keys

Starting with 2024.4 release, IPF SDK is capable of doing flow version selection based on supporting context keys. To make troubleshooting easier, these keys can be included as labels into all available BAM metrics.

A list of keys to include is available at ipf.business-metrics-processor.propagated-context-metrics-settings.propagated-context-keys-included-as-tags. Setting the list with the following…​

ipf {
  business-metrics-processor {
    propagated-context-metrics-settings.propagated-context-keys-included-as-tags = [ipf_version_selection]
  }
}

…​will result in inclusion of ipf_version_selection as a label whenever the metrics processor observes the ipf_version_selection key in the PropagatedSupportingContext PDS.

Error Code Metrics

Available Metrics

Error Code Count

The metric ipf_businessmetrics_errorcodes_total represents a count of error codes that have been seen by IPF Metrics Processor - an example of the metric is ipf_businessmetrics_errorcodes_total{code="E37:00001"}.

The error code label is taken from a process flow events originalReasonCode field - if a value is present and not blank, the counter is updated.

The metric always contains a code label.

If a payment produces more than one error code, each instance is counted. If a payment produces duplicate error codes, e.g. many events contain the same error code, each duplicate instance is counted.

Error code counts are emitted immediately, whereas payment metrics are emitted on completion of the payment. Payment metrics may therefore trail the error code counts when viewing the metrics within a specific time period.

Labels

The error code metric is labelled with the actual error code, e.g. ipf_businessmetrics_errorcodes_total{code="E37:00001"}.

Each unique error code once seen by IPF Metrics Processor represents a new time series for the metric.

In addition to any other labels applied to payment metrics, the main error code label is also captured and applied. Where a payment does not have an error code, the label is still applied with a value of 'None'