# MySQL

# Introducción

**Este plugin tiene como finalidad monitorizar bases de datos MySQL**, mediante consultas que extraerán información sobre datos que son claves para conocer el rendimiento y estado de la bases de datos, como son el número de conexiones, número de consultas, estado de los buffer, estado del cache y estado de los reinicios. Estos datos se verán reflejados en PandoraFMS, en módulos que aportaran el valor estadístico, dentro de un agente que representará a cada base de datos.

Este plugin está desarrollado para usarse con Pandora FMS Discovery, por lo que a diferencia de otros plugins no genera agentes por XML, si no que todo lo descubierto se devuelve en la salida JSON del plugin.

# Prerrequisitos

Este plugin realiza conexiones remotas a las bases de datos a monitorizar, por lo que es necesario asegurar la conectividad entre el servidor de Pandora FMS y dichas bases de datos.

A su vez los siguientes permisos son requeridos para el usuario que se utiliza para conectar.  
  
SELECT sobre las tablas de la base de datos.  
SELECT sobre las tablas de INFORMATION\_SCHEMA.  
SHOW STATUS (permite consultar el estado del servidor)  
SHOW VARIABLES (permite acceder a las variables de configuración del servidor).

# Parámetros y configuración

**Parámetros**

<table border="1" id="bkmrk---conf-ruta-al-archi" style="border-collapse: collapse; width: 100%; height: 150px;"><tbody><tr style="height: 29px;"><td style="width: 50%; height: 29px;">--conf</td><td style="width: 50%; height: 29px;">Ruta al archivo de configuración</td></tr><tr style="height: 29px;"><td style="width: 50%; height: 29px;">--target\_databases</td><td style="width: 50%; height: 29px;">Ruta al listado de bases de datos objetivo a monitorizar</td></tr><tr style="height: 46px;"><td style="width: 50%; height: 46px;">--target\_agents</td><td style="width: 50%; height: 46px;">Ruta al listado de agentes objetivo en los que almacenar los datos de las bases de datos objetivo. Este parámetro es opcional, y se usará para dar nombres de agentes personalizados a los agentes generados por el plugin.</td></tr><tr style="height: 46px;"><td style="width: 50%; height: 46px;">--custom\_queries</td><td style="width: 50%; height: 46px;">Ruta al fichero con la definición de consultas personalizadas a las bases de datos objetivo. Este parámetro es opcional y cada consulta realizada se corresponderá con un módulo.</td></tr></tbody></table>

**Archivo de configuración (--conf)**

El contenido del fichero será el siguiente:

```
agents_group_id = < ID del grupo en el que se crearán los agentes >
interval = < Intervalo de monitorización de los agentes en segundos >
user = < Usuario de conexión >
password = < Contraseña >
threads = < Número de hilos que se usaran para la creación de agentes >
modules_prefix = < Prefijo de módulos >
execute_custom_queries = < Activar con 1 para habilitar el uso de consultas personalizadas >
scan_databases = < Activar con 1 para monitorizar todas las bases de datos del server >
agent_per_database = < Activar con 1 para crear un agente por cada base de datos encontrada en los objetivos a monitorizar >
db_agent_prefix = < Prefijo que se incluira en el nombre de cada agente creado para cada base de datos encontrada en los objetivos a monitorizar >
analyze_connections = < Activar con 1 para habilitar la monitorización de conexiones >
engine_uptime = < Activar con 1 para habilitar la monitorización del tiempo en ejecución >
query_stats = < Activar con 1 para habilitar la moitorización de estadísticas de consultas >
innodb_stats = < Activar con 1 para habilitar la monitorización de estadísticas de innodb >
cache_stats = < Activar con 1 para habilitar la monitorización de estadísticas de cache >
```

<span style="text-decoration: underline;">Ejemplo:</span>

```
agents_group_id = 10
interval = 300
user = sa 
password = HHgD85V@
threads = 1
modules_prefix = 
execute_custom_queries = 1
analyze_connections = 1
engine_uptime = 1
query_stats = 1
innodb_stats = 1
cache_stats = 1
scan_databases = 1
agent_per_database = 1
db_agent_prefix = mysql.
```

**Listado de bases de datos objetivo (--target\_databases)**

