Documentation for a newer release is available. View Latest

Configuración del Connector

La configuración de un Connector puede establecerse en archivos de configuración de IPF. Esta sección explica las diversas opciones de configuración disponibles para los distintos tipos de connector, sus valores predeterminados y el mecanismo de fallback que le permite suministrar solo una configuración parcial y, en caso contrario, usar los valores predeterminados documentados a continuación.

Opciones de configuración

Sending Connectors

Las opciones de configuración permitidas para un sending connector (send connector y request-reply connectors) son:

Property Name

Description

Type

Default Value

manual-start

Cuando se establece en false, el connector se inicia automáticamente después de su creación; de lo contrario, su método start debe invocarse manualmente.

Boolean

false

queue-size

Tamaño de una fuente (source) de cola que puede usarse para manejar backpressure, por ejemplo, situaciones de productor rápido.

Integer

50

call-timeout

Duración máxima de espera para un acuse de recibo antes de completar el future devuelto excepcionalmente con una TimeoutException.

Duration

30s

correlation-stage-timeout

Este ajuste evita que respuestas retrasadas intenten persistir en el correlation store y sean procesadas una vez que el call-timeout ha transcurrido, causando así que se envíe un mensaje a pesar de que el resultado de entrega indique lo contrario. NOTA: Esto siempre debe ser menor que call-timeout; se lanzará una excepción si no es el caso y el inicio de la aplicación fallará si call-timeout es menor que correlation-stage-timeout

Duration

5s

max-concurrent-offers

Número máximo de ofertas pendientes cuando el buffer está lleno.

Integer

500

parallelism

Número máximo de llamadas paralelas para el send connector

Integer

500

parallelism-per-partition

Número máximo de envíos paralelos por UnitOfWorkId. Debe ser menor que parallelism.

Integer

1

throttle-count

Limita el throughput a un número especificado de mensajes consumidos por unidad de tiempo. Cuando se establece este valor, también debe proporcionarse throttle-duration.

Integer

Not set

throttle-duration

Se usa con 'throttle-count' para establecer la velocidad máxima de consumo de mensajes. Para más detalles, consulte la documentación de Message Throttling.

Duration

Not set

resiliency-settings

La configuración de resiliencia para este connector; consulte Resiliency Settings

ResiliencyConfig

default resiliency config

Receiving Connectors

La configuración permitida para un receiving connector es:

Property Name Description Type Default Value

manual-start

Cuando se establece en false, el connector se inicia automáticamente después de su creación; de lo contrario, su método start debe invocarse manualmente.

Boolean

true

throttle-count

Si se establece el valor, limita el throughput a un número especificado de mensajes consumidos por unidad de tiempo. Si se establece. Si este valor se establece, también es necesario establecer throttle-duration.

Integer

Not set

throttle-duration

Si se establece, se usa junto con throttle-count para fijar la velocidad máxima de consumo de mensajes. Para más detalles, vea doc.akka.io/japi/akka/2.6/akka/stream/javadsl/Flow.html#throttle(int,java.time.Duration)

Duration

Not set

mapping-parallelism

Si se establece, limita el número de operaciones de mapping concurrentes ejecutadas sobre los mensajes consumidos.

Integer

number of available processors

receiver-parallelism-type

Define la manera en que los mensajes se manejan en paralelo. Opciones disponibles:

  • ORDERED - los mensajes se consumen en paralelo en el orden en que se reciben, y se reconocen en el mismo orden

  • ORDERED_PARTITIONED - los mensajes se consumen en paralelo en el orden en que se reciben, y se reconocen en el mismo orden, pero el paralelismo para mensajes que comparten el UnitOfWorkId se limita a un grado configurable

  • UNORDERED - los mensajes se consumen en paralelo en el orden en que se reciben, y se reconocen en su orden de finalización, lo cual puede impactar algunos transports (por ejemplo, Kafka)

Enum

ORDERED_PARTITIONED

