Enterprise Log Share: API de REST Logpull

Información general

Los clientes del plan Enterprise de Cloudflare tienen acceso al servicio Enterprise Log Share (ELS), una API de RESTful para consumir registros de solicitudes a través de HTTP. Esta API ofrece un método para que los clientes accedan a los registros de solicitudes de un dominio mediante una clave de API de cliente.

ELS no se encuentra habilitado de forma predeterminada. Si desea activar ELS para el dominio del plan Enterprise, póngase en contacto con el equipo de asistencia de Cloudflare.

Estos registros contienen datos relacionados con el cliente de la conexión, la ruta de solicitud a través de la red de Cloudflare y la respuesta del servidor web de origen.  Estos datos resultan útiles para mejorar los registros existentes en un servidor de origen. 

El punto de conexión /logs/requests caducó en 2018.

Periodo de retención de datos

Puede consultar los datos de registro una vez que haya pasado un periodo de 5 minutos (en relación con la hora real en la que se haya realizado la solicitud) y hasta un periodo máximo de 72 horas.   

Orden de los datos devueltos

La ruta de la API de REST «logs/received» expone los datos recibidos por hora, que corresponde a la hora en la que se ha grabado el evento en el disco del sistema de agregación de registros de Cloudflare. 

La clasificación por hora de agregación de los registros en lugar de la hora de generación ofrece una latencia menor (más rápida) de la canalización de recursos compartidos de registros y la extracción determinista de registros. Funcionalmente, este proceso es parecido a la finalización de un archivo de registro o a la lectura de rsyslog (aunque en fragmentos).

Esto significa que si desea obtener registros durante un intervalo de tiempo determinado, puede hacerlo emitiendo una llamada por cada minuto consecutivo (u otro intervalo de tiempo). Debido a que las líneas de registro se agrupan por tiempo de recepción y disponibilidad, no existen «datos que llegan tarde». Una respuesta para un minuto determinado nunca cambiará. No debe buscar reiteradamente un intervalo de tiempo determinado para recibir registros, ya que estos convergen en nuestro sistema de agregación.

Formato de los datos devueltos

La API de REST Logpull devuelve datos en formato NDJSON, donde cada línea de registro es un objeto JSON válido.  Las principales herramientas de análisis, como Google BigQuery y AWS Kinesis, requieren este formato.

Si desea convertir los datos de registro resultantes en una matriz JSON con un elemento de matriz por línea de registro, puede utilizar la herramienta jq.  Básicamente, canaliza la respuesta de la API a jq con el indicador slurp (o simplemente s):

<API request code> | jq -s

Patrón de acceso recomendado

El patrón de acceso básico es «necesito todos los registros de la zona Z para el minuto M», donde el minuto M hace referencia a la hora en la que se han grabado los registros en el disco de nuestro sistema de agregación de registros. Intente ejecutar su consulta cada minuto para comenzar. Si las respuestas son demasiado cortas, intente aumentarlas a 5 minutos como máximo (esta opción será apropiada en la mayoría de zonas). Si las respuestas son demasiado largas, intente disminuirlas a 15 segundos. En el caso de que su zona tenga tantos registros que se tarde más de 1 minuto en leer registros de 1 minuto, ejecute 2 trabajadores escalonados para que soliciten registros de 1 minuto cada 2 minutos. 

Los datos devueltos por la API no cambian para llamadas repetidas. Si bien el orden de los mensajes en la respuesta puede ser diferente, la cantidad y el contenido siempre serán los mismos para una consulta determinada si el código de respuesta es 200 y no hay ningún error en la lectura del cuerpo de la respuesta.

Dado que nuestro sistema de procesamiento de registros introduce los datos en lotes, la mayoría de las zonas que reciben menos de un millón de solicitudes por minuto, tendrán minutos «vacíos»: las consultas de ese minuto darán como resultado respuestas con el estado 200, pero sin datos en el cuerpo. Esto no significa que no hayan habido solicitudes que Cloudflare redirigiera mediante proxy para ese minuto; simplemente significa que nuestro sistema no ha procesado un lote de registros para esa zona en ese minuto.

