Para agentes de IA: hay un índice de documentación disponible en https://www.mongodb.com/es/docs/llms.txt — versiones en markdown de todas las páginas están disponibles agregando .md a cualquier ruta URL.

Operaciones de Atlas Stream Processing

Esta guía describe las mejores prácticas para administrar Atlas Stream Processing, incluyendo procedimientos específicos para flujos de trabajo esenciales.

Cada procesador de Stream Processing depende de conexiones a fuentes de datos y sumideros. Atlas Stream Processing cifra todos los datos en tránsito mediante TLS/SSL, pero las conexiones básicas siguen pasando datos a través de Internet público. Para lograr un rendimiento óptimo y seguridad con Atlas Stream Processing, tenga en cuenta las prácticas descritas en esta sección.

Para garantizar una comunicación segura entre Atlas Stream Processing y los sistemas externos privados, como los clústeres autogestionados de Apache Kafka o las API privadas, utilice conexiones de emparejamiento de VPC o VNet. Estas conexiones protegen sus datos de la exposición al Internet público. Tenga en cuenta que, además de establecer la conexión de emparejamiento, debe configurar explícitamente las tablas de enrutamiento para la VPC de su aplicación a fin de dirigir el tráfico al bloque CIDR de su Atlas VPC. Para aprender más sobre cómo configurar su tabla de rutas, consulte la documentación de VPC de su proveedor externo.

Para enrutar datos de transmisión entre diferentes proyectos de Atlas dentro de la misma organización, Atlas Stream Processing admite Conexiones entre proyectos. Las conexiones entre proyectos transmiten datos sin exponer los clústeres a la Internet privada, lo que garantiza la privacidad sin la necesidad de configurar manualmente el emparejamiento de VPC.

Atlas Stream Processing admite las siguientes integraciones de AWS:

  • S3

  • Kinesis Data Streams

  • Lambda (como $externalFunction)

Cada una de estas integraciones es compatible con Unified AWS Access. La configuración del acceso unificado elimina la necesidad de almacenar ID de acceso estáticos o credenciales secretas en MongoDB, y es el modelo de autenticación recomendado para todas las integraciones de AWS.

Atlas Stream Processing admite la autenticación en los brokers de Apache Kafka mediante OIDC con JSON Web Tokens. Sin embargo, esta funcionalidad actualmente solo admite proveedores de identidad a los que se puede acceder a través de redes públicas. Esta funcionalidad no es compatible para proveedores de identidad dentro de la VPC de un cliente.

Atlas Stream Processing proporciona varios mecanismos para garantizar un servicio fiable y robusto en escenarios de fallos comunes, incluidos puntos de control, filas de letra muerta y procesadores de conmutación por error.

Atlas Stream Processing supervisa el estado del procesador de transmisión mediante un latido de 30segundos. Si un procesador de transmisión no envía un latido durante más de 30 segundos, Atlas Stream Processing reinicia automáticamente el procesador.

Atlas Stream Processing gestiona automáticamente los cambios de topología para integraciones particionadas como AWS Kinesis.

Puede configurar Atlas Stream Processing para enrutar datos sin procesar a una fila de letra muerta (DLQ). Luego puede ver los registros sin procesar en la DLQ para corregir errores de procesamiento.

La cola de mensajes fallidos (DLQ) captura únicamente los errores de procesamiento por documento. Otros errores impiden que se ejecute el procesador y no generan registros de la DLQ. Estos errores incluyen errores de sintaxis o configuración no válidas del pipeline y errores dentro del sistema Atlas Stream Processing. Para estos errores, Atlas Stream Processing aplica sus políticas de gestión de errores y reintentos.

Si un documento no se procesa correctamente y el procesador de flujos no tiene configurada una DLQ, Atlas Stream Processing descarta el documento. Las estadísticas de la DLQ, como stats.dlqMessageCount, siguen registrando el fallo. Si se realiza un muestreo del procesador con sp.processor.sample(), el documento con errores seguirá apareciendo en los resultados de la muestra.

Algunas etapas de pipeline definen su propio comportamiento de gestión de errores, que determina si un documento que falla llega a la cola de mensajes no entregados (DLQ):

Etapa
Campo
Comportamiento del manejo de errores

validationAction

  • "discard": Comportamiento por defecto. Descarta el documento sin escribirlo en la DLQ.

  • "dlq": guarda el documento en la DLQ.

