T3.3: Uses PTools for Performance Analysis

Resumen de Métricas PTools

El SQL Performance Analysis Toolkit (PTools) proporciona tres métricas de rendimiento primarias que distinguen diferentes aspectos de comportamiento de ejecución de consulta. Comprender estas métricas es esencial para diagnosticar cuellos de botella de rendimiento y optimizar consultas SQL.

Tiempo (Time Spent)

Tiempo representa la métrica de rendimiento general, medida en segundos, indicando la duración total de ejecución de consulta. Esta métrica se recolecta a diferentes niveles dependiendo de la opción Action: opción Action 2 registra estadísticas solo para el loop externo de la consulta (recolectando estadísticas en la apertura y cierre de la consulta, que es la suma del tiempo total para realizar todas las invocaciones de OPEN, FETCH, y CLOSE), mientras opción Action 3 registra estadísticas para todos los niveles de módulo de la consulta. Cuando los módulos están anidados, las estadísticas del módulo MAIN son números inclusivos representando los resultados generales para la consulta completa.

Referencias Globales (Global Refs)

Global References mide el número de accesos de variable global hechos a la base de datos durante ejecución de consulta. Dado que InterSystems IRIS almacena datos persistentes en globals, esta métrica se correlaciona directamente con actividad I/O de base de datos. Un número alto de referencias globales puede indicar patrones de acceso a datos ineficientes, índices faltantes, o planes de consulta pobremente optimizados. Esta métrica es particularmente valiosa para identificar consultas que realizan full table scans en lugar de index scans.

Comandos (Commands Executed)

Commands rastrea el número de líneas de código ObjectScript ejecutadas durante procesamiento de consulta. Esta métrica refleja la complejidad computacional del plan de ejecución de consulta. Conteos de comando más altos pueden indicar lógica de consulta compleja, múltiples iteraciones de loop, o rutas de ejecución ineficientes. Cuando se combina con métricas Time y Global Refs, Commands ayuda a distinguir entre operaciones ligadas a CPU (alto Commands, bajo Global Refs) y operaciones ligadas a I/O (alto Global Refs, Commands más bajo relativo a tiempo).

Read Latency y Visualización de Estadísticas

El framework PTools también proporciona Read Latency medido en milisegundos, que específicamente rastrea tiempo de espera de disco y ayuda a identificar cuellos de botella I/O. Estas estadísticas se muestran para Query Totals y para cada módulo de Query plan cuando se usa la característica Alternate Show Plans con opción "Compare Show Plans with Stats". El parámetro opción Collect (valor predeterminado 15 = 1 + 2 + 4 + 8) controla qué estadísticas de rendimiento específicas se recolectan, permitiendo recolección selectiva basada en requisitos de análisis.

La API %SYSTEM.SQL.PTools

La clase %SYSTEM.SQL.PTools proporciona la API preferida para invocar funcionalidad del SQL Performance Analysis Toolkit a través de ObjectScript. Esta interfaz reagrupa y reorganiza funcionalidad implementada en métodos de las clases base %SYS.PTools, proporcionando una interfaz más limpia e intuitiva para desarrolladores y administradores de base de datos.

Métodos de Alcance de Recolección

El toolkit ofrece múltiples métodos para iniciar recolección de estadísticas de rendimiento en diferentes alcances:

• setSQLStatsFlag(): Activa recolección para el sistema entero, afectando todos los namespaces y procesos
• setSQLStatsFlagByNS(): Habilita recolección de estadísticas para un namespace específico, permitiendo análisis dirigido sin impacto de rendimiento a nivel de sistema
• setSQLStatsFlagJob(): Activa recolección para el proceso o trabajo actual, haciéndolo ideal para analizar flujos de trabajo de aplicación específicos
• setSQLStatsFlagByPID(): Permite activación para un proceso o trabajo especificado por Process ID, con manejo especial: si el primer parámetro no se especifica, se especifica como $JOB, o se especifica como cadena vacía (""), invoca setSQLStatsFlagJob() en su lugar

