From 4eccdc93d3d5d4747ef35f7450dee14caa6f3464 Mon Sep 17 00:00:00 2001 From: Egutierrez Date: Mon, 23 Mar 2026 23:41:04 +0100 Subject: [PATCH] docs: add Marquez utilities documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- MARQUEZ_UTILITIES.md | 409 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 409 insertions(+) create mode 100644 MARQUEZ_UTILITIES.md diff --git a/MARQUEZ_UTILITIES.md b/MARQUEZ_UTILITIES.md new file mode 100644 index 0000000..6823c76 --- /dev/null +++ b/MARQUEZ_UTILITIES.md @@ -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 -inputs "file:///a" -outputs "file:///b" + +# Completar exitosamente +marquez-cli run complete -job my_job -run-id -outputs "postgres://table" + +# Marcar como fallido +marquez-cli run fail -job my_job -run-id +``` + +### 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)