Tutorial de Timelion: De cero a héroe

Este tutorial también se publicó en el blog privado de Tim.

Timelion es una herramienta de visualización para series temporales en Kibana. Las visualizaciones de series temporales son visualizaciones que analizan datos en un orden temporal. Timelion se puede usar para dibujar gráficos bidimensionales con el tiempo graficado sobre el eje X.

¿Cuál es la ventaja por sobre usar simplemente las visualizaciones en barra o líneas? Timelion adopta un enfoque diferente. En lugar de usar un editor visual para crear gráficos, usted define un gráfico encadenando funciones mediante la sintaxis específica de Timelion. Esta sintaxis habilita ciertas funciones que los gráficos tradicionales de series de puntos no ofrecen, como dibujar datos de distintos índices o fuentes de datos en un gráfico.

Este tutorial primero le dará una breve introducción a la interfaz de usuario de timelion en Kibana y luego explicará la sintaxis de Timelion y mostrará varios casos prácticos que no podía o aún no puede hacer con las visualizaciones típicas de Kibana.

La interfaz de usuario

Puede acceder a timelion desde la navegación principal en el lado izquierdo de la página.

Puede tener múltiples gráficos en una planilla de timelion. Para agregar un nuevo gráfico a la planilla use el enlace Add (Agregar) en la barra del menú superior. New (Nuevo) generará una planilla completamente nueva.

El cuadro de entrada en la parte superior de la ventana muestra la expresión para el gráfico seleccionado actualmente. Haga clic en un gráfico para seleccionarlo para edición. Todas las expresiones que verá a lo largo de este tutorial se insertarán en ese cuadro de texto.

Al usar el botón Save (Guardar) en el menú, puede guardar la planilla de timelion completa con todos los gráficos o el gráfico enfocado actualmente como una visualización que puede colocar en cualquier panel.

El intervalo de fechas de los datos que se muestran actualmente puede estar influenciado por el conocido selector de fecha en el extremo superior derecho de la página. Para establecer la escala del eje X, se usa la casilla de selección que está junto a la entrada de la expresión. Está configurada de manera predeterminada en “automático”, de modo que determinará automáticamente qué escala sería buena según el intervalo de tiempo seleccionado. Si desea forzar, por ejemplo, un punto de datos por día, puede configurar esto en 1d.

Expresiones de Timelion

La expresión más simple, que también se usará automáticamente para los gráficos nuevos, es la siguiente:

.es(*)

Las funciones de Timelion siempre comienzan con un punto seguido por el nombre de la función, y luego llevan un paréntesis que contiene todos los parámetros de la función (en este caso, solo el asterisco).

La función .es (o .elasticsearch si le encanta escribir palabras largas) recoge datos de Elasticsearch y los dibuja a lo largo del tiempo.

Si no especifica un índice en la expresión (en un instante veremos cómo hacerlo), se buscarán datos en todos los índices de su Elasticsearch. Puede cambiar este valor predeterminado en la Configuración avanzada de Kibana modificando el ajuste timelion:es.default_index.

De manera predeterminada, la función .es solo contará la cantidad de documentos, lo que dará como resultado un gráfico que muestra la cantidad de documentos a lo largo del tiempo.

Si está ingresando esa simple expresión y solo obtiene una línea plana, a pesar de haber seleccionado un intervalo de fechas que contiene datos, lo más probable es que sus datos no usen @timestamp como nombre para el campo de tiempo principal. Puede cambiar el nombre predeterminado a través de la configuración timelion:es.timefield en la Configuración avanzada o usar el parámetro timefield en la función .es para configurarlo para una serie individual. En la próxima sección aprenderá a configurar parámetros.

Parámetros de funciones

Las funciones tienen múltiples parámetros, al igual que la función .es. Cada parámetro tiene un nombre que usted puede usar entre paréntesis para establecer su valor.

Los parámetros también tienen un orden, que se muestra mediante autocompletar o la documentación (usando el botón Docs en el menú superior).

Si no especifica el nombre del parámetro, Timelion asigna los valores a los parámetros en el orden en que están listados en la documentación.

