Reindexación de flujos de datos debido a conflictos de mapping

Cuando surgen conflictos de mapping en los campos, ya sean del estándar Elastic Common Schema (ECS) o específicos de la fuente de datos, es necesario reindexar tus datos con Herramientas de desarrollo. Estos conflictos pueden afectar negativamente cualquier función posterior tras la ingestión, lo que provoca resultados inexactos o impide el uso del conjunto de datos completo en características como visualizaciones, dashboards, la app de Security y agregaciones. Esta publicación de blog detalla los pasos para este proceso de reindexación.

El contenido de este blog se ha elaborado y verificado utilizando las versiones 9.2.8 y 8.19.14 de Elastic, junto con las versiones 2.3.0 y 1.2.0 de Filestream Integration.

Nota importante: Dependiendo de tu entorno, algunos pasos pueden requerir modificaciones específicas. Además, ten en cuenta que las plantillas dinámicas se eliminaron de la plantilla del componente @package a partir de la versión 2.3.3 de Filestream Integration.

Antes de comenzar el proceso de reindexación, es importante considerar la asignación actual de almacenamiento en tu entorno. Los pasos descritos a continuación implican crear una copia del índice de respaldo existente, que residirá temporalmente en el nivel de datos caliente.

Niveles de datos de Elasticsearch

• Caliente: el nivel caliente es el punto de entrada de Elasticsearch para los datos temporales, donde se almacenan los datos más recientes y buscados con frecuencia. Los nodos de nivel caliente requieren lecturas y escrituras rápidas, lo que necesita más recursos y almacenamiento más rápido (SSD). Este nivel es obligatorio y los nuevos índices de flujos de datos se asignan automáticamente aquí.
• Tibio: los Datos temporales pueden pasar al nivel tibio una vez que se consultan con menos frecuencia que los datos indexados recientemente en el nivel caliente. El nivel tibio suele contener datos de las últimas semanas. Las actualizaciones siguen estando permitidas, pero probablemente sean poco frecuentes. Los nodos en el nivel tibio generalmente no necesitan ser tan rápidos como los del nivel caliente. Para la resiliencia, los índices en el nivel tibio deben configurarse para usar una o más réplicas.
• Frío: los datos que son de búsqueda poco frecuente pueden pasar del nivel tibio al frío. El nivel frío, aunque sigue permitiendo realizar búsquedas, prioriza los costos de almacenamiento más bajos frente a la velocidad de búsqueda. Alternativamente, el nivel frío puede almacenar índices regulares con réplicas en lugar de snapshots buscables, lo que permite el uso de hardware menos costoso para datos antiguos sin reducir los requisitos de espacio en disco en comparación con el nivel tibio.
• Congelado: los datos que se consultan con poca frecuencia o que ya no se consultan se mueven del nivel frío al congelado para su ciclo de vida restante. Este nivel utiliza un repositorio de snapshot e índices parcialmente montados para almacenar y cargar datos, lo que reduce el almacenamiento local y los costos al tiempo que permite la búsqueda. Las búsquedas en el nivel congelado suelen ser más lentas que en el nivel frío, ya que es posible que Elasticsearch tenga que recuperar los datos congelados del repositorio de snapshot. Recomendamos nodos de nivel congelado dedicados.

Requisitos previos: determinar qué campos presentan conflictos

Para determinar qué campos tienen conflictos de mapping, navega a Stack Management -> Data Views -> logs-* (usar la vista de datos logs-* es la jerarquía más alta de datos presente con el prefijo logs-). Si hay algún conflicto, habrá un cuadro amarillo que lo indique. Puedes hacer clic en Ver conflictos o, en el cuadro de tipo de campo junto al cuadro de búsqueda , seleccionar conflicto.

Al hacer clic en el botón amarillo Conflicto, se mostrará qué índices están asociados con qué tipos de mapping.

Esta situación (donde el campo se mapea como un keyword y un long) generalmente ocurre porque los datos se ingirieron antes de que se definiera un tipo de mapping específico en la plantilla de componente para el flujo de datos relevante. En esos casos, Elasticsearch intenta configurar el mapping basándose en sus plantillas dinámicas.

Para determinar qué mapeo es apropiado para el campo y si el campo es un campo ECS, se necesita verificación con referencia de campo ECS. Si el campo en cuestión no es un campo ECS, hay que revisar su valor para determinar el mapeo correcto.

