Refinamiento de X-Ray MVP

[milo19980525]

Se requiere revisar algunas características finales para completar el MVP de X-Ray.

Especificaciones técnicas

• El último desarrollo de X-Ray, se encuentra en rama feature/x-ray.
• El desarrollo final de X-Ray se encuentra documentado en: #81.

Sub Tareas

• [x] Documentación de implementación de X-Ray en un documento técnico que evidencie: Las características generales de X-Ray (Segmentos, trazas, configuración en AWS, métricas, costos y planeación de costos), los archivos que se han modificado transversales a la OATI, espesificaciones técnicas de las funciones y librerías utilizadas, la estrategia de implementación de X-Ray en nuevas APIs, la estrategia de implementación de X-Ray en APIs antiguas, posibles inconvenientes.
• [x] Analizar y proponer una estrategia de instrumentalización automatizada para utilizar X-Ray desde las APIs antiguas.

Criterios de aceptación

• [x] Se documenta lo requerido en un documento que se encuentre en formato Word y PDF.
• [x] Se plantea una o varias estrategias para la automatización de la instrumentalización de X-Ray en antiguas APIs.

Requerimientos

• [x] Funcionalidad de X-ray funcional con el API de cumplidos_dve_mid y cumplidos_crud.

Dependencias

• No presenta.

Definition of Ready - DoR

• [x] Está refinada y estimada en puntos de historia por el equipo.
• [x] Incluye la descripción y criterios de aceptación, con el detalle funcional y especificaciones técnicas, de forma entendible por cualquier miembro del equipo.
• [x] No tiene bloqueos que impidan su ejecución.
• [x] Las dependencias entán identificadas y resueltas.
• [x] Puede ser probada dentro del Sprint.

Definition of Done - DoD - Desarrollo

• [x] Criterios de aceptación cumplidos.
• [x] Documentación de issue realizada.
• [x] Aprobada por SM/Líder técnico.

[a52290451]

Estrategia de instrumentación de APIs CRUD en GO, con el SDK de AWS X-Ray

Inyección de código con Hygen o Script en Python

Ya sea empleando la herramienta Hygen para crea una platilla de automatización de código, o utilizando un script en Python, se deben realizar los siguientes pasos:

1. En local, ubicarse en la carpeta "/go/src/github.com/udistrital/"
2. Crear una carpeta con el nombre del API:

mkdir nombre_api

3. Ubicarse en la carpeta recién creada:

cd nombre_api

4. Clonar el repositorio en local:

git clone "link de repositorio"

5. Crear la rama "feature/X-Ray" en local:

git checkout -b feature/X-Ray

6. Descargar la dependencia de xray con:

go get -u github.com/udistrital/utils_oas

7. Ingresar al archivo main.go
8. Buscar las líneas de código "import (" y "beego.Run()".
9. Posterior a "import (", inyectar la importación del paquete xray:

"github.com/udistrital/utils_oas/xray"

10. Anterior a "beego.Run()", inyectar el inicializador de xray:

xray.InitXRay()

11. Ejecutar el comando "go mod init" en linea de comandos para actualizar el archivo "go.mod".
12. Ejecutar el comando "go mod tidy" en linea de comandos para actualizar las dependencias en el archivo "go.sum".
13. Incluir todos los cambios realizados en el área de preparación del commit con:

git add .

14. Crear el commit para subir los cambios:

git commit -m "feat: implementación de xray"

15. Realizar la subida de los cambios en la rama "feature/X-Ray"

git push origin feature/X-Ray

El resto de los pasos no se pueden automatizar ya que son al interior de cada repositorio.

Nota: esta estrategia, para la instrumentación de APIs CRUD con el SDK de AWS X-Ray para GO, puede realizarse con la automatización de código, ya sea utilizando Hygen o Python. Bastaría con ejecutar la plantilla en Hygen o el Script en Python para lograr el refactor automatico de cada API.

Prerrequisitos

1. Las APIs a ser instrumentadas deben estar codificadas en GO.
2. Las APIs deben estar ubicadas en el repositorio principal de la OATI.
3. Se debe contar con un usuario en GitHub que tenga permisos para realizar cambios en todos los repositorios.
4. En caso de utilizar Hygen, se debe tener instalado Hygen en local, junto con la plantilla del refactor de código.
5. En caso de utilizar Python, se debe instalar Python 3.x.x, crear un entorno virtual para el mismo, instalar las dependencias necesarias para ejecutar el script y ubicar el script de refactor en la carpeta "github.com/udistrital/".

[a52290451]

Estrategia de instrumentación de APIs MID en GO, con el SDK de AWS X-Ray

Para la instrumentación de APIs MID es necesario intervenir dos archivos:

1. main.go
2. utilidades.go

La intervención en el archivo "main.go" es mínima, basta con agregar dos líneas de código que representan la importación del paquete "github.com/udistrital/utils_oas/xray" y el inicializador de xray "xray.InitXRay()".

Ahora, para el archivo "utilidades.go" es necesario seguir una estructura predefinida para las peticiones entrantes y salientes que se realicen al interior del API. Actualmente, para las APIs mid no se sigue un estándar en cuanto a la realización de estas peticiones, por lo que no todas las APIs tienen el archivo utilidades.go como método de desacoplamiento, o incluso, aquellas que utilizan este archivo, no siguen un estándar definido para los métodos.

Por lo anterior, se propone la siguiente estrategia.

1. En el repositorio de utilidades de la OATI "github.com/udistrital/utils_oas" se cuenta con un paquete para GO llamado "request" en el cual se definen una serie de métodos para realizar peticiones hacia otras APIs, utilizando un estándar predefinido. El primer paso es complementar este paquete con los métodos necesarios para todas las APIs Mid e instrumentarlo con el SDK de AWS X-Ray.
2. Una vez se tenga listo el paquete "request" con todos los métodos necesarios, el siguiente paso es definir un lineamiento para que cada una de las 36 APIs MID existentes se refactoricen y realicen todas sus peticiones internas a través de este nuevo paquete. Esto implica realizar manualmente el ajuste en el código fuente de cada API. De esta forma se desacopla la realización de peticiones de las APIs y se garantiza un seguimiento completo con X-Ray de todas las solicitudes.

Nota: para la implementación de esta estrategia no se utiliza una herramienta de automatización de código ya que en cada API se presenta un caso distinto en cuanto al manejo de las peticiones, por lo que no es posible generar un estándar para aplicar una regla que permita generar código automático.

[a52290451]

El Manual Técnico para el servicio de monitoreo de AWS X-Ray presenta todos los aspectos técnicos y funcionales de su implementación en las APIs, así como otras características importantes.

[milo19980525]

@a52290451 no se ha terminado el documento técnico.

[a52290451]

Se realiza la actualización del documento técnico con la inclusión de las secciones Conclusiones y Recomendaciones.

Queda pendiente agregar mas recomendaciones asociadas al manejo de la consola AWS XRAY.

Nota: las recomendaciones asociadas a la instrumentación de APIs aún no se agregan ya que estas van de la mano con las estrategias he instrucciones de implementación.