Enterprise 日志共享:Logpull REST API

概述

Cloudflare Enterprise 客户能够访问Enterprise 日志共享 (ELS) 服务,这是一个 RESTful API,用于通过 HTTP 消费请求日志。此 API 为客户提供使用客户端 API 密钥访问域的请求日志的方法。

默认情况下不启用 ELS。要为您的 Enterprise 域名激活 ELS,请联系 Cloudflare 支持。

这些日志包含与连接客户端相关的数据、通过 Cloudflare 网络的请求路径,以及来自源站 Web 服务器的响应。  这些数据非常适用于丰富源站上的现有日志。 

/logs/requests 端点在 2018 年已被弃用。

数据保留期

您可以查询过去 5 分钟(相对于发出此请求的实际时间)开始的日志数据,最长可追溯 72 小时。   

返回数据的顺序

“日志/已接收”REST API 路由按接收时间显示数据,这是在 Cloudflare 日志聚合系统中将事件写入磁盘的时间。 

按日志聚合时间排序而不是按日志生成时间排序会实现更低(更快)的日志共享管道延迟和确定性日志提取。 从功能上讲,它类似于跟踪日志文件或从 rsyslog 读取(尽管为成块读取)。

这意味着如果要获取给定时间范围的日志,可以通过为每个连续分钟(或其他时间范围)发出一个调用来执行此操作。由于日志行按接收时间和可用时间进行批处理,因此没有“迟到的数据”。 给定分钟的响应永远不会改变。您不必重复轮询某个给定时间范围来接收日志,因为它们涵盖那段时间时间会在我们的系统的日志。

返回数据的格式

Logpull Rest API 以 NDJSON 格式返回数据,其中每个日志行都是一个有效的 JSON 对象。  Google BigQuery 和 AWS Kinesis 等主要分析工具要求使用这种格式。

如果您要将生成的日志数据转换为每个日志行包含一个数组元素的 JSON 数组,则可使用 jq 工具。  基本上,您使用 slurp (或简称 s)标志将 API 响应传递到 jq:

<API request code> | jq -s

建议访问模式

基本访问模式是“给我 M 分钟内域名 Z 的所有日志”,其中分钟 M 是指在我们的日志系统中将日志记录写入磁盘的时间。开始时,可以尝试每分钟运行一次查询。如果响应太小,则最多延长到 5 分钟(这将适用于大多数域名)。 如果响应太大,请尝试缩短到 15 秒。如果您的域名有太多日志,以致于读取 1 分钟的日志需要超过 1 分钟的时间,则交错运行 2 名工作人员,每人每 2 分钟请求一次 1 分钟的日志。 

API 返回的数据在重复调用时不会更改。响应中的日志顺序可能不同,但如果响应代码为 200 且读取响应正文时没有错误,则这些日志的数量和内容对于给定查询将始终相同。

由于数据是由我们的日志处理系统批量引入的,因此每分钟查看少于 100 万条请求的大多数域名将具有“空”分钟:这样一分钟的查询将产生状态为 200 的响应,但正文中没有数据。这并不意味着在那一分钟内没有 Cloudflare 代理的请求;这只是意味着我们的系统在那一分钟内没有为该域名批量处理日志。

访问

/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>]

必要参数:

  • start:包容性;时间戳格式的 unix(根据定义为UTC)、unix nano 或 rfc3339(指定时区);比现在早最多 7 天
  • end:排他性;格式与 start 相同;必须比现在提前至少 5 分钟,并且晚于 start
startend 的最大时间范围不能超过 1 小时。start 是包括您指定的时间点的,end 是不包含您指定的时间点的。因此,要从上午 10 点开始获取每分钟的所有数据,正确的值为:start=2018-05-15T10:00:00Z&end=2018-05-15T10:01:00Z,然后  start=2018-05-15T10:01:00Z&end=2018-05-15T10:02:00Z,依此类推;“重叠”将得到正确处理。
  •  请求标头:
    • X-Auth-Email
    • X-Auth-Key(全局 API 密钥)

可选参数:

  • count:返回最多那一数量的记录。要返回所有记录,则不要包含 count 参数。
  • sample:仅返回记录的示例;sample=0.1 表示返回 10%(十分之一)的记录
  • fields:要返回的逗号分隔的字段列表;当为空时,返回默认列表(9 个字段)。
  • timestamps (beta):将返回时间戳字段所采用的格式,其中之一:“unixnano”(默认值)、“unix”、“rfc3339”。

示例 cURL: 

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>]