Sintaxis de Invocación

Estos métodos pueden invocarse desde ObjectScript o desde SQL como procedimientos almacenados. Desde SQL, la sintaxis es: `SELECT %SYSTEM_SQL.PTools_setSQLStatsFlag(2,,8)`. Desde ObjectScript, la sintaxis es: `SET rtn=##class(%SYSTEM.SQL.PTools).setSQLStatsFlag(2,,8)`. Todos los métodos toman un parámetro entero de opción Action y retornan una cadena separada por dos puntos, el primer elemento de la cual es el valor de opción Action previo. Este valor de retorno habilita verificar configuraciones previas antes de hacer cambios.

Interfaz del Management Portal

El Management Portal proporciona una interfaz gráfica para activar estadísticas de rendimiento desde la pestaña Settings en la página SQL Runtime Statistics, accesible vía System Explorer > Tools > SQL Performance Tools > SQL Runtime Statistics, o System Explorer > SQL > Tools > SQL Runtime Statistics. Esta interfaz simplifica configuración para administradores que prefieren gestión basada en GUI sobre control programático.

Propósito de Opciones Action

El parámetro de opción Action controla el alcance y comportamiento de recolección de estadísticas en el framework PTools. Comprender estas opciones es crítico para balancear necesidades de análisis de rendimiento con sobrecarga del sistema.

Métodos a Nivel de Sistema y Namespace (setSQLStatsFlag, setSQLStatsFlagByNS)

Para métodos setSQLStatsFlag() y setSQLStatsFlagByNS():

• Action 0: Desactiva generación de código de estadísticas completamente, deshabilitando todo rastreo de rendimiento
• Action 1 (predeterminado): Activa generación de código de estadísticas para todas las consultas pero no recolecta estadísticas, preparando consultas para análisis potencial sin incurrir sobrecarga de recolección
• Action 2: Registra estadísticas solo para el loop externo de la consulta, recolectando estadísticas en la apertura y cierre de la consulta, que representa la suma del tiempo total para realizar todas las invocaciones de OPEN, FETCH, y CLOSE. Esta opción proporciona métricas generales de rendimiento de consulta con sobrecarga mínima
• Action 3: Registra estadísticas para todos los niveles de módulo de la consulta, incluyendo el módulo principal y todos los módulos de subconsulta. Cuando los módulos están anidados, las estadísticas del módulo MAIN son números inclusivos representando resultados generales para la consulta completa

Métodos Específicos de Trabajo (setSQLStatsFlagJob, setSQLStatsFlagByPID)

Para métodos setSQLStatsFlagJob() y setSQLStatsFlagByPID(), las opciones Action difieren ligeramente:

• Action -1: Desactiva estadísticas para el trabajo específico
• Action 0 (predeterminado): Usa el valor de configuración del sistema
• Actions 1, 2, y 3: Igual que setSQLStatsFlag() y sobrescriben la configuración del sistema

Transición Entre Opciones Action

La transición entre opciones Action requiere comprender requisitos de compilación:

• 0 a 1: Requiere compilar Routines y Classes que contengan SQL para realizar generación de código de estadísticas, y purgar consultas en caché para forzar regeneración de código cuando se trabaja con Dynamic SQL o drivers de base de datos
• 1 a 2: Simplemente requiere cambiar la opción action para comenzar a recolectar estadísticas, permitiendo que análisis de rendimiento SQL sea habilitado en entornos de producción en ejecución con disrupción mínima
• 1 a 3 (o 2 a 3): Requiere compilar Routines y Classes nuevamente y purgar consultas en caché. Opción Action 3 comúnmente solo se usa en consultas identificadas con rendimiento pobre en entornos no de producción debido a sobrecarga significativa
• 1, 2, o 3 a 0: No requiere purgar consultas en caché

Cuándo Aplica Opción Collect

Cuando la opción Action está establecida a 2 o 3, el parámetro de opción Collect permite control de grano fino sobre qué estadísticas de rendimiento se recolectan. Esta capacidad es valiosa para reducir sobrecarga en entornos de producción donde solo se necesitan métricas específicas para análisis.

