> For the complete documentation index, see [llms.txt](https://docs.facephi.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.facephi.com/sdks/backend-sdk/finger/release_notes/2.2.1_release_notes.md).

# 2.2.1

**Fecha de lanzamiento:** 23 de septiembre de 2026

## Descripción general

Facephi Finger Service 2.2.1 permite ajustar por despliegue los umbrales con los que `GET /api/v1/finger/metrics` clasifica el estado del servicio y publica sus alertas, y corrige el mensaje de estado de las licencias válidas. No cambia el contrato de las operaciones de huella dactilar: las peticiones y respuestas de 2.2.0 siguen siendo válidas.

## Novedades

### Umbrales configurables de las métricas operativas

La clasificación del estado (`state.classification`) y las alertas de `GET /api/v1/finger/metrics` usan estos umbrales, que ahora se pueden ajustar sin una nueva versión:

| Parámetro                               | Por defecto | Uso                                                                                                                   |
| --------------------------------------- | ----------- | --------------------------------------------------------------------------------------------------------------------- |
| `metrics_saturation_queue_p95_ms`       | `250`       | Percentil 95 de la latencia de cola (1 minuto, ms) a partir del cual la cola se considera saturada                    |
| `metrics_saturation_min_inflight_ratio` | `1.0`       | Fracción de `number_of_threads` que deben superar las peticiones en curso para considerar el servicio saturado        |
| `metrics_error_rate_warning`            | `0.05`      | Tasa de error de 5 minutos a partir de la cual el servicio se clasifica como `degraded` y se activa `HIGH_ERROR_RATE` |
| `metrics_idle_rps_threshold`            | `0.01`      | Peticiones por segundo de 15 minutos por debajo de las cuales el servicio se clasifica como `idle`                    |
| `metrics_quality_alert_window_seconds`  | `900`       | Ventana durante la que una extracción de baja calidad mantiene activa la alerta `LOW_QUALITY`; `0` la desactiva       |

* Se configuran en `config.json`, con las variables de entorno `FACEPHI_FINGER_REST_METRICS_*` (por ejemplo, `FACEPHI_FINGER_REST_METRICS_ERROR_RATE_WARNING`) o en tiempo de ejecución con `POST /api/v1/finger/config`.
* Un valor que no se pueda interpretar, o negativo, se descarta con un aviso en el log y se usa el de la fuente de menor prioridad, así que un error tipográfico nunca deja el servicio sin una política de clasificación válida.
* Los umbrales solo cambian cómo se resume el snapshot: no cambian el procesamiento de las huellas.

### Cambios en la clasificación y las alertas

* La alerta `LOW_QUALITY` tiene en cuenta el tiempo: se desactiva cuando no se observa ninguna extracción de baja calidad durante `metrics_quality_alert_window_seconds`, aunque la proporción acumulada de extracciones de baja calidad siga por encima del umbral. Su `since` indica el inicio del episodio de baja calidad vigente; `quality.summary.lowQualitySince` sigue indicando la primera extracción de baja calidad desde el arranque.
* La clasificación `saturated` exige que las peticiones en curso superen estrictamente los hilos configurados, de modo que la propia petición que lee `/metrics` ya no cuenta como trabajo pendiente en un servicio de un solo hilo.

### Correcciones

* Con una licencia válida, `license.statusMessage` de `GET /api/v1/finger/health` y `state.license.statusMessage` de `GET /api/v1/finger/metrics` muestran `The license is valid.`. En la versión 2.2.0 mostraban `Unrecognized licensing error code: LF_OK. Please contact support.`, un mensaje cosmético que no indicaba ningún problema.

## Notas de migración

* No es necesario cambiar las integraciones de 2.2.0.
* Si tus paneles o alertas dependían de que `LOW_QUALITY` permaneciera activa, ten en cuenta que ahora se desactiva al cabo de `metrics_quality_alert_window_seconds` sin extracciones de baja calidad.
* Si tus sondas o alertas comparaban `license.statusMessage` con el texto de 2.2.0, compara en su lugar `license.valid`.

## Despliegue

```bash
docker pull facephicorp.jfrog.io/docker-pro-fphi/facephi-finger-service:2.2.1

docker run -d \
  -p 6982:6982 \
  -v /path/to/license:/app/license \
  -v /path/to/config:/app/config \
  --name finger-service \
  facephicorp.jfrog.io/docker-pro-fphi/facephi-finger-service:2.2.1
```

## Requisitos

| Componente        | Requisito                          |
| ----------------- | ---------------------------------- |
| Sistema operativo | Linux x86\_64                      |
| Licencia          | Archivo de licencia Facephi válido |
| Docker            | Recomendado para el despliegue     |

## Limitaciones conocidas

* Los endpoints de operaciones de huella dactilar solo están disponibles cuando el servicio se ejecuta en el rol `master`.
* Las actualizaciones dinámicas de configuración se aplican en memoria y no se persisten automáticamente.
* Solo los parámetros de conexión con el procesamiento (en los nodos `master`) y los umbrales `metrics_*` se aplican en tiempo de ejecución; el resto requiere reiniciar el servicio.

## Documentación

* [Guía de instalación](/sdks/backend-sdk/finger/installation/installation_instructions.md)
* [Especificaciones técnicas](/sdks/backend-sdk/finger/technical_documentation/technical_specifications.md)
* [Registro de cambios](/sdks/backend-sdk/finger/changelog.md)

## Soporte

Para soporte técnico, contacta con tu representante de Facephi.