Documentation for a newer release is available. View Latest

Monitorización y observabilidad

La estrategia en IPF para monitorización y observabilidad se consigue utilizando un paradigma dirigido por eventos, categorización estricta del comportamiento de la aplicación y extensibilidad para exponer estos datos a través de canales apropiados, con las mejores herramientas.

La monitorización de servicios de aplicaciones IPF puede hacerse de tres maneras principales:

  • APIs HTTP

  • Métricas de series temporales vía Prometheus y Grafana

  • Logging de la aplicación

Fuera de alcance:

  • Application Performance Monitoring (APM) - Algo a considerar si dicho software está disponible en el sitio del cliente. Software APM como Dynatrace o AppDynamics puede ayudar a diagnosticar problemas potenciales antes de que se materialicen.

  • Monitorización de infraestructura, p. ej., Brokers, contenedores

Definiciones

La "aplicación IPF" en realidad está compuesta por múltiples paquetes de software en tiempo de ejecución. Esta sección describirá la terminología que se usará aquí:

Component Sometimes known as Description Needs to be in Akka cluster with other similar nodes?

Payment Services (Customised)

Write side

El conjunto de flujos de pago que el cliente ha definido.

Puede haber múltiples de estos representando diferentes conjuntos de flujos (p. ej., credit transfer, recall, value-added service).

Yes

CSM Service

CSM Pack, Scheme Pack

Un adaptador para un proveedor de pagos como un esquema de pagos, wallet, etc.

No

Support Services

Notification Service

Procesamiento adicional de eventos hacia sistemas de terceros.

Yes

APIs de servicios individuales (HTTP)

Hay ciertas APIs HTTP que están habilitadas por defecto y que pueden interrogarse cuando la aplicación está en ejecución, cada una con un propósito específico.

Aquí hay un resumen de esas APIs y los elementos de configuración que establecen sus hostnames y puertos:

What is it? What does it do? Example use case API reference (or similar) Default hostname Default port Host override env var Port override env var Available on

Spring Boot Actuator API

Métricas estilo Spring Boot para la JVM, propiedades de configuración de Spring, beans, health

Para verificar la versión de librerías activas

Click here

0.0.0.0

8080

MANAGEMENT_SERVER_ADDRESS

MANAGEMENT_SERVER_PORT (establecer a -1 para deshabilitar)

  • Client Implementation(s)

  • Scheme Connector

Akka Management Cluster HTTP API

Información sobre el cluster Akka en ejecución para propósitos de depuración

Para verificar el estado del cluster y gestionar nodos manualmente

Click here

(el resultado de InetAddress.getLocalHost().getHostAddress() que suele ser - pero no siempre - 127.0.0.1)

8558

AKKA_MANAGEMENT_HTTP_HOSTNAME

AKKA_MANAGEMENT_HTTP_PORT

  • Client Implementation(s)

Spring Boot Actuator API

Usa esta API para consultar el ApplicationContext de Spring que se está ejecutando en este nodo en particular. Algunos endpoints de Spring Actuator interesantes para IPF:

  • conditions: Verifica que el lado de escritura y lectura de la aplicación se han configurado correctamente en los nodos relevantes

  • env: Muestra variables de entorno para comprobar que los overrides son correctos

  • health: Útil para liveness probes y similares

  • info: Información general de la aplicación (también útil para liveness probes)

Hay más endpoints disponibles. Consulta el enlace de Spring Boot Actuator en la tabla superior para ver todos los detalles. Además, consulta esta sección sobre cómo habilitar y deshabilitar endpoints de Actuator (MANAGEMENT_ENDPOINT_X_ENABLED donde X es la parte relevante del Actuator).

Para información sobre cómo configurar TLS para los endpoints de Actuator, ver esta sección.

Akka Cluster HTTP Management

Esta API permite al usuario interactuar con el cluster Akka subyacente de IPF usando una interfaz HTTP.

El uso principal de esta API es verificar el estado del cluster. Los componentes de implementación de cliente de IPF requieren que todos los nodos "write" que sirven el mismo conjunto de flujos (p. ej., credit transfer, recall, digital wallet payout) estén en un cluster Akka juntos. Si no es el caso, no se tomará nuevo trabajo para evitar pérdida de transacciones.