receiver-parallelism

Si se establece, limita el número de mensajes mapeados que pueden procesarse concurrentemente.

Integer

number of available processors

receiver-parallelism-per-partition

Solo se aplica si receiver-parallelism-type está establecido en ORDERED_PARTITIONED. Si se establece, limita el número de mensajes mapeados por UnitOfWorkId que pueden procesarse concurrentemente. Debe ser menor que receiver-parallelism.

Integer

1

resiliency-settings

La configuración de resiliencia para este connector; consulte Resiliency Settings

ResiliencyConfig

default resiliency config

Resiliency Settings

Tanto la configuración del sending como del receiving connector permiten definir la configuración de resiliencia mediante un bloque 'resiliency-settings'. La mayoría de las propiedades de este bloque se utilizan para establecer valores de configuración para Resilience4j retry y circuit breaker, que se utilizan para envolver llamadas con circuit breaking, fallback o routing, y reintentos. Tenga en cuenta que, como algunas configuraciones de Resilience4j pueden entrar en conflicto entre sí, no todos los parámetros de esta biblioteca están expuestos en este bloque de ajustes. Además, algunos valores predeterminados de Resilience4j han sido anulados en este bloque para alinearse mejor con los requisitos de una aplicación IPF.

Property Name Description Type Resilience4j equivalent Default Value Config

enabled

Permite activar/desactivar la resiliencia

Boolean

n/a

true

yes

minimum-number-of-calls

Determina el número mínimo de llamadas (dentro de una ventana deslizante) que deben realizarse antes de que el circuit breaker pueda calcular la tasa de errores para determinar la salud del transport.

Integer

minimumNumberOfCalls

1

yes

max-attempts

Determina el número máximo de reintentos a realizar. Tenga en cuenta que esto incluye el primer intento fallido.

Integer

maxAttempts

1

yes

attempt-timeout

Cuánto esperar a que se complete un único intento antes de fallarlo.

Duration

n/a

30s

yes

reset-timeout

Cuánto esperar en estado OPEN antes de pasar a HALF_OPEN e intentar cerrar el circuito.

Duration

waitDurationInOpenState

1s

yes

initial-retry-wait-duration

Cuánto esperar antes de reintentar. Esto establece la duración inicial y puede aumentar en sucesivos reintentos debido al multiplicador de backoff.

Duration

La primera mitad de intervalFunction.

1s

yes

backoff-multiplier

Cada reintento sucesivo esperará la duración previa multiplicada por el backoff multiplier.

Integer

La segunda mitad de intervalFunction.

2

yes

retry-on-failure-when

Dada una excepción lanzada por el código decorado, devuelve un boolean para determinar si se reintenta. Esto evita reintentar en excepciones donde múltiples intentos no resolverán el fallo.

Boolean

n/a

true

yes

retry-on-result-when

Dado un resultado exitoso, es decir, no se lanzó ninguna excepción, devuelve un boolean para determinar si se reintenta. Esto se usa para disparar reintentos basados en el objeto devuelto por el código decorado en un receiving connector.

Boolean

retryOnResult

false

yes

fail-after-max-attempts

Booleano para habilitar o deshabilitar el lanzamiento de MaxRetriesExceededException cuando el Retry alcanza el maxAttempts configurado y el resultado sigue sin pasar el retryOnResultPredicate

Boolean

failAfterMaxAttempts

false

yes

failure-rate-threshold

Cuando la tasa de fallos es igual o mayor que el umbral, el CircuitBreaker pasa a open y comienza a cortar (short-circuit) las llamadas.

Double

failureRateThreshold

50

yes

slow-call-rate-threshold

El CircuitBreaker considera una llamada como lenta cuando la duración es mayor que slowCallDurationThreshold. Cuando el porcentaje de llamadas lentas es igual o mayor que el umbral, el CircuitBreaker pasa a open y comienza a cortar llamadas.

Double

slowCallRateThreshold

100

yes

