Automatic Process - Suite Completa de Datos

Plataforma completa de ingesta, procesamiento y visualización de datos con lineage tracking automático.

---

🎯 Arquitectura

┌─────────────────────────────────────────────────────────────────┐
│                    DATA PIPELINE STACK                          │
└─────────────────────────────────────────────────────────────────┘

📅 SCHEDULING          🔄 MESSAGING           💾 STORAGE
┌──────────┐          ┌──────────┐          ┌──────────┐
│  Dagu    │────────→ │   NATS   │────────→ │PostgreSQL│
│ (Native) │          │JetStream │          │ClickHouse│
└────┬─────┘          └──────────┘          └──────────┘
     │                                             │
     │ ⚙️ TRANSFORMATIONS                         │
     └────────────────────────────────────────────┘
                            │
                            ↓
                    📊 LINEAGE            📈 VISUALIZATION
                    ┌──────────┐          ┌──────────┐
                    │ Marquez  │          │ Grafana  │
                    │OpenLineage│         │ Metabase │
                    └──────────┘          │   Rill   │
                            ↑             └──────────┘
                            │
                    🔍 MONITORING
                    ┌──────────┐
                    │Prometheus│
                    │   Loki   │
                    │  Alloy   │
                    └──────────┘

---

🚀 Quick Start

1. Iniciar Todos los Servicios

# Core services
docker-compose up -d

# Analytics
docker-compose -f docker-compose-analytics.yml up -d

# Databases
docker-compose -f docker-compose-databases.yml up -d

# Lineage
docker-compose -f docker-compose-marquez.yml up -d

# Messaging
docker-compose -f docker-compose-nats.yml up -d

# Orchestration (Dagu ya está corriendo como systemd)
systemctl --user status dagu.service

2. Acceder al Dashboard

Homer Dashboard: http://localhost:8080

Desde ahí puedes acceder a todos los servicios.

---

📦 Servicios Disponibles

🎨 Visualization

Servicio	Puerto	Descripción
Grafana	3500	Dashboards y alertas
Metabase	3200	Business Intelligence
Rill	9009	BI Dashboard moderno

📊 Monitoring

Servicio	Puerto	Descripción
Prometheus	9090	Métricas y alertas
Loki	3100	Agregación de logs
Alloy	12345	Colector de telemetría

🔄 Orchestration & Transformations

Servicio	Puerto	Descripción
Dagu	8090	DAG Scheduler & Data Transformations (nativo WSL)

📨 Messaging

Servicio	Puerto	Descripción
NATS JetStream	4222/8222	Message broker

💾 Databases

Servicio	Puerto	Descripción
PostgreSQL	5434	Base de datos relacional
ClickHouse	8123/9000	Base de datos analítica
DBGate	3300	Database management UI

🗺️ Data Lineage

Servicio	Puerto	Descripción
Marquez	3001/5000	OpenLineage tracking

---

🏗️ Crear un Pipeline de Datos

Ejemplo: Ingestión desde API

1. Crear el script de recolección

# ~/dagu/scripts/fetch_api_data.py
#!/usr/bin/env python3
import requests
import json
from datetime import datetime

def fetch_data():
    response = requests.get('https://api.example.com/data')
    data = response.json()

    # Guardar temporalmente
    with open('/tmp/api_data.json', 'w') as f:
        json.dump(data, f)

    # Log a Marquez
    log_lineage('START', 'api.example.com', '/tmp/api_data.json')

if __name__ == '__main__':
    fetch_data()

2. Crear el DAG en Dagu

# ~/dagu/dags/api_ingestion.yaml
name: api_ingestion
description: Ingesta datos desde API cada hora

schedule:
  - "0 * * * *"  # Cada hora

env:
  - NATS_URL: nats://localhost:4222
  - POSTGRES_URL: postgresql://postgres:postgres@localhost:5434/postgres