El cluster encuentra otros nodos similares por sí mismo, pero en caso de que la aplicación parezca no estar consumiendo nuevo trabajo, este debería ser el primer punto a comprobar para asegurar que el cluster está en un estado válido y que la aplicación no está en un "split brain" (múltiples nodos creados en clusters separados).

Las situaciones de split brain pueden resolverse usando Akka Split Brain Resolver. Más información disponible en el sitio de Akka.

El endpoint Akka Cluster HTTP Management también permite operaciones de actualización. Si este comportamiento no es deseado, establece la variable de entorno AKKA_MANAGEMENT_READ_ONLY a true para habilitar el modo de solo lectura, donde la información del cluster solo puede recuperarse pero no actualizarse.

La configuración TLS para Akka Management es la misma que para Spring Boot, pero los prefijos server o management.server se reemplazan por akka.management. Por ejemplo, para establecer la ruta del keystore, la propiedad sería akka.management.ssl.keystore o AKKA_MANAGEMENT_SSL_KEYSTORE (el equivalente en Spring Boot sería server.ssl.keystore o SERVER_SSL_KEYSTORE).

Métricas de series temporales

Las métricas se exponen mediante un servidor HTTP Prometheus que es interrogado a intervalos por Prometheus y visualizado con herramientas como Grafana y Kibana.

El componente AlertManager realiza agregación configurable de eventos basada en umbrales y condiciones para traducir este comportamiento del sistema en algo que pueda requerir acción por parte de un Operador.

monitoring

Métricas de aplicación relevantes

Las métricas agregadas a nivel de aplicación también se exponen con el mismo mecanismo:

Metric name Type Description Event information Source

ipf_behaviour_end_to_end_latency_seconds_bucket

Histogram

Tiempo en segundos que dura la ejecución de un flujo

behaviour - nombre del flujo de IPF, event - tiempo desde el inicio del flujo hasta este evento, type - uno de CSM_STATES_ONLY, NO_CSM_STATES o FULL_FLOW

Spring Actuator (TCP/8080)

ipf_behaviour_end_to_end_latency_seconds_count

Counter

Número total de invocaciones

mismas etiquetas que en ipf_behaviour_end_to_end_latency_seconds_bucket

Spring Actuator (TCP/8080)

ipf_behaviour_end_to_end_latency_seconds_sum

Counter

Tiempo total empleado por todas las invocaciones

mismas etiquetas que en ipf_behaviour_end_to_end_latency_seconds_bucket

Spring Actuator (TCP/8080)

ipf_behaviour_per_state_latency_seconds_bucket

Histogram

Tiempo que pasan los flujos en ese estado

behaviour - nombre del flujo, status - estado

Spring Actuator (TCP/8080)

ipf_behaviour_per_state_latency_seconds_count

Counter

Número total de llamadas a ese estado

behaviour - nombre del flujo, status - estado

Spring Actuator (TCP/8080)

ipf_behaviour_per_state_latency_seconds_sum

Counter

Tiempo empleado por todas las llamadas a ese estado

behaviour - nombre del flujo, status - estado

Spring Actuator (TCP/8080)

ipf_behaviour_flows_in_state

Gauge

Número de flujos activos por estado

behaviour - nombre del flujo, status - estado

Spring Actuator (TCP/8080)

ipf_behaviour_command_processing_times

Histogram

Tiempos desde el momento en que IPF recibe un command hasta que se completan todos los efectos secundarios

Segmentado por behaviour, nombre del command, estado previo, estado resultante, resultado de la llamada (success, failure)

Esta métrica está deshabilitada por defecto debido a la gran cantidad de memoria que consume a altas cargas y cuando se usa ZGC. Puedes habilitarla estableciendo ipf.behaviour.metrics.processing-time-metrics-enabled = true en la aplicación, pero debes asegurarte de que ZGC no está en uso y hay suficiente memoria.

Spring Actuator (TCP/8080)