Sistema de Valor Bitmask

La opción Collect se especifica agregando juntos valores enteros asociados con cada tipo de estadística a recolectar. El framework usa un enfoque bitmask donde cada tipo de estadística está representado por una potencia de 2: valor 1 representa un tipo de métrica, valor 2 representa otro, valor 4 representa un tercer, y valor 8 representa un cuarto tipo de métrica. El valor predeterminado de 15 (1 + 2 + 4 + 8) recolecta todas las estadísticas disponibles, proporcionando datos de rendimiento completos al costo de sobrecarga máxima.

Verificación de Configuraciones Actuales

Los métodos de familia setSQLStatsFlag retornan el valor previo de la opción Collect como segundo elemento separado por dos puntos en la cadena de retorno. Los administradores pueden determinar configuraciones actuales usando métodos o procedimientos almacenados getSQLStatsFlag() o getSQLStatsFlagByPID(). Cuando todas las estadísticas se recolectan (el predeterminado), estos métodos retornan 15 como valor del segundo elemento. Este mecanismo de retorno habilita a administradores preservar y restaurar configuraciones previas al hacer cambios de configuración temporales.

Balanceo de Sobrecarga y Perspectivas

Al seleccionar valores específicos de opción Collect, administradores de base de datos pueden balancear la necesidad de perspectivas de rendimiento con preocupaciones de sobrecarga del sistema. Por ejemplo, recolectar solo métricas Time y Global Refs (omitiendo Commands y Read Latency) usaría un valor Collect más pequeño, reduciendo el costo computacional de recolección de estadísticas mientras aún proporciona indicadores clave de rendimiento para identificar consultas lentas y patrones de I/O de base de datos excesivos. La documentación de referencia de clase %SYSTEM.SQL.PTools proporciona información detallada sobre valores enteros específicos y sus tipos de métrica correspondientes.

Propósito de Perfilado de Palabra Clave

Las palabras clave %PROFILE y %PROFILE_ALL proporcionan un enfoque dirigido para análisis de rendimiento habilitando recolección de estadísticas para sentencias SQL individuales sin activar perfilado a nivel de sistema o namespace. Esta capacidad es esencial para analizar consultas específicas después de que investigación preliminar ha identificado problemas potenciales de rendimiento.

%PROFILE vs %PROFILE_ALL

La palabra clave %PROFILE es equivalente a setSQLStatsFlagJob(2) y recolecta estadísticas solo para el módulo de consulta principal. La sintaxis es directa: adjuntar %PROFILE a una sentencia SELECT, INSERT, UPDATE, o DELETE. Por ejemplo:

• `SELECT %PROFILE_ALL * FROM Sample.Person`
• `INSERT %PROFILE INTO TableName VALUES (...)`
• `UPDATE %PROFILE TableName SET ...`
• `DELETE %PROFILE FROM TableName WHERE ...`

La palabra clave %PROFILE_ALL es equivalente a setSQLStatsFlagJob(3) y recolecta estadísticas para el módulo de consulta principal y todos sus módulos de subconsulta, proporcionando datos de rendimiento completos para consultas complejas con componentes anidados.

Ventajas Sobre Recolección a Nivel de Sistema

Este enfoque basado en palabra clave evita el drenaje sustancial de recursos que acompaña recolectar estadísticas a través del sistema entero o un namespace específico. Mientras la recolección a nivel de sistema proporciona amplitud de información útil para identificar qué consultas necesitan atención, el perfilado basado en palabra clave proporciona profundidad de información para consultas específicas que ya han sido identificadas como problemáticas. El enfoque de palabra clave se usa mejor para análisis concertado de consultas específicas para examinar consultas particulares una vez que ha identificado los esquemas o configuraciones que no están funcionando tan bien como se esperaba.

Mejores Prácticas