“rayids”接受的唯一参数是“fields”和“timestamps”。rayids 路由将返回 0、1 或更多记录(Ray ID 可能不唯一)。

服务期望

对于给定域名和时间范围,收到 200 响应并完全读取该响应后,以下所有后续请求都将如此:

  • 返回记录的数量和内容将相同。
  • 返回记录的顺序可以(并且可能)不同。

响应字段:

  • 当在请求 URL 中明确设置时,响应字段将永远不会更改,除非字段被指定为 “beta”,在这种情况下,它可能随时被删除
  • 未明确设置时,将使用默认字段;默认字段集可能随时更改。

限制:

  • 速率限制是每个域名每 5 秒 1 个请求。多个请求可以同时运行,但新请求每 5 秒只能发出一次。超过限制会导致 429 错误响应。
  • 最大时间范围(startend 参数之差为 1 小时)
  • 对于大于 1 分钟的时间范围,最大响应大小为 1GB 未压缩;对于 1 分钟或更短的时间范围,没有限制
    • 由于响应是stream方式传输的,因此无法提前确定响应大小。在stream传输 1GB 数据后,响应将失败,并且连接终止。允许用户根据请求量将查询调整到不会导致失败的范围。我们相信这是比任意时间范围(例如,每次 1 分钟)的硬限制请求更好的解决方案。

 

深度 API 参数

count

当提供 "?count=" 时,响应将包含最多 count 个结果。由于结果未排序,因此您可能会对重复请求获取不同的数据。

sample

当提供 "?sample=" 时,返回匹配记录的示例。如果"sample=0.1",将返回大约 10% 的记录。采样是随机的:重复调用不仅会返回不同的记录,而且返回记录的数量也可能略有不同。

如果还指定了 "?count=",则 count 将被应用于返回的记录数,而不是采样记录数。因此,对于 "sample=0.05" 和 "count=7",当总共有 100 条记录可用时,将返回大约 5 条记录。当有 1000 条记录时,将返回 7 条记录。当有 10000 条记录时,将返回 7 条记录。

fields

如果未指定“fields”,则默认情况下将返回一组有限的字段。此默认字段集可能随时更改。可在此处找到所有可用字段的完整列表:

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

字段以逗号分隔列表的形式传递给请求。因此,要拥有“ClientIP”和“RayID”,请使用:

fields=ClientIP,RayID

指定字段的顺序无关紧要,并且未指定响应中字段的顺序。

通过使用 Bash subshell 和 jq,您可以下载包含所有可用字段的日志,无需手动复制并将字段粘贴到请求中,例如:

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 "," -)"

当前可用字段(截至 2018 年 5 月):

