02 Analizar y diseñar

Ejecuta este módulo desde el directorio de artefactos del taller:

cd "$(git rev-parse --show-toplevel)/workshops/elasticsearch_migration_lab/part2"

Tiempo estimado: 60–90 minutos

Descripción general

Antes de utilizar herramientas de migración, analizarás el entorno de Elasticsearch en ejecución, mapearás sus conceptos a ClickHouse (el destino), traducirás consultas representativas a SQL de ClickHouse y redactarás un registro de decisiones de arquitectura (ADR) que documente la estrategia de migración. En esta parte no se modifica la infraestructura: es un ejercicio de reflexión que guía el plan de ejecución de la Parte 3.

Requisitos previos

• El entorno de la Parte 1 está en ejecución (consulta la comprobación de la Parte 1)
• Pasan todas las comprobaciones: bash ../part1/validation/check.sh
• jq está instalado (brew install jq en macOS, apt-get install jq en Debian/Ubuntu)

Lo que producirás

Tres entregables, todos en exercises/:

Las respuestas modelo están en solutions/. Completa cada ejercicio antes de consultarlas.

Referencia: mapeo de conceptos fundamentales

Utiliza esta tabla en los Ejercicios 2A y 2C.

Referencia: mapeo de ECS a convenciones semánticas de OTel

En la Parte 3 configurarás OTel Collector para emitir campos nativos de OTel. Utiliza esta tabla para traducir cada campo ECS documentado en el Ejercicio 2A. Los campos que permanecen en los Maps LogAttributes / SpanAttributes / ResourceAttributes del collector se indican como tales; promuévelos a columnas de nivel superior solo cuando los patrones de consulta lo justifiquen (consulta la Decisión 3 del ADR).

Ejercicio 2A: mapeo del modelo de datos

Entregable: Completa exercises/worksheet.md.

Examina tu entorno de Elasticsearch y rellena una sección de la hoja por cada flujo (logs-web_access-lab, logs-application-lab, logs-infrastructure-lab). Después propón un diseño de tabla de ClickHouse para cada uno.

Comandos de inspección

Ejecútalos desde cualquier host que pueda acceder a Elasticsearch en http://localhost:9200 (el mismo host de la Parte 1).

Enumerar flujos de datos y sus índices subyacentes:

curl -s "http://localhost:9200/_data_stream/logs-*" | jq '.data_streams[] | {name, indices: [.indices[].index_name], generation}'

Obtener el mapeo de un flujo:

curl -s "http://localhost:9200/logs-web_access-lab/_mapping" | jq .

Contar campos hoja únicos del mapeo — excluye metacampos de ES (_id, _index, _source, _doc_count, etc.) que inflarían el recuento en ~14:

curl -s "http://localhost:9200/logs-web_access-lab/_field_caps?fields=*" \
  | jq '[.fields | to_entries[] | select(.key | startswith("_") | not)] | length'

Obtener estadísticas del índice (documentos y tamaño):

curl -s "http://localhost:9200/logs-web_access-lab/_stats" \
  | jq '.indices | to_entries[] | {index: .key, docs: .value.primaries.docs.count, size_bytes: .value.primaries.store.size_in_bytes}'

Obtener la asignación de shards:

curl -s "http://localhost:9200/_cat/shards/logs-web_access-*?v"

Inspeccionar la política ILM y la fase actual:

curl -s "http://localhost:9200/_ilm/policy/lab-observability-policy" | jq .
curl -s "http://localhost:9200/logs-web_access-lab/_ilm/explain" \
  | jq '.indices | to_entries[] | {index: .key, phase: .value.phase, age: .value.age}'

Inspeccionar los pipelines de ingesta:

for p in default-enrichment web-access-enrichment app-log-enrichment infra-log-parsing; do
  echo "=== $p ==="
  curl -s "http://localhost:9200/_ingest/pipeline/$p" | jq ".\"$p\".processors"
done

Comprobar estadísticas de pipelines (documentos y fallos):