Acceso

/logs/received

https://api.cloudflare.com/client/v4/zones/<zone_id>/logs/received?start=<unix|rfc3339>&end=<unix|rfc3339>[&count=<int>][&sample=<float>][&fields=<fields>][&timestamps=<string>]

Parámetros requeridos:

  • start: inclusivo; marca de tiempo con formato unix (que, por definición, es UTC), unix nano o rfc3339 (especifica la zona horaria); no debe ser anterior a 7 días con respecto al momento actual
  • end: exclusivo; mismo formato que para el parámetro start; debe ser al menos 5 minutos antes con respecto al momento actual y posterior al inicio
El intervalo de tiempo máximo de start a end no puede ser superior a 1 hora. El parámetro de inicio (start) es inclusivo, mientras que el parámetro de fin (end) es exclusivo. Por lo tanto, si desea obtener todos los datos para cada minuto, a partir de las 10 a. m., los valores correspondientes serán los siguientes: start=2018-05-15T10:00:00Z&end=2018-05-15T10:01:00Z, posteriormente, start=2018-05-15T10:01:00Z&end=2018-05-15T10:02:00Z y así sucesivamente; la «superposición» se gestionará correctamente.
  •  encabezados:
    • X-Auth-Email
    • X-Auth-Key (clave de API global)

Parámetros opcionales:

  • count: devuelve hasta tantos registros. Para devolver todos los registros, no incluya el parámetro count.
  • sample: solo devuelve una muestra de los registros; la opción muestra=0,1 significa que devuelve el 10 % (1 de 10) de los registros.
  • fields: lista separada por comas de los campos que se devolverán; cuando está vacía, se devuelve la lista predeterminada (9 campos).
  • timestamps (beta): formato en el que se devolverán los campos de marcas de tiempo. Una de las siguientes: «unixnano» (predeterminada), «unix», «rfc3339».

cURL de muestra: 

curl -s -H "X-Auth-Email: monkey@zoo.com" -H "X-Auth-Key: banana12345" "https://api.cloudflare.com/client/v4/zones/4f8g90r42275bce56f242596aic6fc5b/logs/received?start=2017-07-18T22:00:00Z&end=2017-07-18T22:01:00Z&count=1&fields=RayID,ClientIP"

/logs/rayids

https://api.cloudflare.com/client/v4/zones/<zone_id>/logs/rayids/<ray_id>?[&fields=<string>][&timestamps=<strings>]

Los únicos argumentos aceptados por «rayids» son «campos» y «marcas de tiempo». La ruta rayids devolverá 0, 1 o varios registros (los Ray IDs pueden no ser únicos).

Expectativas de servicio

Una vez que se recibe una respuesta de 200 y se lee completamente para una zona y un intervalo de tiempo determinados, tenga en cuenta lo siguiente para todas las solicitudes subsiguientes:

  • El número y contenido de registros devueltos serán los mismos.
  • El orden de los registros devueltos puede ser diferente (y es probable que lo sea).

Campos de respuesta:

  • Cuando se configuran explícitamente en la dirección URL de solicitud, los campos de respuesta nunca cambian, a menos que se designe un campo como «beta», en cuyo caso se puede eliminar en cualquier momento.
  • Cuando no se configuran explícitamente, se utilizarán campos predeterminados; el conjunto de campos predeterminados puede cambiar en cualquier momento.

Límites:

  • el límite de frecuencia eficaz es de 1 solicitud cada 5 minutos por zona. Si bien se pueden ejecutar varias solicitudes al mismo tiempo, solo se puede realizar una solicitud nueva cada 5 segundos. Si se supera el límite, se produce una respuesta de error 429.
  • Intervalo de tiempo máximo (la diferencia entre los parámetros start y end es de 1 hora).
  • El tamaño de respuesta máximo es de 1 GB sin comprimir para los intervalos de tiempo superiores a 1 minuto; para los intervalos de tiempo de 1 minuto o inferiores, no hay límite.
    • Debido a que las respuestas se transmiten por secuencias, no hay manera de determinar el tamaño de la respuesta con anterioridad. Después de transmitir 1 GB de datos, la respuesta fallará y finalizará la conexión. Esto permite a los usuarios adaptar sus consultas a un intervalo que no ofrezca fallos en función del volumen de solicitudes. Creemos que esta solución es mejor que las solicitudes limitadas para un intervalo de tiempo arbitrario (p. ej., 1 minuto a la vez).

 