onError

  • "dlq": comportamiento por defecto. Guarda el documento en la DLQ.

  • "ignore": pasa el documento a la siguiente etapa de pipeline.

  • "fail": detiene el procesador de flujos, incluso si configura una DLQ.

onError

  • "dlq": comportamiento por defecto. Guarda el documento en la DLQ.

  • "ignore": descarta el documento.

  • "fail": detiene el procesador de flujos, incluso si configura una DLQ.

Cuando examine su DLQ, busque los siguientes errores de procesamiento comunes:

  • Análisis de carga útil

    El registro entrante está mal formado y no se puede analizar. Esto a menudo se debe a JSON no válido.

  • Evaluación de expresiones

    Una expresión en el pipeline de procesamiento no se evalúa correctamente.

    Ejemplo

    Su pipeline incluye el campo de configuración $emit.config.tombstoneWhen para borrar registros de Kafka, y un documento dado no tiene el campo a evaluar.

  • Límite de tamaño

    El registro saliente supera el límite de tamaño de su receptor de destino, como 1 MB para Amazon Web Services Kinesis.

  • Generación de claves

    El procesador encuentra un error al generar una llave de partición para su destino.

  • Datos tardíos

    Su procesador utiliza ventanas y un documento determinado llegó después de que expirara el período configurado de retraso permitido.

Cada registro de la DLQ contiene el documento que no se pudo procesar y los detalles del fallo. Para consultar el esquema completo del documento de la DLQ, consulta la guía de supervisión.

Después de analizar las causas de los errores de procesamiento, modifique sus fuentes de datos ascendentes para corregir los datos antes de que entren en su pipeline de Atlas Stream Processing, o modifique su pipeline para gestionar los casos extremos.

Considere las siguientes opciones de remediación para los registros en la DLQ después de utilizarlos como guía para las correcciones en su configuración de Atlas Stream Processing:

  • Descartar

    Si un registro está muy mal formado o es irrelevante —por ejemplo, datos muy atrasados en sistemas con alta sensibilidad temporal—, bórrelo de la colección.

  • Corrección manual

    Para un registro con errores menores de JSON o uno de importancia vital, ajuste manualmente los campos e insértelos directamente en su receptor de destino.

  • Reprocesamiento automatizado:

    Para grandes volúmenes de datos recuperables y relevantes, cree un script secundario o un procesador de transmisión adicional que lea de la DLQ y aplicar una transformación contra condiciones de error conocidas antes de enrutar los datos limpios al receptor de destino.

Atlas Stream Processing proporciona procesadores de conmutación por error para evitar la interrupción del servicio en el evento de fallo del sistema en toda la región.

Los siguientes principios definen una configuración de conmutación por error sólida para proteger sus cargas de trabajo de Atlas Stream Processing.

  • Implementar clústeres de Atlas en múltiple regiones.

    Para garantizar la operación continua de sus procesadores de flujo en un evento de conmutación por error regional, utilice clústeres multiregionales para cualquier clúster de Atlas al que se conecte su procesador de flujo. Atlas Stream Processing no bloquea la conmutación por error para clústeres de una sola región, pero este principio garantiza que las conexiones de origen o destino permanezcan activas cuando la región primaria no esté disponible.

  • Cree espacios de trabajo de Atlas Stream Processing para cada región.

    Después de implementar sus clústeres multiregionales, cree un espacio de trabajo para cada región. Este principio minimiza la latencia de las conexiones entre sus procesadores de transmisión y sus bases de datos Atlas de apoyo.

  • Rellenar el Registro de conexiones con conexiones de copia de seguridad.

    Configure las conexiones para cada origen y destino en el espacio de trabajo de cada región. Asegúrese de configurar las conexiones no solo para conexiones básicas, sino también para VPC y conexiones de nodos privados.

  • Configurar la recuperación ante desastres específica de la conexión

    Para garantizar la continuidad del servicio para un procesador de flujos, cualquier proveedor externo del que dependa también debe tener habilitada la conmutación por error. Asegúrese de que cada origen o destino de proveedor externo esté configurado correctamente según su documentación.

    Ejemplo

    Si su procesador de flujo utiliza un clúster de Kafka como origen o destino, configure el clúster para el mantenimiento de la compensación del consumidor para permitir que Atlas Stream Processing reanude el procesamiento desde una compensación de grupo de consumidores.

  • Ejecutar pruebas en seco rutinarias.

    Verifique su configuración de conmutación por error realizando periódicamente simulacros de conmutación por error. Estas pruebas en seco sirven tanto para asegurar que su configuración se conecte a las redes y cargue los puntos de control correctamente, como para entrenar el flujo de trabajo de conmutación por error para que sea más fácil de realizar cuando sea necesario. Considere establecer una cadencia regular de ejecutar simulacros de conmutación por error y ejecute un simulacro cada vez que modifique la configuración de conmutación por error.