ipf_behaviour_input_handling_overall

Histogram

Tiempo para realizar una llamada a IPF, incluyendo tiempo de persistencia de eventos, ejecución de todos los efectos secundarios y posibles reintentos

Segmentado por behaviour, nombre del command, resultado de la llamada (success/failure)

Esta métrica está deshabilitada por defecto debido a la gran cantidad de memoria que consume a altas cargas y cuando se usa ZGC. Puedes habilitarla estableciendo ipf.behaviour.metrics.processing-time-metrics-enabled = true en la aplicación, pero debes asegurarte de que ZGC no está en uso y hay suficiente memoria.

Spring Actuator (TCP/8080)

flow_started_total

Counter

Número de transacciones creadas (iniciadas)

behaviour - nombre del flujo, description - igual que behaviour

Spring Actuator (TCP/8080)

flow_finished_total

Counter

Número de transacciones que han alcanzado un estado terminal (final)

behaviour - nombre del flujo, description - igual que behaviour, reasonCode - reasonCode usado en el estado final, state - nombre del estado terminal

Spring Actuator (TCP/8080)

state_timeout_total

Counter

Número de flujos que han generado un timeout system event

behaviour - nombre del flujo, description - estado que expiró

Spring Actuator (TCP/8080)

action_invoked_total

Counter

Se eleva cuando el dominio IPF invoca una action en un sistema externo

behaviour - nombre del flujo, description - nombre de la acción llamada

Spring Actuator (TCP/8080)

action_timeout_total

Counter

Se eleva cuando una action invocada por IPF no ha recibido respuesta dentro del timeout configurado

behaviour - nombre del flujo, description - nombre de la acción llamada

Spring Actuator (TCP/8080)

domain_event_persisted_total

Counter

Se eleva cuando un Domain Event se ha persistido correctamente

behaviour - nombre del flujo, description - nombre del evento

Spring Actuator (TCP/8080)

unexpected_command_total

Counter

Se eleva cuando el dominio IPF recibe un command que no puede manejarse en el estado actual del aggregate

command_name - nombre del command, status - estado del flujo cuando se recibió el command

Spring Actuator (TCP/8080)

ipf_processing_data_journal_latency_seconds_bucket

Histogram

que registra la duración entre la creación de un domain event y el momento en que se envía a ODS; las duraciones serán sensibles al desfase de tiempo entre servidores, por lo que deben tratarse solo como estimaciones

Spring Actuator (TCP/8080)

ipf_processing_data_journal_latency_seconds_count

Counter

Conteo del número total de domain events enviados a ODS

ipf_processing_data_journal_latency_seconds_sum

Counter

Tiempo total empleado para enviar domain events a ODS
Type Usage

CSM_STATES_ONLY

Registra solo el tiempo empleado en estados relacionados con CSM (p. ej., clearing and settling, requesting status, etc.)

NO_CSM_STATES

Registra el tiempo entre el primer y último evento del flujo, menos el tiempo pasado en estados relacionados con CSM (p. ej., clearing and settling, requesting status, etc.)

FULL_FLOW

Registra el tiempo entre el primer y último evento del flujo

Dashboards de Spring Boot

Métricas básicas de la JVM a través del endpoint prometheus de Spring Boot Actuator. Hay varios dashboards que pueden usarse para visualizar estos datos, pero recomendamos este de la colección de dashboards de Grafana.

Dashboards de Akka

Hay algunos dashboards de Grafana listos para usar que están disponibles para Akka, documentados y disponibles para descarga aquí. Los dashboards de Akka interesantes que buscar - en lo que respecta a IPF - son:

  • Event Sourced Behaviours: Métricas sobre events y commands procesados por flujos IPF

  • Akka Streams y Akka Streams (extended): Métricas de rendimiento del procesamiento de conectores

Dashboards específicos de IPF

También hay algunos dashboards específicos de IPF:

Name Description Required Data

IPF Connectors

Estadísticas por conector sobre números de requests enviados, recibidos y tiempos de respuesta promedio por conector.

IPF Flow Timings

Estadísticas por flujo sobre cuánto tardan los flujos en procesarse desde la iniciación hasta alcanzar un estado final.