slow-call-duration-threshold

Configura el umbral de duración por encima del cual las llamadas se consideran lentas e incrementan la tasa de llamadas lentas.

Duration

slowCallDurationThreshold

60000ms

yes

max-wait-duration-in-half-open-state

Cuando se establece en 0ms en realidad no se está configurando; cualquier otro tiempo sí establecerá la variable

Duration

maxWaitDurationInHalfOpenState.

0ms

yes

permitted-number-of-calls-in-half-open-state

Configura el número de llamadas permitidas cuando el CircuitBreaker está en HALF_OPEN.

Integer

permittedNumberOfCallsInHalfOpenState

10

yes

sliding-window-size

Configura el tamaño de la ventana deslizante que se usa para registrar el resultado de las llamadas cuando el CircuitBreaker está cerrado.

Integer

slidingWindowSize

100

yes

sliding-window-type

Si la ventana deslizante es COUNT_BASED, se registran y agregan las últimas slidingWindowSize llamadas. Si la ventana es TIME_BASED, se registran y agregan las llamadas de los últimos slidingWindowSize segundos.

SlidingWindowType

slidingWindowType

COUNT_BASED

yes

automatic-transition-from-open-to-half-open

Si es true, el CircuitBreaker pasará automáticamente de open a half-open y no se necesitará una llamada para disparar la transición. Se crea un hilo para monitorear todas las instancias de CircuitBreakers y pasarlas a HALF_OPEN una vez que pase waitDurationInOpenState. Si es false, la transición a HALF_OPEN solo ocurre si se realiza una llamada, incluso después de que haya pasado waitDurationInOpenState. La ventaja aquí es que ningún hilo monitorea el estado de todos los CircuitBreakers.

Boolean

automaticTransitionFromOpenToHalfOpenEnabled

true

yes

retry-scheduler-thread-pool-size

Determina cuántos hilos puede usar el planificador de reintentos.

Integer

n/a

number of available processors

no

reroute-messages-on-failure

Dado un resultado de fallo, devuelve un boolean para determinar si se deben re-enviar mensajes a la cola

Boolean

n/a

Llama al predicado retryOnFailureWhen o al valor de retry-on-failure-when

no

retryExceptions

Debe especificar la ruta de clase completa y el nombre de clase para que funcione correctamente; por ejemplo, java.lang.String. También debe ser una clase que extienda java.lang.Throwable

List<String> in config. List<Class<Throwable>>

retryExceptions and recordExceptions.

null

no

ignoreExceptions

Debe especificar la ruta de clase completa y el nombre de clase para que funcione correctamente; por ejemplo, java.lang.String. También debe ser una clase que extienda java.lang.Throwable

List<String> in config. List<Class<Throwable>>

ignoreExceptions

[]

no

retry-on-send-result-when

Dado un resultado exitoso, es decir, no se lanzó ninguna excepción, devuelve un boolean para determinar si se reintenta. Esto se usa para disparar reintentos basados en el objeto devuelto por el código decorado en un sending connector. Un ejemplo de donde esto puede ser útil es si un servidor HTTP responde con un código de respuesta HTTP exitoso a una solicitud, pero el cuerpo contiene detalles de error que indican que puede ser necesario reintentar.

Boolean

retryOnResult.

Devuelve true cuando el DeliveryOutcome devuelto es un fallo y retryOnFailureWhen devuelve true para la excepción que causó el fallo

no

recordException

Configura un Predicate que evalúa si una excepción debe registrarse como un fallo y así aumentar la tasa de fallos. El Predicate debe devolver true si la excepción debe contar como fallo. Debe devolver false si la excepción debe contar como éxito, a menos que la excepción sea explícitamente ignorada por ignoreExceptions(Class[]) o ignoreException(Predicate).

Predicate<Throwable>

recordException

null

no

ignoreException