Una vez que se asegure de que las mejores prácticas están implementadas, cree un procesador de transmisión y verifique su configuración de conmutación por error.

Atlas Stream Processing admite la conmutación por error regional automatizada solo para procesadores con las siguientes configuraciones:

  • Origen y destino de Atlas

  • Atlas source y Apache Kafka sink

Para obtener más información sobre la conmutación por error automatizada, consulte Procesador de conmutación por error.

Sin embargo, puede configurar una arquitectura de Atlas Stream Processing que admita la conmutación por error manual para cualquier combinación de conexión de origen y destino.

Interfaz
Tipo de conmutación por error

Puede iniciar una conmutación por error forzada a nivel de espacio de trabajo o de procesador de flujo.

Para iniciar la conmutación por error del espacio de trabajo de Stream Processing, siga el procedimiento descrito en Activador de conmutación por error del espacio de trabajo de Stream Processing.

Para iniciar la conmutación por error de un procesador de flujo individual, siga el procedimiento descrito en Iniciar la conmutación por error de un procesador de flujo.

En caso de un evento de interrupción del servicio regional:

1

Cuando note síntomas de una interrupción del servicio, realice una revisión de su informe de estado preferido para verificar el evento. Puede ver esta información en la página de Estado de MongoDB Cloud o en la página de estado de su proveedor de nube. Puede configurar Alertas de Stream Processing de Atlas. Tenga en cuenta la marca de tiempo del evento de error.

2

Siga el procedimiento descrito en Iniciar conmutación por error para un procesador de transmisión. Para asegurarse de que el servicio se reanude desde el último evento de transmisión consumido, pase la marca de tiempo que anotó anteriormente como parámetro startAtOperationTime.

Procesadores que utilizan fuentes de Apache Kafka se reanudan según los desplazamientos del grupo de consumidores.

3

Cuando su región primaria vuelva a estar en linea, sus procesadores primarios se reiniciarán automáticamente, lo que dará lugar a un procesamiento duplicado. Cree y ejecute un script para comprobar continuamente el estado de la región primaria y detener todos los procesadores de esa región cuando vuelva a estar en linea.

4

Una vez completada la conmutación por error, compruebe periódicamente el estado de la región principal de su espacio de trabajo. Puede ver esta información en la página de Estado de MongoDB Cloud o en la página de estado de su proveedor de nube. También puede configurar alertas de Stream Processing de Atlas. Si utiliza la supresión automática del procesador primario, puede configurar el script para devolver notificaciones cuando detecte que los procesadores primarios se reinician automáticamente.

5

Detén tus procesadores de streaming de conmutación por error. Tenga en cuenta la marca de tiempo de cada parada.

6

Reinicie los procesadores de transmisión en su región principal. Para asegurarse de que el servicio se reanude desde el último evento de transmisión consumido, pase la marca de tiempo que anotó anteriormente como parámetro startAtOperationTime.

Procesadores que utilizan fuentes de Apache Kafka se reanudan según los desplazamientos del grupo de consumidores.

Tenga en cuenta lo siguiente al configurar sus sistemas para la conmutación por error regional o al activar la conmutación por error manual:

  • Cuando se produce una conmutación por error regional, Atlas Stream Processing promueve los procesadores de conmutación por error inactivos en su región de conmutación por error a procesadores activos. Estos procesadores reanudan el Stream Processing desde el último punto de controldisponible.

  • Los puntos de control de Atlas Stream Processing garantizan que no tengan más de 10 minutos de antigüedad. Sin embargo, los procesadores de conmutación por error vuelven a procesar cualquier dato que su procesador primario procesó desde el último punto de control al iniciarse. Recuperación ante fallos: garantías de la semántica de procesamiento de 'al menos una vez'.

  • Si un procesador de conmutación por error no se inicia durante un evento de conmutación por error regional, sigue asumiendo el rol de procesador activo. A continuación, puede solucionar la causa subyacente y reiniciar el procesador con normalidad en la región de conmutación por error.