steps:
  # 1. Fetch data from API
  - name: fetch
    command: python ~/dagu/scripts/fetch_api_data.py

  # 2. Validate data
  - name: validate
    command: |
      python ~/dagu/scripts/validate_schema.py \
        --input /tmp/api_data.json
    depends: [fetch]

  # 3. Publish to NATS
  - name: publish_nats
    command: |
      nats pub data.api.raw \
        "$(cat /tmp/api_data.json)" \
        --server=$NATS_URL
    depends: [validate]

  # 4. Consume and ingest to PostgreSQL
  - name: ingest_postgres
    command: |
      python ~/dagu/scripts/nats_to_postgres.py \
        --stream data.api.raw \
        --table api_events
    depends: [publish_nats]

  # 5. Push metrics
  - name: metrics
    command: |
      python ~/dagu/scripts/push_metrics.py \
        --job api_ingestion \
        --success true
    depends: [ingest_postgres]

handlers:
  failure:
    - name: alert
      command: |
        echo "Pipeline failed!" | \
        curl -X POST http://localhost:9093/api/v1/alerts

3. Monitorear en Grafana

1. Ir a http://localhost:3500
2. Crear dashboard con:
   • Query a Prometheus: job_success{job="api_ingestion"}
   • Logs de Loki: {job="dagu"} |= "api_ingestion"

4. Verificar Lineage en Marquez

1. Ir a http://localhost:3001
2. Buscar job: api_ingestion
3. Ver el grafo completo de datos:

   api.example.com → /tmp/api_data.json → NATS → PostgreSQL
   

---

📝 Scripts Helper Incluidos

~/dagu/scripts/log_lineage.py

Envía eventos OpenLineage a Marquez

python ~/dagu/scripts/log_lineage.py \
  --event START \
  --source api.example.com \
  --target /tmp/data.json \
  --job my_pipeline

~/dagu/scripts/push_metrics.py

Publica métricas a Prometheus

python ~/dagu/scripts/push_metrics.py \
  --job my_pipeline \
  --success true \
  --duration 45

~/dagu/scripts/publish_to_nats.sh

Publica mensajes a NATS JetStream

./~/dagu/scripts/publish_to_nats.sh data.stream data.json

~/dagu/scripts/nats_to_postgres.py

Consume de NATS e ingesta a PostgreSQL

python ~/dagu/scripts/nats_to_postgres.py \
  --stream data.raw \
  --table events \
  --batch-size 100

---

🎯 Casos de Uso

1. ETL desde API a Warehouse

API → Dagu (fetch) → NATS → PostgreSQL → Grafana
         ↓
      Marquez (lineage tracking)

2. Stream Processing en Tiempo Real

IoT Devices → NATS → Dagu (transform) → ClickHouse → Rill
                ↓
             Marquez

3. Reporting Diario

Dagu (schedule) → PostgreSQL (query) → Metabase (dashboard) → Email
         ↓
      Marquez

---

🔧 Configuración

NATS JetStream

# Crear stream
nats stream add DATA_STREAM \
  --subjects "data.*" \
  --storage file \
  --retention limits \
  --max-age 7d

# Ver estado
nats stream ls
nats stream info DATA_STREAM

PostgreSQL

# Conectar
psql -h localhost -p 5434 -U postgres -d postgres

# Crear tabla
CREATE TABLE events (
  id SERIAL PRIMARY KEY,
  timestamp TIMESTAMPTZ DEFAULT NOW(),
  source VARCHAR(255),
  data JSONB,
  lineage_job VARCHAR(255)
);

ClickHouse

# Conectar
clickhouse-client --host localhost --port 9000

# Crear tabla
CREATE TABLE events (
  timestamp DateTime,
  source String,
  data String,
  lineage_job String
) ENGINE = MergeTree()
ORDER BY timestamp;

---

📊 Monitoring

Ver Métricas en Prometheus

http://localhost:9090

Queries útiles:
- job_success{job="*"}
- job_duration_seconds{job="*"}
- rate(job_executions_total[5m])

Ver Logs en Grafana

http://localhost:3500 → Explore → Loki

Queries útiles:
- {job="dagu"}
- {job="dagu"} |= "error"
- {job="dagu"} |= "api_ingestion"

Ver Lineage en Marquez

http://localhost:3001