IPF Resilience4j

Informa estadísticas sobre los circuit breakers de conectores usando métricas definidas en Resilience4J.

IPF JVM Overview

Proporciona algunas estadísticas sobre la JVM, por ejemplo memoria heap, por pod en el cluster. Para un dashboard más detallado ver IPF JVM (Actuator)

IPF CSM Simulator

Informa sobre las métricas de request/response de simuladores CSM desplegados en el cluster.

Requiere una etiqueta namespace en Prometheus

IPF Node Degradation

Informa sobre una amplia gama de métricas de servicios de aplicación (MongoDB/Akka…​) para determinar la salud general del ecosistema IPF y ayudar a identificar si ha habido degradación del rendimiento a lo largo del tiempo.

IPF ODS Ingestion

Estadísticas relacionadas con el servicio de ingesta ODS informando sobre cualquier lag entre ingestiones, así como métricas relacionadas con Kafka/MongoDB.

Se asume que el nombre del pod es ods-ingestion.

El consumer group de Kafka para el ingreso se asume llamado ipf-processing-data-ingress-consumer-group.

El topic de egreso de Kafka se asume llamado IPF_PROCESSING_DATA.

IPF Transaction Status

Informa estadísticas basadas en métricas de flujo para mostrar transacciones en estados completados o no completados

Se asume que el nombre del estado de finalización termina con la palabra Completed o de lo contrario todos los eventos acabarán en el panel Rejected

IPF ESB Actions & Inputs

Informa sobre métricas de actions e inputs de Event Sourced Behaviours (ESBs) proporcionando la tasa de ejecución entre estas funciones.

IPF JVM (Actuator)

Proporciona estadísticas detalladas sobre la JVM a partir de métricas proporcionadas por el actuator de Spring.

IPF Requests Info

Proporciona métricas generales y por conector sobre tiempos de request y response.

Requiere una etiqueta namespace en Prometheus

Ejemplo funcional de uso de PromQL para generar un gráfico personalizado

Requisito

Un gráfico de tarta para representar todos los estados de finalización CSM de todas las transacciones que ocurrieron en este día natural y que tardaron menos del SLA de 5 segundos.
— Business Analyst

Paso 1 - Elección de la métrica

Primero debes encontrar la métrica más cercana que proporcione los datos necesarios; en este caso los datos del histograma ipf_behaviour_end_to_end_latency_seconds deberían funcionar.

sum by(event) (
 increase(
  ipf_behaviour_end_to_end_latency_seconds_bucket{type="CSM_STATES_ONLY", service=~".*creditor.*", le="5.0"}[15m]
 )
)

Esta consulta devolverá el número de estados completados en un intervalo de 15 minutos agrupados por event

  • increase - calcula el incremento en la serie temporal del vector de rango

  • sum - calcula el total en la serie temporal

Más funciones PromQL que pueden usarse se encuentran aquí.

step2

Paso 2 - Agrupar por días

Ahora puedes crear un diario para hoy con la siguiente consulta

last_over_time(
 sum by(event) (
  increase(
   ipf_behaviour_end_to_end_latency_seconds_bucket{type="CSM_STATES_ONLY", service=~".*creditor.*", le="5.0"}[1d] offset -1d
   )
  )
 [1d:1d]
)

  • last_over_time - el valor del punto más reciente en el intervalo especificado

step1

Paso 3 - Limitar a un solo día

Altera las Query options del panel para añadir un relative time de now/d

step3

Paso 4 - Cambiar el estilo del gráfico

Usando el selector Visualization del lado derecho, elige la opción Pie Chart y cambia el Title a Calls to Scheme. También podrás añadir los siguientes cambios:

step4a

  • Añade etiquetas al gráfico de tarta de Name

  • Cambia Legend mode a Table, coloca a Right y añade Label Values de Percent y Value

Ahora puedes guardar el dashboard, que se verá algo así

step4b

Configuración de exportadores

Las métricas de Spring Boot Actuator se exponen a través del mismo servidor HTTP Actuator documentado arriba. Consulta arriba cómo cambiar el host y puerto del Actuator.

