CONTENEDOR D CONTENEDOR DE KP EDOR DE KP

CONTENEDOR DE KP
DICIEMBRE 2014
Versión 1
1 INDICE
1
INDICE ................................................................
................................................................................................
............................................ 2
2
INTRODUCCIÓN ..............................................................................................................................
................................
.............................. 3
2.1
OBJETIVOS Y ALCANCE
CANCE DEL PRESENTE DOCUMENTO
D
................................................................
.................................... 3
3
DESCRIPCIÓN DEL CONTENEDOR
ENEDOR DE KPS SOFIA2 ................................................................
............................................ 4
4
CARACTERISTICAS DE KPS
PS CONTENIDOS .........................................................................................
......................... 5
5
4.1
DIRECTORIO DE EJECUCIÓN:................................................................................................
................................
................................... 5
4.2
MENSAJES A ENVIAR AL SIB: ................................................................................................
................................
.................................. 5
4.3
FORMATO DE MENSAJES ................................................................................................
................................
........................................ 5
4.4
LOGS................................................................
................................................................................................
.................................. 6
4.5
CÓDIGOS DE RESPUESTA ................................................................................................
................................
........................................ 7
4.6
FICHEROS EJECUTABLES................................................................................................
................................
......................................... 8
4.7
PROPIEDADES DE UN KP ................................................................................................
................................
........................................ 9
CONSOLA DE ADMINISTRACIÓN
ACIÓN ................................................................................................
................................... 10
5.1
ALTA DE UN NUEVO KP EN EL CONTENEDOR DE KPS ................................................................
................................. 10
5.2
LISTADO DE KPS EN CONTENEDOR DE KPS ................................................................
.............................................. 12
5.3
CONSULTA Y MONITORIZACIÓN
CIÓN DE UN KP EN EL CONTENEDOR ...................................................
................... 13
Página 2/15
2 INTRODUCCIÓN
2.1
Objetivos y alcance del presente documento
En este documento se describe el funcionamiento del contenedor de KPs de Sofia2. Contiene
información de interés para cualquier programador de KPs que vayan a ser desplegados en el
contenedor de KPs de Sofia2.
Página 3/15
3 DESCRIPCIÓN DEL CONTENEDOR DE KPs SOFIA2
El contenedor de KPs de Sofia2 consiste en un entorno para la ejecución de KPs
desplegados por usuarios privilegiados de la plataforma.
Libera a estos usuarios colaboradores de la necesidad de disponer de un entorno físico
de máquinas para ejecutar sus KPs, proporcionándoles una infraestructura 24x7 con
conectividad al SIB Sofia2 para ejecutarlos
ejecutar
KPs.
En la Versión 2 del contenedor de KPs desplegado en la Release Sofia2 2.15 se
soportan 3 tipos de KPs:
•
KPs Python: Scripts
ripts en lenguaje de programación Python.
•
KPs Java:: Ficheros jar comprimidos como jar ejecutables.
•
KPs URL:: URL accesible desde el contenedor de KPs (internet o intranet) que
ante una petición HTTP devuelva uno o varios mensajes a enviar al SIB.
La ejecución de un KP consiste en invocaciones programadas mediante una expresión
CRON. Una vez se cumple la condición temporal del CRON, el contenedor invoca al
KP para su ejecución, teniendo un límite temporal para finalizar o de lo contrario el
contenedor
or de KPs abortará la ejecución.
Una vez finaliza la ejecución un KP, el contenedor procede a recuperar los mensajes
generados
erados y los persiste y los envía al SIB.
Página 4/15
4 CARACTERISTICAS DE KPs CONTENIDOS
Los KPs contenidos en el contenedor de KPs deben cumplir un conjunto de requisitos para
integrarse con este:
4.1
Directorio de Ejecución:
Los KPs de tipo Java y Python se despliegan físicamente en el contenedor de KPs en un
directorio donde pueden crear ficheros (logs y mensajes) y leer recursos (properties).
(prop
4.2
Mensajes a enviar al SIB:
Un KP puede generar tras su ejecución uno o varios mensajes para que sean recogidos por el
contenedor y enviados al SIB de Sofia2.
Estos mensajes serán recogidos por el contenedor y serán enviados en nombre del KP al SIB.
Esto es, a efectos de autenticación/autorización se utilizarán las credenciales del propio KP.
Los mensajes se informan al SIB tras la ejecución de la siguiente manera:
•
KPs Java y Python:: Creando el propio KP uno o varios ficheros de mensajes, que el
contenedor identificará por el nombre, ya que durante el alta del KP en la consola de
administración, se informará el prefijo en el nombre de estos ficheros.
•
URL: Devolviendo en el cuerpo de la respuesta HTTP el listado de mensajes a enviar al
SIB.
En el caso de mensajes informados por ficheros, será el propio contenedor de KPs quien borre
tales ficheros una vez haya leído los mensajes y persistido para su envio al SIB.
4.3
Formato de mensajes
Cada mensaje generado por un KP tras su ejecución para ser recogidos
recogidos por el contenedor de
KPs, tendrán el siguiente formato de objeto JSON, siendo el contenedor quien construya y
envie al SIB un mensaje SSAP INSERT con la información del mensaje:
{<ontologia>:{<instancia_ontologia}}
Por ejemplo el siguiente objeto representaria un mensaje SSAP INSERT sobre la ontologia
SensorTemperatura:
Página 5/15
{"SensorTemperatura":{ "Sensor": { "geometry": { "coordinates": [ 40.512967, -3.67495 ],
"type": "Point" }, "assetId": "S_Temperatura_00066", "measure": 25, "timestamp": {
"$date": "2014-04-29T08:24:54.005Z"}}}}}
29T08:24:54.005Z"}}}}}
Dependiendo del tipo de KP, los mensajes serán
serán informados al contenedor de una forma u otra:
•
KPs Java y Python:: Fichero de texto donde cada línea contiene un objeto JSON
representando un mensaje.Tras
mensaje.
finalizar la ejecución del KP, el contenedor leerá el
fichero de texto generado línea a línea, construyendo un mensaje SSAP INSERT con
cada una. En un mismo fichero es posible generar mensajes haciendo referencia a
diferentes ontologías.
Por
or ejemplo, el siguiente fichero seria un
u fichero válido:
{"SensorTemperatura":{ "Sensor": { "measure": 25, "timestamp": { "$date": "2014-04
"2014 04-29T08:24:55.005Z"}}}}
{"SensorTemperatura":{ "Sensor": { "measure": 24,
2 "timestamp": { "$date": "2014-04
04-29T08:25:25.005Z"}}}}
{"SensorTemperatura":{
":{ "Sensor": { "measure": 25,
2 "timestamp": { "$date": "2014-04
04-29T08:25:55.005Z"}}}}
{"SensorTemperatura":{ "Sensor": { "measure": 26,
2 "timestamp": { "$date": "2014-04
04-29T08:26:25.005Z"}}}}
{"SensorTemperatura":{ "Sensor": { "measure": 27,
2 "timestamp": { "$date": "2014-04
04-29T08:26:55.005Z"}}}}
{"SensorTemperatura":{ "Sensor": { "measure": 26,
2 "timestamp": { "$date": "2014-04
04-29T08:27:25.005Z"}}}}
•
KPs URL: Respuesta HTTP de tipo mime application/json conteniendo en el cuerpo
de la misma un Array JSON con cada uno de los objetos respresentando un mensaje a
enviar al SIB.
Por ejemplo, el siguiente Array JSON en el cuerpo de la respuesta seria una respuesta
válida:
[
{"SensorTemperatura":{ "Sensor": { "measure": 25, "timestamp": { "$date": "2014-04
04-29T08:24:55.005Z"}}}},
{"SensorTemperatura":{ "Sensor": { "measure": 24,
2 "timestamp": { "$date": "2014-04
04-29T08:25:25.005Z"}}}},
{"SensorTemperatura":{ "Sensor": { "measure": 25,
2 "timestamp": { "$date": "2014-04
04-29T08:25:55.005Z"}}}},
{"SensorTemperatura":{
eratura":{ "Sensor": { "measure": 26,
2 "timestamp": { "$date": "2014-04
04-29T08:26:25.005Z"}}}},
{"SensorTemperatura":{ "Sensor": { "measure": 27,
2 "timestamp": { "$date": "2014-04
04-29T08:26:55.005Z"}}}},
{"SensorTemperatura":{ "Sensor": { "measure": 26,
2 "timestamp": { "$date": "2014-04
04-29T08:27:25.005Z"}}}}
]
4.4
Logs
Los KPs de tipo Java y Python pueden generar durante su ejecución uno o varios ficheros de
trazas. Estas trazas serán descargables desde la consola de Administración en un fichero zip.
Los ficheros
ros de trazas deben ser generados por el propio programa del KP durante en su
directorio de ejecución.
Página 6/15
El contenido de los ficheros de trazas es libre, ya que el contenedor de KPs no lo analiza.
Únicamente es necesario informar durante la creación del KP en
en la consola de Administración
el prefijo que tendrán como nombre estos ficheros de trazas.
Los ficheros de trazas son descargables desde la consola de administración. Una vez se
solicita al contenedor la descarga de las trazas, el contenedor escanea el directorio
di
de
ejecución del KP buscando ficheros cuyo nombre comience por el prefijo indicado y los
empaqueta en un zip para descargar.
4.5
Códigos
digos de respuesta
Un KP ejecutado en el contenedor de KPs debe finalizar siempre su ejecución tras un tiempo
determinado.
En caso de no finalizar en el tiempo que tenga asignado, será el contenedor de KPs quien
aborte su ejecución.
Los códigos de respuesta válidos interpretables por el contenedor de KPs son:
•
KPs Java y Python: Finalizarán su ejecución devolviendo en la función main un entero
interpretable por el contenedor de KPs:
o
0
(EXIT_SUCCESS)
(EXIT_SUCCESS):
Finalización
satisfactoria.
El
contenedor
de
KPs
contabilizara la ejecución como satisfactoria y procederá a leer los
l ficheros de
mensajes generados para generar los mensajes de INSERT.
o
1
(EXIT_FAILURE_WITH_MESSAGES)
(EXIT_FAILURE_WITH_MESSAGES):
Finalización
errónea
pero
con
mensajes.. El contenedor de KPs contabilizará la ejecución como errónea, pero
considerará que los ficheros de mensajes generados
generados contienen mensajes a
enviar al SIB y procederá a su lectura.
o
2
(EXIT_FAILURE_DISCARDING_MESSAGES):
Finalización
err
errónea.
El
contenedor de KPs contabilizará la ejecución
ejecución como errónea y descartará los
ficheros de mensajes generados por el KP durante la ejecución.
•
KPs URL: Devolverán un código HTTP de respuesta:
respuesta
o
200 (HTTP_OK): Finalización satisfactoria. El contenedor de KPs contabilizará la
ejecución como satisfactoria y leerá el cuerpo de la respuesta para generar los
mensajes de INSERT.
o
Otro código: Finalización errónea. El contenedor de KPs contabilizará le
ejecución como errónea y no generará mensajes de INSERT.
Página 7/15
4.6
Ficheros Ejecutables
Los Kps Python y Java necesitan la subida al contenedor de un fichero ejecutable, de manera
que debe cumplir ciertas características para poder ser ejecutado por el Runtime
correpondiente.
•
KPs Java: Deben ser empaquetados en un fichero JAR autoejecutable. Esto es:
Dentro del JAR se deben incluir todas aquellas clases necesarias para la
o
ejecución del KP que no estén incluidas
incluidas en las librerías de la JRE del
contenedor.
Debe incluirse un punto de entrada al programa. Esto es, una clase con un
o
método main que controla el inicio y finalización del programa.
Debe indicarse el punto de entrada al programa en un fichero MANIFEST.MF
M
o
indicando la clase donde está el método main mediante la propiedad MainMain
Class:
Main-Class:
Class: com.indra.kp.Main
Por ejemplo, un KP java a desplegar en el contenedor tendría esta estructura:
Donde:
o
Main.class:: Clase que contiene el método
m
main que actua de punto de
entrada al programa Java.
o
MANIFEST.MF Descriptor del ejecutable Java:
MANIFEST.MF:
Manifest-Version:
Version: 1.0
Class-Path:
Path: .
Main-Class:
Class: com.indra.kp.Main
•
KPs Python: Deben ser desplegados como scripts Python. Esto es:
o
Deben desplegarse en un fichero que contenga una función main que actue de
punto de entrada al programa e incluir todos los import y funciones necesarias
para su ejecución.
Página 8/15
4.7
Propiedades de un KP
Durante el alta de un KP en el contenedor de KPs es posible registrar
registrar en la consola de
administración un conjunto de propiedades que podrá leer el KP durante su ejecución.
En función del tipo de KP de que se trate, las propiedades serán interpretadas por el
contenedor de una forma o otra:
•
KPs Java y Python: El contenedor
contenedor de KPs creará en el directorio de ejecución del KP
un fichero que contendrá todas las propiedades registradas en formato:
<nombre_propiedad>=<valor>
Por ejemplo:
Propiedad1=valor1
Propiedad2=valor2
Propiedad3=valor3
De manera que el programador del KP podrá leer dichas propiedades leyendo el fichero
de propiedades creado por el KP en su directorio de ejecución.
El contenedor de KPs creará el fichero de propiedades con el mismo nombre que el KP,
pero con extensión .properties
•
KPs URL: En este tipo de KPs
KPs se diferencian dos tipos de propiedades:
o
Argumentos de Cabecera: El contenedor de KPs añadirá a la cabecera de la
petición HTTP las propiedades de este tipo.
o
Argumentos de Consulta: El contenedor de KPs añadirá a la URL los
parámetros indicados de este tipo.
t
Página 9/15
5 CONSOLA DE ADMINISTRACIÓN
La consola de administración de Sofia2 integra las funcionalidades del contenedor de KPs.
El contenedor de KPs es accesible desde el menú:
menú
5.1
Alta de un nuevo KP en el contenedor de KPs
Para dar de alta un nuevo KP en el contenedor de KPs de Sofia2 se dispone en la consola de
administración la opción: Contenedor KP’s/APPs > Crear KPs/APPs en contenedor
Página 10/15
En esta pantalla es necesario especificar información acerca del KP que se va a dar de alta.
La información
formación común independientemente del tipo de KP es:
o
KP:: Identificador del KP registrado en Sofia2 al que pertenece el KP a registrar en el
contenedor.
o
Instancia de KP:: Identificador de KP a registrar en el contenedor
o
Tipo de contenedor de KP:
K : En la versión actual todos son los KPs son temporizados y
se lanzan periódicamente conforme a la expresión CRON.
o
Lenguaje:: Lenguaje de programación del KP, permite al contenedor seleccionar el
runtime con el que lanzar el KP.
o
Timeout:: Tiempo en segundos que el contenedor asigna al KP para completar su
ejecución. Si el KP no finaliza en dicho tiempo, el contenedor aborta la ejecución.
o
Descripción:: Descripción informativa del contenedor.
En función del lenguaje elegido será necesario informar también:
o
Lenguaje Java o Python:
Python
o
Programa: Fichero ejecutable con el código del programa a ejecutar por el
contenedor.
o
Nombre del programa: Nombre que el contenedor dará al programa en el
contenedor.
o
Prefijo de ficheros de mensajes: Prefijo que tendrán los ficheros de mensajes
generados por el fichero ejecutable. Será lo que el contenedor utilice para
o
Propiedades: Pares de clave-valor
clave valor con las propiedades que necesita el
programa. Estas propiedades se utilizan por el contenedor de KPs para crear un
fichero en el directorio
directorio de ejecución con dichas propiedades.
propiedades El fichero de
propiedades tendrá el mismo nombre que el programa junto con la extensión
.properties.
De este modo si se definen para el programa MiPrograma las siguientes
propiedades:
El contenedor creará el fichero
fi
MiPrograma.properties en su directorio de
ejecución con el siguiente contenido:
Página 11/15
Propiedad2=valor2
Propiedad3=valor3
Propiedad1=valor1
o
Lenguaje de tipo URL::
o
URL: Dirección
n a la que el contenedor hará las peticiones HTTP GET cada vez
que se ejecute.
o
Parámetros Cabecera HTTP: Lista de pares clave-valor
valor a incluir en la cabecera
de la petición HTTP GET.
o
Parámetros de la petición HTTP: Lista de pares clave--valor con los query
param a añadir a la petición HTTP.
5.2
Listado de KPs en contenedor de KPs
Para consultar el listado de KPs en el contenedor de KPs de Sofia2 se dispone en la consola
de administración la opción: Contenedor KP’s/APPs > Mis KPs/APPs en Contenedor
Página 12/15
Desde esta pantalla es posible buscar filtrando por nombre e identificador de instancia, la lista
de KPs que tenemos registrados en el contenedor de KPs.
Asimismo, desde la lista de KPs tenemos acceso a las opciones de Consulta, Actualización y
borrado de un KP en el contenedor.
5.3
Consulta y monitorización de un KP en el contenedor
Desde la pantalla de listado de KPs es posible visualizar un KP con el estado actual de todas
sus propiedades:
Página 13/15
Así como administrar ciertos aspectos de su ejecución tales como:
•
Logs:: Es posible descargar en un fichero zip los ficheros de logs generados por un KP
así como borrarlos.
•
Mensajes Erroneos: Son mensajes generados por el KP y que tras intentar su envio al
SIB como un mensaje de tipo INSERT, el contenedor de KPs ha descartado
descar
por alguna
razón Es posible tanto descargar en un fichero estos mensajes, como borrarlos.
•
Estado: Es posible detener la ejecución de un KP de manera que mientras se
encuentre detenido, el contenedor de KPs no procederá ejecutarlo aunque se cumplan
las condiciones especificadas en la expresión CRON.
Página 14/15
Y monitorizar la ejecución del KP obteniendo la siguiente información:
•
Número total de ejecuciones.
•
Número
mero de ejecuciones abortadas por el contenedor
•
Número
mero de ejecuciones finalizadas devolviendo un código de error.
•
Tiempo total de ejecución consumido por el KP en el contenedor.
•
Tiempo médio de cada ejecución.
•
Número de mensajes enviados satisfactoriamente al SIB.
•
Número de mensajes leidos por el contenedor y almacenados para envio al SIB.
•
Número de mensajess erroneos tras su envio al SIB
Página 15/15