Si un campo, como log.offset en este ejemplo, no está documentado en el ECS, los siguientes pasos son investigar el valor del campo, determinar qué tipo de mapping conflictivo tiene más índices de respaldo y examinar las plantillas componentes de los otros índices.

Por lo general, el tipo de mapeo asociado al mayor número de índices es el correcto, pero te recomendamos que compruebes el valor del campo en cuestión para asegurarte de ello. Para confirmar la validez de un tipo de mapeo (por ejemplo, long), también debes verificar que el valor del campo sea apropiado para ese tipo. Esta verificación se puede realizar empleando Discover para buscar el campo en cuestión. Revisar otros flujos de datos que contengan el mismo campo también puede servir como confirmación adicional.

Para revisar los valores presentes en el campo con el problema de mapping, vuelve al botón amarillo Conflictomencionado anteriormente, haz clic en el botón Conflicto, selecciona uno de los índices de respaldo y péguelo en una sesión de Discover . Tu declaración del lenguaje de búsqueda de Kibana (KQL) debería verse como la siguiente captura de pantalla, para incluir el delimitador de campo _index:.

Prepara la nueva plantilla de componente personalizado del índice de respaldo

Para abordar el conflicto de mapping en el flujo de datos, primero examina la plantilla de componentes correspondiente @package. Puedes encontrar esto en Stack Management -> Gestión de indexación> Plantilla de componentes. Busca el flujo de datos y selecciona el enlace @package correspondiente. Esta plantilla contiene mapping para el campo listos para usar y, aunque no es común tener una falta de coincidencia de mapping, es posible que se pase por alto el tipo más apropiado.

Revisa la plantilla para asegurarte de que contiene el anidamiento y el mapeo de campos necesarios para el campo en cuestión. Por ejemplo, si la plantilla indica incorrectamente log.offset como keyword, esta es la fuente del problema.

Importante: Debido a que no se recomienda modificar las plantillas @package/administradas, debes usar o crear una plantilla de componente @custom para corregir el tipo de mapeo (por ejemplo, para log.offset) para todos los datos futuros.

• No recomendamos modificar las plantillas @package/administradas, ya que cuando actualices la integración a una versión más reciente, cualquier cambio que realices en la plantilla @package se sobrescribirá. Por eso recomendamos usar las plantillas de @custom .
• Si un flujo de datos experimenta conflictos de mapeo, debes agregar cualquier anidamiento o mapeo de campos faltantes (ECS y no ECS) a la plantilla de componente @custom del flujo de datos. Crea esta plantilla si aún no existe y asegúrate de especificar el tipo de mapeo correcto para el campo.
• Si tienes varios conflictos en tu data view, aplica todos los mapping faltantes necesarios para el flujo de datos en simultáneo para que la reindexación se realice una vez en lugar de varias veces. Contar con entradas para el ingreso de datos correcto en la plantilla de componentes @custom plantilla de componentes garantizará que cualquier futura ingesta de datos siga la misma pauta de mapping.

Para crear la plantilla de componente @custom (o verificar que está en uso y rellenada), navega a Plantillas de Índice, escribe el nombre del flujo de datos en cuestión y haz clic en la plantilla de @custom correspondiente que esté usando el flujo de datos. Si la plantilla aún no está creada, aparecerá un cuadro amarillo que te permitirá crear la plantilla a través de la UI.

La captura de pantalla a continuación muestra la página siguiente una vez que se selecciona Crear plantilla de componente. Deja los valores predeterminados tal como están en la primera página y haz clic en Mappings o Siguiente hasta que llegues a la página Mappings.

Para establecer explícitamente el mapeo de un nuevo campo que entra o para actualizar un campo que tenga un conflicto de mapeo, cuando el flujo de datos se revierte debido a la configuración establecida en la política de ciclo de vida del índice, se necesita una entrada para el campo en el que existe el conflicto.

Lo siguiente establecerá el mapeo para el campo log.offset en la plantilla de componente @custom para el flujo de datos filestream. Repite los pasos para agregar cualquier campo personalizado o actualizar los campos necesarios del @package con los mapeos adecuados, si es necesario, para este set de datos. En este ejemplo, al establecer el desplazamiento en Long, el tipo de campo será Numeric y el tipo numérico será Long. Haz clic en Agregar campo y luego fuera del área para continuar.

