T2.2: Tracks Application Data

Comprender la estructura de globals

Los globals son arrays multidimensionales dispersos y jerárquicos almacenados en disco. Persisten entre procesos y reinicios del sistema. Cada clase persistente almacena sus datos en globals -- entender la estructura subyacente de globals es esencial para la depuración y el análisis de rendimiento.

 // Establecer nodos de global
 SET ^Customer(1, "Name") = "John Smith"
 SET ^Customer(1, "Email") = "john@example.com"
 SET ^Customer(2, "Name") = "Jane Doe"
 SET ^Customer(2, "Email") = "jane@example.com"

 // Mostrar todo el árbol del global
 ZWRITE ^Customer
 // Salida:
 // ^Customer(1,"Email")="john@example.com"
 // ^Customer(1,"Name")="John Smith"
 // ^Customer(2,"Email")="jane@example.com"
 // ^Customer(2,"Name")="Jane Doe"

Navegar globals con $ORDER

$ORDER devuelve el siguiente subíndice en un nivel dado, permitiendo el recorrido de nodos de global:

 // Iterar a través de todos los IDs de clientes
 SET id = ""
 FOR {
     SET id = $ORDER(^Customer(id))
     QUIT:id=""
     WRITE "Customer ", id, ": ", ^Customer(id, "Name"), !
 }

Usar $DATA para verificar la existencia de nodos

$DATA devuelve un valor que indica si un nodo existe y/o tiene hijos:

• 0 = el nodo no existe y no tiene descendientes
• 1 = el nodo existe pero no tiene descendientes
• 10 = el nodo no existe pero tiene descendientes
• 11 = el nodo existe Y tiene descendientes

 IF $DATA(^Customer(1)) {
     WRITE "Customer 1 exists", !
 }
 // Usar $DATA para verificar antes de acceder
 IF $DATA(^Config("settings", "timeout"))#2 {
     SET timeout = ^Config("settings", "timeout")
 }

Visor de globals del Portal de Administración

Navegar a System Explorer > Globals para examinar, buscar y editar globals. Puede:

• Ver globals en todos los namespaces
• Filtrar por prefijo de nombre de global
• Profundizar en niveles de subíndices
• Exportar e importar datos de globals
• Eliminar globals o nodos individuales

Localizar globals de datos de clase

Las clases persistentes almacenan datos en globals nombrados según la clase. Use la definición de almacenamiento en Studio/VS Code para encontrar el nombre exacto del global:

 // Para la clase MyApp.Customer, los datos típicamente están en:
 // ^MyApp.CustomerD (global de datos)
 // ^MyApp.CustomerI (global de índices)
 // ^MyApp.CustomerS (contador de secuencia)
 ZWRITE ^MyApp.CustomerD

^%ISCLOG: Logging de diagnóstico integrado

^%ISCLOG es una facilidad de logging de diagnóstico utilizada por el código del framework de InterSystems — gateway CSP, servicios web, producciones de Interoperability y otros componentes del sistema. Normalmente no se llama directamente desde el código de aplicación; en su lugar, el código del sistema llama a las macros $$$ISCLOG y $$$SysLog (definidas en %occDiagnostics.inc) para generar entradas de log.

Cómo funciona:

• El global ^%ISCLOG (valor de nivel superior) controla el nivel de logging: 0=deshabilitado, 1=solo errores, 2=advertencias y errores, 3=todos los mensajes (más detallado)
• Las entradas de log se escriben en el global ^ISCLOG (sin el prefijo %) en el namespace %SYS
• Las entradas se pueden ver usando la clase %Library.SysLog o haciendo ZWRITE ^ISCLOG en el namespace %SYS

 // Habilitar logging de diagnóstico en máxima verbosidad
 SET ^%ISCLOG = 3

 // Opcionalmente limitar el tamaño del log (por defecto es ilimitado)
 SET ^%ISCLOG("MaxLogEntries") = 10000

 // Después de la resolución de problemas, deshabilitar el logging (impacta el rendimiento cuando está habilitado)
 SET ^%ISCLOG = 0

 // Ver entradas de log — cambiar al namespace %SYS primero
 ZN "%SYS"
 ZWRITE ^ISCLOG

 // O usar la clase %Library.SysLog para consultar entradas programáticamente
 SET rs = ##class(%Library.SysLog).FindAll()
 WHILE rs.%Next() {
     WRITE rs.%Get("TimeStamp"), " ", rs.%Get("Message"), !
 }

Importante: Recuerde establecer ^%ISCLOG a 0 después de la resolución de problemas, ya que el logging detallado consume espacio en disco e impacta el rendimiento.

Construir logs de aplicación personalizados

Para logging específico de la aplicación, cree globals estructurados con marcas de tiempo, severidad y contexto. A diferencia de ^%ISCLOG (que es para diagnósticos del sistema/framework), los globals de logging personalizados le dan control total sobre lo que su aplicación registra:

ClassMethod Log(level As %String, message As %String, context As %String = "")
{
    SET seq = $INCREMENT(^MyApp.Log)
    SET ^MyApp.Log(seq) = $LISTBUILD(
        $ZTIMESTAMP,
        level,
        $USERNAME,
        $JOB,
        context,
        message
    )
    // También mantener un índice basado en fecha para recuperación eficiente
    SET date = +$HOROLOG
    SET ^MyApp.Log("date", date, seq) = ""
}

 // Uso
 DO ##class(MyApp.Logger).Log("INFO", "Order created", "OrderId=1234")
 DO ##class(MyApp.Logger).Log("ERROR", "Payment failed: timeout", "OrderId=1234")

Recuperar y analizar datos de log

 // Iterar a través de entradas de log recientes
 SET id = ""
 FOR {
     SET id = $ORDER(^MyApp.Log(id), -1)  // Orden inverso (más reciente primero)
     QUIT:id=""
     SET entry = ^MyApp.Log(id)
     SET timestamp = $LISTGET(entry, 1)
     SET level = $LISTGET(entry, 2)
     SET message = $LISTGET(entry, 6)
     WRITE id, " [", level, "] ", message, !
 }

Logging basado en archivos

Para integración con sistemas externos de gestión de logs, escribir en archivos:

 SET file = ##class(%Library.File).%New("/var/log/myapp/application.log")
 DO file.Open("WSA")   // Write, Stream, Append
 DO file.WriteLine($ZDATETIME($ZTIMESTAMP, 3, 1) _ " [INFO] Application started")
 DO file.Close()

Métricas a nivel de proceso con $SYSTEM.Process

$SYSTEM.Process proporciona acceso a contadores detallados de rendimiento del proceso:

 // Obtener el conteo de referencias a globals del proceso actual
 WRITE $SYSTEM.Process.GlobalReferences(), !

 // Obtener líneas de ObjectScript ejecutadas
 WRITE $SYSTEM.Process.LinesExecuted(), !

 // Obtener conteo de lecturas de disco
 WRITE $SYSTEM.Process.DiskReadCount(), !

 // Medir el rendimiento de un bloque de código
 SET startGref = $SYSTEM.Process.GlobalReferences()
 SET startLines = $SYSTEM.Process.LinesExecuted()
 SET startTime = $ZHOROLOG  // Marca de tiempo de alta precisión

 // ... código siendo medido ...
 DO ##class(MyApp.DataLoader).ProcessBatch()

 SET elapsedTime = $ZHOROLOG - startTime
 SET globalRefs = $SYSTEM.Process.GlobalReferences() - startGref
 SET linesExec = $SYSTEM.Process.LinesExecuted() - startLines

 WRITE "Time: ", elapsedTime, " seconds", !
 WRITE "Global refs: ", globalRefs, !
 WRITE "Lines executed: ", linesExec, !

Uso de ^IRIS.Temp para métricas transitorias

Los globals ^IRIS.Temp residen en la base de datos IRISTEMP, que nunca se registra en el journal. Esto los hace ideales para almacenar contadores de rendimiento y métricas temporales sin impactar el rendimiento de transacciones ni el volumen del journal:

 // Rastrear conteos de llamadas API por endpoint
 SET ^IRIS.Temp.Metrics("API", endpoint, $PIECE($HOROLOG, ",", 1)) =
     $INCREMENT(^IRIS.Temp.Metrics("API", endpoint, $PIECE($HOROLOG, ",", 1)))

 // Rastrear tiempos de ejecución de métodos
 SET startTime = $ZHOROLOG
 // ... ejecución del método ...
 SET elapsed = $ZHOROLOG - startTime
 SET ^IRIS.Temp.Metrics("Timing", methodName, $JOB) = elapsed

Estadísticas de rendimiento SQL

Use $SYSTEM.SQL.Stats para analizar el rendimiento de consultas SQL:

 // Obtener estadísticas SQL
 DO $SYSTEM.SQL.Stats.DisplayStats()

 // Para una consulta específica, examinar el plan de consulta
 SET stmt = ##class(%SQL.Statement).%New()
 SET sc = stmt.%Prepare("SELECT * FROM MyApp.Customer WHERE State = ?")
 DO stmt.%ShowPlan()

Monitoreo línea por línea

Habilitar monitoreo línea por línea para profiling de ejecución de código:

 // Habilitar monitoreo para una rutina
 DO $SYSTEM.Monitor.LineLevelMonStart("MyApp.DataLoader")

 // Ejecutar el código
 DO ##class(MyApp.DataLoader).ProcessBatch()

 // Detener el monitoreo y ver resultados
 DO $SYSTEM.Monitor.LineLevelMonStop()

 // Resultados almacenados en ^%SYS.MONLBL
 ZWRITE ^%SYS.MONLBL

Construir un panel de rendimiento

Combinar métricas para una vista integral:

ClassMethod CollectMetrics() As %Status
{
    SET timestamp = $ZTIMESTAMP
    SET metrics = $LISTBUILD(
        $SYSTEM.Process.GlobalReferences(),
        $SYSTEM.Process.LinesExecuted(),
        $SYSTEM.Process.DiskReadCount(),
        $SYSTEM.Process.JournalEntryCount()
    )
    SET ^IRIS.Temp.PerfLog($INCREMENT(^IRIS.Temp.PerfLog)) =
        $LISTBUILD(timestamp) _ metrics
    RETURN $$$OK
}