Es importante no agregar la palabra clave %PROFILE a muchas consultas en un intento de recolectar estadísticas sobre una sección grande del sistema. Hacer esto derrota el propósito de perfilado dirigido y puede impactar significativamente el rendimiento general del sistema. En su lugar, el flujo de trabajo recomendado es: 1. Usar SQL Runtime Statistics para identificar consultas problemáticas 2. Usar palabras clave %PROFILE o %PROFILE_ALL en esas consultas específicas para análisis detallado 3. Usar las estadísticas detalladas para guiar esfuerzos de optimización como creación de índice, reescritura de consulta, o ajustes de esquema

El Método exportSQLStats()

Después de recolectar estadísticas de rendimiento usando PTools, el método exportSQLStats() proporciona el mecanismo para exportar datos de estadísticas a un archivo o mostrarlo en la terminal para análisis. Este método es parte de la clase %SYSTEM.SQL.PTools y soporta invocación desde contextos tanto SQL como ObjectScript.

Sintaxis de Invocación y Opciones de Formato

Desde SQL, el método se invoca usando la sentencia CALL: `CALL %SYSTEM_SQL.PTools_exportSQLStats('$IO')`. Esta sintaxis usa por defecto formato H (HTML), que produce salida formateada adecuada para ver en navegadores web o visores capaces de HTML. Desde ObjectScript, el método se invoca como: `SET status=##class(%SYSTEM.SQL.PTools).exportSQLStats("$IO")`. Esta sintaxis usa por defecto formato T (texto), que produce salida de texto plano adecuada para visualización de terminal o almacenamiento de archivo de texto. El parámetro '$IO' dirige salida al dispositivo actual, típicamente la terminal. Para exportar a archivo, especificar una ruta de archivo en lugar de '$IO'.

Alternativa: Interfaz StatsSQLView

Una alternativa a exportSQLStats() es consultar la interfaz %SYS_PTools.StatsSQLView, que presenta estadísticas recolectadas en formato de conjunto de resultados SQL tabular. Este enfoque habilita usar herramientas y técnicas SQL estándar para filtrar, ordenar, y analizar datos de rendimiento. Código ObjectScript ejemplo: ```objectscript SET qStatus = tStatement.%Prepare("SELECT * FROM %SYS_PTools.StatsSQLView") SET rsstats = tStatement.%Execute() DO rsstats.%Display() ``` Este enfoque es particularmente útil para integrar análisis de rendimiento en scripts de monitoreo automatizado o herramientas de reporte personalizadas.

Flujo de Trabajo de Exportación Típico

El flujo de trabajo típico para usar exportSQLStats() involucra: 1. Limpiar estadísticas previas usando clearSQLStatsALL() 2. Activar recolección de estadísticas usando setSQLStatsFlagJob() o setSQLStatsFlag() 3. Ejecutar la consulta a ser analizada 4. Llamar exportSQLStats() para ver las estadísticas recolectadas

Los datos exportados incluyen todas las métricas configuradas por la opción Collect, incluyendo Time, Global Refs, Commands, y Read Latency para cada módulo de consulta. Estos datos completos habilitan diagnóstico detallado de cuellos de botella de rendimiento y proporcionan evidencia cuantitativa para decisiones de optimización.

Comportamiento Predeterminado y Propósito de Opción Terminate

La recolección de estadísticas continúa hasta que se termina explícitamente por defecto. Sin embargo, la opción Terminate proporciona capacidades de terminación automática esenciales para entornos de producción donde la recolección de estadísticas indefinida podría impactar rendimiento o consumir almacenamiento excesivo.

Especificación de Parámetros de Terminación

Por defecto, la recolección continúa indefinidamente hasta terminarse emitiendo otro método setSQLStatsFlag[nnn](). Cuando la opción Action está establecida a 1, 2, o 3, los administradores pueden especificar un parámetro de opción Terminate consistente en ya sea un período transcurrido en minutos o un timestamp especificado. La opción Terminate también especifica la opción Action a reiniciar cuando ese período transcurra. Por ejemplo, la cadena "M:120:1" establece M (minutos transcurridos) a 120 minutos, al final de los cuales la opción Action se reinicia a 1. Todas las demás opciones se reinician a los valores predeterminados apropiados para esa opción Action.

