Configuración en tiempo de ejecución (Systemplane)

Visualiza y modifica la configuración operativa de Matcher en tiempo de ejecución a través de Systemplane: ajusta límites de tasa, intervalos de workers y el máximo de pools de tenants sin reiniciar el servicio.

Systemplane te permite ver y modificar la configuración admitida de Matcher sin reiniciar el servicio. El comportamiento de aplicación varía según la clave: la configuración leída en cada solicitud puede aplicarse en la siguiente, mientras que una recarga de configuración detiene y reinicia un worker en ejecución cuando cambia su configuración.

​

Por qué usar Systemplane

---

En un despliegue tradicional, cambiar un valor de configuración significa actualizar variables de entorno y reiniciar el servicio. Systemplane elimina ese tiempo de inactividad para muchas configuraciones:

• Ajustar límites de tasa durante picos de tráfico sin redeploy — evitando interrupciones del servicio en momentos de alto volumen de transacciones
• Ajustar intervalos de workers según la carga de trabajo observada; una recarga de configuración reconcilia el worker afectado y lo reinicia cuando cambia su configuración en ejecución
• Actualizar el número máximo de pools de tenants a medida que cambian los patrones de tráfico; los ajustes de conexiones PostgreSQL por pool requieren cambiar el entorno y reiniciar
• Inspeccionar valores actuales en tiempo de ejecución para diagnosticar problemas en producción sin bucear en logs

​

Cómo funciona

---

Systemplane proporciona una API de gestión de clave-valor plana. Todas las claves de configuración están en un único namespace bajo /system/matcher.

​

Endpoints

Endpoint	Método	Qué hace
/system/matcher	GET	Listar todas las claves y sus valores actuales
/system/matcher/:key	GET	Obtener el valor actual de una clave específica
/system/matcher/:key	PUT	Actualizar el valor de una clave específica

Estos endpoints son servidos directamente por la instancia de Matcher en ejecución. No están versionados bajo /v1 — usa las rutas anteriores exactamente como se muestran.

​

Permisos

---

Las rutas de configuración y catálogo de Systemplane están protegidas por la misma autenticación utilizada por las rutas de la API de Matcher. Cuando la autenticación está habilitada, estas rutas requieren el permiso RBAC system-runtime-config:admin (recurso system-runtime-config, acción admin). GET /system/matcher/streaming/manifest es una ruta independiente y requiere streaming-manifest:read.

Cuando la autenticación está deshabilitada, todos los endpoints son accesibles sin restricciones.

​

Comportamientos de aplicación

---

No todos los valores de configuración pueden cambiarse en tiempo de ejecución. Cada clave tiene un comportamiento de aplicación que indica cuándo surten efecto los cambios:

Comportamiento	Qué sucede
Solo bootstrap	El valor se lee una vez al inicio. Debes reiniciar el servicio para que los cambios surtan efecto.
Lectura en vivo	Los cambios surten efecto inmediatamente en la próxima solicitud.
Reconstrucción de bundle	Los cambios desencadenan una actualización de estado interno. Surte efecto en segundos.
Reconciliación de worker	Una recarga de configuración reconcilia los workers. Si cambió la configuración de un worker en ejecución, Matcher lo detiene y lo reinicia.

La mayoría de las claves que son solo bootstrap NO están registradas en la API de Systemplane — se gestionan exclusivamente a través de variables de entorno. Esto evita que un PUT de administrador parezca exitoso mientras el proceso en ejecución continúa silenciosamente usando el valor del momento de arranque. Las claves de Swagger registradas son la excepción: están visibles en Systemplane, pero siguen siendo solo bootstrap (consulta la nota más abajo).

​

Claves de configuración comunes

---

A continuación se muestran las claves más comúnmente ajustadas, organizadas por categoría. Para una lista completa, llama a GET /system/matcher.

​

Claves ajustables en tiempo de ejecución

Estas claves pueden cambiarse sin reiniciar Matcher:

swagger.enabled, swagger.host y swagger.schemes están registradas y visibles en Systemplane, pero no son controles en vivo. El montaje de Swagger y los valores del handler se capturan durante el bootstrap, por lo que un PUT en tiempo de ejecución no cambia el comportamiento en vivo de la interfaz ni de la especificación. Cambia su configuración de arranque y reinicia Matcher.