"CacheCacheStatus": "unknown | miss | expired | updating | stale | hit | ignored | bypass | revalidated", 
“CacheResponseBytes”:
“高速缓存返回的字节数”,
“CacheResponseStatus”:
“高速缓存返回到节点的 HTTP 状态代码:所有请求(包括不可缓存的请求)都通过缓存:另请参阅 CacheStatus 字段”,
“CacheTieredFill”:
“分层高速缓存用于服务此请求 (beta)”,
“ClientASN”:
“客户 AS 号”,
“ClientCountry”:
“客户端 IP 地址的国家/地区”,
“ClientDeviceType”:
“客户端设备类型”,
“ClientIP”:
“客户端的 IP 地址”,
"ClientIPClass":
“客户端 IP 类:'unknown'、'clean'、'badHost'、'searchEngine'、'whitelist'、'greylist'、'monitoringService'、'securityScanner'、'noRecord'、'scan'、'backupService'、'mobilePlatform'、'tor'",
“ClientRequestBytes”:
“客户端请求中的字节数”,
“ClientRequestHost”:
“客户端请求的主机”,
“ClientRequestMethod”:
“客户端请求的 HTTP 方法”,
“ClientRequestProtocol”:
“客户端请求的 HTTP 协议”,
"ClientRequestReferer":
“HTTP 请求引用者”,
“ClientRequestURI”:“
客户端请求的 URI”,
“ClientRequestUserAgent”:
“客户端的用户代理”,
“ClientSSLCipher”:
“客户端 SSL 密码套件”,
“ClientSSLProtocol”:
“客户端 SSL (TLS) 协议”,
“ClientSrcPort”:
“客户端源端口”,
"EdgeColoID":
“Cloudflare 节点 colo id”,
“EdgeEndTimestamp”:
“节点完成向客户端发送响应的 Unix 纳秒时间戳”,
“EdgePathingOp”:
“表示为此请求发出了什么类型的响应(未知 = 没有特定操作)”,
“EdgePathingSrc”:
“详细说明如何根据安全检查对请求进行分类(未知 = 无特定分类)”,
“EdgePathingStatus”:
“表示用于确定处理此请求的数据(未知 = 无数据)”,
“EdgeRateLimitAction”:
“阻止规则采取的措施;如果不采取任何措施,则为空”(beta),
“EdgeRateLimitID”:
“UINT64:触发阻止(禁止)或simulate操作的速率限制规则的内部规则 ID。如果不采取行动,则为 0。(beta)”,
“EdgeRequestHost”:
“从节点到源站 (beta) 的请求上的主机标头”,
“EdgeResponseBytes”:
“节点返回给客户端的字节数”,
“EdgeResponseCompressionRatio”:
“节点响应压缩率”,
“EdgeResponseContentType”:
“节点响应内容类型标头值 (beta)”,
“EdgeResponseStatus”:
“Cloudflare 向客户端返回的 HTTP 状态代码”,
“EdgeServerIP”:“向源站发出请求的节点服务器的 IP (beta)”,
“EdgeStartTimestamp”:
“节点收到来自客户端的请求的 Unix 纳秒时间戳”,
“OriginIP”:
“源站的 IP”,
“OriginResponseBytes”:
“源站返回的字节数”,
“OriginResponseHTTPExpires”:
“RFC1123 格式的源站‘到期’标头的值”,
“OriginResponseHTTPLastModified”:
“RFC1123 格式的源站‘上次修改’标头的值”,
“OriginResponseStatus”:
“源站返回的状态”,
“OriginResponseTime”:
“源站将响应返回到节点所用的纳秒数”,
“OriginSSLProtocol”:
“用于连接到源站 (beta) 的 SSL (TLS) 协议”,
“RayID”:
“请求的ID”,
“SecurityLevel”:
“此请求时配置的安全级别。这用于确定 IP reputation系统的敏感度”,
“WAFAction”:
“WAF 采取的行动,如果触发”,
“WAFFlags”:
“其他配置标记:simulate (0x1) | null”,
“WAFMatchedVar”:
“最近匹配的变量的全名”,
“WAFProfile”:
“WAF 配置文件:低 |中 | 高”,
“WAFRuleID”:
“应用的 WAF 规则的 ID”,
“WAFRuleMessage”:
“与触发规则关联的规则”,
“WorkerCPUTime”:“执行 worker所花费的时间(以微秒为单位),如果有 (beta)”,
"WorkerStatus":
“作为字符串从 worker 守护程序返回的状态 (beta)”,
"WorkerSubrequest":
“此请求是否为 worker 子请求 (beta)”,
"WorkerSubrequestCount":
“worker 在处理此请求时发出的子请求数 (beta)”,
“ZoneID”:
“内部域名 ID”

时间戳

默认情况下,响应中的时间戳被返回为 Unix 纳秒整数。可设置 timestamps= 查询参数来更改返回响应时间戳的格式。可能的值为:unix、unixnano、rfc3339。注意:unix 和 unixnano 将时间戳作为整数返回;rfc3339 将时间戳作为字符串返回。

响应

到在我们的日志聚合点将数据写入磁盘时为这些数据加上时间戳。

响应数据在 json 中返回,每行 1 个 json 对象(1 个日志)。带有默认字段的日志示例:

{
"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"
}

估算每日数据量

要快速估算每天访问域名的数据量(日志行数和它们占用的字节数),则在 24 小时内在 1000 个数据样本中请求 1 个数据;注意 start=2017-09-10T00:00:00Z 和 end=2017-09-11T00:00:00Z,跨越 24 小时,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

根据此信息,每天日志数约为 47146000,字节大小为 15GB。大小估计基于默认响应字段集;更改响应字段集(请参阅“字段”部分)将更改响应大小。

为获得对每日流量的准确估计,最好在整个 24 小时内进行查询。如果响应大小太小或太大,则调整样本值,而不是时间范围。

压缩

默认情况下会压缩响应 (gzip)。Curl 透明地解压缩响应,除非使用 -H"accept-encoding: gzip" 加以调用。在这种情况下,输出仍然是 gzip 压缩。您应预计压缩数据约是未压缩的 5-10%。这意味着在具有 1GB 响应大小限制(未压缩)时,压缩的响应将为 50-100MB。

Beta

标记为“beta”的功能和字段仍在测试和验证中。它们可能会被移除,恕不另行通知。

Not finding what you need?

95% of questions can be answered using the search tool. This is the quickest way to get a response.

由 Zendesk 提供技术支持