OpenTelemetry en Moodle 5.2: cómo gobernar la telemetría en producción

Moodle 5.2 reduce mucho el esfuerzo necesario para producir trazas. La integración oficial crea un tramo raíz para las peticiones web y los comandos de consola, y añade instrumentación específica para tareas, eventos y llamadas a servicios web. Para obtener esa cobertura inicial no hace falta modificar el código del LMS. Hay que instalar la extensión de OpenTelemetry para PHP, el paquete de integración y un exportador, y configurar su conexión.

Con esto queda resuelta la generación de telemetría, pero la observabilidad exige algo más.

Observar una plataforma significa poder responder una pregunta operativa antes de que el daño se extienda: por qué no termina el envío de un cuestionario, dónde se acumula el cron, qué integración está agotando el tiempo de respuesta o si una nueva versión ha degradado un recorrido crítico. Conservar millones de tramos sin esas preguntas solo produce un almacén caro.

La tesis de esta guía es que OpenTelemetry debe implantarse en Moodle como una capacidad operativa gobernada, no como un exportador activado por defecto. La implantación necesita una frontera propia, un contrato de datos, una política de muestreo, recorridos prioritarios y pruebas de aceptación. Instalar los componentes es solo el primer paso y probablemente el menos importante.

La instrumentación produce datos sobre el sistema; la observabilidad los convierte en decisiones sobre el servicio que reciben alumnos y docentes.

La integración inicial de Moodle cubre trazas

OpenTelemetry puede representar trazas, métricas y registros, pero la integración documentada de Moodle 5.2 se centra en tramos de traza. Conviene fijar esa frontera porque la palabra «OpenTelemetry» invita a atribuir al paquete todo lo que permite el ecosistema.

La cobertura inicial es esta:

La documentación de usuario añade el enrutado —controlador y acción— a la cobertura automática. El detalle exacto de nombres y atributos puede cambiar con las versiones del paquete, de PHP y de Moodle. Por eso el inventario real no debe copiarse de un artículo: se obtiene en un entorno de prueba con las mismas versiones que producción.

También importa lo que no se puede deducir. Una traza puede mostrar cuánto tardó un envío, pero no prueba que el alumno aprendiera. Tampoco sustituye a las métricas de infraestructura, los registros de aplicación, las comprobaciones sintéticas ni la analítica del aprendizaje. Mezclar esos planos lleva a dos errores: pedir a la telemetría técnica conclusiones pedagógicas y creer que un backend de trazas reemplaza todo el sistema de monitorización.

La primera decisión consiste, por tanto, en definir el alcance de la señal: esta implantación empieza con trazas técnicas de Moodle. Las demás señales se integran después con sus propios contratos y responsables.

La arquitectura de producción necesita un colector intermedio

En una demostración se puede enviar OTLP directamente desde PHP al backend. En producción prefiero interponer un OpenTelemetry Collector cerca de Moodle. La propia documentación de OpenTelemetry lo recomienda para evitar que el proceso de la aplicación se ocupe de los reintentos, el envío por lotes, el cifrado o el filtrado de datos sensibles.

La separación crea cuatro zonas con responsabilidades distintas:

1. Moodle y PHP generan las trazas. La aplicación las produce y las entrega con rapidez, pero no decide qué proveedor retendrá los datos durante meses.
2. El colector de entrada protege la aplicación. Recibe OTLP en una red controlada, limita la memoria, agrupa los envíos y evita que una indisponibilidad aguas abajo se traslade sin control al LMS.
3. La capa de procesamiento aplica las políticas. Elimina los atributos prohibidos, normaliza los recursos, filtra el ruido y aplica la política de muestreo.
4. El backend permite investigar. Indexa, consulta, visualiza y conserva lo que ha superado la política, y puede cambiar sin obligar a instrumentar Moodle de nuevo.

El mero hecho de incluir un colector no aporta resiliencia. Hay que decidir qué ocurre cuando su cola se llena, cuánto tiempo reintenta, dónde descarta y cómo se notifican sus propios fallos. El procesador de muestreo en cola, por ejemplo, necesita mantener trazas en memoria hasta tomar una decisión. Si recibe más trazas de las que puede retener, puede descartarlas antes de evaluarlas. También hace falta vigilar el propio sistema de observabilidad.

Hay una prueba especialmente importante en PHP: apagar o aislar el backend de telemetría durante una prueba de carga y comprobar que la latencia del campus permanece dentro del límite acordado. Los exportadores de PHP pueden añadir latencia, y el colector cercano ayuda a reducirla; asumir que la telemetría no afecta al tiempo de respuesta sería una mala forma de estrenarla.