Tanto las métricas de Prometheus de Akka como las específicas de IPF están disponibles en el mismo servidor web exportador de Prometheus, que por defecto escucha en todas las interfaces (0.0.0.0) y en el puerto 9001. Para cambiar estos detalles, las variables de entorno relevantes son:

  • CINNAMON_PROMETHEUS_HTTP_SERVER_HOST

  • CINNAMON_PROMETHEUS_HTTP_SERVER_PORT

Si estas propiedades se cambian, recuerda también cambiar el lado de Prometheus para que Prometheus pueda recopilar datos de series temporales desde las direcciones correctas.

Logging

IPF usa Logback para la configuración de logging. Esto permite al usuario configurar un setup de logging que pueda reflejar el de otras aplicaciones desarrolladas dentro de la organización, y hacer que IPF informe de los datos de log de la misma manera.

Este documento explicará algunos setups típicos de logging que pueden usarse para sacar datos de log de varias maneras.

Para todos los setups, el archivo de configuración de Logback debe montarse en el classpath de la app. Para una imagen construida por Icon, siempre está disponible en /[name of container]/conf. Así que si el contenedor se llama credit-transfer, entonces la configuración de Logback puede montarse en /credit-transfer/conf/logback.xml.

Opción 1: Elasticsearch/Logstash/Kibana

Una pila popular en la industria es ELK: una combinación de Elasticsearch, Logstash (y/o Beats) y Kibana. Antes se conocía como la pila ELK, pero con la introducción de Beats, Elastic ha promovido el nombre más genérico "Elastic Stack" para este setup.

En cualquier caso, el setup se ve así:

elk

Primero necesitamos configurar Logstash para escuchar un puerto TCP. Aquí hay un ejemplo de cómo configurarlo en Logstash:

input {
    tcp {
        port => 4560
        codec => json_lines
    }
}

Esto hace que Logstash escuche en el puerto 4560 líneas JSON separadas por el carácter de nueva línea \n. El appender Logstash Logback hace esto por nosotros y puede configurarse así:

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
  <appender name="stash" class="net.logstash.logback.appender.LogstashAccessTcpSocketAppender">
      <destination>127.0.0.1:4560</destination>
      <encoder class="net.logstash.logback.encoder.LogstashAccessEncoder" />
  </appender>

  <appender-ref ref="stash" />
</configuration>

Esto configurará que los logs de la aplicación IPF se envíen a Logstash. Configurar Logstash para conectarse a Elasticsearch (y Kibana a Elasticsearch) está fuera del alcance de este documento pero se puede encontrar en el sitio de Elastic aquí.

Más ejemplos, incluyendo:

  • Configuración de TLS sobre la conexión TCP, y;

  • Una variante UDP del appender

Pueden encontrarse en la página de GitHub del appender Logstash Logback aquí.

Configurar un appender de Logstash para System Events

Si deseas agregar IPF system events, considera usar com.iconsolutions.payments.systemevents.utils.Slf4jEventLogger que reenvía todos los system events recibidos a un appender. Esto puede usarse junto con este appender Logstash para enviar system events a un agregador como Elasticsearch como se mencionó arriba.

Aquí hay un ejemplo de configuración Logback que toma eventos Slf4jEventLogger y los envía a nuestro appender STASH:

<logger name="com.iconsolutions.payments.systemevents.utils.Slf4jEventLogger" level="DEBUG" additivity="false">
    <appender-ref ref="STASH"/>
</logger>

Opción 2: Splunk

Aparte de un setup específico como el anterior, una verdadera app "twelve-factor" debe emitir sus logs - sin buffer - a stdout, y esto puede analizarse con software como Splunk.

splunk

Splunk proporciona un appender HTTP para Logback. Está documentado aquí. Ese documento también describe algunas consideraciones de rendimiento para logging con HTTP, y también un appender TCP que puede usarse en lugar de HTTP.

La plantilla Logback a la que se hace referencia en ese documento se puede encontrar aquí.