Una vez que se hayan agregado todos los campos necesarios, haz clic para revisar y selecciona Crear plantilla de componente cuando esté listo. Todos los nuevos datos que se ingesten a partir de este paso tendrán log.offset configurado en long.

Creación de la nueva estructura de índice de respaldo

El nuevo índice de respaldo debe tener los mappings existentes de la plantilla de componentes del flujo de datos, así como la plantilla de componentes ECS ecs@mappings. La ecs@mappings plantilla de componente se aplica después del componente del flujo de datos como un recurso general para mappings adicionales que potencialmente no se capturaron en las plantillas de componentes anteriores.

Ve a la pestaña del navegador para ver el mapeo @package del flujo de datos. (Go to Stack Management -> Gestión de índices -> Plantilla de componentes -> logs-filestream.generic@package -> Gestionar -> Editar.) Una vez allí, haz clic en la sección Revisión, luego en Solicitar y finalmente en el botón Copiar a la derecha. El contenido JSON de la plantilla de componentes copiada garantizará que se conserven los mapeos y configuraciones de campo restantes mientras actualizamos el mapeo del campo log.offset. El JSON formará la estructura de respaldo para el índice de respaldo recién reindexado.

Importante: si no se copiara el JSON de la plantilla y se continuara trabajando con la reindexación, el log.offset conflicto se resolvería, pero habría nuevos conflictos con la integración, ya que no se mantendría la integridad de las asignaciones actuales, lo que crearía un doble trabajo para resolver el problema original.

Abre una segunda pestaña del navegador, navega a Herramientas de desarrollo y pega el contenido copiado. Ahora, para limpiar lo que se pegó:

Modificaciones a la solicitud

1. Nombre del índice: Reemplaza _component_template/logs-filestream.generic@package con el nombre del índice de respaldo que pretendes reindexar, añadiendo -1 al final. Por ejemplo, usa PUT <backing index to reindex>-1.

• El adjunto -1 indica una reindexación y no entrará en conflicto con la configuración predeterminada de rollover de ILM, que se basa en la fecha de creación del índice.