La configuración mínima es deliberadamente aburrida

La integración se instala fuera de la administración de Moodle. Requiere la extensión de PHP, el paquete de Moodle y un exportador. La configuración vive en php.ini o en variables de entorno, lo que la sitúa bajo la responsabilidad del equipo de plataforma:

pecl install opentelemetry
composer require moodlehq/moodle-package-otel
composer require open-telemetry/exporter-otlp

Un punto de partida hacia un colector por HTTP podría declarar, como mínimo:

OTEL_PHP_AUTOLOAD_ENABLED="true"
OTEL_SERVICE_NAME="moodle-campus"
OTEL_TRACES_EXPORTER="otlp"
OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf"
OTEL_EXPORTER_OTLP_ENDPOINT="http://otel-collector:4318"

Esta configuración no es una receta universal. Aún habría que definir la autenticación del transporte cuando corresponda, los atributos de recurso, los límites, la política de muestreo, la retención y la configuración del propio colector. El nombre lógico del servicio debería mantenerse estable entre pruebas y producción. El entorno se distingue con deployment.environment.name y la versión con service.version, como atributos de recurso controlados, para comparar despliegues sin fragmentar la identidad del servicio.

Moodle permite desactivar toda su integración con OTEL_PHP_DISABLED_INSTRUMENTATIONS=moodlelms y desactivar componentes concretos, como moodlelms.cronlistener. Esa opción es un freno de emergencia y una herramienta de diagnóstico, no el mecanismo habitual para controlar el coste. Si una tarea genera ruido, primero hay que entender si está revelando un problema de operación; silenciarla por defecto puede ocultarlo.

El control de cambios pertenece al mismo repositorio y al mismo proceso que el resto de la infraestructura. Una modificación del muestreo o de los atributos puede cambiar lo que el equipo será capaz de investigar en el próximo incidente. Por eso, cualquier cambio debe revisarse, probarse y poder revertirse.

Antes de muestrear hay que medir el flujo

El borrador habitual empieza por «guardemos un uno por ciento». Ese número carece de significado sin conocer el flujo de entrada y las preguntas que se quieren responder.

Durante un piloto acotado, mide al menos:

• peticiones y trazas por segundo en hora normal y en pico;
• número de tramos por traza en cada recorrido prioritario;
• tamaño serializado antes y después de procesar;
• proporción de errores y distribución de latencias;
• atributos con más valores distintos;
• memoria, CPU, colas, rechazos y retraso del colector;
• bytes ingeridos e indexados por el backend;
• tiempo de retención realmente necesario para investigar.

Con esos datos se puede construir un presupuesto. Una aproximación útil para el volumen diario exportado es:

trazas por día × tramos medios por traza × fracción retenida × bytes medios por tramo

Esta aproximación no equivale a la factura. El backend puede cobrar por ingesta, almacenamiento, indexación, consultas, réplicas o salida de red. La fórmula sirve para comparar políticas sobre datos propios, no para inventar un precio universal.

Volumen y cardinalidad exigen controles distintos

El volumen crece al generar más trazas o más tramos. La cardinalidad crece cuando un atributo admite muchos valores diferentes: identificadores de usuario, curso, intento o URL sin normalizar. En las métricas, una etiqueta de alta cardinalidad puede multiplicar las series. En las trazas, aumenta el espacio de búsqueda, la presión de indexación y el riesgo de incorporar datos personales, aunque el efecto económico concreto depende del backend.

Por eso no eliminaría todos los identificadores ni los conservaría todos. Mantendría solo los necesarios para una pregunta operativa legítima, transformados cuando sea posible y con acceso limitado. No incluiría nombres, correos, respuestas, calificaciones ni contenido de mensajes en atributos de telemetría. El identificador de traza sirve para correlacionar; no convierte el almacén de observabilidad en un expediente académico.

El colector puede eliminar, sustituir, transformar o filtrar atributos antes de exportarlos. Esa frontera es el lugar adecuado para aplicar el contrato, siempre que el dato no se haya enviado ya a una red o proceso indebido. La regla más segura sigue siendo no generarlo si no hace falta.

Cómo elegir una política de muestreo

El muestreo en cabeza decide al inicio si una traza se conserva. Es sencillo y eficiente, pero no conoce el resultado completo: por sí solo no garantiza que retenga todos los errores o las peticiones lentas. El muestreo en cola espera a recibir la mayor parte de la traza y puede tomar la decisión según el estado, la latencia o los atributos. A cambio, consume memoria, introduce estado y exige operar el componente que toma la decisión.