El primer parámetro de la función .es es el parámetro q (de «query», «consulta» en inglés), que es una cadena de consulta usada para filtrar los datos para esta serie. También puede referenciar explícitamente este parámetro por su nombre y siempre recomendaría hacerlo apenas pase más de un parámetro a la función. Por lo tanto, las siguientes dos expresiones son equivalentes:

.es(*) 
.es(q=*) 

    Los múltiples parámetros están separados por coma. La función `.es` tiene otro parámetro llamado `index`, que puede usarse para especificar un patrón de índices para esta serie, entonces la consulta no se volverá a ejecutar en todos los índices (o a donde haya cambiado la configuración anterior).
    

timelion 
.es(q=*, index=logstash-*) 

    Si el valor de su parámetro contiene espacios o comas, debe poner el valor entre comillas simples o dobles. Si no, puede omitir estas comillas.
    

timelion 
.es(q='some query', index=logstash-*) 

    ### Cambio de funciones
    
    Muchas de las funciones de timelion se usan para modificar series de datos. Los aplica al cambiar las funciones en la expresión. La función `.label` es una de esas funciones. Puede usarla para cambiar la etiqueta de una serie:
    

timelion 
.es(q=country:de).label(Germany) 

    También puede encadenar varias funciones, como veremos más tarde en este tutorial.
    
    ### Series múltiples
    
    Una de las ventajas de usar timelion es la capacidad de agregar series temporales múltiples a un gráfico. Las series múltiples se deben separar con una coma en la expresión:
    

timelion 
.es(q=de), .es(q=us) 

    Ahora también puede encadenar funciones en cada serie, por ejemplo, para etiquetas específicas:
    

