Programa que se encarga de descargar y procesar datos de viajes y transacciones Transantiago.
El proyecto se encuentra desarrollado en Python 3.8 y utiliza los siguientes servicios de Amazon Web Services para su funcionamiento: EC2, S3 y Cloudwatch.
Para no tener conflictos de dependencias se recomienda hacer uso de un entorno virtual, este puede ser creado usando la librería virtualenv.
# instalar librería virtualenv
pip install virtualenv
# crear entorno virtual
virtualenv venv
# activar entorno virtual
source venv/bin/activate
Las librerías necesarias para ejecutar el proyecto están definidas en el archivo requirements.txt
ubicado en la raíz del proyecto y se pueden instalar rápidamente con el comando:
pip install -r requirements.txt
Además para agregar el comando adatrap_miner a las variables de ambiente se debe ejecutar:
pip install -e .
El funcionamiento del programa se requieren las credenciales de un usuario AWS con permisos AmazonEC2FullAccess, AmazonS3FullAccess, AmazonS3FullAccess, CloudWatchAgentServerPolicy y CloudWatchAgentAdminPolicy. Los siguientes pasos detallan como crear un usuario AWS con los permisos necesarios.
Para crear un usuario nuevo se debe acceder a la plataforma IAM de AWS en la sección usuarios y seleccionar la opción Add User:
Posteriormente se debe escribir un nombre de usuario en User name, marcar la casilla Programmatic access y avanzar al siguiente paso haciendo click en el botón Next: permissions.
En esta sección se darán los permisos de EC2, S3 y Cloudwatch al usuario. Para esto debe seleccionar la opción Attach existing policies directly. Posteriormente en el cuadro de búsqueda buscar EC2Fullaccess y marcar las casillas AmazonEC2FullAccess, AmazonS3FullAccess, CloudWatchAgentAdminPolicy, CloudWatchAgentServerPolicy y AmazonSSMFullAccess
Finalmente se puede ir al siguiente paso Next: Tags.
Opcionalmente se pueden añadir etiquetas para identificar o almacena datos referente al usuario. Ir al paso siguiente Next Review.
En esta sección se debe revisar que todos los datos estén correctos y avanzar al siguiente
El usuario ha sido creado exitosamente, por lo que es importante guardar sus credenciales en la sección download.csv
. Ambas credenciales Access key ID y Secret access key serán utilizadas para la configuración del proyecto.
Se debe crear un archivo .env en la raíz del proyecto el cual incluirá las credenciales y otra información en el siguiente formato:
# Id de acceso creado en el paso anterior.
AWS_ACCESS_KEY_ID=
# Clave de acceso creado en el paso anterior
AWS_SECRET_ACCESS_KEY=
# Región donde se ubicará la instancia EC2 (Ejemplo: us-east-1)
REGION_NAME=
# Id de la imagen a utilizar en la instancia EC2 (Ejemplo: ami-0b697c4ae566cad55, imagen de Microsoft Windows Server 2019 Base)
AMI_ID=
# Nombre de la máquina ec2 a utilizar (ej: t2.micro)
INSTANCE_TYPE=
# Par de claves para acceso ec2 (Si se desea crear una nueva key pair dejar un nombre por defecto.)
KEY_PAIR=
# Nombre de log de grupo Cloudwatch
LOG_GROUP=
# Id para el log general
GENERAL_LOG_STREAM=
# Bucket donde se encuentra ejecutable ADATRAP
EXECUTABLES_BUCKET=
# Bucket de gps
GPS_BUCKET_NAME=
# Bucket de po
OP_PROGRAM_BUCKET_NAME=
# Bucket de archivo 196
FILE_196_BUCKET_NAME=
# Bucket de transacciones
TRANSACTION_BUCKET_NAME=
# Bucket S3 donde se almacenan los resultados de ADATRAP
OUTPUT_DATA_BUCKET_NAME=
# Bucket S3 donde se almacena el archivo de detalle de servicios
SERVICE_DETAIL_BUCKET_NAME=
# Version de ejecutable ADATRAP
EXECUTABLE_VERSION=
Para obtener el ID (AMI_ID) de la imagen a utilizar se debe buscar dentro de las disponibles para el usuario AWS. Por ejemplo, en este link se encuentra un listado de imágenes disponibles.
Para la creación de instancias EC2 y el manejo de estas se requiere tener una keypar para poder acceder a las instancias creadas en python. Para esto el programa tiene un comando que permite la creación de un keypar dado los datos de usuario en el archivo .env (variables AWS_ACCESS_KEY_ID y AWS_SECRET_ACCESS_KEY).
Este comando crea una keypair con el nombre dado como argumento o ec2-keypair por defecto, la cual se registra en AWS y se almacena localmente en la raíz del proyecto.
Para crear un keypar se debe ejecutar:
adatrap_miner create-key-pair [key-pair-name]
Si todo resulta correcto se obtendrá el siguiente mensaje:
INFO:__main__:¡Keypair creado exitosamente! El archivo ec2-keypair.pem se encuentra en la raíz del proyecto.
En caso de que la keypar exista el programa arrojará un error:
ERROR:__main__:El keypair 'ec2-keypair' ya existe
Ya habiendo sido creada la keypair, esta se encontrará disponible en el panel de administración EC2 de AWS:
Después de crear la key-pair es importante agregar su nombre en la variable KEY_PAIR archivo .env
Para el funcionamiento de adatrap-Miner se requiere la creación de un log group de Cloudwatch y un log stream. Un log stream es una secuencia de eventos de log que se comparten en la misma fuente, mientras que un log group es un conjunto de log streams.
Por lo tanto adatrap-Miner utilizará el log group para crear log streams asociados a las instancias EC2 creadas. Por otra parte utilizará el log stream creado como un log general de eventos asociados al proyecto.
Para crear un Log Group se debe acceder a la plataforma Cloudwatch y seleccionar la opción Create log group.
Se debe ingresar un nombre en Log group name. En la sección Retention setting se debe seleccionar la opción "1 week" . Esto permitirá que los logs se almacenen durante una semana como máximo.
Finalmente se debe seleccionar la opción create
Es importante agregar el nombre del log group al parámetro LOG_GROUP del archivo .env
Para agregar un log stream se debe ingresar al log group creado desde la interfaz de Cloudwatch y seleccionar la opción Create log stream.
Finalmente también se debe agregar el nombre a la variable GENERAL_LOG_STREAM del archivo .env.
Para el funcionamiento del programa se requiere que las fuentes de datos se encuentren almacenada en buckets de S3. Estos datos son los siguientes:
Estos datos se deben encontrar en el formato YYYY-MM-DD.po.zip, donde YYYY-MM-DD representa desde que día es válido el diccionario. Sus archivos internos deben estar en formato gz.
El nombre del bucket asociado a los diccionarios de servicio debe ingresarse como valor en la variable OP_PROGRAM_BUCKET_NAME del archivo .env
Los datos de gps deben estar en formato YYYY-MM-DD.gps.gz donde YYYY-MM-DD representa el día donde el archivo es válido.
Se debe almacenar el nombre del bucket en la variable GPS_BUCKET_NAME del archivo .env
Estos datos deben tener el formato YYYY-MM-DD.196.gz donde YYYY-MM-DD representa el día donde el archivo es válido.
El nombre de este bucket se debe almacenar en la variable FILE_196_BUCKET_NAME del archivo .env
Los datos se deben encontrar en formato YYYY-MM-DD.trx.gz donde YYYY-MM-DD representa el día donde el archivo es válido.
El nombre del bucket se debe almacenar en la variable TRANSACTION_BUCKET_NAME en el archivo .env
Este archivo debe estar en formato Diccionario-DetalleServicioZP_YYYYMMDD_YYYYMMDD.csv.gz donde el primer el par YYYYMMDD representan desde que día hasta que día es válido el archivo.
El nombre de este bucket se debe almacenar en la variable SERVICE_DETAIL_BUCKET_NAME
El archivo ejecutable ADATRAP se debe encontrar en un bucket con el formato pvmtsc_vX.exe donde X es la versión del programa.
El archivo de configuración de ADATRAP se debe encontrar en el mismo bucket, con formato pvmtsc_vX.par donde X es la versión del archivo.
Ambas versiones de los archivos deben ser la misma para el correcto funcionamiento.
Un ejemplo de un archivo configurable de configuración compatible con la versión 0.2 se encuentra aquí
El nombre del bucket se debe almacenar en la variable EXECUTABLES_BUCKET y la versión del ejecutable en la variable EXECUTABLE_VERSION del archivo .env
Es recomendable ejecutar los tests del programa para verificar su correcto funcionamiento:
python -m unittest
Para ejecutar adatrap_miner se deben ejecutar el comando con la fecha en formato YYYY-MM-DD
adatrap_miner create-ec2-instance 2021-04-22
Si se crea la instancia correctamente se desplegará un mensaje como el siguiente:
adatrap_miner create-ec2-instance 2020-06-28
> INFO:adatrap_miner:Creando instancia para el día 2020-06-28...
> INFO:adatrap_miner:Instancia creada con id: i-074c9c8020b3e24d0 para el día 2020-06-28
> INFO:adatrap_miner:Creando log stream para instancia i-074c9c8020b3e24d0...
> INFO:adatrap_miner:Log Stream creado con nombre: i-074c9c8020b3e24d0
Al ejecutarse el comando se creará una instancia EC2 con un id. También se creará un log stream en cloudwatch con nombre del id de la instancia creada.
Este id puede ser utilizado para detener la instancia manualmente u obtener los logs asociado a su funcionamiento.
Para detener una instancia EC2 se debe ejecutar
adatrap_miner stop-ec2-instance ID
Donde ID es el id de la instancia.
Si la instancia existe se desplegará un mensaje como el siguiente:
adatrap_miner stop-ec2-instance i-01467ca70263c5b71
> INFO:adatrap_miner:Finalizando instancia con id i-01467ca70263c5b71...
> INFO:adatrap_miner:Instancia con id i-01467ca70263c5b71 finalizada.
Para obtener los logs asociados a un log stream se debe ejecutar
adatrap_miner get-log-stream LOGNAME
Donde LOGNAME es el nombre del log stream.
Si se quiere almacenar en un archivo se debe utilizar la variable -o
adatrap_miner get-log-stream LOGNAME -o OUTPUTNAME
El proceso de ejecución de ADATRAP levanta una máquina virtual con sistema operativo Windows, pueden haber situaciones donde sea necesario acceder a ella para revisar logs u otro archivo. Para realizar esta acción se deben ejecutar los siguientes pasos:
- Ir a consola de ec2 instances de aws
- Hacer click en el id de la instancia que se quiere inspeccionar
- Una vez ubicado en el detalle de la instancia, presionar el botón "connect"
- Seleccionar tab "RDP client"
- Presionar botón "get password"
- Presionar botón "browse" y seleccionar archivo .pem que se creó al momento de crear una llave para correr las instancias (este debe coincidir con la llave asociada al momento de creación de la instancia)
- Presionar botón "Decrypt Password", lo que entregará la contraseña requerida al momento de establecer la conexión
- En este punto, la consola de AWS muestra los tres parámetros necesarios para conectar:
- Public DNS
- User name
- Password
- Abrir windows remote client ("Conexión a escritorio remoto")
- Descargar archivo de conexión con formato RDP
- Abrir archivo rdp con windows remote client
- Los archivos del programa ADATRAP-miner se descargan en el disco
c:\\ - Los logs de la instalación de las dependencias son almacenados en la
ruta
\ProgramData\Amazon\EC2-Windows\Launch\Log\UserdataExecution.log - El programa adatrap_miner está asociado a la versión de python del sistema, por lo que se puede ejecutar desde cualquier consola o powershell
- Para simular una ejecución del programa se puede usar la llamada
adatrap_miner execute-adatrap. Si se agrega la opción-do--debugel programa realiza todos los pasos salvo la ejecución del programa adatrap
Es necesario que las instancias de ejecución tengan disponible el puerto 3389 para que la conexión remota sea exitosa,
para esto es necesario modificar el security group usado en ellas, que es el security group por defecto (usualmente de
nombre default). En la siguiente imagen se muestran los permisos que debe tener el security group en la
sección inbound rules.