Parámetros de API en profundidad

count

Cuando se proporciona «?count=», la respuesta contendrá resultados hasta count. Debido a que los resultados no están ordenados, es probable que obtenga datos distintos en solicitudes repetidas.

sample

Cuando se proporciona «?sample=», se devuelve una muestra de registros coincidentes. Si se trata de «sample=0,1», se devolverá aproximadamente el 10 % de los registros. El muestreo es aleatorio: las llamadas repetidas no solo devolverán registros distintos, sino que también variarán ligeramente con respecto a la cantidad de registros devueltos.

Cuando también se especifica «?count=», el recuento se aplica a la cantidad de registros devueltos, en lugar de a los registros muestreados. Por lo tanto, cuando exista un total de 100 registros disponibles en «sample=0,05» y «count=7», se devolverán aproximadamente 5. Si hay 1000 registros, se devolverán 7. Si hay 10 000 registros, se devolverán 7.

fields

Si no se especifica «fields», se devolverá un conjunto limitado de campos de forma predeterminada. Este conjunto predeterminado de campos puede cambiar en cualquier momento. La lista completa de todos los campos disponibles se puede encontrar aquí:

https://api.cloudflare.com/client/v4/zones/<zone_tag>/logs/received/fields

Los campos se pasan a la solicitud como una lista separada por comas. Entonces, para «ClientIP» y «RayID», utilice lo siguiente:

fields=ClientIP,RayID

El orden en que se especifican los campos no es importante, y el orden de los campos en la respuesta no se especifica.

Mediante la subshell Bash y jq, puede descargar los registros con todos los campos disponibles sin copiar ni pegar manualmente los campos en la solicitud de la siguiente manera:

curl -s -H "X-Auth-Email: monkey@zoo.com" -H "X-Auth-Key: banana12345" "https://api.cloudflare.com/client/v4/zones/4f8g90r42275bce56f242596aic6fc5b/logs/received?start=2017-07-18T22:00:00Z&end=2017-07-18T22:01:00Z&count=1&fields=$(curl -s -H "X-Auth-Email: monkey@zoo.com" -H "X-Auth-Key: banana12345" "https://api.cloudflare.com/client/v4/zones/4f8g90r42275bce56f242596aic6fc5b/logs/received/fields" | jq '. | to_entries[] | .key' -r | paste -sd "," -)"

Campos disponibles actualmente (a mayo de 2018):