Clave	Variable de entorno	Descripción
server.body_limit_bytes	HTTP_BODY_LIMIT_BYTES	Tamaño máximo del cuerpo para rutas con buffer (positivo y no mayor que 128 MiB). Las cargas en streaming usan ingestion.max_upload_bytes.
cors.allowed_origins	CORS_ALLOWED_ORIGINS	Orígenes CORS permitidos
cors.allowed_methods	CORS_ALLOWED_METHODS	Métodos CORS permitidos
cors.allowed_headers	CORS_ALLOWED_HEADERS	Cabeceras CORS permitidas
rate_limit.enabled	RATE_LIMIT_ENABLED	Habilitar o deshabilitar el límite de tasa global
rate_limit.max	RATE_LIMIT_MAX	Máximo de solicitudes por ventana de límite de tasa
rate_limit.expiry_sec	RATE_LIMIT_EXPIRY_SEC	Duración de la ventana de límite de tasa (segundos)
rate_limit.export_max	EXPORT_RATE_LIMIT_MAX	Límite de tasa del endpoint de exportación
rate_limit.dispatch_max	DISPATCH_RATE_LIMIT_MAX	Límite de tasa del endpoint de dispatch
rate_limit.admin_max	ADMIN_RATE_LIMIT_MAX	Límite de tasa del plano admin (/system)
idempotency.retry_window_sec	IDEMPOTENCY_RETRY_WINDOW_SEC	Ventana para reintentar solicitudes idempotentes fallidas
idempotency.success_ttl_hours	IDEMPOTENCY_SUCCESS_TTL_HOURS	Cuánto tiempo se almacenan en caché las claves de idempotencia completadas
fetcher.discovery_interval_sec	FETCHER_DISCOVERY_INTERVAL_SEC	Base del TTL del lock distribuido que serializa las actualizaciones manuales de descubrimiento de Fetcher; el lease en tiempo de ejecución es 2× este valor
export_worker.enabled	EXPORT_WORKER_ENABLED	Habilitar o deshabilitar el worker de exportación
export_worker.poll_interval_sec	EXPORT_WORKER_POLL_INTERVAL_SEC	Con qué frecuencia el worker de exportación verifica nuevos trabajos
cleanup_worker.enabled	CLEANUP_WORKER_ENABLED	Habilitar o deshabilitar el worker de limpieza
cleanup_worker.interval_sec	CLEANUP_WORKER_INTERVAL_SEC	Intervalo del worker de limpieza
scheduler.interval_sec	SCHEDULER_INTERVAL_SEC	Intervalo de polling del scheduler
archival.enabled	ARCHIVAL_WORKER_ENABLED	Alternar el worker de archivado creado durante el arranque. Si el archivado estaba deshabilitado al arrancar, Systemplane no puede crear el worker
webhook.timeout_sec	WEBHOOK_TIMEOUT_SEC	Timeout para el despacho de webhooks/callbacks
callback_rate_limit.per_minute	CALLBACK_RATE_LIMIT_PER_MIN	Máximo de callbacks por sistema externo por minuto
deduplication.ttl_sec	DEDUPE_TTL_SEC	TTL de deduplicación en segundos

​

Claves multi-tenant (ajustables en tiempo de ejecución)

Estas claves controlan el comportamiento multi-tenant y pueden ajustarse sin reinicio. Consulta Modo Multi-Tenant para más detalles.

Habilitar el modo multi-tenant en sí (tenancy.multi_tenant_enabled / MULTI_TENANT_ENABLED) es solo bootstrap — se lee una vez al inicio y requiere un reinicio. No está registrado en la API de Systemplane y no puede alternarse en tiempo de ejecución. Consulta la tabla de solo bootstrap más abajo.

Clave	Variable de entorno	Descripción
tenancy.multi_tenant_url	MULTI_TENANT_URL	URL del servicio de multi-tenancy
tenancy.multi_tenant_max_tenant_pools	MULTI_TENANT_MAX_TENANT_POOLS	Máximo de pools de tenant concurrentes
tenancy.multi_tenant_idle_timeout_sec	MULTI_TENANT_IDLE_TIMEOUT_SEC	Timeout de inactividad para evicción de pool de tenant
tenancy.multi_tenant_cache_ttl_sec	MULTI_TENANT_CACHE_TTL_SEC	TTL de caché de configuración de tenant

​

Claves solo bootstrap (requieren reinicio)

Estas claves no están registradas en la API de systemplane. Cámbialas mediante variables de entorno y reinicia:

Clave	Variable de entorno	Descripción
tenancy.multi_tenant_enabled	MULTI_TENANT_ENABLED	Habilitar infraestructura multi-tenant. Se lee una vez al inicio; requiere un reinicio para cambiar.
app.env_name	ENV_NAME	Nombre del entorno de la aplicación
telemetry.enabled	ENABLE_TELEMETRY	Habilitar OpenTelemetry
app.log_level	LOG_LEVEL	Nivel de log de la aplicación (debug, info, warn, error, fatal)
server.address	SERVER_ADDRESS	Dirección de escucha del servidor HTTP
postgres.primary_host	POSTGRES_HOST	Host de la base de datos primaria
postgres.primary_port	POSTGRES_PORT	Puerto de la base de datos primaria
postgres.primary_db	POSTGRES_DB	Nombre de la base de datos primaria
redis.host	REDIS_HOST	Host de Redis
rabbitmq.host	RABBITMQ_HOST	Host de RabbitMQ
auth.enabled	PLUGIN_AUTH_ENABLED	Habilitar middleware de autenticación
auth.host	PLUGIN_AUTH_ADDRESS	Dirección del servicio de autenticación

​

Mejores prácticas

---

Inspecciona los valores actuales antes de cambiar

Llama a GET /system/matcher para ver todos los valores actuales en tiempo de ejecución antes de realizar cualquier cambio. Esto confirma lo que el proceso está usando realmente, que puede diferir de las variables de entorno si se realizaron llamadas PUT anteriores.

Prueba los cambios en staging primero

El comportamiento de aplicación en tiempo de ejecución varía según la clave, y los cambios de workers pueden reiniciar el worker afectado. Prueba en un entorno de staging antes de aplicar a producción.

Reinicia para claves solo bootstrap

Si una clave no es visible en GET /system/matcher, es solo bootstrap. Actualiza la variable de entorno y reinicia el servicio — no hay ruta en tiempo de ejecución para esos valores. Una clave visible puede seguir siendo solo bootstrap cuando su documentación lo indique: las claves de Swagger registradas aceptan un PUT en tiempo de ejecución, pero solo surten efecto después de reiniciar.

​

Próximos pasos

---

Modo multi-tenant

Habilitar y configurar el aislamiento de tenant.

Enrutamiento de excepciones

Configurar cómo se despachan las excepciones a sistemas externos.

Reglas de coincidencia

Configurar reglas de coincidencia de transacciones.

Seguridad

Autenticación, autorización y protección de datos.