automatic-process/MARQUEZ_UTILITIES.md

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:

cd ~/AutomaticProyects/automatic_process/tools/marquez-cli
make install

Uso:

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:

~/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:

~/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:

# 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:

# 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:

# 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:

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

# 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

# Abrir Marquez Web UI
xdg-open http://localhost:3001

# Buscar por job o dataset
# Ver grafo visual de lineage

Método 3: API REST

# 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

cd ~/AutomaticProyects/automatic_process/tools/marquez-cli
make install
marquez-cli version

2. Probar con Ejemplo

# 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

#!/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

# 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

# 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:

   ~/dagu/scripts/examples/simple_pipeline_with_lineage.sh
   

2. Verifica el lineage:

   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:

  export MARQUEZ_URL="http://localhost:5000"
  export MARQUEZ_NAMESPACE="automatic-process"
  

• Genera Run ID una sola vez y reutilízalo en todo el pipeline:

  RUN_ID=$(uuidgen)
  

• Usa trap para manejar errores automáticamente:

  trap 'marquez-cli run fail -job $JOB_NAME -run-id $RUN_ID' ERR
  

• Verifica lineage después de cada ejecución:

  marquez-cli lineage -name "postgres://table"
  

---

Última actualización: 2026-03-23 Versión: 1.0.0 Autor: Lucas (@egutierrez)