T5.1: Uses Troubleshooting Tools

Descripción General

InterSystems IRIS proporciona un conjunto completo de herramientas de monitoreo de rendimiento, desde paneles generales a nivel del sistema hasta perfiladores detallados línea por línea. La elección de la herramienta adecuada depende de si se está investigando un cuello de botella a nivel del sistema, una consulta SQL lenta o una rutina ObjectScript específica.

Uso de $ZH para Medir Tiempos de Código

La forma más simple y directa de medir el rendimiento es usando la variable especial $ZH, que devuelve la marca de tiempo actual como un número de punto flotante de alta resolución en segundos. Al capturar $ZH antes y después de un bloque de código, se puede calcular el tiempo transcurrido con precisión inferior al milisegundo.

ClassMethod TimedOperation() As %String
{
    Set start = $ZH

    // Code to measure
    For i = 1:1:100000 {
        Set ^TempData(i) = $RANDOM(1000000)
    }

    Set elapsed = $ZH - start
    Write "Elapsed time: ", elapsed, " seconds", !
    Return elapsed
}

Para comparar dos enfoques:

ClassMethod CompareApproaches()
{
    // Approach 1: String concatenation
    Set start1 = $ZH
    Set str = ""
    For i = 1:1:10000 {
        Set str = str _ "X"
    }
    Set time1 = $ZH - start1

    // Approach 2: $JUSTIFY pre-allocation
    Set start2 = $ZH
    Set str = $JUSTIFY("", 10000)
    Set str = $TRANSLATE(str, " ", "X")
    Set time2 = $ZH - start2

    Write "Concatenation: ", time1, " seconds", !
    Write "$JUSTIFY:       ", time2, " seconds", !
}

Monitor de Rendimiento del Sistema ^%PERFMON

La utilidad ^%PERFMON es un monitor de rendimiento a nivel del sistema que recopila métricas como referencias a globales, llamadas a rutinas, líneas ejecutadas y otros contadores. Se ejecuta como un proceso en segundo plano con intervalos de muestreo configurables.

// Start the performance monitor (from Terminal)
Do ^%PERFMON

// Programmatic control
// Start collecting with 5-second sample interval
Do Start^%PERFMON(5)

// Let it run for a period...
Hang 60

// Stop collecting
Do Stop^%PERFMON

// Display collected results
Do Report^%PERFMON

Métricas clave capturadas por ^%PERFMON incluyen:

• GloRef: Número de referencias a globales (lecturas y escrituras)
• GloSet: Número de operaciones SET sobre globales
• GloKill: Número de operaciones KILL sobre globales
• RouLine: Líneas de ObjectScript ejecutadas
• RouLoad: Número de cargas de rutinas desde disco a caché

%SYS.PTools para Rendimiento SQL

El paquete %SYS.PTools proporciona análisis de rendimiento de consultas SQL. Captura planes de ejecución, tiempos y estadísticas de las consultas SQL.

// Enable SQL statistics collection
Do ##class(%SYS.PTools.SQLStats).SetSQLStatsJob(3)

// Execute your SQL queries...
Set rs = ##class(%SQL.Statement).%ExecDirect(,
    "SELECT Name, DOB FROM Sample.Person WHERE Age > 50")

// View collected statistics
Do ##class(%SYS.PTools.SQLStats).DisplayStats()

// Disable collection
Do ##class(%SYS.PTools.SQLStats).SetSQLStatsJob(0)

También se pueden analizar los planes de consulta directamente:

// Show the query plan for a specific query
Set stmt = ##class(%SQL.Statement).%New()
Set sc = stmt.%Prepare("SELECT Name FROM Sample.Person WHERE SSN = ?")
Do stmt.%ShowPlan()

Monitoreo Línea por Línea con ^MONLBL

La utilidad ^MONLBL proporciona perfilado de ejecución línea por línea, mostrando exactamente cuántas veces se ejecutó cada línea y cuánto tiempo tardó cada una. Esto es invaluable para identificar puntos calientes dentro de una rutina.

// Start line-by-line monitoring for a specific routine
Do Start^%MONLBL("MyApp.MyClass.1")

// Execute the code you want to profile
Do ##class(MyApp.MyClass).MyMethod()

// Stop monitoring
Do Stop^%MONLBL

// Display results - shows each line with execution count and time
Do Report^%MONLBL

La salida del informe muestra columnas para:

• Line: La línea de código fuente
• Count: Número de veces que se ejecutó la línea
• Total Time: Tiempo acumulado gastado en la línea
• Average Time: Tiempo promedio por ejecución

Páginas de System Operation del Management Portal

El Management Portal proporciona varias páginas clave bajo System Operation:

• System Dashboard: Vista general en tiempo real de CPU, memoria, disco y utilización de caché
• Processes: Lista de todos los procesos activos con tiempo de CPU, estado, namespace y rutina actual
• Locks: Tabla de bloqueos actual mostrando todos los bloqueos retenidos y cualquier conflicto de bloqueo
• Task Manager: Tareas programadas y en ejecución con historial de ejecución
• System Usage: Desglose detallado del consumo de recursos

Navegar a: System Operation > System Dashboard para la vista general principal. Desde la página Processes, se puede profundizar en procesos individuales para ver su pila de llamadas, variables y uso de recursos.

Descripción General

La compilación de clases en InterSystems IRIS involucra múltiples fases: preprocesamiento de macros, análisis de sintaxis, generación de código y compilación final de las rutinas intermedias generadas. Los errores pueden ocurrir en cualquier fase, y comprender qué fase produjo un error es crítico para diagnosticar el problema.

Errores Comunes de MPP (Macro Pre-Processor)

Los errores de MPP ocurren antes de que el código ObjectScript sea analizado. Se relacionan con macros, directivas #Include e instrucciones del preprocesador.

"Referenced macro not defined" - Este error ocurre cuando el código usa una macro ($$$MacroName) que el compilador no puede encontrar:

// ERROR: Missing #Include
Class MyApp.Example Extends %Persistent
{
    Method Save() As %Status
    {
        Set sc = ..%Save()
        // ERROR: $$$ISERR is defined in %occStatus.inc
        // but we forgot to include it
        If $$$ISERR(sc) {
            Write "Error!", !
        }
    }
}

Solución: Agregar la directiva #Include apropiada al inicio de la clase:

Include %occStatus

Class MyApp.Example Extends %Persistent
{
    Method Save() As %Status
    {
        Set sc = ..%Save()
        If $$$ISERR(sc) {
            Write "Error!", !
        }
    }
}

Para múltiples archivos de inclusión:

Include (%occStatus, %occErrors, MyApp.Macros)

Class MyApp.Example Extends %Persistent
{
    // Can now use macros from all three include files
}

Errores de Carácter Inválido

Estos típicamente surgen de caracteres Unicode invisibles introducidos al copiar y pegar desde páginas web, procesadores de texto o editores externos:

// ERROR: "Invalid character" - smart quotes instead of regular quotes
Set name = "John"    // Uses Unicode curly quotes (U+201C, U+201D)

// FIX: Use standard ASCII quotes
Set name = "John"    // Uses standard double quotes (U+0022)

Causas comunes:

• Comillas tipográficas (\u201c \u201d en lugar de ")
• Guion medio o guion largo (\u2013 o \u2014 en lugar de -)
• Espacios de no separación (U+00A0 en lugar de espacio regular)
• Caracteres de ancho cero

Orden de Compilación de Dependencias

Cuando las clases se referencian entre sí, el orden de compilación importa. Si la Clase A extiende la Clase B, entonces la Clase B debe compilarse primero.

// Class B must be compiled BEFORE Class A
Class MyApp.Base Extends %Persistent
{
    Property Name As %String;
}

Class MyApp.Child Extends MyApp.Base
{
    Property Age As %Integer;
}

Compilar con verificación de dependencias:

// Compile a single class with dependency checking
Do $SYSTEM.OBJ.Compile("MyApp.Child", "ck")

// Compile an entire package (handles dependencies automatically)
Do $SYSTEM.OBJ.CompilePackage("MyApp", "ck")

// Compile all classes in namespace
Do $SYSTEM.OBJ.CompileAll("ck")

Referencia de indicadores de compilación:

• c: Compilar
• k: Conservar código fuente generado (útil para depuración)
• d: Mostrar salida de compilación
• b: Incluir subclases
• u: Actualizar solamente (omitir clases sin cambios)

Diagnóstico de Errores de Compilación en la Práctica

// Capture compilation status programmatically
Set sc = $SYSTEM.OBJ.Compile("MyApp.Problem", "ck")
If $$$ISERR(sc) {
    // Display the full error text
    Do $SYSTEM.Status.DisplayError(sc)
}

// View errors in the Management Portal:
// System Explorer > Classes > select class > Compile
// Errors appear in the Output pane

Patrones comunes de errores de compilación y sus causas:

Mensaje de Error	Causa Probable
"Referenced macro not defined"	#Include faltante o error tipográfico en el nombre de la macro
"Invalid character"	Caracteres no ASCII por copiar y pegar
"Class 'X' does not exist"	Dependencia no compilada o error tipográfico en el nombre de clase
"Method 'X' does not exist in class 'Y'"	Nombre de método incorrecto o clase no recompilada
"Property 'X' does not exist"	Error tipográfico en nombre de propiedad o referencia a clase incorrecta
"Datatype class 'X' does not exist"	Clase de tipo de datos faltante o mal escrita