Casos de Uso de Producción

Esta capacidad de terminación automática es particularmente valiosa en entornos de producción donde habilitar recolección de estadísticas detallada (Action 3) para solución de problemas debería ser limitada por tiempo para prevenir impacto de rendimiento continuo:

• "M:60:2": Recolectar estadísticas detalladas a nivel de módulo por una hora, luego automáticamente degradar a Action 2 (solo loop externo) para monitoreo continuo con sobrecarga más baja
• "M:1:2": Recolectar estadísticas intensivas por solo un minuto antes de reiniciar, como se demuestra en los ejemplos de documentación

Formato de Valor de Retorno

Los métodos de familia setSQLStatsFlag retornan el valor previo de la opción Terminate como quinto elemento separado por dos puntos en la cadena de retorno, codificado como valor que representa la configuración de terminación. Los administradores pueden examinar configuraciones actuales usando métodos getSQLStatsFlag() o getSQLStatsFlagByPID(). El formato de retorno separado por dos puntos es: `Action:Collect:Namespace1:Namespace2:Terminate:FlagType`, donde el valor Terminate codifica las configuraciones de terminación para inspección y restauración programática.

Dos Enfoques para Monitoreo de Rendimiento

InterSystems IRIS proporciona dos enfoques distintos para monitoreo de rendimiento: SQL Runtime Statistics y el SQL Performance Analysis Toolkit (PTools). Comprender cuándo usar cada enfoque es esencial para gestión efectiva de rendimiento.

SQL Runtime Statistics

SQL Runtime Statistics proporciona monitoreo de rendimiento general siempre activo que no puede desactivarse. Estas estadísticas se recolectan cuando operaciones de consulta se preparan y son visibles desde tablas INFORMATION_SCHEMA.STATEMENTS, STATEMENT_DAILY_STATS, y STATEMENT_HOURLY_STATS. Runtime statistics incluyen:

• Avg Time: Duración promedio de tiempo que la consulta toma en segundos
• Run Count: Número de veces que la consulta ha sido ejecutada
• Avg Rows: Número promedio de filas retornadas
• Avg Commands: Número promedio de comandos ejecutados

Para asegurar recolección eficiente de estadísticas, los datos se escriben solo a intervalos establecidos, que puede resultar en retrasos de hasta 30 minutos antes de que las estadísticas aparezcan. Una tarea del sistema ejecuta automáticamente una vez por hora en todos los namespaces para agregar estadísticas específicas de proceso en estadísticas globales.

SQL Performance Analysis Toolkit (PTools)

El SQL Performance Analysis Toolkit proporciona capacidades de perfilado activo para sentencias SQL específicas o grupos de sentencias. PTools recolecta información detallada sobre ejecución incluyendo Time, Global Refs, Commands, y Read Latency a nivel de módulo. Sin embargo, el perfilado activo puede incrementar significativamente la carga en el servidor. Por lo tanto, PTools está destinado para esfuerzos de análisis de código concertado después de examinar SQL Runtime Statistics para determinar qué consultas específicas necesitan examen más cercano. No está destinado para monitoreo continuo de código en ejecución.

Flujo de Trabajo Combinado Recomendado

El flujo de trabajo recomendado combina ambos enfoques: usar SQL Runtime Statistics para monitoreo continuo para identificar consultas con Avg Time pobre o Avg Commands alto, luego usar PTools (vía métodos setSQLStatsFlag o palabras clave %PROFILE) para análisis detallado de consultas problemáticas identificadas. La herramienta Alternate Show Plans une ambos enfoques mostrando estadísticas estimadas normalmente, pero estadísticas de runtime reales cuando recolección PTools está activada. Esta combinación proporciona gestión de rendimiento completa: identificación amplia vía Runtime Statistics, diagnóstico profundo vía PTools, y sobrecarga mínima durante operaciones normales.