Configura un Predicate que evalúa si una excepción debe ignorarse y no contar como fallo ni como éxito. El Predicate debe devolver true si la excepción debe ignorarse. Debe devolver false si la excepción debe contar como fallo.

Predicate<Throwable>

ignoreException

null

no

Configuración predeterminada

Todos los connectors vienen con un conjunto predefinido de configuración base que se usará si no se anula en el punto de construcción del connector.

La configuración predeterminada se proporciona a continuación y coincide con la definida en la sección anterior.

ipf.connector {
  default-receive-connector {
    manual-start = true
    receiver-parallelism-type = ORDERED_PARTITIONED
    receiver-parallelism-per-partition = 1
    resiliency-settings = ${ipf.connector.default-resiliency-settings}
  }

  default-send-connector {
    manual-start = false
    call-timeout = 30s
    queue-size = 50
    max-concurrent-offers = 500
    parallelism = 500
    parallelism-per-partition = 1
    send-message-association = true
    resiliency-settings = ${ipf.connector.default-resiliency-settings}
  }
  # Inherit everything from default-send-connector and then override some of the resiliency settings
  default-rr-send-connector = ${ipf.connector.default-send-connector} {
    resiliency-settings {
      reroute-messages-on-failure = false
      minimum-number-of-calls = 10
    }
  }
  default-resiliency-settings {
    enabled = true
    minimum-number-of-calls = 1
    max-attempts = 1
    attempt-timeout = 30s
    attempt-timeout = ${?ipf.connector.default-send-connector.call-timeout}
    reset-timeout = 1s
    initial-retry-wait-duration = 1s
    backoff-multiplier = 2
    retry-on-failure-when = true
    retry-on-result-when = false
    fail-after-max-attempts = false
    failure-rate-threshold = 50
    slow-call-rate-threshold = 100
    slow-call-duration-threshold = 60000ms
    max-wait-duration-in-half-open-state = 0ms
    permitted-number-of-calls-in-half-open-state = 10
    sliding-window-size = 100
    sliding-window-type = COUNT_BASED
    automatic-transition-from-open-to-half-open = true
    retry-exceptions = []
    ignore-exceptions = []
  }
}

Uso de la configuración

Al construir un connector, es posible anular estas propiedades proporcionando un configRoot. Cuando se proporciona, el connector utilizará este configRoot como base de las propiedades a usar. Por ejemplo, si construimos un connector como:

var sendConnector = new SendConnector.Builder<String, String>("TestConnector")
    .withActorSystem(actorSystem) (1)
    .withConfigRoot("test-config") (2)
    .build();

Aquí estamos proporcionando ambos:

1 el ActorSystem
2 la raíz de configuración - un valor de tipo string.

Le estamos diciendo a nuestro connector que nuestra raíz de configuración aquí es test-config. Esto significa que, donde en nuestra configuración predeterminada de connector los valores predeterminados del send connector están en ipf.connector.default-send-connector, aquí usaremos test-config como configuración principal y luego ipf.connector.default-send-connector como respaldo.

Para ilustrarlo, supongamos que establecemos el archivo de configuración así:

test-config {
    parallelism = 700
    manual-start = false
}

Aquí estamos definiendo nuevos valores de configuración para parallelism y manual-start. Podríamos haber proporcionado igualmente los valores de configuración para las otras propiedades. Al proporcionar solo estos dos, nuestro connector tendrá:

  1. Un parallelism de 700

  2. Un ajuste manual-start de false.

  3. Todas las demás propiedades heredadas de la configuración predeterminada; por ejemplo, el queue-size se establecerá en 50.

También podemos proporcionar anulaciones a los ajustes de configuración en el constructor mediante nuestro código Java. Por ejemplo, considere la siguiente configuración:

var sendConnector = new SendConnector.Builder<String, String>("TestConnector")
    .withActorSystem(actorSystem)
    .withParallelism(700)
    .withManualStart(false)
    .build();

Esto conduciría a que se construyera el mismo connector que en nuestra implementación mediante configuración.