For AI agents: fetch the complete documentation index at /llms.txt, the full documentation corpus at /llms-full.txt, the agent skill at /skill.md, or this page as Markdown at /es/docs/modules/observability.md (or send Accept: text/markdown).
Auditoría, analíticas y errores
Comprende la actividad con contexto de espacio y datos de eventos saneados.
Encuentre información útil cuando una acción falla
La observabilidad significa ver lo que hizo su aplicación. Comience con la terminal que ejecuta su servidor web: repita una acción fallida y lea el primer error y cualquier ID de correlación, una etiqueta que vincula los mensajes de la misma solicitud. Comparte el comando, tiempo y error de sanitizado al pedir ayuda; no comparta archivos o tokens .env.
Para informes de errores alojados, siga Estado y operaciones para configurar los ajustes de monitoreo admitidos en apps/web/.env.local o el panel de entorno del host. Guarde y reinicie el servidor. Desencadene una falla de prueba controlada en un entorno de prueba y confirme que aparece con el contexto del espacio de trabajo correcto. La supervisión configurada no prueba que haya recibido un evento.
ALERT_WEBHOOK_URL es un destino opcional HTTPS para alertas de fallas en la entrega de webhooks de trabajos y terminales. Si lo necesita, cree un punto final entrante compatible y guarde su URL en el lado del servidor; de lo contrario déjelo vacío. Pídale a un agente que simule una falla y confirme exactamente una alerta, sin secretos en su texto. No active trabajo remunerado ni fallas en las cuentas de los clientes para esta prueba.
Mantén un registro de auditoría del espacio de trabajo
Los registros de auditoría capturan cambios, como actualizaciones de configuración de proveedores dentro de un espacio de trabajo. Resuelve el espacio de trabajo autenticado antes de leer o escribir estos registros y conserva ese ámbito al añadir eventos específicos del producto.
Registra la acción y los identificadores necesarios para entenderla. Las credenciales de proveedores y otros valores sensibles deben permanecer fuera de las cargas de auditoría y los registros.
Captura eventos del producto
El paquete de observabilidad expone un adaptador AnalyticsClient y valores AnalyticsEvent con ámbito de espacio de trabajo. Cada evento contiene un nombre, identidad diferenciada, workspaceId y propiedades opcionales.
Usa createObservability para enrutar eventos mediante el cliente de analíticas configurado. Las propiedades estructuradas se redactan antes de la entrega; mantén el texto libre sensible fuera de los nombres de eventos y los valores de propiedades.
Informa de errores con contexto seguro
ErrorClient captura excepciones con etiquetas workspaceId y contexto adicional estructurado. La capa de observabilidad compartida sanea excepciones y redacta el contexto sensible antes de reenviarlo al cliente configurado.
Usa adaptadores locales para verificar eventos y excepciones capturados sin llamar a un proveedor de supervisión. Antes de habilitar un destino externo, prueba que las etiquetas del espacio de trabajo sigan presentes y que las credenciales se eliminen.
Sigue una solicitud a través de tareas, trabajos y webhooks
Los límites de entrada generan un ID de correlación corr_<uuid> que vincula la solicitud original con el trabajo que inicia. El envío de tareas de IA pone el ID en la carga de la tarea y el evento ai_task_submitted; cada receptor de webhook de facturación genera uno por solicitud y el programador genera uno por cada trabajo despachado.
El mismo ID se incluye en las propiedades de eventos job.completed y ai_task_completed, los datos adicionales de captureException, la carga del registro webhook_event y los metadatos de carga webhook_delivery: así llega dentro del cuerpo firmado que recibe quien se suscriba. Se admiten ID ausentes o mal formados: el consumidor crea uno nuevo en vez de rechazar filas anteriores.
Alerta ante fallos reales
Configura ALERT_WEBHOOK_URL con cualquier endpoint HTTPS que acepte un POST JSON con la forma {text, name, severity, context}; un webhook entrante de estilo Slack funciona tal cual. Las alertas se envían sin bloquear y con un tiempo de espera de cinco segundos; si falla la entrega, se registra una advertencia en consola y el alertador no hace nada si la variable no está configurada.
Las alertas incluidas son job.failed (warning: un controlador de trabajo lanzó un error o el tipo de trabajo es desconocido) y webhook.delivery_failed (critical: solo cuando una entrega saliente alcanza un fallo terminal tras el intento final; los reintentos normales no alertan y cada fila de entrega genera como máximo una alerta).
Mide duraciones y transmite registros estructurados
serverObservability.measure mide una operación asíncrona y emite un evento analítico <name>.duration con durationMs, tanto si tiene éxito como si falla, sin ocultar el error original. La ejecución del trabajo ai.task.execute ya está envuelta, así que su duración llega al cliente analítico configurado.
serverObservability.logger escribe una línea JSON por registro en stdout con campos base de entorno y servicio; la capa de redacción compartida elimina secretos antes de emitir cualquier línea.