«CacheCacheStatus»: "unknown | miss | expired | updating | stale | hit | ignored | bypass | revalidated", 
«CacheResponseBytes»:
«cantidad de bytes devueltos por la memoria caché»,
«CacheResponseStatus»:
«código de estado HTTP devuelto por la memoria caché al perímetro: todas las solicitudes (incluidas las que no se pueden almacenar en la memoria caché) pasan por la memoria caché: consulte también el campo CacheStatus»,
«CacheTieredFill»:
«se ha utilizado la memoria caché en capas para ofrecer esta solicitud (beta)»,
«ClientASN»:
«número AS del cliente»,
«ClientCountry»:
«país de la dirección IP del cliente»,
«ClientDeviceType»:
«tipo de dispositivo del cliente»,
«ClientIP»:
«dirección IP del cliente»,
«ClientIPClass»:
«clase de IP del cliente:  'unknown','clean','badHost','searchEngine','whitelist','greylist','monitoringService','securityScanner','noRecord','scan','backupService','mobilePlatform','tor'»,
«ClientRequestBytes»:
«cantidad de bytes en la solicitud del cliente»,
«ClientRequestHost»:
«host solicitado por el cliente»,
«ClientRequestMethod»:
«método HTTP de la solicitud del cliente»,
«ClientRequestProtocol»:
«protocolo HTTP de la solicitud del cliente»,
«ClientRequestReferer»:
«origen de referencia de la solicitud HTTP»,
«ClientRequestURI»: «
URI solicitado por el cliente»,
«ClientRequestUserAgent»:
«agente de usuario notificado por el cliente»,
«ClientSSLCipher»:
«cifrado SSL del cliente»,
«ClientSSLProtocol»:
«protocolo SSL (TLS) del cliente»,
«ClientSrcPort»:
«puerto de origen del cliente»,
«EdgeColoID»:
«ID de colo del perímetro de Cloudflare»,
«EdgeEndTimestamp»:
«marca de tiempo de nanosegundo Unix que ha finalizado el perímetro enviando la respuesta al cliente»,
«EdgePathingOp»:
«indica qué tipo de respuesta se ha emitido para esta solicitud (unknown = sin acción específica)»,
«EdgePathingSrc»:
«detalla cómo se ha clasificado la solicitud en función de las comprobaciones de seguridad (unknown = sin clasificación específica)»,
«EdgePathingStatus»:
«indica qué datos se han utilizado para determinar la gestión de esta solicitud (unknown = sin datos)»,
«EdgeRateLimitAction»:
«acción tomada por la regla de bloqueo; el campo queda vacío si no se realiza ninguna acción (beta)»,
«EdgeRateLimitID»:
«uint64: ID de regla interno de la regla de limitación de frecuencia que activa un bloqueo (prohibición) o simula una acción. El resultado es 0 si no se realiza ninguna acción (beta)»,
«EdgeRequestHost»:
«encabezado de host en la solicitud desde el perímetro hasta el origen (beta)»,
«EdgeResponseBytes»:
«cantidad de bytes devueltos por el perímetro del cliente»,
«EdgeResponseCompressionRatio»:
«relación de compresión de respuesta de perímetro»,
«EdgeResponseContentType»:
«valor de encabezado de tipo de contenido de respuesta de perímetro (beta)»,
«EdgeResponseStatus»:
«código de estado HTTP devuelto por Cloudflare al cliente»,
«EdgeServerIP»: «IP del servidor perimetral que realiza una solicitud al origen (beta)»,
«EdgeStartTimestamp»:
«marca de tiempo de nanosegundo Unix en que el perímetro ha recibido la solicitud del cliente»,
«OriginIP»:
«IP del servidor de origen»,
«OriginResponseBytes»:
«cantidad de bytes devueltos por el servidor de origen»,
«OriginResponseHTTPExpires»:
«valor del encabezado de origen 'caducidad' en formato RFC1123»,
«OriginResponseHTTPLastModified»:
«valor del encabezado de origen 'last-modified' en formato RFC1123»,
«OriginResponseStatus»:
«estado devuelto por el servidor de origen»,
«OriginResponseTime»:
«cantidad de nanosegundos que ha tardado el origen en devolver la respuesta al perímetro»,
«OriginSSLProtocol»:
«protocolo SSL (TLS) utilizado para conectarse con el origen (beta)»,
«RayID»:
«ID de la solicitud»,
«SecurityLevel»:
«nivel de seguridad configurado en el momento de la solicitud. Esto se utiliza para determinar la sensibilidad del sistema de reputación de IP»,
«WAFAction»:
«acción realizada por el WAF, si la opción se encuentra activada»,
«WAFFlags»:
«marcas de configuración adicionales: simulate (0x1) | null»,
«WAFMatchedVar»:
«nombre completo de la variable coincidente más reciente»,
«WAFProfile»:
«perfil de WAF: low | med | high»,
«WAFRuleID»:
«ID de la regla WAF aplicada»,
«WAFRuleMessage»:
«mensaje de regla asociado a la regla activada»,
«WorkerCPUTime»: «cantidad de tiempo en microsegundos empleada en la ejecución de un worker, si corresponde (beta)»,
«WorkerStatus»:
«estado devuelto por el demonio del worker como una cadena (beta)»,
«WorkerSubrequest»:
«si esta solicitud ha sido o no una solicitud secundaria de worker (beta)»,
«WorkerSubrequestCount»:
«cantidad de solicitudes secundarias emitidas por un worker al gestionar esta solicitud (beta)»,
«ZoneID»:
«ID de zona interno»

