docs: add Marquez utilities documentation

Añadida guía completa de utilidades de Marquez CLI. Contenido: - Descripción del binario marquez-cli y sus capacidades - Conceptos clave: datasets, jobs, runs - Reglas de lineage tracking (SIEMPRE/NUNCA) - Métodos para recuperar lineage (CLI, Web UI, API REST) - Quick start y ejemplos de uso - Comandos útiles y tips - Referencia a ejemplos y documentación adicional Archivo: MARQUEZ_UTILITIES.md
2026-03-23 23:41:04 +01:00
parent 5f3bc84696
commit 4eccdc93d3
1 changed files with 409 additions and 0 deletions
@@ -0,0 +1,409 @@
+# Marquez CLI Utilities
+
+Utilidades en Go para gestionar **datasets**, **jobs** y **runs** con lineage tracking completo en Marquez (OpenLineage).
+
+---
+
+## 📦 ¿Qué se Creó?
+
+### 1. **Binario `marquez-cli`** (Go)
+
+Herramienta CLI completa para interactuar con Marquez:
+
+- ✅ Registrar y consultar **datasets**
+- ✅ Registrar y consultar **jobs**
+- ✅ Enviar eventos de **runs** (START, RUNNING, COMPLETE, FAIL)
+- ✅ Consultar **lineage** de datasets
+- ✅ Listar recursos (namespaces, jobs, datasets)
+- ✅ Sin dependencias externas (solo Go stdlib)
+- ✅ Binario estático de ~5MB
+
+**Ubicación**: `~/AutomaticProyects/automatic_process/tools/marquez-cli/`
+
+**Instalación**:
+```bash
+cd ~/AutomaticProyects/automatic_process/tools/marquez-cli
+make install
+```
+
+**Uso**:
+```bash
+marquez-cli help
+marquez-cli version
+```
+
+---
+
+### 2. **Scripts de Ejemplo**
+
+#### a) `simple_pipeline_with_lineage.sh`
+
+Pipeline simple que demuestra:
+- Generación de Run ID
+- Eventos START, RUNNING, COMPLETE
+- Tracking de transformaciones
+- Manejo de errores
+
+**Ubicación**: `~/dagu/scripts/examples/simple_pipeline_with_lineage.sh`
+
+**Uso**:
+```bash
+~/dagu/scripts/examples/simple_pipeline_with_lineage.sh
+```
+
+#### b) `etl_to_postgres_with_lineage.sh`
+
+ETL completo con carga a PostgreSQL:
+- Extract desde API
+- Transform con jq
+- Load a PostgreSQL
+- Lineage completo del flujo
+
+**Ubicación**: `~/dagu/scripts/examples/etl_to_postgres_with_lineage.sh`
+
+**Uso**:
+```bash
+~/dagu/scripts/examples/etl_to_postgres_with_lineage.sh
+```
+
+---
+
+### 3. **DAG de Ejemplo para Dagu**
+
+DAG completo con lineage tracking integrado:
+- Generación de Run ID único
+- Eventos en cada paso del pipeline
+- Handler de errores (FAIL event)
+- Handler de éxito
+- Cleanup de archivos temporales
+
+**Ubicación**: `~/dagu/dags/example_lineage_tracking.yaml`
+
+**Uso**:
+```bash
+# Ejecutar manualmente desde Dagu UI
+http://localhost:8090
+
+# O desde CLI
+dagu start example_lineage_tracking
+```
+
+---
+
+## 🎯 Conceptos Clave de Marquez
+
+### Datasets
+
+Representan **fuentes de datos** (tablas, archivos, APIs, streams).
+
+**Naming Convention**:
+```
+postgres://host:port/db/schema/table
+clickhouse://host:port/database/table
+nats://host:port/subject
+file:///absolute/path
+api://domain/endpoint
+```
+
+**Comandos**:
+```bash
+# Registrar dataset
+marquez-cli dataset register -name "postgres://localhost:5434/postgres/public/events"
+
+# Listar datasets
+marquez-cli list datasets
+```
+
+---
+
+### Jobs
+
+Representan **procesos/pipelines** que leen/escriben datasets.
+
+**Naming Convention**:
+- Usa nombres descriptivos: `fetch_api_data`, `transform_sales`
+- Evita guiones, usa guiones bajos
+- Mismo nombre que el DAG en Dagu
+
+**Comandos**:
+```bash
+# Registrar job
+marquez-cli job register -name my_pipeline
+
+# Listar jobs
+marquez-cli list jobs
+
+# Ver runs de un job
+marquez-cli job runs -name my_pipeline
+```
+
+---
+
+### Runs
+
+Representan **ejecuciones** de un job con inputs/outputs específicos.
+
+**Lifecycle**:
+1. **START** - Inicio de ejecución
+2. **RUNNING** - Progreso (opcional, múltiples)
+3. **COMPLETE** o **FAIL** - Finalización
+
+**Comandos**:
+```bash
+RUN_ID=$(uuidgen)
+
+# START
+marquez-cli run start -job my_job -run-id $RUN_ID
+
+# RUNNING (progreso intermedio)
+marquez-cli run running -job my_job -run-id $RUN_ID \
+  -inputs "file:///tmp/raw.json" \
+  -outputs "file:///tmp/clean.json"
+
+# COMPLETE
+marquez-cli run complete -job my_job -run-id $RUN_ID \
+  -outputs "postgres://table"
+
+# FAIL (en caso de error)
+marquez-cli run fail -job my_job -run-id $RUN_ID
+```
+
+---
+
+## 📋 Reglas de Lineage
+
+### ✅ SIEMPRE debes:
+
+1. **Enviar evento START** al inicio del pipeline
+2. **Usar el mismo Run ID** en todos los eventos del mismo run
+3. **Declarar TODOS los inputs** (APIs, archivos, tablas que lees)
+4. **Declarar TODOS los outputs** (archivos, streams, tablas que escribes)
+5. **Enviar evento COMPLETE** al finalizar exitosamente
+6. **Enviar evento FAIL** si hay errores (usar trap/handler)
+7. **Usar URIs bien formados** para datasets
+8. **Usar namespace consistente** (`automatic-process`)
+
+### ❌ NUNCA debes:
+
+1. Omitir el evento START
+2. Olvidar el evento COMPLETE/FAIL
+3. Cambiar el Run ID en medio del pipeline
+4. Usar nombres ambiguos para datasets
+5. Saltarte el lineage en pipelines críticos
+
+---
+
+## 🔍 Recuperar Lineage
+
+### Método 1: CLI
+
+```bash
+# Ver lineage de un dataset
+marquez-cli lineage -name "postgres://localhost:5434/postgres/public/events"
+
+# Formato JSON (para scripts)
+marquez-cli lineage -name "postgres://table" -format json
+
+# Con más profundidad
+marquez-cli lineage -name "postgres://table" -depth 20
+```
+
+### Método 2: Web UI
+
+```bash
+# Abrir Marquez Web UI
+xdg-open http://localhost:3001
+
+# Buscar por job o dataset
+# Ver grafo visual de lineage
+```
+
+### Método 3: API REST
+
+```bash
+# Ver lineage directo desde API
+curl "http://localhost:5000/api/v1/lineage?nodeId=dataset:automatic-process:postgres://table&depth=10" | jq .
+
+# Listar jobs
+curl http://localhost:5000/api/v1/namespaces/automatic-process/jobs | jq .
+
+# Ver runs de un job
+curl http://localhost:5000/api/v1/namespaces/automatic-process/jobs/my_job/runs | jq .
+```
+
+---
+
+## 🚀 Quick Start
+
+### 1. Instalar marquez-cli
+
+```bash
+cd ~/AutomaticProyects/automatic_process/tools/marquez-cli
+make install
+marquez-cli version
+```
+
+### 2. Probar con Ejemplo
+
+```bash
+# Ejecutar pipeline de ejemplo
+~/dagu/scripts/examples/simple_pipeline_with_lineage.sh
+
+# Ver lineage generado
+marquez-cli lineage -name "file:///tmp/users_clean.json"
+```
+
+### 3. Crear tu Primer Pipeline
+
+```bash
+#!/bin/bash
+set -euo pipefail
+
+JOB_NAME="my_first_pipeline"
+RUN_ID=$(uuidgen)
+
+# Manejo de errores
+cleanup() {
+  marquez-cli run fail -job $JOB_NAME -run-id $RUN_ID
+}
+trap cleanup ERR
+
+# START
+marquez-cli run start -job $JOB_NAME -run-id $RUN_ID
+
+# Tu trabajo aquí
+echo "Doing work..."
+curl https://api.example.com/data > /tmp/data.json
+
+# COMPLETE
+marquez-cli run complete \
+  -job $JOB_NAME \
+  -run-id $RUN_ID \
+  -inputs "api://example.com/data" \
+  -outputs "file:///tmp/data.json"
+
+echo "✓ Pipeline completed!"
+```
+
+---
+
+## 📊 Estructura de Archivos
+
+```
+~/AutomaticProyects/automatic_process/
+├── tools/
+│   └── marquez-cli/           # Código fuente del CLI
+│       ├── main.go            # CLI principal
+│       ├── openlineage.go     # Cliente API
+│       ├── go.mod             # Módulo Go
+│       ├── Makefile           # Build automation
+│       ├── README.md          # Documentación completa
+│       ├── QUICKSTART.md      # Guía rápida
+│       └── marquez-cli        # Binario compilado
+│
+├── MARQUEZ_UTILITIES.md       # Este archivo
+│
+~/dagu/
+├── scripts/
+│   └── examples/
+│       ├── simple_pipeline_with_lineage.sh
+│       └── etl_to_postgres_with_lineage.sh
+│
+└── dags/
+    └── example_lineage_tracking.yaml
+```
+
+---
+
+## 🔧 Comandos Útiles
+
+### Gestión de Runs
+
+```bash
+# Iniciar run con inputs/outputs
+marquez-cli run start -job my_job -inputs "api://source" -outputs "file:///tmp/data"
+
+# Marcar progreso
+marquez-cli run running -job my_job -run-id <uuid> -inputs "file:///a" -outputs "file:///b"
+
+# Completar exitosamente
+marquez-cli run complete -job my_job -run-id <uuid> -outputs "postgres://table"
+
+# Marcar como fallido
+marquez-cli run fail -job my_job -run-id <uuid>
+```
+
+### Consultas
+
+```bash
+# Ver todos los jobs
+marquez-cli list jobs
+
+# Ver runs de un job
+marquez-cli job runs -name my_job
+
+# Ver lineage completo
+marquez-cli lineage -name "postgres://localhost:5434/postgres/public/events"
+
+# Ver datasets
+marquez-cli list datasets
+```
+
+---
+
+## 📚 Documentación Adicional
+
+- **README Completo**: `~/AutomaticProyects/automatic_process/tools/marquez-cli/README.md`
+- **Quick Start**: `~/AutomaticProyects/automatic_process/tools/marquez-cli/QUICKSTART.md`
+- **CLAUDE.md**: Guía de servicios manipulables
+- **OpenLineage Spec**: https://openlineage.io/
+- **Marquez Docs**: https://marquezproject.ai/
+
+---
+
+## 🎯 Próximos Pasos
+
+1. **Ejecuta el ejemplo**:
+   ```bash
+   ~/dagu/scripts/examples/simple_pipeline_with_lineage.sh
+   ```
+
+2. **Verifica el lineage**:
+   ```bash
+   marquez-cli lineage -name "file:///tmp/users_clean.json"
+   ```
+
+3. **Adapta el patrón** a tus propios pipelines
+
+4. **Siempre sigue las reglas** de lineage tracking
+
+---
+
+## 💡 Tips
+
+- **Usa variables de entorno** para configuración:
+  ```bash
+  export MARQUEZ_URL="http://localhost:5000"
+  export MARQUEZ_NAMESPACE="automatic-process"
+  ```
+
+- **Genera Run ID una sola vez** y reutilízalo en todo el pipeline:
+  ```bash
+  RUN_ID=$(uuidgen)
+  ```
+
+- **Usa trap para manejar errores** automáticamente:
+  ```bash
+  trap 'marquez-cli run fail -job $JOB_NAME -run-id $RUN_ID' ERR
+  ```
+
+- **Verifica lineage después** de cada ejecución:
+  ```bash
+  marquez-cli lineage -name "postgres://table"
+  ```
+
+---
+
+**Última actualización**: 2026-03-23
+**Versión**: 1.0.0
+**Autor**: Lucas (@egutierrez)