Observabilidad Documentación
Visión general
Tracking de páginas, sesiones y visitantes, accesos de borde y análisis de logs.
Esta referencia cubre 5 engines. Cada endpoint trae ruta, permiso, parámetros, respuesta y los errores posibles.
Accesos de borde
Propósito
Analiza logs de acceso del borde: clustering de IPs, jornadas de navegación, desempeño de backends y anomalías de seguridad.
Interpreta una respuesta query_range del agregador de logs con líneas de acceso HTTP del borde, aplica una lista de confianza (rangos de la red interna, IPs del equipo e IPs del equipo aprendidas por el índice vectorial) para saltar tráfico confiable, y luego ejecuta uno o más modos de análisis: clustering DBSCAN del comportamiento por IP, sesiones de navegación por IP, percentiles de latencia por backend y detección de anomalías de seguridad por reglas estáticas + embeddings. Los límites de las reglas estáticas (404s y total de requests por IP) escalan con el intervalo de tiempo cubierto.
Parámetros (params)
| Campo | Tipo | Obligatorio | Por defecto | Descripción |
|---|---|---|---|---|
mode | string | no | "full" | Modo de análisis: "full", "clustering", "journeys", "performance" o "security". |
start | string | no | Datetime ISO-8601 u offset relativo ("24h", "7d") que marca el inicio de la ventana de consulta en vivo. Usado solo cuando data se omite y los logs deben buscarse en vivo en el agregador; innecesario cuando el payload viene inline en data. | |
end | string | no | "now" | Datetime ISO-8601 o "now" que marca el fin de la ventana de consulta en vivo. Relevante solo junto con start. |
log_query | string | no | Expresión selectora del stream de logs de la consulta en vivo. Relevante solo junto con start; por defecto: el stream de logs de acceso del borde de la plataforma. | |
limit | integer | no | 5000 | Máximo de líneas de log buscadas en modo de consulta en vivo. |
anomaly_threshold | number | no | 0.7 | Umbral de similitud en el índice vectorial bajo el cual un patrón de request se señala como anomalía de seguridad por embeddings (modos security/full). |
from_file | string | no | Ruta local de una respuesta del agregador pre-descargada, usada solo en pruebas offline del lado del worker. Los clientes de la API entregan el payload vía data. |
Columnas de data[]
| Columna | Tipo | Obligatoria | Descripción |
|---|---|---|---|
status | string | sí | Status de la respuesta del agregador, siempre "success" para un payload válido. |
data | object | sí | Sobre de resultado query_range del agregador de logs: resultType ("streams"), result (array de {stream: {etiqueta: valor, ...}, values: [[timestamp_ns, línea], ...]}, una entrada por stream coincidente) y stats (estadísticas de la consulta, ignoradas por la engine). Las líneas que no coinciden con el formato de log de acceso HTTP del borde se saltan en vez de fallar el job. |
Respuesta
En modo asíncrono (por defecto), 202 Accepted con {"process_uuid", "result_url"}; el resultado sale en GET /api/v1/results/{process_uuid}. Con ?sync=true o ?dry_run=true la respuesta es 200 con el resultado inline (y 504 con el process_uuid si el worker no responde a tiempo).
Errores
403- la engine no está enallowed_enginesde tu suscripción.413- subida por encima demax_upload_mb.422- engine desconocida o inactiva en el catálogo.429- cuota diaria (max_jobs_per_day) o por minuto excedida.
La validación es fail-fast: un envío rechazado no tiene ningún efecto secundario.
curl -X POST "https://intelligence.echosistema.live/api/v1/edge_traffic/process?dry_run=true&playground=true" \
-H "X-TENANT-KEY: $TENANT_KEY"Análisis de logs
Propósito
Analiza logs de aplicación: frecuencia de errores, amenazas de seguridad y anomalías de errores inéditos.
Interpreta una respuesta query_range del agregador de logs con líneas de log de aplicación (texto prefijado por severidad, o JSON por línea en el canal ia), filtra por severidad mínima y ejecuta uno o más modos de análisis: frecuencia/distribución de errores por canal y nivel, reglas estáticas de seguridad (fuerza bruta en auth, severidad crítica, servicio caído) y detección de anomalías en tres capas por embeddings (conocido/similar/nuevo) contra una baseline vectorial de mensajes de error anteriores.
Parámetros (params)
| Campo | Tipo | Obligatorio | Por defecto | Descripción |
|---|---|---|---|---|
mode | string | no | "full" | Modo de análisis: "full", "errors", "security" o "anomaly". |
start | string | no | Datetime ISO-8601 u offset relativo ("24h", "7d") que marca el inicio de la ventana de consulta en vivo. Usado solo cuando data se omite; innecesario cuando el payload viene inline en data. | |
end | string | no | "now" | Datetime ISO-8601 o "now" que marca el fin de la ventana de consulta en vivo. Relevante solo junto con start. |
log_query | string | no | Expresión selectora del stream de logs de la consulta en vivo. Relevante solo junto con start; por defecto: el stream de logs de aplicación de la plataforma. | |
limit | integer | no | 5000 | Máximo de líneas de log buscadas en modo de consulta en vivo. |
min_level | string | no | "WARNING" | Severidad mínima a analizar (DEBUG < INFO < NOTICE < WARNING < ALERT < ERROR < CRITICAL < EMERGENCY). Las entradas bajo ese nivel se descartan antes del análisis. |
anomaly_threshold | number | no | 0.7 | Score de similitud en el índice vectorial bajo el cual un mensaje de error se clasifica como nuevo (nunca visto) en los modos anomaly/full. |
similarity_threshold | number | no | 0.9 | Score de similitud por encima del cual un mensaje de error se clasifica como conocido y se salta. Los scores entre anomaly_threshold y este valor se reportan como "similar, investigar". |
from_file | string | no | Ruta local de una respuesta del agregador pre-descargada, usada solo en pruebas offline del lado del worker. Los clientes de la API entregan el payload vía data. |
Columnas de data[]
| Columna | Tipo | Obligatoria | Descripción |
|---|---|---|---|
status | string | sí | Status de la respuesta del agregador, siempre "success" para un payload válido. |
data | object | sí | Sobre de resultado query_range del agregador de logs: resultType ("streams"), result (array de {stream: {etiqueta: valor, ...}, values: [[timestamp_ns, línea], ...]}) y stats (ignorado). La etiqueta filename del stream elige el parser: archivos ia-*.log/ia.log se interpretan como un JSON por línea, el resto como texto prefijado por severidad. Las líneas no interpretables se saltan en vez de fallar el job. |
Respuesta
En modo asíncrono (por defecto), 202 Accepted con {"process_uuid", "result_url"}; el resultado sale en GET /api/v1/results/{process_uuid}. Con ?sync=true o ?dry_run=true la respuesta es 200 con el resultado inline (y 504 con el process_uuid si el worker no responde a tiempo).
Errores
403- la engine no está enallowed_enginesde tu suscripción.413- subida por encima demax_upload_mb.422- engine desconocida o inactiva en el catálogo.429- cuota diaria (max_jobs_per_day) o por minuto excedida.
La validación es fail-fast: un envío rechazado no tiene ningún efecto secundario.
curl -X POST "https://intelligence.echosistema.live/api/v1/log_analyzer/process?dry_run=true&playground=true" \
-H "X-TENANT-KEY: $TENANT_KEY"Tracking de páginas
Propósito
Clasifica páginas web por reglas de URL/título y construye un índice de búsqueda semántica.
Consume un lote de páginas únicas (una fila por page_url distinta con un campo embed_text, preagregado por el colector de tracking), clasifica cada página en una categoría por reglas de patrón de URL/título, genera el embedding con el modelo de la plataforma (una llamada en lote) y lo graba en el índice vectorial de páginas. Corre diariamente poco después de la medianoche.
Parámetros (params)
| Campo | Tipo | Obligatorio | Por defecto | Descripción |
|---|---|---|---|---|
max_workers | integer | no | 4 | Tamaño del pool de threads usado para clasificar y grabar páginas en paralelo tras la llamada de embedding en lote. Acotado al rango 1-16. |
from_file | string | no | Ruta local de un payload pre-descargado, usada solo en pruebas offline del lado del worker. Los clientes de la API entregan el payload vía data. |
Columnas de data[]
| Columna | Tipo | Obligatoria | Descripción |
|---|---|---|---|
type | string | no | Discriminador del payload escrito por el colector de tracking ("tracking_pages"). No es leído por la engine. |
collected_at | string | no | Timestamp ISO-8601 de cuándo se recolectó el lote. Retornado en el resumen del resultado. |
page_count | integer | no | Número de entradas en pages, como lo reporta el colector. No es leído por la engine (informativo). |
pages | array | sí | Páginas únicas a clasificar. Cada ítem es un objeto con page_url, title, platform_id, total_views, team_views (vistas del equipo de la plataforma, para segmentación equipo × externo), unique_sessions, first_seen, last_seen y embed_text (el texto enviado al modelo de embedding). Las páginas sin embed_text se saltan. |
Respuesta
En modo asíncrono (por defecto), 202 Accepted con {"process_uuid", "result_url"}; el resultado sale en GET /api/v1/results/{process_uuid}. Con ?sync=true o ?dry_run=true la respuesta es 200 con el resultado inline (y 504 con el process_uuid si el worker no responde a tiempo).
Errores
403- la engine no está enallowed_enginesde tu suscripción.413- subida por encima demax_upload_mb.422- engine desconocida o inactiva en el catálogo.429- cuota diaria (max_jobs_per_day) o por minuto excedida.
La validación es fail-fast: un envío rechazado no tiene ningún efecto secundario.
curl -X POST "https://intelligence.echosistema.live/api/v1/tracking_pages/process?dry_run=true&playground=true" \
-H "X-TENANT-KEY: $TENANT_KEY"Tracking de sesiones
Propósito
Detecta jornadas de sesión anómalas por similitud de embeddings contra una baseline vectorial.
Limpia y normaliza la jornada de páginas de cada sesión (quita hostnames, colapsa navegaciones de refinamiento por tipeo, dedupe, techo de 50 páginas), genera el embedding en bloques con el modelo de la plataforma, busca similitud en la baseline vectorial de sesiones y clasifica cada sesión como team, normal o anomalous. Cada sesión se graba de vuelta en el índice, así la baseline crece incrementalmente. La búsqueda en la baseline excluye puntos de equipo y anómalos y se limita al platform_id de la sesión, y la señalización por score solo se activa cuando la colección tiene al menos min_baseline puntos (calentamiento).
Parámetros (params)
| Campo | Tipo | Obligatorio | Por defecto | Descripción |
|---|---|---|---|---|
anomaly_threshold | number | no | 0.7 | Score mínimo de similitud para considerarse normal. Las sesiones por debajo (o marcadas como robots) se reportan como anomalías; las sesiones del equipo siempre se saltan la puntuación. |
min_baseline | integer | no | 100 | Umbral de calentamiento: por debajo de ese número de puntos indexados, la señalización por score queda desactivada (las flags de robot siguen aplicando). Evita que una baseline inmadura marque toda sesión como anómala y envenene la colección. |
max_workers | integer | no | 4 | Tamaño del pool de threads usado para buscar y grabar sesiones en paralelo tras la llamada de embedding en lote. Acotado al rango 1-16. |
from_file | string | no | Ruta local de un payload pre-descargado, usada solo en pruebas offline del lado del worker. Los clientes de la API entregan el payload vía data. |
Columnas de data[]
| Columna | Tipo | Obligatoria | Descripción |
|---|---|---|---|
type | string | no | Discriminador del payload escrito por el colector de tracking ("tracking_sessions"). No es leído por la engine. |
collected_at | string | no | Timestamp ISO-8601 de cuándo se recolectó el lote. Retornado en el resumen del resultado. |
session_count | integer | no | Número de entradas en sessions, como lo reporta el colector. No es leído por la engine (informativo). |
first_tracking_id | integer | no | Menor id de fila de tracking de origen cubierto por el lote. Retornado en el resumen para cursores de ejecución incremental. |
last_tracking_id | integer | no | Mayor id de fila de tracking de origen cubierto por el lote. Retornado en el resumen para cursores de ejecución incremental. |
sessions | array | sí | Sesiones de usuario a analizar. Cada ítem lleva session_id, platform_id, user_uuid, is_team, is_robot, pages (lista ordenada de rutas de URL), first_page, last_page, duration_seconds, reached_contact, campos de geolocalización/ISP (ip_address, country_code, latitude, longitude, isp, org), campos de dispositivo (device_type, os_name, browser_name, screen_w, screen_h, language), campos UTM, referer, first_event, last_event y embed_text. Las sesiones de página única en /api/ o sin embed_text se filtran antes de puntuar. |
Respuesta
En modo asíncrono (por defecto), 202 Accepted con {"process_uuid", "result_url"}; el resultado sale en GET /api/v1/results/{process_uuid}. Con ?sync=true o ?dry_run=true la respuesta es 200 con el resultado inline (y 504 con el process_uuid si el worker no responde a tiempo).
Errores
403- la engine no está enallowed_enginesde tu suscripción.413- subida por encima demax_upload_mb.422- engine desconocida o inactiva en el catálogo.429- cuota diaria (max_jobs_per_day) o por minuto excedida.
La validación es fail-fast: un envío rechazado no tiene ningún efecto secundario.
curl -X POST "https://intelligence.echosistema.live/api/v1/tracking_sessions/process?dry_run=true&playground=true" \
-H "X-TENANT-KEY: $TENANT_KEY"Tracking de visitantes
Propósito
Clasifica visitantes como humano, bot, scraper o crawler por similitud de embeddings más flags de señal.
Genera el embedding del perfil IP/dispositivo/comportamiento de cada visitante en bloques con el modelo de la plataforma, busca similitud en la baseline vectorial de visitantes y combina el score con señales sospechosas (IP de datacenter, tasa alta de requests, sin tamaño de pantalla, user-agent de robot) para clasificar al visitante. Los visitantes del equipo siempre se saltan el análisis. Cada visitante se graba de vuelta en el índice (la baseline crece incrementalmente) y los ip_id señalados se devuelven para bloqueo aguas abajo. Cada punto del índice corresponde a un par IP+dispositivo, y la sospecha por score solo se activa con la colección por encima de min_baseline puntos; las señales duras siempre aplican.
Parámetros (params)
| Campo | Tipo | Obligatorio | Por defecto | Descripción |
|---|---|---|---|---|
anomaly_threshold | number | no | 0.7 | Score mínimo de similitud para considerarse no sospechoso. Combinado con las flags de señal para derivar la clasificación final (human/bot/scraper/crawler/suspicious). |
min_baseline | integer | no | 100 | Umbral de calentamiento: por debajo de ese número de puntos indexados, la sospecha por score queda desactivada (las señales duras como IP de datacenter o user-agent de robot siguen aplicando). |
max_workers | integer | no | 4 | Tamaño del pool de threads usado para buscar y grabar visitantes en paralelo tras la llamada de embedding en lote. Acotado al rango 1-16. |
from_file | string | no | Ruta local de un payload pre-descargado, usada solo en pruebas offline del lado del worker. Los clientes de la API entregan el payload vía data. |
Columnas de data[]
| Columna | Tipo | Obligatoria | Descripción |
|---|---|---|---|
type | string | no | Discriminador del payload escrito por el colector de tracking ("tracking_visitors"). No es leído por la engine. |
collected_at | string | no | Timestamp ISO-8601 de cuándo se recolectó el lote. No es leído por la engine (informativo). |
visitor_count | integer | no | Número de entradas en visitors, como lo reporta el colector. No es leído por la engine (informativo). |
first_tracking_id | integer | no | Menor id de fila de tracking de origen cubierto por el lote. Retornado en el resumen para cursores de ejecución incremental. |
last_tracking_id | integer | no | Mayor id de fila de tracking de origen cubierto por el lote. Retornado en el resumen para cursores de ejecución incremental. |
visitors | array | sí | Perfiles de visitantes a clasificar. Cada ítem lleva ip_id, device_id (clavea el punto del índice vectorial, uno por par IP+dispositivo), ip_address, isp, org, is_robot, campos de geolocalización (country_id, country_code, city_id, latitude, longitude), campos de dispositivo (os_name, browser_name, device_type, device_brand, screen_w, screen_h), contadores de comportamiento (sessions, page_views, unique_pages, first_seen, last_seen), flags de señal sospechosa (is_datacenter_ip, high_rate, no_screen, is_team) y embed_text. Los visitantes sin embed_text se saltan. |
Respuesta
En modo asíncrono (por defecto), 202 Accepted con {"process_uuid", "result_url"}; el resultado sale en GET /api/v1/results/{process_uuid}. Con ?sync=true o ?dry_run=true la respuesta es 200 con el resultado inline (y 504 con el process_uuid si el worker no responde a tiempo).
Errores
403- la engine no está enallowed_enginesde tu suscripción.413- subida por encima demax_upload_mb.422- engine desconocida o inactiva en el catálogo.429- cuota diaria (max_jobs_per_day) o por minuto excedida.
La validación es fail-fast: un envío rechazado no tiene ningún efecto secundario.
curl -X POST "https://intelligence.echosistema.live/api/v1/tracking_visitors/process?dry_run=true&playground=true" \
-H "X-TENANT-KEY: $TENANT_KEY"