marcas de tiempo

De forma predeterminada, las marcas de tiempo se devuelven como enteros de nanosegundos de Unix en las respuestas. El parámetro de consulta timestamps=, se puede configurar para cambiar el formato en que se devuelven las marcas de tiempo. Los valores posibles son los siguientes: unix, unixnano, rfc3339. Nota: unix y unixnano devuelven marcas de tiempo como enteros, mientras que rfc3339 las devuelve como cadenas.

Respuesta

Los datos se marcan con la hora en la que se han grabado en el disco en nuestro punto de agregación de registros.

Los datos de respuesta se devuelven en json, 1 objeto json (1 mensaje de registro) por línea. Ejemplo de mensaje de registro con campos predeterminados:

{
«ClientIP»: «89.163.242.206»,
«ClientRequestHost»: «www.theburritobot.com»,
«ClientRequestMethod»: «GET»,
«ClientRequestURI»: «/static/img/testimonial-hipster.png»,
«EdgeEndTimestamp»: 1506702504461999900,
«EdgeResponseBytes»: 69045,
«EdgeResponseStatus»: 200,
«EdgeStartTimestamp»: 1506702504433000200,
«RayID»: «3a6050bcbe121a87»
}

Estimación de los volúmenes de datos diarios

Para estimar rápidamente la cantidad de datos de una zona por día (la cantidad de líneas de registro y la cantidad de bytes que ocupan), solicite una muestra de 1 de 1000 datos durante un periodo de 24 horas; tenga en cuenta que start=2017-09-10T00:00:00Z y end=2017-09-11T00:00:00Z abarcan un periodo de 24 horas, y sample=0,001.

curl -s -H"X-Auth-Email: MONKEY" -H"X-Auth-Key: BANANA" \
    "https://api.cloudflare.com/client/v4/zones/<ZONE_TAG>/logs/received?start=2017-09-10T00:00:00Z&end=2017-09-11T00:00:00ZZ&sample=0.001" \
    >sample.log
...
$ wc -l sample.log
47146 sample.log
...
$ ls -lh sample.log
-rw-r--r-- 1 mik mik 15M Sep 11 18:56 sample.log

Según esta información, la cantidad aproximada de mensajes por día es de 47 146 000 y el tamaño de bytes es de 15 GB. La estimación del tamaño se basa en el conjunto de campos de respuesta predeterminado; al cambiar el conjunto de campos de respuesta (consulte la sección «Campos»), se modificará el tamaño de la respuesta.

Para obtener una estimación precisa del tráfico diario, es mejor realizar una consulta de 24 horas. Si el tamaño de la respuesta es demasiado corto o largo, adapte el valor de muestra, en lugar del intervalo de tiempo.

Compresión

Las respuestas se comprimen de forma predeterminada (gzip). cURL descomprime las respuestas de forma transparente, a menos que se llame con -H"accept-encoding: gzip". En ese caso, la salida permanece descomprimida. Debe esperar que los datos comprimidos sean aproximadamente de un 5 % o un 10 % de los datos sin comprimir. Esto significa que con el límite de tamaño de respuesta de 1 GB (sin comprimir), las respuestas comprimidas serán de 50 MB a 100 MB.

Beta

Las funciones y los campos marcados como «beta» todavía se encuentran en etapa de prueba y validación. Se pueden retirar sin previo aviso.

¿No has encontrado una respuesta satisfactoria?

Nuestra herramienta de búsqueda puede contestar el 95% de las preguntas más comunes y es la mejor manera de conseguir una respuesta rápida.

Tecnología de Zendesk