curl -s "http://localhost:9200/_nodes/stats/ingest?filter_path=nodes.*.ingest.pipelines" \
  | jq '.nodes | to_entries[0].value.ingest.pipelines'

Verificar que funciona el enriquecimiento:

curl -s "http://localhost:9200/logs-web_access-lab/_search?size=1" \
  | jq '.hits.hits[0]._source | {remote_addr, geo, user_agent_parsed, "event.severity": ."event".severity}'

Contar valores únicos en campos de alta cardinalidad:

curl -s -H 'Content-Type: application/json' "http://localhost:9200/logs-web_access-lab/_search?size=0" -d '{
  "aggs": {
    "services": {"cardinality": {"field": "service"}},
    "paths":    {"cardinality": {"field": "request_path.keyword"}},
    "ips":      {"cardinality": {"field": "remote_addr"}}
  }
}' | jq .aggregations

Inspección: Carga de trabajo 2 (trazas y logs APM)

OTel Demo escribe en traces-apm-* y en unos 18 flujos logs-apm.app.*. La Sección 4 de la hoja cubre esta carga.

Enumerar flujos APM:

curl -s "http://localhost:9200/_data_stream/traces-apm*,logs-apm*" \
  | jq '.data_streams[] | {name, generation}'

Muestrear las claves de nivel superior de una traza:

curl -s "http://localhost:9200/traces-apm-*/_search?size=1" \
  | jq '.hits.hits[0]._source | keys'

Cardinalidades de campos de traza y división por tipo de evento:

curl -s -H 'Content-Type: application/json' "http://localhost:9200/traces-apm-*/_search?size=0" -d '{
  "aggs": {
    "services":    {"cardinality": {"field": "service.name"}},
    "transactions":{"cardinality": {"field": "transaction.name"}},
    "languages":   {"terms": {"field": "service.language.name"}},
    "event_types": {"terms": {"field": "processor.event"}}
  }
}' | jq .aggregations

Percentiles de duración de transacciones (para p50/p95 de la Sección 4a):

curl -s -H 'Content-Type: application/json' "http://localhost:9200/traces-apm-*/_search?size=0" -d '{
  "query": {"term": {"processor.event": "transaction"}},
  "aggs": {
    "dur_pct": {"percentiles": {"field": "transaction.duration.us", "percents": [50, 95, 99]}}
  }
}' | jq .aggregations

Documentos de flujos de logs por servicio de OTel Demo:

curl -s "http://localhost:9200/_cat/indices/logs-apm.app.*?h=index,docs.count&format=json" \
  | jq 'sort_by(-(."docs.count" | tonumber)) | .[] | {index, docs: .["docs.count"]}'

Registrar una referencia de latencia

Antes de diseñar el esquema de destino, registra cuánto tardan 3 consultas canónicas en la pila ES actual. En la Parte 3 repetirás los equivalentes de ClickHouse. Usa el campo .took (milisegundos que ES dedicó a servir la consulta, sin red ni serialización).

# Q1 — Top 10 request paths (status 200)
for i in 1 2 3; do
  curl -s -H 'Content-Type: application/json' \
    "http://localhost:9200/logs-web_access-lab/_search?size=0" -d '{
      "query":{"bool":{"filter":[{"term":{"status":"200"}}]}},
      "aggs":{"top_paths":{"terms":{"field":"request_path.keyword","size":10}}}
    }' | jq '.took'
done

# Q2 — 5xx count per 1m in last 1h
for i in 1 2 3; do
  curl -s -H 'Content-Type: application/json' \
    "http://localhost:9200/logs-web_access-lab/_search?size=0" -d '{
      "query":{"bool":{"filter":[
        {"range":{"status":{"gte":"500"}}},
        {"range":{"@timestamp":{"gte":"now-1h"}}}]}},
      "aggs":{"errors":{"date_histogram":{"field":"@timestamp","fixed_interval":"1m"}}}
    }' | jq '.took'
done

