> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.
# 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](/es/matcher/configuration/matcher-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
***
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.
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.
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
***
Habilitar y configurar el aislamiento de tenant.
Configurar cómo se despachan las excepciones a sistemas externos.
Configurar reglas de coincidencia de transacciones.
Autenticación, autorización y protección de datos.