El contenido del fichero será un listado de bases de datos objetivo, separando cada base de datos por comas o por líneas. El formato para una base de datos podrá ser cualquiera de los siguientes:

```
ip:puerto
ip
```

En caso de no indicarse el puerto, se usará el puerto 3306 TCP por defecto para la conexión al objetivo.

<span style="text-decoration: underline;">Ejemplo:</span>

```
172.17.0.2, 172.17.0.3
172.17.0.4:3306
```

**Listado de agentes objetivo (--target\_agents)**

El contenido del fichero será un listado de bases de nombres de agentes, separando cada agente por comas o por líneas. Estos nombres de agentes se usarán para volcar la información de cada base de datos objetivo en el nombre de agente indicado correspondiente, en lugar de dejar que el plugin genere los nombres de agentes de forma automática.

La posición de cada nombre de agente en el listado debe coincidir con la posición de la base de datos objetivo en su propio listado, es decir, el nombre para la primera base de datos objetivo será el primer nombre de este listado, teniendo en cuenta que las líneas en blanco son ignoradas.

<span style="text-decoration: underline;">Ejemplo:</span>

```
agente1,,agente3
agente4
agente5,agente6,agente7,,agente9
```

**Consultas personalizadas (--custom\_queries)**

Se debe introducir un módulo por cada consulta personalizada que se pretenda monitorizar. Los módulos deben seguir una estructura, que es la siguiente:

```
check_begin      --> Etiqueta de abertura del módulo
name             --> Nombre del módulo
description      --> Descripción del módulo.
operation        --> Tipo de operación 
datatype         --> Tipo de módulo
min_warning      --> Configuración del umbral mínimo de warning
max_warning      --> Configuración del umbral máximo de warning
str_warning      --> Configuración de string de warning
warning_inverse  --> Activar el intervalo inverso con 1 para umbral de warning
min_critical     --> Configuración del umbral mínimo de critical
max_critical     --> Configuración del umbral máximo de critical
str_critical     --> Configuración de string de critical
critical_inverse --> Activar el intervalo inverso con 1 para umbral de crítico
module_interval  --> Este intervalo se calcula como un multiplicador del intervalo del agente. 
target           --> Consulta personalizada
target_databases --> Agentes de bases de datos en los que se creará el módulo
check_end        --> Etiqueta de cierre del módulo
```

En caso de habilitarse la monitorización de cada base de datos dentro de los servidores MySQL objetivo, las consultas personalizadas se lanzarán para cada una de dichas bases de datos. En esos casos, es posible referenciar a la base de datos en uso con la variable "**$\_\_self\_dbname**".

<span style="text-decoration: underline;">Ejemplo:</span>

```
check_begin
name Select 1 $__self_dbname
description Number of invalid objects
operation value
datatype generic_data
min_warning 5
target SELECT 1;
target_databases all
check_end

check_begin
name Agents count in $__self_dbname
description Number of invalid objects
operation value
datatype generic_data
min_warning 5
target SELECT COUNT(*) FROM $__self_dbname.tagente;
target_databases pandora
check_end

check_begin
name Agents in $__self_dbname
description Invalid objects (detail)
operation full
datatype generic_data
target SELECT id_agente, nombre FROM $__self_dbname.tagente limit 10;
target_databases pandora
check_end
```

# Ejecución manual

El formato de la ejecución del plugin es el siguiente:

```bash
./pandora_mysql \
--conf < ruta al fichero de configuración > \
--target_databases < ruta al fichero de configuración que contiene las bases de datos objetivo > \
[ --target_agents < ruta al fichero de configuración de agentes > ] \
[ --custom_queries < ruta al fichero de configuración que contiene las consultas personalizas > ]
```

Por ejemplo:

```shell
./pandora_mysql \
--conf /usr/share/pandora_server/util/plugin/mysql.conf \
--target_databases /usr/share/pandora_server/util/plugin/targets.conf \
--target_agents /usr/share/pandora_server/util/plugin/target_agents.conf \
--custom_queries /usr/share/pandora_server/util/plugin/custom_queries.conf
```

# Discovery

Este plugin puede integrarse con el *Discovery* de Pandora FMS.

Para ello se debe cargar el paquete ".disco" que puede descargar desde la librería de Pandora FMS:

[https://pandorafms.com/library/](https://pandorafms.com/library/)

[![image-1687944626011.png](https://pandorafms.com/guides/public/uploads/images/gallery/2023-06/scaled-1680-/image-1687944626011.png)](https://pandorafms.com/guides/public/uploads/images/gallery/2023-06/image-1687944626011.png)

Una vez cargado, se podrán monitorizar entornos de MySQL creando tareas de *Discovery* desde la sección *Management &gt; Discovery &gt; Applications*.

[![image-1687944793853.png](https://pandorafms.com/guides/public/uploads/images/gallery/2023-06/scaled-1680-/image-1687944793853.png)](https://pandorafms.com/guides/public/uploads/images/gallery/2023-06/image-1687944793853.png)

Para cada tarea se solicitarán los siguientes datos mínimos:

- **MySQL target string**: Lista de objetivos MySQL a monitorizar por la tarea. Será una lista separada por comas o por líneas. Cada base de datos objetivo se podrá definir con el formato IP:PUERTO o IP.
- **User**: Usuario de conexión a las bases de datos objetivo.
- **Password**: Contraseña del usuario indicado.

[![image-1684762901367.png](https://pandorafms.com/guides/public/uploads/images/gallery/2023-05/scaled-1680-/image-1684762901367.png)](https://pandorafms.com/guides/public/uploads/images/gallery/2023-05/image-1684762901367.png)

También se podrá ajustar la configuración de la tarea para personalizar la monitorización deseada:

- **Max threads**: Para optimizar el tiempo de ejecución, se podrán configurar múltiples hilos para monitorizar los agentes de la tarea. Hay que tener en cuenta que configurar múltiples hilos puede aumentar el uso de CPU de la tarea.
- **Target agent**: Lista de agentes objetivo para los objetivos MySQL a monitorizar. Es decir, los nombres con los que se generarán los agentes de cada objetivo definido en la tarea. Será una lista separada por comas o por líneas. La posición de los nombres en la lista deberá coincidir con la posición de los objetivos MySQL en su lista, es decir, el primer nombre se usará para el primer objetivo y así sucesivamente. Si la lista se separa por líneas, las líneas en blanco se ignorarán. Si no se especifica un nombre de agente para un objetivo se usará su IP o FQDN como nombre del agente.
- **Custom module prefix**: Texto incluido como prefijo para los todos los nombres de módulos generados. Es útil para localizar los módulos generados por la tarea o distinguirlos de otros.
- **Scan databases**: Si se activa se monitorizarán las distintas bases de datos de cada objetivo MySQL.
- **Create agent per database**: Si se activa se creará un agente distinto para cada base de datos de cada objetivo MySQL. Es necesario activar la monitorización de bases de datos para que funcione.
- **Custom database agent prefix**: Texto incluido como prefijo para los nombres que se generarán para los agentes individuales de cada base de datos de cada objetivo MySQL. Es útil para localizar los agentes generados por a tarea o distinguirlos de otros.
- **Check engine uptime**: Si se activa monitorizará el uptime de los objetivos.
- **Retrieve query statistics**: Si se activa monitorizará las estadísticas de consultas.
- **Analyze connections**: Si se activa monitorizará las conexiones.
- **Retrieve InnoDB statistics**: Si se activa monitorizará las estadísticas de InnoDB.
- **Retrieve cache statistics**: Si se activa monitorizará las estadísticas de caché.
- **Execute custom queries**: Si se activa permitirá ejecutar consultas personalizadas a cada objetivo MySQL y a cada bases de datos.
- **Custom queries**: Bloque de configuración para definir las consultas personalizadas que se ejecutarán. Cada consulta generará un nuevo módulo para cada agente de la tarea.

[![image-1684762917289.png](https://pandorafms.com/guides/public/uploads/images/gallery/2023-05/scaled-1680-/image-1684762917289.png)](https://pandorafms.com/guides/public/uploads/images/gallery/2023-05/image-1684762917289.png)

Las tareas completadas con éxito tendrán un resumen de ejecución con la siguiente información:

- **Total agents**: Número total de agentes generados por la tarea.
- **Target agents**: Número total de agentes generados por la tarea para los targets definidos.
- **Databases agents**: Número total de agentes generados por la tarea para las bases de datos descubiertas.
- **Targets up**: Número total de objetivos conectados con éxito.
- **Targets down**: Número total de objetivos a los que no se ha podido conectar.

[![image-1684762934681.png](https://pandorafms.com/guides/public/uploads/images/gallery/2023-05/scaled-1680-/image-1684762934681.png)](https://pandorafms.com/guides/public/uploads/images/gallery/2023-05/image-1684762934681.png)

Las tareas que no se completen con éxito tendrán un resumen de ejecución en el que se registrarán los errores que se hayan producido.

# Agentes y módulos generados por el plugin

El plugin creará un agente por cada base de datos objetivo. Ese agente contendrá los siguientes módulos

Si esta activado **engine\_uptime**:

<table border="1" id="bkmrk-restart_detection-pa" style="border-collapse: collapse; width: 100%;"><tbody><tr><td style="width: 50%;">restart\_detection</td><td style="width: 50%;">**Será 0 si se ha detectado un reinicio inesperado, y 1 de no ser este el caso.**  Cuando un servidor se reinicia inesperadamente, puede haber una interrupción en el acceso a la base de datos y potencialmente se pueden perder transacciones o datos no guardados correctamente.</td></tr></tbody></table>

Si esta activado **query\_stats**:

<table border="1" id="bkmrk-queries-monitorizar-" style="border-collapse: collapse; width: 100%;"><tbody><tr><td style="width: 50%;">queries</td><td style="width: 50%;">**Número de consultas totales.** Monitorizar las consultas es esencial para comprender la carga de trabajo que se está ejecutando en el servidor y evaluar el rendimiento general del sistema. Al supervisar el número total de consultas, puedes identificar picos de actividad, optimizar el rendimiento y detectar posibles problemas, como consultas ineficientes o excesivas.</td></tr><tr><td style="width: 50%;">query rate</td><td style="width: 50%;">**Tasa de consultas.** La tasa de consultas se refiere a la velocidad a la que se están ejecutando las consultas en el servidor de MySQL. Monitorizar la tasa de consultas te permite evaluar la carga de trabajo del servidor en tiempo real y detectar patrones de uso. Una alta tasa de consultas puede indicar una gran demanda de recursos y requerir ajustes en la configuración del servidor o mejoras de hardware para mantener un rendimiento óptimo. Por otro lado, una baja tasa de consultas puede indicar una infrautilización de los recursos disponibles o problemas de rendimiento en la aplicación.</td></tr><tr><td style="width: 50%;">query select</td><td style="width: 50%;">**Número de consultas SELECT.** Las consultas SELECT se utilizan para recuperar datos de la base de datos. Monitorizar las consultas SELECT te permite evaluar la eficiencia de las consultas y la optimización de los índices. Al identificar consultas SELECT lentas o ineficientes, puedes tomar medidas para mejorar su rendimiento, como añadir índices adecuados, optimizar las consultas o ajustar la configuración del servidor.</td></tr><tr><td style="width: 50%;">query update</td><td style="width: 50%;">**Número de consultas UPDATE.** Las consultas UPDATE se utilizan para modificar los datos existentes en la base de datos. Monitorizar las consultas UPDATE es importante para evaluar la frecuencia y la eficiencia de las actualizaciones de datos. Puedes identificar consultas UPDATE que afectan a un gran número de filas o que tienen un impacto significativo en el rendimiento del servidor. Esto te permite optimizar las consultas, revisar la estructura de las tablas o tomar medidas para reducir la carga generada por las actualizaciones.</td></tr><tr><td style="width: 50%;">query delete</td><td style="width: 50%;">**Número de consultas DELETE.** Las consultas DELETE se utilizan para eliminar datos de la base de datos. Monitorizar las consultas DELETE es útil para evaluar la frecuencia y la eficiencia de las eliminaciones de datos. Puedes identificar consultas DELETE que afectan a un gran número de filas o que tienen un impacto significativo en el rendimiento del servidor. Esto te permite optimizar las consultas, revisar la estructura de las tablas o tomar medidas para reducir la carga generada por las eliminaciones.</td></tr><tr><td style="width: 50%;">query insert</td><td style="width: 50%;">**Número de consultas INSERT.** Las consultas INSERT se utilizan para insertar nuevos datos en la base de datos. Monitorizar las consultas INSERT te permite evaluar la frecuencia y la eficiencia de las inserciones de datos. Puedes identificar consultas INSERT que están generando una alta carga en el servidor o que podrían estar causando problemas de rendimiento. Esto te permite optimizar las consultas, revisar la estructura de las tablas o considerar estrategias de inserción diferida para mejorar el rendimiento en entornos de alta concurrencia.</td></tr></tbody></table>

Si esta activado **analyze\_connections**:

<table border="1" id="bkmrk-current-connections-" style="border-collapse: collapse; width: 100%;"><tbody><tr><td style="width: 50%;">current connections</td><td style="width: 50%;">**Número de conexiones actuales.** El número de conexiones actuales se refiere al número de conexiones simultáneas establecidas con el servidor de MySQL en un momento dado. Es esencial monitorizar este valor para asegurarse de que el servidor puede manejar la carga de trabajo actual. Si el número de conexiones actuales se acerca al límite máximo de conexiones permitidas, es posible que los nuevos usuarios o aplicaciones no puedan conectarse correctamente. También es importante verificar si hay un aumento inusual en las conexiones, lo que podría indicar un problema de rendimiento o una posible actividad maliciosa.</td></tr><tr><td style="width: 50%;">connections ratio</td><td style="width: 50%;"> **Ratio de conexiones.** El ratio de conexiones se refiere a la frecuencia con la que se establecen y cierran las conexiones en el servidor de MySQL. Monitorizar este valor puede ayudarte a identificar patrones de uso y picos de actividad. Un alto ratio de conexiones puede indicar una alta demanda de recursos y requerir acciones como ajustar la configuración del servidor, aumentar la capacidad de hardware o revisar el diseño de la aplicación. Por otro lado, un bajo ratio de conexiones puede sugerir una infrautilización de los recursos disponibles.</td></tr><tr><td style="width: 50%;">aborted connections</td><td style="width: 50%;">**Número de conexiones abortadas.** Las conexiones abortadas son aquellas que se interrumpen de forma anormal antes de completar su ciclo de vida normal. Esto puede ocurrir debido a problemas de red, errores de autenticación, consultas ineficientes o problemas de configuración del servidor. Monitorizar las conexiones abortadas es fundamental para identificar y solucionar problemas que puedan afectar la estabilidad y el rendimiento del servidor de MySQL. Al detectar patrones de conexiones abortadas, puedes tomar medidas correctivas y optimizar tu aplicación o infraestructura para evitar interrupciones no deseadas.</td></tr></tbody></table>

Si esta activado **innodb\_stats**:

<table border="1" id="bkmrk-innodb-buffer-pool-p" style="border-collapse: collapse; width: 100%; height: 319px;"><tbody><tr style="height: 29px;"><td style="width: 50%; height: 29px;">Innodb buffer pool pages total</td><td style="width: 50%; height: 29px;">**Número total de páginas en el buffer pool (utilización).** El búfer de InnoDB es una parte esencial de la arquitectura de almacenamiento de InnoDB en MySQL. Monitorizar el número total de páginas en el búfer de InnoDB es importante para evaluar la eficiencia del búfer y su capacidad para almacenar datos en memoria en lugar de tener que acceder a ellos desde el disco. Un valor adecuado y bien ajustado del búfer de InnoDB puede mejorar el rendimiento general del sistema al reducir la necesidad de realizar lecturas y escrituras en disco.</td></tr><tr style="height: 29px;"><td style="width: 50%; height: 29px;">Innodb buffer pool read requests</td><td style="width: 50%; height: 29px;">**Lectura del buffer pool de innodb.** Esta métrica indica la cantidad de veces que se ha solicitado leer datos desde el búfer de InnoDB. Monitorizar las solicitudes de lectura del búfer de InnoDB puede ayudarte a evaluar la eficacia del búfer y determinar si la mayoría de las lecturas se están atendiendo desde la memoria o si hay una alta carga de lecturas desde el disco. Un alto número de solicitudes de lectura del búfer de InnoDB puede indicar una buena utilización de la memoria y un mejor rendimiento.</td></tr><tr style="height: 29px;"><td style="width: 50%; height: 29px;">Innodb disk reads</td><td style="width: 50%; height: 29px;">**Cantidad de operaciones de lectura.** Las lecturas desde el disco en InnoDB se refieren a las operaciones de lectura que se realizan directamente desde el almacenamiento en disco en lugar de utilizar los datos almacenados en el búfer de InnoDB. Monitorizar las lecturas desde el disco te permite evaluar la eficiencia del búfer de InnoDB y determinar si se están realizando demasiadas lecturas desde el disco. Un alto número de lecturas desde el disco puede indicar una necesidad de ajustar el tamaño del búfer de InnoDB o mejorar la eficiencia de las consultas.</td></tr><tr style="height: 29px;"><td style="width: 50%; height: 29px;">Innodb disk writes</td><td style="width: 50%; height: 29px;">**Cantidad de operaciones de escritura.** Las escrituras en disco en InnoDB se refieren a las operaciones de escritura que se realizan directamente en el almacenamiento en disco. Monitorizar las escrituras en disco es importante para evaluar la carga de escritura y determinar si se están realizando demasiadas operaciones de escritura que puedan afectar al rendimiento. Un alto número de escrituras en disco puede indicar la necesidad de optimizar las operaciones de escritura o considerar la posibilidad de utilizar técnicas como el ajuste de caché o la escritura en lotes (batch writing) para mejorar el rendimiento.</td></tr><tr style="height: 29px;"><td style="width: 50%; height: 29px;">Innodb disk data read</td><td style="width: 50%; height: 29px;">**Cantidad de datos leídos del disco.** Esta métrica se refiere a la cantidad de datos que se han leído desde el disco en InnoDB. Monitorizar la cantidad de datos leídos desde el disco te ayuda a evaluar el rendimiento y la eficiencia de las operaciones de lectura en InnoDB. Un alto volumen de datos leídos desde el disco puede indicar un problema de rendimiento y la necesidad de optimizar las consultas o mejorar la eficiencia del búfer de InnoDB.</td></tr><tr style="height: 29px;"><td style="width: 50%; height: 29px;">Innodb disk data written</td><td style="width: 50%; height: 29px;">**Cantidad de datos escritos en el disco.** Esta métrica se refiere a la cantidad de datos que se han escrito en el disco en InnoDB. Monitorizar la cantidad de datos escritos en disco te ayuda a evaluar el rendimiento y la eficiencia de las operaciones de escritura en InnoDB. Un alto volumen de datos escritos en disco puede indicar una alta carga de escritura y la necesidad de optimizar las operaciones de escritura o considerar técnicas como el ajuste de caché o la escritura en lotes (batch writing) para mejorar el rendimiento.</td></tr></tbody></table>

Si esta activado **cache\_stats**:

<table border="1" id="bkmrk-query-cache-enabled-" style="border-collapse: collapse; width: 100%;"><tbody><tr><td style="width: 50%;">query cache enabled</td><td style="width: 50%;">**Caché de consulta activada.** La caché de consultas (query cache) en MySQL permite almacenar en memoria las consultas y sus resultados para que puedan ser reutilizados si se repite exactamente la misma consulta. Monitorizar si la caché de consultas está habilitada o deshabilitada es importante para evaluar el impacto de la caché en el rendimiento general del sistema. La caché de consultas puede mejorar el rendimiento al evitar la ejecución repetida de consultas idénticas, pero también puede tener un impacto negativo si las consultas cambian con frecuencia o si el tamaño de la caché es insuficiente.</td></tr><tr><td style="width: 50%;">query hit ratio</td><td style="width: 50%;">**Ratio de aciertos de consulta.** El ratio de aciertos de consulta (query hit ratio) se refiere a la proporción de consultas que se han resuelto mediante la caché de consultas en comparación con el total de consultas ejecutadas. Monitorizar el ratio de aciertos de consulta te permite evaluar la eficacia de la caché de consultas y determinar si está siendo utilizada de manera efectiva. Un alto ratio de aciertos de consulta indica un buen rendimiento de la caché, mientras que un bajo ratio puede indicar que la caché no está optimizada o que las consultas cambian con frecuencia.</td></tr></tbody></table>

El plugin también creará un módulo por cada consulta personalizada definida en el fichero de configuración.