Atlas Stream Processing proporciona varias herramientas de observabilidad para evaluar el rendimiento y el estado de sus espacios de trabajo, conexiones y procesadores. Además, para rastrear el estado del servicio regional y las interrupciones del servicio, puede visitar la página de Estado de la nube de MongoDB.

Atlas Stream Processing aprovisiona recursos por cada procesador de transmisión. Para obtener más información, consulta la Guía de selección de nivel.

Para los procesadores de Atlas Stream Processing que operan en clústeres de Atlas, asegúrese de escalar también tanto sus procesadores como sus clústeres proporcionalmente a las necesidades de E/S de su pipeline. En particular, evalúe los procesadores que realizan un gran volumen de operaciones $lookup o $merge como candidatos para el escalado vertical del clúster.

Atlas Stream Processing puede usar un clúster de Atlas $source para consumir eventos de flujo de cambios. Para garantizar un rendimiento y una fiabilidad óptimos para dichos procesadores de transmisión, revise las siguientes consideraciones:

  • Tamaño de la oplog window

    Los procesadores de transmisión aprovechan el clúster $source de oplog para reanudar el servicio después de una interrupción. Si un procesador está inactivo durante un período superior al período de retención del oplog, el token de reanudación puede apuntar a datos truncados, lo que provoca un error ChangeStreamHistoryLost.

    Mitigue este riesgo alineando el tamaño del oplog con el tiempo de inactividad aceptable para sus sistemas de Stream Processing.

  • Opciones de reanudación

    Atlas Stream Processing admite reanudar el flujo de cambios $source``s from either the last stored checkpoint with ``resumeFromCheckpoint o un momento específico con startAtOperationTime. Para evitar lagunas o duplicaciones en los datos procesados, defina una política estandarizada sobre qué opciones de reanudación utiliza en un escenario determinado.

  • Ingestión de backlog

    Los procesadores de flujo que operan en un namespace grande pueden experimentar largos períodos iniciales de procesamiento de puesta al día. Considere reducir el alcance del namespace de su procesador de flujo o elegir un punto de inicio más reciente para reducir este período inicial de puesta al día.

  • Imágenes de Change Stream

    La auditoría, las transacciones de compensación y las operaciones de deshacer requieren acceso al estado del documento previo al procesamiento. Cuando trabaje con Atlas como origen, habilite documento Pre- y Post-publicación para admitir estas operaciones. Cuando implemente la compatibilidad para preimágenes o postimágenes de documentos, verifique la cobertura y la estabilidad en todo su sistema.

  • La etapa ``$replaceRoot``

    Las fuentes de flujo de cambios devuelven documentos que agrupan metadatos operativos con el contenido del documento afectado. Escribir estos documentos en un receptor requiere que los consumidores trabajen con el esquema de eventos de cambio en lugar de la lógica empresarial del documento de origen. A menos que necesite los metadatos, utilice la etapa $replaceRoot para promover el subdocumento de contenido de origen antes de un procesamiento posterior.

  • Pipeline orientado a uniones

    Atlas Stream Processing admite la etapa $lookup para permitir enriquecimientos similares a uniones de datos de transmisión. Estas operaciones pueden aumentar la latencia de procesamiento. Considere limitar sus pipelines de Atlas Stream Processing a solo aquellas $lookup operaciones que deben realizarse antes de escribir en un receptor, reservando enriquecimientos más complejos para vistas precalculadas.

  • Puntos de control obsoletos

    Los puntos de control contienen solo el historial de eventos, no la lógica de procesamiento. Cuando reanuda la operación desde un punto de control, su procesador de transmisión aplica la lógica de su pipeline actual a los eventos antiguos, lo que puede provocar una falta de coincidencia entre su estado descendente existente y su nueva salida. Considere la posibilidad de introducir un nuevo procesador de transmisión en lugar de reanudar desde un punto de control si necesita una semántica de procesamiento significativamente diferente.

  • Planificación de reinicio

    Durante el reinicio, un procesador de flujo podría experimentar un rendimiento reducido de eventos nuevos. Para aumentar la resiliencia del sistema, programe reinicios para tener en cuenta la capacidad temporalmente reducida.

  • Planificación de conmutación por error

    Desarrollar procedimientos estándar para el uso compartido de puntos de control del procesador de transmisión en todas las regiones, la elección de puntos de reanudación seguros y la validación de la coherencia de la salida para garantizar que los eventos de conmutación por error regionales no provoquen problemas de calidad de los datos.