Hay tres campos obligatorios:

  • url: La URL de Splunk a la que reenviar

  • token: El token proporcionado por Splunk para autenticación y autorización

  • index: El índice de Splunk (repositorio) para almacenar estos datos de log

Opción 3: Archivos (no recomendado)

Hacer logging a archivo rompe principios cloud-native sobre no hacer suposiciones acerca de un sistema de archivos subyacente. Los logs deben tratarse como flujos de datos en lugar de archivos que requieren mantenimiento.

Usa este enfoque solo como último recurso cuando sea absolutamente imposible usar un enfoque más moderno para logging. Para más información, consulta XI. Logs en The Twelve-Factor App.

Es posible especificar un appender de archivo normal de Logback. Un logback.xml típico podría verse así:

logback.xml
<?xml version="1.0" encoding="UTF-8" scan="true"?>
<configuration>
    <jmxConfigurator />
    <appender name="FILE"
              class="ch.qos.logback.core.rolling.RollingFileAppender">
        <file>/opt/ipf/logs/credit-transfer-service.log</file>
        <rollingPolicy class="ch.qos.logback.core.rolling.FixedWindowRollingPolicy">
            <fileNamePattern>/opt/ipf/logs/credit-transfer-service.log.%i</fileNamePattern>
            <minIndex>1</minIndex>
            <maxIndex>20</maxIndex>
        </rollingPolicy>
        <triggeringPolicy class="ch.qos.logback.core.rolling.SizeBasedTriggeringPolicy">
            <maxFileSize>50MB</maxFileSize>
        </triggeringPolicy>
        <encoder>
            <pattern>%date{yyyy-MM-dd} %d{HH:mm:ss.SSS} %-5level %X{traceId} %logger{36} %X{sourceThread} %X{akkaSource} - %msg%n</pattern>
        </encoder>
    </appender>

    <root level="INFO">
        <appender-ref ref="FILE" />
    </root>
</configuration>

Este archivo crea la siguiente configuración:

  • El archivo de log se analiza para cambios en vivo cada minuto (scan="true").

  • La configuración de logging puede modificarse en vivo con JMX. Más información en este enlace.

  • Logging a archivo en /opt/ipf/logs/credit-transfer-service.log.

  • Rotación de archivos a /opt/ipf/logs/credit-transfer-service.log.n, donde n es un número entre 1-20, y la rotación ocurre cuando credit-transfer-service.log alcanza 50 MB. Ten en cuenta que solo se conservarán 20 archivos de este tipo (es decir, un total de 1 GB de logs).

Este archivo también puede ser recolectado por un framework como Splunk forwarder o Beats como se muestra en el siguiente diagrama:

file

System Events

Qué son los IPF System Events

  • Las aplicaciones IPF se sustentan en un framework de System Events, que proporciona capacidades pub/sub entre componentes de aplicación.

  • Jerárquicos, extensibles, versionados, catalogados. Todas las áreas de la aplicación: Technical, Functional & Lifecycle. Todos los eventos incluyen propiedades comunes: ubicación de origen, hora de creación, nivel, tipo, contexto de asociación; es sencillo obtener todos los System Events para un pago dado.

  • El marco de datos fundamental para capturar comportamiento de la aplicación, proporcionando un lugar para construir funcionalidad extensible dirigida por eventos, que luego puede alimentar tareas de soporte como proporcionar datos para monitorización y alertas.

  • Patrón de suscripción de procesadores de System Events: "Actuar en todos los WARN level Infrastructure System Events".

  • Configurar múltiples procesadores, estilo funcional, almacenar / transformar – emitir sobre un Connector.

  • Todos los System Events que un servicio IPF puede emitir están catalogados y tienen un esquema, están versionados respecto al software desplegado.

  • Se anima a añadir nuevos eventos específicos del cliente para una solución dada. Proporcionando una extensión muy limpia para aprovechar el framework existente y aportar información adicional.

events

Dónde se definen

La lista completa de system events que IPF produce está listada aquí.

Solución de problemas de mensajes de error

Los eventos en esta tabla son eventos ERROR registrados por IPF y describen pasos de remediación recomendados a seguir si se encuentran.