Buscar:
- Jobs: api_ingestion, data_transform
- Datasets: /tmp/api_data.json, postgres://events
- Runs: últimas ejecuciones

---

🚨 Troubleshooting

Dagu no responde

# Ver logs
journalctl --user -u dagu.service -f

# Reiniciar
systemctl --user restart dagu.service

NATS no conecta

# Ver estado
docker logs nats

# Verificar puerto
nats server ping nats://localhost:4222

Base de datos no accesible

# PostgreSQL
docker logs postgres-main

# ClickHouse
docker logs clickhouse

Marquez no registra eventos

# Ver logs
docker logs marquez

# Probar API manualmente
curl http://localhost:5000/api/v1/namespaces

---

📚 Documentación Adicional

• CLAUDE.md: Guía técnica de manipulación de servicios
• TRANSFORMATIONS.md: Guía completa de transformaciones con Dagu
• ~/dagu/README.md: Documentación específica de Dagu
• Dagu Docs: https://dagu.sh/
• OpenLineage Spec: https://openlineage.io/
• NATS Docs: https://docs.nats.io/

---

🤝 Contribuir

Añadir un nuevo pipeline

1. Crear script en ~/dagu/scripts/
2. Crear DAG en ~/dagu/dags/
3. Añadir lineage tracking
4. Crear dashboard en Grafana
5. Documentar en este README

Añadir un nuevo servicio

1. Crear docker-compose-<servicio>.yml
2. Añadir a Homer en homer/assets/config.yml
3. Documentar puertos y configuración
4. Actualizar CLAUDE.md si necesita manipulación especial

---

📊 Arquitectura Detallada

                    ┌─────────────┐
                    │   DAGU      │
                    │  Scheduler  │
                    └──────┬──────┘
                           │
            ┌──────────────┼──────────────┐
            │              │              │
            ▼              ▼              ▼
    ┌───────────┐  ┌───────────┐  ┌───────────┐
    │  Script   │  │  Script   │  │  Script   │
    │  Fetch    │  │ Transform │  │  Export   │
    └─────┬─────┘  └─────┬─────┘  └─────┬─────┘
          │              │              │
          └──────────────┼──────────────┘
                         │
                    ┌────▼────┐
                    │  NATS   │
                    │JetStream│
                    └────┬────┘
                         │
          ┌──────────────┼──────────────┐
          │              │              │
          ▼              ▼              ▼
    ┌──────────┐  ┌──────────┐  ┌──────────┐
    │PostgreSQL│  │ClickHouse│  │   Dagu   │
    │          │  │          │  │Transform │
    └────┬─────┘  └────┬─────┘  └────┬─────┘
         │             │             │
         └─────────────┼─────────────┘
                       │
          ┌────────────┼────────────┐
          │            │            │
          ▼            ▼            ▼
    ┌─────────┐  ┌─────────┐  ┌─────────┐
    │ Grafana │  │Metabase │  │  Rill   │
    └─────────┘  └─────────┘  └─────────┘

         Lineage Tracking (Marquez)
    ┌────────────────────────────────┐
    │ API → NATS → DB → Visualization│
    └────────────────────────────────┘

---

🔐 Credenciales

Servicio	Usuario	Password	Puerto
PostgreSQL	postgres	postgres	5434
ClickHouse	default	clickhouse	8123
Marquez DB	marquez	marquez	5433
Metabase DB	metabase	metabase	(interno)
NATS	nats	nats123	4222

⚠️ IMPORTANTE: Cambiar passwords en producción

---

📈 Roadmap

• Añadir dbt para transformaciones SQL
• Integrar Airflow como alternativa a Dagu
• Añadir Kafka como alternativa a NATS
• Implementar data quality con Great Expectations
• Dashboard unificado de lineage + monitoring
• CI/CD para pipelines de datos
• Disaster recovery y backups automáticos

---

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

---

📞 Soporte

Para issues y preguntas:

• Gitea: https://gitea-dgg044oo04woo4ggcsws4gk0.organic-machine.com/dataforge/automatic-process
• Claude Assistant: Disponible 24/7 para gestión de pipelines