# Q3 — Trace lookup by any trace.id (grab a real one first)
TID=$(curl -s "http://localhost:9200/traces-apm-*/_search?size=1" | jq -r '.hits.hits[0]._source.trace.id')
for i in 1 2 3; do
  curl -s -H 'Content-Type: application/json' \
    "http://localhost:9200/traces-apm-*/_search?size=10" -d "{\"query\":{\"term\":{\"trace.id\":\"$TID\"}}}" \
    | jq '.took'
done

Registra la mediana de las 3 ejecuciones de cada consulta en la Sección 5 de exercises/worksheet.md.

Consejo: Al proponer la clave ORDER BY de ClickHouse, piensa qué combinación reúne mejor las filas consultadas juntas. Los dashboards de la Parte 1 son la guía principal de patrones de acceso.

Ejercicio 2B: traducción de patrones de consulta

Entregable: Completa exercises/query-translation.md.

El archivo contiene 5 consultas representativas de Elasticsearch extraídas de los dashboards y la interfaz APM de la Parte 1. Escribe el SQL de ClickHouse equivalente contra un esquema de destino llamado otel_logs (o otel_traces para búsquedas de trazas) con estas columnas:

¿Por qué Map en lugar de columnas individuales? El esquema OTel utiliza un Map para almacenar atributos con flexibilidad y sin depender del proveedor. En la Parte 3 extraerás los campos consultados con frecuencia (como status) a columnas materializadas para mejorar el rendimiento.

Ejercicio 2C: registro de decisiones de arquitectura

Entregable: Completa exercises/adr-template.md.

Escribe un ADR breve que cubra siete decisiones estratégicas. No hay una única respuesta «correcta»: la justificación debe ser coherente con la configuración ES actual (Ejercicio 2A) y las restricciones de ClickHouse Cloud (almacenamiento columnar basado en objetos y sin alertas integradas).

Las siete decisiones:

1. Enfoque de migración — ¿ejecución paralela, transición total o fases por tipo de log?
2. Estrategia de agentes — ¿OTel Collector directo, puente Filebeat → Vector → OTel o Filebeat → Kafka → Vector → OTel?
3. Estrategia de esquema — ¿esquema OTel predeterminado, personalizado con columnas materializadas o tabla de origen Null + MV? Especifícalo para cada tipo de log y las trazas APM, propón una clave ORDER BY para cada uno y decide cómo tratar los campos nuevos tras el lanzamiento (solo Map, promoción automática, columna JSON o híbrido).
4. Traducción del pipeline de ingesta — ¿dónde se implementa cada procesador de ES? GeoIP (diccionario o procesador del collector), análisis de user-agent y grok, derivación de severidad y marca de tiempo de ingesta.
5. Ciclo de vida — fases ILM innecesarias (y por qué), periodo de retención y cláusula TTL.
6. Migración de alertas — herramienta y recreación de 2 reglas de Kibana (High Error Rate: >5% de 5xx en 5m; Service Heartbeat: ningún log de un servicio durante >3m).
7. Datos históricos — ¿backfill de los ~62 millones de documentos de ES, inicio desde cero conservando ES solo para lectura o solución híbrida? Si haces backfill, ¿con qué herramienta y cómo eliminas duplicados?

Comprobación

Antes de continuar a la Parte 3, verifica:

• exercises/worksheet.md tiene todos los campos cumplimentados para los 3 flujos de datos
• Cada sección propone un diseño de tabla de ClickHouse (clave de partición, ORDER BY, columnas materializadas y TTL)
• Has identificado qué fases de ILM son innecesarias en ClickHouse Cloud y por qué
• exercises/query-translation.md contiene SQL de ClickHouse funcional para las 5 consultas
• exercises/adr-template.md contiene una justificación para cada una de las 7 decisiones (no solo una elección)
• Has comparado tu hoja y el ADR con solutions/ y puedes explicar las desviaciones deliberadas

Siguiente: Parte 3: Ejecución de la migración →