Cómo usar los registros de depuración de Salesforce para depurar Apex (guía 2026)
Si tus registros de depuración de Salesforce no aparecen, son difíciles de leer o no incluyen la salida que necesitas, empieza aquí. Configurarás una marca de seguimiento, leerás un ejemplo de registro específico y usarás Apex Replay Debugger en VS Code para inspeccionar lo que ocurrió durante la ejecución.
El objetivo es responder una pregunta concreta: ¿qué hizo el código y en qué punto se desvió de lo que esperabas?
Dónde encontrar los registros de depuración de Salesforce
En Salesforce, abre Configuración, ingresa Registros de depuración en Búsqueda rápida y selecciona Registros de depuración. Para capturar una nueva transacción, crea una marca de seguimiento para el usuario que la ejecuta, reproduce el problema, actualiza la página y abre el registro resultante.
Si la lista está vacía, sigue las verificaciones para registros faltantes. Si primero necesitas configurar el registro, ve a configuración de marcas de seguimiento.
Por qué no aparecen tus registros de depuración de Salesforce
Revisa estos puntos antes de agregar más instrucciones de depuración:
| Verificación | Qué hacer |
|---|---|
| La marca de seguimiento venció o aún no está activa | Verifica las horas de inicio y vencimiento y reproduce el problema dentro de ese intervalo. El registro no reconstruye la actividad anterior. |
| Estás rastreando al usuario equivocado | Rastrea al usuario que realmente ejecuta la transacción. Puede ser un usuario de integración o de automatización, en lugar de tu propia cuenta. |
| Estás revisando la organización equivocada | Confirma que la acción y la marca de seguimiento correspondan al mismo sandbox o a la misma organización de producción. |
| La organización almacena más de 1,000 MB de registros de depuración | Elimina los registros que ya no necesites. Salesforce bloquea la creación o edición de marcas de seguimiento cuando se supera este umbral de almacenamiento. |
| La organización generó más de 1,000 MB en 15 minutos | Salesforce desactiva las marcas de seguimiento. Reduce el volumen de registros; Salesforce permite reactivar el seguimiento después de 15 minutos. |
Salesforce documenta ambos umbrales de almacenamiento y volumen en sus límites de registros de depuración. Para los suscriptores de eventos de plataforma que usan el usuario predeterminado Proceso automatizado, consulta las instrucciones de Salesforce sobre marcas de seguimiento para Proceso automatizado.
Cuando el registro existe, pero falta tu mensaje
Cada registro de depuración tiene un límite de 20 MB. Salesforce recorta los registros que superan ese tamaño, y las líneas eliminadas pueden provenir de distintas partes del registro, incluida la salida anterior de System.debug() Reduce el nivel de detalle y captura una reproducción más acotada antes de asumir que la instrucción nunca se ejecutó.
Revisa también el nivel de registro de Apex Code. Una llamada simple a System.debug(message) genera un evento de nivel DEBUG, por lo que una configuración INFO lo excluirá. Por último, confirma que la ruta de ejecución del código haya llegado a tu instrucción. Una condición, un retorno o una excepción anterior pueden explicar la ausencia del mensaje. Consulta la referencia de niveles de registro de Salesforce.
Configura una marca de seguimiento y un nivel de depuración
A marca de seguimiento le indica a Salesforce de quién capturar la actividad y cuándo. Un nivel de depuración controla la cantidad de detalle que se registra para cada categoría, como Apex Code, Database o Workflow.
- Ve a Configuración > Registros de depuración y haz clic en Nuevo para crear una marca de seguimiento.
- Elige Usuario como tipo de entidad con seguimiento y selecciona al usuario que reproducirá el problema.
- Configura un intervalo breve de inicio y vencimiento que cubra tu investigación.
- Selecciona o crea un nivel de depuración llamado ApexDebug. Comienza con Apex Code = DEBUG, Apex Profiling = INFO, y Database = INFO. Mantén las demás categorías en el nivel más bajo que resulte útil para el problema.
- Guarda, reproduce el problema una vez y actualiza la página de registros de depuración.
- Abre el registro que coincida con el usuario, la hora y la operación que acabas de probar.
Estos son los ajustes iniciales para el siguiente ejemplo. Aumenta el detalle de Workflow al investigar Flow, o el de Callout al investigar una solicitud externa. Consulta las instrucciones de configuración de registros de depuración de Salesforce para conocer los campos de configuración y los permisos necesarios.
Los niveles de registro, de menor a mayor detalle, son NONE, ERROR, WARN, INFO, DEBUG, FINE, FINER y FINEST. Una categoría incluye eventos del nivel seleccionado y de los niveles inferiores. Usa FINEST cuando necesites ver asignaciones de variables; genera mucha más información de la que requiere este ejemplo básico.
Cómo leer un registro de depuración de Salesforce
Comienza por el comportamiento que esperabas. En este ejemplo, insertar un Book con un precio de 100 debería aplicar un descuento del 10% y guardar un precio de 90.
Agrega una instrucción de diagnóstico que responda una pregunta
En un entorno de pruebas, usa un objeto personalizado llamado Book__c con un campo de moneda llamado Price__c. Este trigger de ejemplo registra el precio antes y después del cálculo y omite los registros sin precio:
trigger BookDiscount on Book__c (before insert) {
for (Book__c book : Trigger.new) {
if (book.Price__c == null) {
continue;
}
Decimal beforePrice = book.Price__c;
book.Price__c = beforePrice * 0.90;
System.debug(LoggingLevel.DEBUG,
'BookDiscount before=' + beforePrice +
' after=' + book.Price__c);
}
}La asignación del campo ocurre en un trigger de tipo before-insert, por lo que no necesita una instrucción de actualización aparte. En una aplicación existente, coloca los diagnósticos en el controlador del trigger correspondiente en lugar de agregar un segundo trigger solo para generar registros. Registra los valores necesarios para probar tu hipótesis; evita volcar registros completos o campos sensibles.
Lee un extracto específico del registro
Con el indicador de seguimiento activo, inserta un Book con un precio de 100. Este extracto abreviado e ilustrativo muestra los eventos que debes revisar. Su encabezado usa la versión 68.0 de la API de Winter '27; la versión de tu organización puede ser diferente.
68.0 APEX_CODE,DEBUG;APEX_PROFILING,INFO;DB,INFO
17:00:00.0 (100000) |EXECUTION_STARTED
17:00:00.0 (900000) |USER_DEBUG|[8]|DEBUG|BookDiscount before=100 after=90
17:00:00.1 (1000000) |CUMULATIVE_LIMIT_USAGE
17:00:00.1 (1000000) |LIMIT_USAGE_FOR_NS|(default)|
Number of SOQL queries: 0 out of 100
Number of DML statements: 0 out of 150
17:00:00.1 (1000000) |CUMULATIVE_LIMIT_USAGE_END
17:00:00.1 (1100000) |EXECUTION_FINISHEDEl encabezado identifica la versión de la API y los ajustes de las categorías. Te ayuda a comprobar si el registro capturó suficiente detalle para la pregunta que estás investigando.
El USER_DEBUG línea se desglosa así:
| Parte | Significado |
|---|---|
17:00:00.0 | Marca de tiempo del evento. |
(900000) | Tiempo transcurrido en nanosegundos desde que comenzó la ejecución. No es el consumo de CPU de la transacción. |
USER_DEBUG | Un evento de diagnóstico generado por System.debug(). |
[8] | La línea de origen que generó el evento. |
DEBUG | El nivel de registro del mensaje. |
| BookDiscount before=100 after=90 | El mensaje de diagnóstico y los valores que elegiste registrar. |
El marcadores de ejecución delimitan la ejecución representada por el registro. En un registro más completo, CODE_UNIT_STARTED y CODE_UNIT_FINISHED te ayudan a localizar triggers y otras unidades de trabajo. Salesforce explica el formato en Detalles del registro de depuración.
El resumen de límites informa el uso de recursos en relación con los límites aplicables. Aquí, el trigger en sí no realiza consultas SOQL ni instrucciones DML. Los dos límites del ejemplo no constituyen una lista completa y los límites varían según el contexto de ejecución; revisa los valores informados para tu transacción.
Encuentra el evento relevante antes de leer las líneas que lo rodean
| Qué estás investigando | Busca |
|---|---|
| Tu salida de diagnóstico | USER_DEBUG o el prefijo de tu mensaje |
| Una excepción lanzada | EXCEPTION_THROWN |
| Un error que terminó la ejecución | FATAL_ERROR |
| Consultas repetidas a la base de datos | SOQL_EXECUTE_BEGIN y SOQL_EXECUTE_END |
| Consumo de límites de ejecución | LIMIT_USAGE_FOR_NS |
Una entrada de EXCEPTION_THROWN puede describir una excepción que se capturó más adelante. Lee los eventos que la rodean y el resultado antes de considerarla la causa de la falla. La referencia de eventos de Salesforce enumera la categoría y el nivel mínimo de cada evento.
Usa la evidencia para acotar la causa
Si el mensaje muestra que 100 pasa a 90, ese cálculo se comportó como se esperaba. Si el registro guardado contiene un valor diferente, revisa las automatizaciones posteriores y cualquier transacción independiente que pueda actualizarlo. Si el mensaje nunca aparece, vuelve a las comprobaciones de registro antes de cambiar la lógica de descuento.
Una vez que encuentres la causa, agrega una prueba de regresión que verifique el valor guardado esperado. Prueba también los casos de precio faltante y múltiples registros; luego elimina los diagnósticos temporales o redúcelos al nivel de detalle que tu equipo necesita.
Depura Apex en VS Code
Usa Apex Replay Debugger cuando un registro de texto dificulte seguir la ruta de ejecución. Reproduce los eventos registrados y permite inspeccionar el código fuente y las variables. No pausa una transacción activa de Salesforce y no requiere una licencia adicional de depuración.
| Herramienta | Dónde | Cómo funciona | Puntos de interrupción | Ten en cuenta | Úsalo cuando |
|---|---|---|---|---|---|
| Apex Replay Debugger | VS Code | Reproduce un registro capturado | Sí, en la reproducción | Un registro a la vez | Es difícil seguir la ruta de ejecución |
| Apex Interactive Debugger | VS Code | Pausa una transacción activa | Sí, en vivo | Las licencias varían según la edición | Necesitas detenerte a mitad de una transacción |
sf apex tail log | Terminal | Transmite registros a medida que llegan | No | Solo rastrea al usuario que inició sesión | Quieres ver registros mientras haces pruebas |
| Puntos de control de Developer Console | Navegador | Captura la memoria, nunca pausa | Hasta 5 puntos de control | Ocultos de forma predeterminada en Winter '27 | Tu equipo ya trabaja allí |
Reproduce la transacción
Instala Salesforce CLI y Salesforce Extension Pack para VS Code. Abre un proyecto de Salesforce DX, autoriza la organización de destino y asegúrate de que tu código fuente local de Apex coincida con el código que generó el registro.
- En la paleta de comandos de VS Code, ejecuta SFDX: Turn On Apex Debug Log for Replay Debugger.
- Reproduce el problema en la organización de destino.
- Ejecuta SFDX: Get Apex Debug Logs, luego selecciona el registro correspondiente.
- Con ese registro abierto, ejecuta SFDX: Launch Apex Replay Debugger with Current File.
- Establece puntos de interrupción en el código fuente correspondiente y usa los controles de depuración para recorrer paso a paso la ejecución registrada e inspeccionar las variables.
Para obtener más detalles de las variables, agrega puntos de control al código fuente de Apex y ejecuta SFDX: Update Checkpoints in Org antes de generar un nuevo registro. Vuelve a cargarlos después de cambiar el código o la ubicación de los puntos de control.
Replay procesa un registro a la vez, por lo que el trabajo asíncrono que genera varios registros requiere una inspección por separado. Salesforce también documenta las limitaciones de las colecciones, las expresiones y los registros compatibles en la guía de Replay Debugger.
Transmite registros desde Salesforce CLI
Si quieres ver registros en tu terminal, usa:
sf apex tail log --target-org my-sandbox --debug-level ApexDebug --colorReemplaza my-sandbox por el alias de tu organización autorizada. ApexDebug debe ser el nombre de desarrollador de un nivel de depuración existente, como el que creaste antes. Este comando configura el registro de depuración para el usuario autenticado y muestra los registros a medida que están disponibles; para rastrear a otro usuario, sigue siendo necesaria la marca de rastreo de ese usuario.
Detén la transmisión con Ctrl+Cy finaliza el rastreo cuando termines la investigación. Consulta la referencia de transmisión de registros de CLI.
Para usar puntos de interrupción en vivo, Salesforce también ofrece Apex Interactive Debugger en sandboxes y organizaciones temporales compatibles. Las licencias varían según la edición; compara las opciones en la descripción general de los depuradores de Apex. Los usuarios de JetBrains también pueden usar Illuminated Cloud, que ofrece herramientas de depuración de Apex.
Usa puntos de control en la Consola de desarrollador
La Consola de desarrollador sigue siendo útil si tu equipo ya usa su flujo de trabajo en el navegador. Un punto de control captura objetos en memoria en un momento específico, lo que puede ayudarte a inspeccionar un valor sin agregar otra instrucción de depuración.
En Winter '27, la Consola de desarrollador está oculta en el menú Configuración de forma predeterminada. Para restaurarla, ingresa Desarrollo en Búsqueda rápida de Configuración, selecciona Consola web, y establece Habilitar Consola de desarrollador para Activo. La nueva Consola web de Salesforce también admite indicadores de seguimiento y registros de depuración; consulta la guía para desarrolladores de Winter '27.
Para capturar un punto de control en la Consola de desarrollador:
- Abre la clase o el desencadenador en la Consola de desarrollador. Para establecer puntos de control, necesitas Ver todos los datos.
- Usa Depurar > Cambiar niveles de registro para verificar un indicador de seguimiento DEVELOPER_LOG para tu usuario. Establece el nivel de Apex Code en FINER o FINEST para depurar con puntos de control.
- Haz clic en el margen junto a la línea ejecutable que quieras inspeccionar.
- Mantén abierta la Consola de desarrollador y reproduce la transacción.
- Abre la pestaña Puntos de control y haz doble clic en el resultado para inspeccionarlo.
Puedes habilitar hasta cinco puntos de control. De forma predeterminada, cada uno realiza una captura inmediatamente antes de la primera ejecución de su línea, una sola vez y no en cada iteración del bucle. Ajusta la iteración de captura en Ubicaciones de puntos de control si es necesario. Los puntos de control capturan el estado sin detener la ejecución.
Salesforce explica el comportamiento de las capturas en Establecer puntos de control en código Apex y la configuración de registro en Pestaña Registros.
Descarga y elimina registros de depuración de forma masiva
Para descargar los diez registros más recientes en una carpeta local, ejecuta:
sf apex get log --target-org my-sandbox --number 10 --output-dir ./debug-logsUsa --log-id en lugar de --number cuando necesites un registro específico. La referencia de descarga de Salesforce describe ambas opciones.
Para eliminar registros seleccionados de forma masiva, abre el Editor de consultas, selecciona Usar Tooling API, y ejecuta:
SELECT Id, StartTime, LogUserId, LogLength, Location
FROM ApexLog
ORDER BY StartTime DESCRevisa los resultados, selecciona los registros que ya no necesites y haz clic en Eliminar fila. Primero, guarda los registros necesarios para cualquier investigación en curso. Esto elimina registros de depuración, no registros de negocio; Salesforce documenta el proceso en Eliminar registros de depuración.
Preguntas frecuentes sobre los registros de depuración de Salesforce
¿Por qué no aparecen mis registros de depuración de Salesforce?
Primero, revisa el período de vigencia del indicador de seguimiento, el usuario que ejecuta la acción y la organización que estás viendo. Luego, verifica los límites de almacenamiento y volumen de registros en solución de problemas de registros faltantes.
¿Cuál es el tamaño máximo de un registro de depuración de Salesforce?
Cada registro de depuración tiene un límite de 20 MB; Salesforce recorta los registros que lo superan. Consulta mensajes de depuración faltantes para saber por qué puede desaparecer parte del contenido.
¿Cuánto dura un indicador de seguimiento?
Un indicador de seguimiento dura hasta la fecha y hora de vencimiento configuradas; Tooling API exige que venza menos de 24 horas después de su inicio. Esto es independiente de la retención de registros: los registros del sistema duran 24 horas y los de monitoreo, siete días, así que consulta la configuración de marcas de seguimiento y la referencia de TraceFlag de Salesforce.
¿Cómo descargo o elimino registros de depuración de forma masiva?
Usa sf apex get log con --number y --output-dir para descargar varios registros recientes. Para eliminarlos, selecciona los registros ApexLog que quieras en los resultados de la consulta de Tooling API en la Consola de desarrollador, como se muestra en gestión masiva de registros.
¿Puedo depurar Apex con puntos de interrupción en Salesforce?
Sí: Replay Debugger usa puntos de interrupción al reproducir un registro capturado, e Interactive Debugger permite depurar en tiempo real en entornos compatibles con la licencia adecuada. Consulta depuración en VS Code para elegir el flujo de trabajo adecuado.
¿Encontraste el error?
Blue Canvas mantiene un historial de Git de los cambios de Apex en tus organizaciones conectadas, para que puedas revisar qué cambió antes de que algo fallara.
Descubre cómo funciona el control de versiones de Salesforce