2. Configuración: Elimina la línea "template" (línea 3), así como la última llave de cierre para toda la carga útil JSON; la línea 3 debería comenzar con "settings": {.

• Sustituye el contenido interior de la sección de ajustes por "index.codec": "best_compression". Esta acción aplicará la mejor compresión de Elastic al índice al momento de la creación.
• Agrega "index.lifecycle.name": "logs", así como una línea para "index.lifecycle.rollover_alias": "".
  1. La "index.lifecycle.name": "logs" entrada aplicará la política de ILM de logs al nuevo índice de respaldo. Modifica el nombre de la política de ILM si no usas logs.
  2. El "index.lifecycle.rollover_alias": "" está en blanco, ya que este índice de respaldo no se rotará, pero la configuración es necesaria para evitar errores de rotación de ILM en la siguiente fase de ILM después de hot.

3. Estructura: la solicitud ahora debería incluir tanto una sección Settings como una sección Mappings. Dentro de "mappings": {deberías encontrar "dynamic_templates" y una sección de "properties" que contiene campos codificados y sus mappings.

4. Modificación de plantillas dinámicas: La sección actual de plantillas dinámicas contiene entradas para campos que pueden sobrescribirse cuando se agregan las ecs@mappings plantillas dinámicas a continuación, lo que provoca redundancia y líneas adicionales que no son necesarias.

• Elimina todas las secciones de "dynamic_templates" excepto la segunda sección llamada "_embedded_ecs-data_stream_to_constant": {.
• Repite el mismo proceso descrito anteriormente, ya que reúne los mappings dinámicos para la plantilla del componente @package , pero esta vez los mappings dinámicos para la plantilla del componente ecs@mappings.
  • Puede ser más fácil copiar todo el contenido de los mapeos de la interfaz de usuario para la plantilla del componente ecs@mappings, pegarlo en la sección Herramientas de desarrollo dynamic_templates que funcione y eliminar las líneas duplicadas e innecesarias cuando sea apropiado. Incluye estos contenidos de configuración de plantilla dinámica después de la entrada"_embedded_ecs-data_stream_to_constant": {. La sección dynamic_templates debería tener un aspecto muy similar al contenido de muestra a continuación en Dev Tools.
• Si dynamic_templates no se incluyen o eliminan por completo, otros campos (revisa la captura de pantalla abajo) tendrán doble mapeo: text y keyword frente a los mapeos adecuados, si la sección de dynamic_templates se dejó incluida. Lo que queda debería ser la sección "properties" debajo de "mappings". Esto también creará problemas en la Data view, ya que los campos se mapearán dos veces (si no se mapearon ya de esta manera) y provocará conflictos de mapeo adicionales.

5. Eliminación de metadatos: elimina la última sección etiquetada "_meta", así como la sección etiquetada "version", si está presente.

6. Formato: indentación automática de las secciones restantes y ajuste o eliminación de cualquier corchete innecesario que impida una ejecución exitosa.

7. Cambio de mapeo: Navega hasta la sección "properties" , encuentra "log"y luego localiza "offset" anidado debajo. Cambia el tipo de keyword a long, y elimina la entrada de línea (incluida la coma) etiquetada "ignore_above": 1024,. Si se agregaste más de una entrada a la plantilla de componente @custom creada anteriormente, inclúyela aquí.

Tu vista de consola de herramientas de desarrollo ahora debería ser similar al ejemplo que se proporciona a continuación.

Una vez que su consola se parezca al ejemplo (incluyendo cualquier campo personalizado adicional y valores personalizados específicos de su entorno), ejecute el comando para crear la estructura básica del nuevo índice de respaldo, haciendo una pausa para resolver cualquier error que surja.

Comenzar el proceso de reindexación

Con el shell del nuevo índice de respaldo creado correctamente, el siguiente paso es reindexar y resolver los conflictos de mapping.

Importante: si el índice de respaldo que presenta el conflicto de mapping es el índice más reciente y es el índice de escritura actual (por ejemplo, el número final del índice de respaldo es -000001), el flujo de datos debe reiniciarse. Es necesario reiniciar el flujo de datos, ya que el índice de escritura actual, al que se le están introduciendo documentos, es un índice de respaldo activo y no se puede modificar.

Con el mapping de campo correcto ahora aplicado al índice de escritura más nuevo a través de la plantilla de componente @custom creada anteriormente, todos los documentos nuevos reflejarán este cambio.

Esto se realiza ejecutando lo siguiente:

Por ejemplo:

La reindexación implica copiar los datos de un índice de respaldo existente a uno nuevo dentro de la misma convención de nomenclatura, generalmente para aplicar los cambios necesarios. Estas modificaciones podrían incluir actualizaciones de una plantilla de componente o la incorporación de un nuevo pipeline de ingesta para procesar los datos.

A continuación, los datos se copiarán desde el índice de respaldo que tiene los mappings incorrectos a un nuevo índice de respaldo. El índice de respaldo original se ha desplazado, lo que significa que no se pueden agregar nuevos documentos. El nuevo índice de respaldo seguirá la misma convención de nombres, que preserva la visibilidad e integridad de los datos al aplicar la política ILM correcta, pero incluirá un sufijo -1 para indicar que fue reindexado.

Ajusta los nombres de los índices según sea necesario y pega el siguiente código en la consola. Al incluir wait_for_completion=false, puedes seguir el progreso de la copia de documentos, lo que ayuda a estimar el tiempo restante de reindexación. Sin esta configuración, no puedes rastrear el estado con el comando GET _tasks a continuación y solo podrás verificar el recuento de documentos en el índice de respaldo más nuevo con GET <backing index name>-1/_count.

Importante: si surgen problemas durante el proceso de reindexación, no vuelvas a ejecutar el comando reindex; hacerlo reiniciará el proceso y creará registros duplicados en el índice que terminan en -1. Si es necesario reiniciar, primero elimina el índice que termina en -1, y luego ejecuta el comando PUT anterior para recrear la nueva shell de índice de respaldo.

Tras la ejecución, la respuesta incluirá un ID de tarea. Puedes monitorear el progreso de la reindexación usando este ID con el comando: GET _tasks/<task ID>.

La duración de la reindexación depende del volumen de datos del índice original. La finalización se puede rastrear si se busca "completed": true al ejecutar el comando GET, lo que debería producir una salida similar.

GET _tasks/<task ID>

Con el proceso de reindexación ya finalizado para el recuento de documentos, el siguiente paso es verificar que los mapeos para el nuevo índice de respaldo y el campo específico en cuestión sean correctas.

Por ejemplo:

Puedes verificar que el mapeo para log.offset es como se muestra a continuación. Para confirmar que otros campos tienen solo una entrada de mapeo (no ambas text y keyword), compáralos con un campo que no formaba parte de la sección de plantilla dinámica en el comando PUT anterior.

Si el índice de respaldo que se está reindexando tiene una gran cantidad de documentos, es útil verificar el estado de esos documentos que se están copiando al nuevo índice de respaldo; esto se puede hacer con los siguientes dos comandos de Herramientas de desarrollo para comparar los recuentos.

GET .ds-logs-filestream.generic-default-2026.04.14-000001/_count

GET .ds-logs-filestream.generic-default-2026.04.14-000001-1/_count

Una vez que se verifique que los recuentos coinciden y que los mapeos correctos están presentes, actualiza el flujo de datos para incluir el nuevo índice de respaldo, para prevenir un índice de respaldo huérfano en la administración de índices, donde la política de ILM nunca se ejecutará en el índice de respaldo.

• El retorno debería ser un reconocimiento de verdadero, si tiene éxito.

Verifica que el nuevo índice de respaldo se haya agregado con el siguiente comando, cerciorándote de que la ilm_policy sea correcta:

Verifique el estado de ILM del índice de respaldo a continuación con el siguiente comando:

• Es normal ver que el índice esté en caliente, ya que fue creado muy recientemente (revisa la línea 8 o 10).

Ejecuta lo siguiente para hacer la transición del índice de respaldo del nivel activo al siguiente nivel apropiado después de la fase caliente de la política de ILM para este flujo de datos. Los valores específicos para phase, action, y name en el current_step siguiente pueden referenciarse a partir de las líneas 11, 13 y 15, respectivamente, en la captura de pantalla proporcionada arriba.

El valor next_step indica la fase de ILM o el nivel de datos posterior al que el índice hará la transición.

Por ejemplo:

• No es necesario, pero como medida de seguridad, puedes ejecutar el comando _ilm/explain de nuevo para cerciorarte de que el índice de respaldo pasó a la siguiente fase y ya no está en caliente.

Una vez que se cumplan las siguientes condiciones, puedes eliminar de forma segura el índice de respaldo original que tenía conflictos de mapeo:

1. Se ha creado correctamente un nuevo índice de respaldo.
2. Los documentos se han trasladado al nuevo índice y la cantidad de documentos coincide.
3. Los mapeos se han corregido (tanto específicos del flujo de datos como ECS).
4. El flujo de datos incorpora el nuevo índice de respaldo.
5. La política de ILM se ha aplicado y ha movido el índice fuera de la fase caliente.

Importante: Como alternativa, antes de eliminar el índice original, puedes consultar la página Data Views. Selecciona logs-* y verifica que el índice de respaldo reindexado (que termina en -1) ahora aparece en la sección long. El índice de respaldo original debería seguir presente en keyword. Si el índice de respaldo reindexado no está en la sección long, vuelve atrás y revisa los pasos anteriores y realiza las correcciones necesarias.

Por ejemplo:

Luego de resolver los conflictos, vuelve a la página Data Views y selecciona logs-*. Si el conflicto estuviera relacionado únicamente con log.offset, ya no debería ver ningún conflicto listado. Si hubiera otros conflictos, el índice de respaldo original ya no debería aparecer en la lista de conflictos; en cambio, el nuevo índice de respaldo debería aparecer ahora en la sección long.

También puedes verificar en Discover que el campo log.offset ahora muestra los iconos correspondientes.

Continúe este proceso, repitiendo los pasos anteriores para cada índice de respaldo que tenga un conflicto de mapeo hasta que todos se resuelvan con éxito.

Referencias:

• Referencia de campo de ECS
• Reindexar documentos

Reflexiones finales

Si sigues los pasos de este blog, resolverás los conflictos de mapping y te asegurarás de que todos los datos nuevos estén correctamente mapeados. Esto se consigue vinculando las plantillas de componentes necesarias a tu fuente de datos. Este flujo de trabajo no solo resuelve los problemas inmediatos, sino que también establece un proceso seguro y repetible para gestionar los cambios en el esquema a medida que tus datos y requisitos evolucionan.