No hay una respuesta automática entre ambos. Utilizaría esta secuencia:

En Moodle añadiría criterios de dominio. Una petición lenta del catálogo y un fallo al cerrar un intento no tienen el mismo impacto. Una tarea programada rutinaria y de mucho volumen tampoco equivale a otra que publica calificaciones. El nombre del servicio y el entorno son atributos de recurso; el tipo de recorrido puede incorporarse mediante instrumentación adicional o reglas controladas, sin guardar el contenido educativo.

Una política razonable suele retener errores, latencias por encima de umbrales acordados, despliegues recientes y una muestra del tráfico sano. «Suele» importa: hasta medir el campus, sigue siendo una hipótesis. El porcentaje se recalcula con el volumen, los recursos disponibles y el presupuesto de cada instalación.

El piloto debe empezar por recorridos educativos

La instrumentación automática cubre muchos puntos de Moodle. El piloto, en cambio, debe seguir de extremo a extremo varios recorridos que el equipo de plataforma y los responsables del servicio reconozcan como críticos. Empezaría por cuatro:

1. Acceso en hora punta. Desde la entrada hasta la página operativa posterior al inicio de sesión, incluido un proveedor de identidad externo si propaga la traza.
2. Entrega de una evaluación. Desde la acción del usuario hasta que el sistema confirma que la entrega ha quedado guardada, con especial atención a reintentos y dependencias.
3. Cálculo o publicación de calificaciones. Tareas, bloqueos y colas que pueden retrasar la devolución al alumno.
4. Una integración institucional. Por ejemplo, matrícula o sincronización, para separar tiempo dentro de Moodle y tiempo en el sistema remoto. En una integración LTI, esta trazabilidad forma parte de la misma disciplina de operar LTI 1.3 en producción: correlacionar la experiencia visible con identidades, colas y dependencias reales.

Para cada recorrido hace falta una ficha breve:

Aquí aparece el límite de la instrumentación automática. Si la traza no se extiende hasta la confirmación que importa al usuario, hay que añadir instrumentación manual o una comprobación sintética. Si no propaga el identificador hacia una dependencia, la investigación quedará cortada. La cobertura se juzga por la pregunta que permite contestar, no por el número de tramos del panel.

Diez pruebas antes de llamarlo observable

La implantación debería superar una prueba de aceptación operativa, no solo mostrar una traza en Jaeger o en cualquier otro backend:

1. Una petición web y un comando CLI aparecen con el servicio, el entorno y la versión correctos.
2. Una tarea programada puede localizarse y distinguirse de una tarea ad hoc.
3. Una llamada a un servicio web conserva la relación entre la entrada a Moodle y la función externa sin exponer secretos.
4. Los atributos prohibidos no llegan al backend ni a los registros del colector.
5. Un error provocado se conserva según la política aprobada.
6. Una petición lenta provocada se conserva y puede localizarse por el recorrido afectado.
7. La pérdida temporal del backend no hace que el campus incumpla el objetivo de latencia acordado.
8. La saturación o descarte del colector genera una alerta propia y cuantificable.
9. Un despliegue puede compararse con el anterior sin mezclar entornos o versiones.
10. Una persona de guardia resuelve un escenario ensayado siguiendo el procedimiento de respuesta y deja evidencia de la decisión.

Si falla la cuarta prueba, hay un problema de gobierno del dato. Si falla la séptima, la observabilidad se ha convertido en dependencia crítica de la experiencia. Si falla la décima, existe telemetría, pero el equipo todavía no puede convertirla en una respuesta operativa.

Criterios para aprobar el despliegue

Moodle 5.2 ha hecho algo valioso: ofrece instrumentación oficial en puntos que antes exigían soluciones locales o investigación manual. Esto reduce el coste de entrada y facilita que una plataforma educativa deje de operar a base de intuiciones.

Pero no convierte una instalación en observable por sí sola. La arquitectura sigue teniendo que separar la generación, el gobierno y el análisis; medir el flujo antes de muestrear; proteger los datos del alumnado; dar prioridad a recorridos con impacto educativo y demostrar que el propio canal de telemetría resiste los fallos.

La decisión para llevar OpenTelemetry a producción debería formularse así: podemos investigar los recorridos críticos con evidencia suficiente, dentro de un presupuesto conocido y sin empeorar ni exponer la experiencia que queremos proteger.

Ese es el punto en el que la telemetría deja de ser otra colección de datos y pasa a ser ingeniería de plataforma.