timelion 
.es(q=de).label(Germany), .es(q=us).label('United States') 

    ![Un gráfico que muestra dos series etiquetadas como Alemania y Estados Unidos.][2]
    
    Ya cubrimos los conceptos básicos para trabajar con Timelion, entonces podemos pasar a una explicación más profunda de varias funciones y lo que puede hacer con ellas.
    
    Funciones de Timelion
    ------------------
    
    Para demostrar las funciones, usaremos algunos datos de muestra que contienen registros de acceso de un servidor web. Los datos de muestra se crearon usando [`makelogs`](https://www.npmjs.com/package/makelogs) que puede usar para crear sus propios datos de muestra.
    
    ### Funciones de las fuentes de datos
    
    Las funciones de las fuentes de datos se pueden usar para cargar datos en el gráfico. Ya vimos la función de datos `.es` que carga datos de Elasticsearch. Timelion ofrece algunas fuentes más desde donde cargar datos, que explicaremos en esta sección.
    
    #### Elasticsearch
    
    Antes de que examinemos las otras funciones de las fuentes de datos, primero debemos volver a examinar la función `.es`. Proporciona más funcionalidad de la que hemos visto hasta ahora.
    
    Como es un caso práctico común para separar en líneas por el valor de un campo específico (lo que puede hacer con una agregación de términos en una visualización regular), la función `.es` tiene un parámetro llamado `split` para eso.
    
    El valor del parámetro `split` debe ser un nombre de campo, seguido por dos puntos, luego un valor numérico que indique cuántos de los valores principales deben tener una línea. La siguiente expresión muestra el tráfico de los cuatro países principales (el código de país se almacena en el campo `geo.dest`) en nuestros datos de muestra:
    

timelion 
.es(split=country:4) 

    ![Un gráfico con cuatro líneas, una para cada uno de los cuatro países principales][3]
    
    El parámetro `metric` se utiliza para controlar el cálculo del valor de Y. La función `.es` pondrá de manera determinada el recuento de los documentos sobre el eje Y. Puede usar el parámetro `metric` para especificar otra agregación de métricas, que se debe usar para calcular el valor en un momento específico. El valor debe ser el nombre de una agregación de métricas de un solo valor, seguido por dos puntos y luego el nombre del campo para calcular en esa agregación.
    
    Los nombres válidos para la agregación son, por ejemplo, `avg` para calcular el valor promedio de un campo, `sum` para la suma, `cardinality` para obtener la cantidad de valores únicos en un campo, `min` y `max` para recuperar el valor mínimo o máximo de un campo.
    
    Si queremos modificar la expresión anterior para mostrar los cuatro países principales según cuántos bytes se han transferido en ese país (para ver qué países son responsables de mi ancho de banda), puede usar el parámetro `metric` de la siguiente manera:
    

timelion 
.es(split=country:4, metric=sum:bytes) 

    ![El gráfico anterior, pero ahora mostrando la suma de bytes en el eje Y][4]
    
    También puede usar múltiples parámetros `split` para crear subcubos (como en las visualizaciones) y múltiples parámetros `metric` para dibujar múltiples valores por punto temporal.
    
    #### static/value
    
    `.static` (o el alias `.value`) simplemente dibujará una línea llana horizontal en el valor dado. Esto puede ser útil para dibujar un umbral visual en un gráfico. También puede usar el parámetro `label` para etiquetar las series directamente:
    

timelion 
.es(), .static(25, label='good visitor level') 

    ![Un gráfico con una línea vertical en el valor 25][5]
    
    #### Banco Mundial
    
    Timelion ofrece funciones para cargar datos directamente del [Banco Mundial](http://data.worldbank.org/), que proporciona muchos datos estadísticos de todo el mundo, por ejemplo, población, PBI y muchos más.
    
    Para extraer los datos del Banco Mundial y colocarlos en su gráfico, puede usar la función `.wbi` (o la forma larga `.worldbank_indicators`). Acepta dos parámetros: `country` (país) e `indicator` (indicador).
    
    `country` puede ser el código ISO de un país específico o si no se cargarán datos específicos para el mundo entero, `indicator` debe ser un indicador válido del Banco Mundial. Puede encontrar una lista de todos los indicadores en su [portal de datos](http://data.worldbank.org/indicator). Si hace clic en un indicador, puede ver el código del indicador real que necesita especificar en la URL, por ejemplo, es `NY.GDP.MKTP.CD` para el PBI de un país o `SP.POP.0014.TO.ZS` para las edades 0 a 14 de la población en porcentaje. Si no especifica un indicador, se carga la población.
    
    Para visualizar el PBI de Francia y Alemania, podría usar la siguiente expresión:
    

timelion 
.wbi(country=de, indicator=NY.GDP.MKTP.CD), .wbi(country=fr, indicator=NY.GDP.MKTP.CD) 

    ![Se muestran dos líneas del PBI de Francia y Alemania.][6]
    
    Si necesita manipular la URL de la solicitud del Banco Mundial, puede usar la función `.wb` en lugar de `.wbi`, que espera la ruta de la solicitud de la API como el parámetro `code`.
    
    #### Más fuentes de datos
    
    Además de las fuentes de datos ya mencionadas, timelion ofrece unas fuentes de datos más, que requieren una cuenta u otro software en ejecución.
    
    `.quandl` se puede usar para consultar datos financieros de [Quandl](https://graphiteapp.org/) y `.graphite` se puede usar para consultar datos de un servidor Graphite en ejecución.
    
    
    #### Compensar fuentes de datos
    
    Cada una de las funciones de las fuentes de datos aceptan un parámetro llamado `offset`. Se puede usar para compensar los datos por un intervalo temporal específico. Esto puede ser útil para comparar datos de distintos intervalos temporales. El parámetro `offset` acepta valores positivos y negativos con una unidad. Las unidades válidas son `s` para segundos, `m` para minutos, `h` para horas, `d` para días, `w` para semanas, `M` para meses y `y` para años. Cambiará la entrada por la compensación especificada antes de dibujarla.
    
    Para graficar nuestros visitantes actuales de la página (de nuestros datos de muestra) en comparación con las visitas de una semana anterior, puede usar la siguiente expresión:
    

timelion 
.es().label(current), .es(offset=-1w).label('prev week') 

    ![Dos series con una compensada por una semana][7]
    
    ### Funciones de diseño
    
    Algunas de las funciones ofrecidas por timelion se usan principalmente para fines de diseño.
    
    #### Estilo de línea
    
    Timelion dibujará los datos con líneas de manera predeterminada. Hay tres funciones para modificar los tipos de gráficos reales: `.lines`, `.bars` y `.points`.
    
    Cada una de ellas soporta un rango de parámetros para modificar, por ejemplo, el ancho de las líneas, los tamaños de los puntos, etc. Para verificar todos los parámetros disponibles, revise la documentación en la aplicación.
    
    Puede ver algunos de los parámetros demostrados en la siguiente expresión:
    

timelion 
.es().bars(), .static(50).points(symbol=cross, radius=2), .static(60).lines(width=5) 

    ![Tres líneas en distintos estilos: barras, puntos y una línea más gruesa][8]
    
    #### Colores
    
    Para especificar manualmente un color para una serie específica, use la función `.color`. Espera el color como un nombre de color HTML o un valor hexadecimal en formato `#rrggbb`. El siguiente ejemplo ilustra el uso:
    

timelion 
.es(q=error).color(#FF0000), .es(q=warning).color(yellow) 

    Si usó el parámetro `split` y como tal tiene múltiples líneas, puede especificar múltiples colores separados por dos puntos:
    

timelion 
.es(split=country:3).color('hotpink:grainsboro:plum') 

    ### Funciones matemáticas
    
    Timelion ofrece varios cálculos matemáticos en series temporales.
    
    Puede encadenar la función `.abs`, si desea que el eje Y muestre los valores absolutos. Puede usar la función `.log` para calcular el logaritmo de todos los valores (y opcionalmente especificar una base logarítmica).
    

timelion 
.static(-5).abs(), .static(1707).log(26) 

    ![Dos líneas, una en y=5 y otra en y=2,2843, que es log(1707)/log(26)][9]
    
    La función `.cusum` puede usarse para calcular la suma acumulativa de todos los valores, es decir, el valor en un punto específico en el tiempo es el valor de todos los puntos previos resumidos. Note que la suma acumulativa solo se calcula desde el punto de tiempo inicial del gráfico y no desde el principio de los tiempos.
    
    La función `.derivative` se puede usar para calcular la derivada de una serie temporal, es decir, la inclinación de la curva:
    

timelion 
.es(), .es().derivative().label(derivative) 

    ![Un gráfico que muestra una curva y la derivada de esta][10]
    
    La función `.mvavg` (long `.movingaverage`) se puede usar para suavizar series uniformes, aplicando una [media móvil](https://www.elastic.co/guide/en/elasticsearch/reference/5.5/search-aggregations-pipeline-movavg-aggregation.html) a las series. Esta función requiere su primer parámetro (`window`), que especifica el tamaño de la ventana como un valor y una unidad de tiempo (vea compensación arriba), que se usa para calcular la media móvil.
    
    La siguiente expresión y su resultado demuestran el efecto suavizante de la media móvil:
    

timelion 
.es().color(#DDD), .es().mvavg(5h) 

    ![El resultado de la serie temporal regular y una curva suave delante de ella][11]
    
    ### Tendencia
    
    Otra característica útil de Timelion es la posibilidad de dibujar líneas de tendencias en un gráfico. En cambio, puede usar la función de encadenamiento `.trend` en cualquier serie para dibujar la línea de tendencia de esa serie.
    
    Para dibujar una línea de tendencia del PBI mundial (y el PBI mundial real), puede usar la siguiente expresión:
    

timelion 
.wbi(indicator=NY.GDP.MKTP.CD).trend(), .wbi(indicator=NY.GDP.MKTP.CD).color(#AAA) 

    ![Se muestra una línea de tendencia lineal y el PBI mundial][12]
    
    ### Diferentes escalas
    
    Agregar múltiples series en un gráfico a veces generará el problema de que los valores de ambas series están en escalas totalmente distintas.
    
    Veamos la siguiente expresión, que dibuja el PBI de Alemania (en USD) y la emisión de CO2 (en toneladas métricas per cápita) en un gráfico:
    

timelion 
.wbi(country=de, indicator=NY.GDP.MKTP.CD), .wbi(country=de, indicator=EN.ATM.CO2E.PC) 

    Afortunadamente, estas dos series están en un orden de magnitud distinto, lo que haría que el PBI resulte claramente visible en el gráfico y la emisión de CO2 simplemente se muestre como una línea plana en la parte inferior del gráfico.
    
    Si no estamos interesados en los valores reales, sino solo en la forma en que cambia la curva con el tiempo, podemos usar la función `.range` para limitar una serie a un nuevo rango de valores, es decir, reescribiendo el valor máximo y mínimo de las series pero dejar la forma intacta.
    

timelion 
.wbi(country=de, indicator=NY.GDP.MKTP.CD).range(0, 10), .wbi(country=de, indicator=EN.ATM.CO2E.PC).range(0, 10) 

    ![Dos series ahora alrededor de la misma escala][13]
    
    De esa forma ahora podemos ver cómo esas dos series pueden tener correlación o no. *Sin duda, nunca debe olvidar que esa correlación no implica relación causal.*
    
    Podemos simplificar la consulta anterior usando la funcionalidad de agrupación de timelion, en la que podemos agrupar múltiples series con paréntesis y encadenar una función al grupo entero:
    

timelion 
(.wbi(country=de, indicator=NY.GDP.MKTP.CD), .wbi(country=de, indicator=EN.ATM.CO2E.PC)).range(0,10) 

    Como perdimos los valores reales con la consulta del rango, en nuestro caso la función `.yaxis` podría ser un poco más práctica. Asignará una serie a un eje X distinto. Debe especificar la cantidad de ejes que debe estar usando (donde 1 es el eje Y predeterminado). Opcionalmente, puede hacer uso de los parámetros `min`, `max`, `label`, `color` y `position` para modificar ese eje Y.
    
    Para alcanzar ahora el efecto similar como con la consulta `.range` pero sin perder los valores reales, puede usar la siguiente expresión para mover las dos series a distintos ejes y.
    

timelion 
.wbi(country=de, indicator=NY.GDP.MKTP.CD), .wbi(country=de, indicator=EN.ATM.CO2E.PC).yaxis(2) 

    ![Las dos mismas series anteriores pero con dos ejes Y][14]
    
    Hay otro problema de escalas que puede resolver difícilmente con las visualizaciones tradicionales de Kibana. Imagine que está dibujando la suma de bytes de sus datos de registro del servidor. Si observa datos de una semana completa, cada punto de datos en el eje X ahora representa una hora de datos, por lo tanto, tiene la suma de todos los bytes transferidos en una hora como un valor. Al seleccionar un intervalo de tiempo distinto, por ejemplo, cuatro horas, cada punto de datos ahora representará un minuto, por lo tanto tendrá un valor de eje Y mucho menor. Los siguientes gráficos muestran esta situación, en la que el gráfico de la izquierda es un rango de una semana y el de la derecha un rango de cuatro horas. Como puede ver, los valores del eje Y en el gráfico de la izquierda son mucho mayores.
    
    ![Dos gráficos con los valores del eje Y mucho mayores en el gráfico de la izquierda][15]
    
    A veces, ese comportamiento no es lo que desea porque es posible que quiera comparar valores absolutos entre ellos sin importar el intervalo de tiempo que está viendo, o quiere que estos valores sean significativos para usted, por ejemplo, porque quiere ver todos los valores en *bytes por segundo*, ya que podría usarse para calcular el ancho de banda en esa unidad.
    
    La función `scaled_interval` resuelve exactamente ese problema. Toma un parámetro (llamado `interval`), que acepta una unidad temporal (como se vio anteriormente). Timelion calculará todos los valores para que sean *para este intervalo* sin importar el intervalo temporal que está mirando. Para ver los *bytes por segundo*, especifique el valor de `1s`, para ver los *bytes por minuto* un valor de `1m`:
    

timelion 
.es(metric=sum:bytes).scaled_interval(1s) 

    Esto no cambiará la forma del gráfico de ninguna manera, simplemente escalará los valores impresos en el eje Y que puede ver cuando desplaza el puntero sobre el gráfico.
    
    ### Cálculo con series
    
    Otra de las grandes ventajas de timelion es la capacidad de calcular con series. Puede sumar, restar, multiplicar o dividir series por números o incluso por otras series.
    
    Un caso práctico de esto es configurar información en relación a otras informaciones. Si usamos los datos de nuestro servidor web de muestra para analizar las visitas de Alemania en comparación con las de Estados Unidos, podemos usar la siguiente expresión con el resultado mostrado:
    

timelion 
.es(de), .es(us) 

    ![Se observan los registros del servidor con valores altos para EE. UU. y valores bajos para Alemania.][16]
    
    Como podemos ver, tenemos algunos visitantes más de EE. UU. que de Alemania pero, por supuesto, EE. UU. tiene una población bastante mayor que Alemania. Podemos usar timelion para dividir cada serie por la población real de ese país que obtenemos del Banco Mundial de la siguiente manera:
    

timelion 
.es(de).divide(.wbi(country=de)), .es(us).divide(.wbi(country=us)) 

    ![Se observa la curva de Alemania ahora mucho mayor que la curva de EU. UU.][18]
    
    Ahora podemos ver que alcanzamos en Alemania un porcentaje mayor de población que en EE. UU.
    
    Puede usar todas las operaciones básicas a través de la función `.add` (o `.plus`), `.subtract`, `.multiply` y `.divide`. Cada una acepta un valor estático u otra serie (como en el ejemplo anterior).
    
    #### Selección condicional
    
    Timelion ofrece una función `.min` y `.max`. Estas tomarán una lista de series múltiples o valores numéricos y siempre devolverán el mínimo de todas las series/los valores numéricos o el máximo (según la función que usó).
    
    De esa forma, podría, por ejemplo, fijar un gráfico en un valor específico:
    

timelion 
.min(.es(), 25) 

    ![Una serie de datos fijados en 25][19]
    
    Otro caso práctico para usar `.min` y `.max` es colorear los gráficos condicionalmente. Por ejemplo, podría resaltar una serie si cruza un umbral específico (en este caso, 25) de la siguiente manera:
    

timelion 
.es().bars(stack=false).color(#F44336), .min(.es(), 25).bars(stack=false).color(#8BC34A) 

Esto primero dibujará los datos regulares .es() como barras en color rojo y luego dibujará los mismos datos pero limitados a 25 en color verde. De esa manera, las barras verdes se dibujarán sobre el color rojo y las barras rojas solo se mostrarán sobre el umbral de 25.

Si desea una solución más compleja para la selección condicional, puede usar la función .if (o la forma larga .condition) para proporcionar una condición y valores si la condición es verdadera o falsa.

Rashid Khan publicó un artículo excelente llamado I have but one .condition(), que explica estas funciones en detalle y muestra hermosos casos prácticos de uso.

¿Qué sigue?

Como hemos visto en este tutorial, Timelion ofrece un amplio rango de características y posibilidades. Algunas de ellas no se ofrecen con las visualizaciones tradicionales, aunque el conjunto de características de visualizaciones tradicionales está creciendo rápido; los gráficos combinados, las agregaciones de procesos y mucho más son algunas de las excelentes nuevas características. También adopta un enfoque diferente al usar un lenguaje de expresión en lugar de un editor de IU tradicional.

Si desea continuar aprendiendo sobre Timelion, recomendaría recurrir a la Getting Started Guide (Guía de introducción) en la documentación.

Si está tratando de hacer cálculos más complejos, Mathlion es un complemento gratuito para cálculos matemáticos avanzados en timelion que vale la pena. Davide Bortolami escribió una publicación excelente sobre Computation near the visualization layer, que explica los antecedentes y los casos de uso de Mathlion.

Desde Kibana 5.4, se ha presentado una nueva y experimental Time Series Visual Builder. Ofrece mucho de la funcionalidad de timelion (e incluso más) pero usando un editor gráfico en lugar de un lenguaje de expresión. Desde Kibana 5.5, timelion y el editor gráfico de series temporales no son similares en cuanto a características. Posiblemente quiera probarlos a los dos y ver cuál satisface mejor sus necesidades.