> ## 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)
> Lee y actualiza la configuración en tiempo de ejecución de Matcher mediante la API de clave-valor de Systemplane. Ajusta los rate limits, los intervalos de los workers y el número máximo de pools de tenants sin reiniciar el servicio.
Systemplane permite ver y modificar la configuración admitida de Matcher sin reiniciar el servicio. El comportamiento de la aplicación varía según la clave: los ajustes de tiempo de solicitud pueden aplicarse en la siguiente solicitud, mientras que una recarga de configuración detiene y reinicia un worker en ejecución cuando su configuración cambia.
## Por qué usar Systemplane
***
En un despliegue tradicional, cambiar un valor de configuración implica actualizar variables de entorno y reiniciar el servicio. Systemplane elimina ese tiempo de inactividad para muchos ajustes:
* **Ajusta los rate limits** durante los picos de tráfico sin un redespliegue
* **Ajusta los intervalos de los workers** según la carga de trabajo observada. Una recarga de configuración sincroniza el worker afectado y lo reinicia cuando su configuración en ejecución cambia
* **Actualiza el número máximo de pools de tenants** a medida que cambian los patrones de tráfico. Los ajustes de conexiones por pool de PostgreSQL requieren un cambio de entorno y un reinicio
* **Inspecciona los valores actuales en tiempo de ejecución** para diagnosticar problemas de producción sin bucear en los logs
## Cómo funciona
***
Systemplane ofrece 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` | Lista todas las claves y sus valores actuales |
| `/system/matcher/:key` | `GET` | Obtiene el valor actual de una clave específica |
| `/system/matcher/:key` | `PUT` | Actualiza el valor de una clave específica |
La instancia de Matcher en ejecución sirve estos endpoints directamente. No están bajo `/v1`. Usa las rutas anteriores exactamente como se muestran.
## Permisos
***
Las rutas de configuración y de catálogo de Systemplane usan la misma autenticación que las rutas de la API de Matcher. Con la autenticación 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 aparte y requiere `streaming-manifest:read`.
Con la autenticación deshabilitada, todos los endpoints son accesibles sin restricción.
## Comportamientos de aplicación
***
Solo puedes cambiar algunos valores de configuración en tiempo de ejecución. Cada clave tiene un **comportamiento de aplicación** que indica cuándo los cambios tienen efecto:
| Comportamiento | Qué ocurre |
| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| **Solo bootstrap** | El valor se lee una sola vez al arrancar. Debes reiniciar el servicio para que los cambios tengan efecto. |
| **Lectura en vivo** | Los cambios tienen efecto de inmediato en la siguiente solicitud. |
| **Reconstrucción del bundle** | Los cambios disparan una actualización del estado interno. Tiene efecto en segundos. |
| **Sincronización del worker** | Una recarga de configuración sincroniza los workers. Si la configuración de un worker en ejecución cambió, Matcher lo detiene y lo reinicia. |
La API de systemplane NO registra la mayoría de las claves solo de bootstrap. Las gestionas exclusivamente mediante variables de entorno. Esto evita una trampa en la que un PUT de administrador parecería tener éxito mientras el proceso en ejecución seguiría usando en silencio el valor de arranque. Las claves de Swagger registradas son una excepción: son visibles en Systemplane pero siguen siendo solo de bootstrap (consulta la nota más abajo).
## Claves de configuración comunes
***
A continuación están las claves que ajustas con más frecuencia, organizadas por categoría. Para obtener la lista completa, llama a `GET /system/matcher`.
### Claves ajustables en tiempo de ejecución
Puedes cambiar estas claves sin reiniciar Matcher:
`swagger.enabled`, `swagger.host` y `swagger.schemes` están registradas y son visibles en Systemplane, pero no son controles en vivo. Matcher captura el montaje de Swagger y los valores del handler en el bootstrap, así que un `PUT` en tiempo de ejecución no cambia la UI en vivo ni el comportamiento de la especificación. En su lugar, 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 de la solicitud 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` | Headers CORS permitidos |
| `rate_limit.enabled` | `RATE_LIMIT_ENABLED` | Habilita o deshabilita el rate limiting global |
| `rate_limit.max` | `RATE_LIMIT_MAX` | Máximo de solicitudes por ventana de rate limit |
| `rate_limit.expiry_sec` | `RATE_LIMIT_EXPIRY_SEC` | Duración de la ventana de rate limit (segundos) |
| `rate_limit.export_max` | `EXPORT_RATE_LIMIT_MAX` | Rate limit del endpoint de exportación |
| `rate_limit.dispatch_max` | `DISPATCH_RATE_LIMIT_MAX` | Rate limit del endpoint de despacho |
| `rate_limit.admin_max` | `ADMIN_RATE_LIMIT_MAX` | Rate limit del plano de administración (`/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 guardan en caché las claves de idempotencia completadas |
| `fetcher.discovery_interval_sec` | `FETCHER_DISCOVERY_INTERVAL_SEC` | Base de TTL para el lock distribuido que serializa las actualizaciones manuales de Discovery; el lease en tiempo de ejecución es 2× este valor |
| `export_worker.enabled` | `EXPORT_WORKER_ENABLED` | Habilita o deshabilita el worker de exportación |
| `export_worker.poll_interval_sec` | `EXPORT_WORKER_POLL_INTERVAL_SEC` | Con qué frecuencia el worker de exportación busca nuevos jobs |
| `cleanup_worker.enabled` | `CLEANUP_WORKER_ENABLED` | Habilita o deshabilita 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 sondeo del planificador |
| `archival.enabled` | `ARCHIVAL_WORKER_ENABLED` | Activa o desactiva el worker de archivado creado en el arranque. Si el archivado estaba deshabilitado en el arranque, Systemplane no puede crear el worker |
| `webhook.timeout_sec` | `WEBHOOK_TIMEOUT_SEC` | Timeout para el despacho de webhook/callback |
| `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 puedes ajustarlas sin reiniciar. Consulta [Modo multi-tenant](/es/products/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 de bootstrap**. Matcher lo lee una vez al arrancar. Un cambio en él requiere un reinicio. La API de Systemplane no lo registra y no puedes cambiarlo en tiempo de ejecución. Consulta la tabla de claves solo de 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 tenants concurrentes |
| `tenancy.multi_tenant_idle_timeout_sec` | `MULTI_TENANT_IDLE_TIMEOUT_SEC` | Timeout de inactividad para la expulsión del pool de tenants |
| `tenancy.multi_tenant_cache_ttl_sec` | `MULTI_TENANT_CACHE_TTL_SEC` | TTL de la caché de configuración del tenant |
### Claves solo de bootstrap (requieren reinicio)
La API de systemplane no registra estas claves. Cámbialas mediante variables de entorno y reinicia:
| Clave | Variable de entorno | Descripción |
| ------------------------------ | ---------------------- | ---------------------------------------------------------------------------------------------------------- |
| `tenancy.multi_tenant_enabled` | `MULTI_TENANT_ENABLED` | Habilita la infraestructura multi-tenant. Se lee una vez al arrancar; requiere un reinicio para cambiarla. |
| `app.env_name` | `ENV_NAME` | Nombre del entorno de la aplicación |
| `telemetry.enabled` | `ENABLE_TELEMETRY` | Habilita 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` | Habilita el 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 hacer cualquier cambio. Esto confirma lo que el proceso usa de verdad. Puede diferir de las variables de entorno después de llamadas PUT previas.
El comportamiento de aplicación en tiempo de ejecución varía según la clave, y los cambios en un worker 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 de bootstrap. Actualiza la variable de entorno y reinicia el servicio. No hay una vía en tiempo de ejecución para esos valores. Una clave visible puede seguir siendo solo de bootstrap cuando su documentación lo dice: las claves de Swagger registradas aceptan un `PUT` en tiempo de ejecución pero solo tienen efecto después de un reinicio.
## Próximos pasos
***
Habilita y configura el aislamiento de tenants.
Configura el despacho de excepciones a sistemas externos.
Configura las reglas de coincidencia de transacciones.
Autenticación, autorización y protección de datos.