可观测性 · Cloudflare Docs

Cloudflare Tunnel 提供日志、指标和诊断工具，帮助您监控隧道运行状况并解决问题。

隧道运行状况

您可以转到 Networking（网络） > Tunnels（隧道） 在 Cloudflare 仪表板 ↗中检查隧道连接状态，或者通过运行 cloudflared tunnel list 来检查。

状态	含义	建议的操作
Healthy（健康）	隧道处于活动状态，并通过与 Cloudflare 全球网络的四个连接来提供流量服务。	无需采取任何操作。您的隧道运行正常。
Inactive	隧道已创建（通过 API 或仪表板），但从未运行 `cloudflared` 连接器来建立连接。	在您的源服务器上安装并运行 `cloudflared` 以将隧道连接到 Cloudflare。您可以在 Cloudflare 仪表板中的 Networking（网络） > Tunnels（隧道）下找到安装命令——选择您的隧道，然后选择 Overview（概览）选项卡中的 Add a replica（添加副本）。对于基于 API 的设置，请参阅安装并运行隧道。
Down（中断）	隧道此前已连接，但当前已断开连接，因为 `cloudflared` 进程已停止。	1. 确保 `cloudflared` 服务或进程在您的服务器上处于活动运行状态。 2. 检查服务器端问题，例如机器断电、应用程序崩溃或最近的网络变更。
Degraded（降级）	`cloudflared` 连接器正在运行且隧道正在提供流量服务，但至少有一个单独的连接失败。若隧道可用性进一步降级，可能会有隧道停机并无法提供流量服务的风险。	1. 查看您的 `cloudflared` 日志以获取连接失败或错误消息。 2. 调查本地网络和防火墙规则，以确保它们没有阻止与 Cloudflare Tunnel IP 和端口的连接。

通知

管理员可以在隧道运行状况或部署状态发生变化时收到警报。通知可以通过电子邮件、webhook 或第三方服务发送。

要配置隧道通知，请参阅创建通知。

Tunnel Creation or Deletion Event

适用对象

希望在其账户中创建或删除 Cloudflare Tunnel 时收到通知的客户。

其他选项/筛选条件

无。

包含于

所有 Cloudflare Zero Trust 套餐。

收到通知后应如何处理？

无需执行任何操作。

Tunnel Health Alert

适用对象

希望在其 Cloudflare Tunnel 的健康状态发生变化时收到警告的客户。

其他选项/筛选条件

无。

包含于

所有 Cloudflare Zero Trust 套餐。

收到通知后应如何处理？

持续监控隧道健康状况，并考虑部署 cloudflared 副本或负载均衡器。

附加信息

请参阅隧道状态，查看可能的隧道状态列表（Healthy、Inactive、Down 和 Degraded）。

日志

隧道日志记录了 cloudflared 与 Cloudflare 全球网络之间的所有活动，以及 cloudflared 与您的源服务器之间的所有活动。

服务器端日志

如果可以访问源站服务器，可以在启动隧道时使用 --loglevel 标志启用日志记录。默认情况下，cloudflared 将日志写入标准错误（stderr），不会在服务器上存储日志。

要将每条日志格式化为 JSON 对象，请在 run 前添加 --output json：

cloudflared tunnel --output json run <UUID>

此格式适用于 Kubernetes 部署和使用 JSON 的日志收集系统。

对于常规持久化日志记录，请使用 --log-directory <PATH> 运行隧道。此标志将日志写入指定目录中的 cloudflared.log，文件达到 1 MB 时轮转，最多保留五份备份。它不会根据日志的存放时间将其删除。

cloudflared tunnel --loglevel info --log-directory <PATH> run <UUID>

对于短期排查，或由其他工具管理轮转时，请改用 --logfile 标志。cloudflared 不会轮转 --logfile 指定的文件。如果同时设置两个标志，--logfile 优先。

远程日志流式传输

您可以在无需通过 SSH 访问服务器的情况下，实时从正在运行的隧道中流式传输日志。

cloudflared 守护进程可以将您账户中任何 Tunnel 的日志流式传输到本地命令行。您的本地机器和源服务器上都必须安装 cloudflared。

在本地机器上，向您的 Cloudflare 账户身份验证 cloudflared：
```
cloudflared tunnel login
```
针对特定的 Tunnel 运行 cloudflared tail：
```
cloudflared tail <UUID>
```
为了更结构化地查看 JSON 消息，您可以将输出管道传输到类似 jq ↗ 的工具：
```
cloudflared tail --output=json <UUID> | jq .
```

如果您运行了多个副本，则可以指定从哪个副本流式传输日志：
```
cloudflared tail --connector-id <REPLICA ID> <UUID>
```
要找到副本 ID，请转到 Networking（网络） > Tunnels（隧道） 并选择您的隧道。所有活动副本都会显示在隧道概述页面的 Connectors（连接器） 列表中。副本 ID 就是 Connector ID（连接器 ID）。

日志过滤选项

您可以按事件类型 (--event)、事件级别 (--level) 或采样率 (-sampling) 过滤日志，以减少从源站流式传输的日志量。这有助于减轻对源站的性能影响，尤其是在源站通常处于高负载的情况下。例如：

cloudflared tail --level debug <UUID>

标志	描述	允许的值	默认值
`--event`	按事件/请求的类型进行过滤。	`cloudflared`, `http`, `tcp`, `udp`	所有事件
`--level`	返回此级别及以上的日志。独立于服务器上的 `--loglevel` 设置运行。	`debug`, `info`, `warn`, `error`, `fatal`	`debug`
`--sampling`	对总日志的一部分进行采样。	`0.0` 到 `1.0` 之间的数字	`1.0`

要从仪表板流式传输 Tunnel 日志：

在 Cloudflare 仪表板中，前往 Networking（网络） > Tunnels（隧道），选择你的隧道。
前往 Tunnels（隧道） ↗
前往 Live logs（实时日志） 选项卡。
选择 Live（实时） 开始流式查看。

查看副本（replica）的日志

如果为同一个隧道运行多个 cloudflared 实例（也称为副本），所有已连接副本的日志会自动流式传输，并按主机名分组，便于识别每条日志由哪台主机产生。

要将日志流筛选为特定副本，请选择 Filter（筛选） 图标，并展开 Replicas（副本） 部分。还可以按 Log Level（日志级别） 和 Event Type（事件类型） 筛选。

网络会话日志

Zero Trust 网络会话日志记录 Cloudflare 路由到隧道的每个私有网络会话。路由到 Cloudflare Tunnel 的会话将 Offramp 报告为 TUNNEL。以下两个字段显示会话的确切发送位置：

字段	描述
`DestinationTunnelID`	接收会话的隧道。
`DestinationReplicaID`	接收会话的 `cloudflared` 副本。此值与仪表板中副本的 Connector ID（连接器 ID）一致。

如果运行多个副本，请使用这些字段确认哪个隧道和副本接收了特定会话的流量。要进一步调查该副本，使用 cloudflared tail --connector-id <DESTINATION_REPLICA_ID> <TUNNEL_ID> 流式查看其日志。

可通过 Logpush 获取网络会话日志。

指标

Tunnel 指标可以显示 Cloudflare Tunnel 随着时间推移的吞吐量和资源使用情况。当您运行 Tunnel 时，cloudflared 会启动一个 Prometheus 指标终结点 —— 即一个以 Prometheus ↗ 格式公开指标的 HTTP 服务器。您可以在远程机器上使用 Prometheus 工具包从 cloudflared 服务器抓取指标数据。

默认指标服务器地址

在非容器化环境中，cloudflared 将指标服务器启动在 127.0.0.1:<PORT>/metrics 上，其中 <PORT> 是 20241 到 20245 范围内第一个可用的端口。如果所有端口都不可用，cloudflared 会绑定到一个随机端口。在容器化环境（Docker、Kubernetes）中，默认地址为 0.0.0.0:<PORT>/metrics。

要确定默认端口，请在 Tunnel 启动时左右检查您的 Tunnel 日志。例如：

2024-12-19T21:17:58Z INF Starting metrics server on 127.0.0.1:20241/metrics

配置自定义地址

要在自定义 IP 地址和端口上提供指标服务，请在 cloudflared 主机上执行以下步骤：

使用 --metrics 标志运行 Tunnel。例如，
```
cloudflared tunnel --metrics 127.0.0.1:60123 run my-tunnel
```
说明
如果您打算从本地网络上的另一台机器获取指标，请将 127.0.0.1 替换为 cloudflared 服务器的内部 IP（例如 198.168.x.x）。要在所有可用的网络接口上提供指标服务，请使用 0.0.0.0。
通过访问 http://localhost:60123/metrics 验证指标服务器是否正在运行。这仅在您配置了本地主机 IP（127.0.0.1 或 0.0.0.0）时才有效。

您现在可以将指标导出到 Prometheus 和 Grafana，以进行数据可视化和查询。有关如何开始使用这些工具的说明，请参阅 Grafana 教程。

cloudflared 指标

名称	描述	类型	标签
`build_info`	构建和版本信息。	GAUGE	`goversion`, `revision`, `type`, `version`
`cloudflared_config_local_config_pushes`	推送到 Cloudflare 的本地配置次数。	COUNTER
`cloudflared_config_local_config_pushes_errors`	在推送本地配置期间发生的错误次数。	COUNTER
`cloudflared_orchestration_config_version`	配置版本。	GAUGE
`cloudflared_tcp_active_sessions`	正在代理到任何源站的并发 TCP 会话数。	GAUGE
`cloudflared_tcp_total_sessions`	已代理到任何源站的 TCP 会话总数。	COUNTER
`cloudflared_tunnel_active_streams`	活动数据流的总数。	GAUGE
`cloudflared_tunnel_concurrent_requests_per_tunnel`	通过每个 Tunnel 代理的并发请求数。	GAUGE
`cloudflared_tunnel_ha_connections`	活动的高可用（HA）连接数。	GAUGE
`cloudflared_tunnel_request_errors`	代理到源站时的错误数。	COUNTER
`cloudflared_tunnel_server_locations`	每个 Tunnel 连接到的位置。`1` 表示当前位置，`0` 表示之前的位置。	GAUGE	`connection_id`, `edge_location`
`cloudflared_tunnel_timer_retries`	未确认的心跳计数。	GAUGE
`cloudflared_tunnel_total_requests`	通过所有 Tunnel 代理的请求数。	COUNTER
`cloudflared_tunnel_tunnel_authenticate_success`	成功进行 Tunnel 身份验证的事件数。	COUNTER
`cloudflared_tunnel_tunnel_register_success`	成功的 Tunnel 注册次数。	COUNTER	`rpcName`
`cloudflared_udp_active_sessions`	正在代理到任何源站的并发 UDP 会话数。	GAUGE
`cloudflared_udp_total_sessions`	已代理到任何源站的 UDP 会话总数。	COUNTER
`coredns_panics_total`	Panic 次数。	COUNTER
`quic_client_closed_connections`	已关闭的连接数。	COUNTER
`quic_client_latest_rtt`	在连接上测量到的最新往返时间（RTT）。	GAUGE	`conn_index`
`quic_client_lost_packets`	从连接中丢失的封包数。	COUNTER	`conn_index`, `reason`
`quic_client_min_rtt`	在连接上测量到的最低 RTT（以毫秒为单位）。	GAUGE	`conn_index`
`quic_client_packet_too_big_dropped`	从源站接收到的、因过大而无法发送到 Cloudflare 并因此被丢弃的封包数。	COUNTER
`quic_client_smoothed_rtt`	为连接计算的平滑 RTT（以毫秒为单位）。	GAUGE	`conn_index`
`quic_client_total_connections`	发起的连接数。对于所有 QUIC 指标，客户端指发起连接的一方。	COUNTER

Prometheus 指标

名称	描述	类型	标签
`promhttp_metric_handler_requests_in_flight`	当前正在提供服务的抓取请求数。	GAUGE
`promhttp_metric_handler_requests_total`	按 HTTP 状态代码分类的抓取总数。	COUNTER	`code`

Go 运行时指标

名称	描述	类型	标签
`go_gc_duration_seconds`	垃圾回收周期的暂停持续时间摘要。	SUMMARY
`go_goroutines`	当前存在的 goroutine 数量。	GAUGE
`go_info`	有关 Go 环境的信息。	GAUGE	`version`
`go_memstats_alloc_bytes`	已分配且仍在使用中的字节数。	GAUGE
`go_memstats_alloc_bytes_total`	分配的字节总数，即使已被释放。	COUNTER
`go_memstats_buck_hash_sys_bytes`	剖析存储桶哈希表所使用的字节数。	GAUGE
`go_memstats_frees_total`	释放的总次数。	COUNTER
`go_memstats_gc_sys_bytes`	用于垃圾回收系统元数据的字节数。	GAUGE
`go_memstats_heap_alloc_bytes`	已分配且仍在使用中的堆字节数。	GAUGE
`go_memstats_heap_idle_bytes`	等待被使用的堆字节数。	GAUGE
`go_memstats_heap_inuse_bytes`	正在使用中的堆字节数。	GAUGE
`go_memstats_heap_objects`	已分配的对象数。	GAUGE
`go_memstats_heap_released_bytes`	释放给操作系统的堆字节数。	GAUGE
`go_memstats_heap_sys_bytes`	从系统获取的堆字节数。	GAUGE
`go_memstats_last_gc_time_seconds`	自 1970 年以来最后一次垃圾回收的秒数。	GAUGE
`go_memstats_lookups_total`	指针查找的总次数。	COUNTER
`go_memstats_mallocs_total`	内存分配（malloc）的总次数。	COUNTER
`go_memstats_mcache_inuse_bytes`	mcache 结构正在使用的字节数。	GAUGE
`go_memstats_mcache_sys_bytes`	从系统获取的用于 mcache 结构的字节数。	GAUGE
`go_memstats_mspan_inuse_bytes`	mspan 结构正在使用的字节数。	GAUGE
`go_memstats_mspan_sys_bytes`	从系统获取的用于 mspan 结构的字节数。	GAUGE
`go_memstats_next_gc_bytes`	下一次垃圾回收发生时的堆字节数。	GAUGE
`go_memstats_other_sys_bytes`	用于其他系统分配的字节数。	GAUGE
`go_memstats_stack_inuse_bytes`	栈分配器正在使用的字节数。	GAUGE

诊断日志

Cloudflare Tunnel 生成收集本地计算机上运行的单个 cloudflared 实例数据的诊断报告。这需要 cloudflared 版本 2024.12.2 或更高版本。

生成诊断信息

（仅限 Linux）要在日志中包含网络诊断，请允许 cloudflared 用户在没有 root 权限的情况下创建 RAW 和 PACKET 套接字：
```
sudo setcap cap_net_raw+ep /usr/bin/traceroute && sudo setcap cap_net_raw+ep /usr/bin/traceroute
```
如果您没有设置 cap_net_raw，则 traceroute 数据将不可用。
获取诊断日志：
```
cloudflared tunnel diag
```
如果在同一个宿主机上运行着多个 cloudflared 实例，请为要诊断的实例指定指标服务器（metrics server）IP 和端口。例如：
```
cloudflared tunnel diag --metrics 127.0.0.1:20241
```

此命令将输出每个诊断任务的状态，并在您的工作目录中放置一个 cloudflared-diag-YYYY-MM-DDThh-mm-ss.zip 文件。

Docker 诊断

cloudflared 从 Tunnel 指标服务器（tunnel metrics server）读取诊断数据。要获取诊断日志，必须从 Docker 容器中公开指标服务器，并使其可从宿主机访问。

确定在 Docker 中运行的 cloudflared 实例的指标服务器端口。
确保在部署容器时启用了端口转发。诊断功能将使用本地端口 20241 向 Docker 实例请求信息，因此您应该将端口 20241 转发到步骤 1 中获取的容器端口：
```
docker run -d -p 20241:<metrics_port> docker.io/cloudflare/cloudflared tunnel ...
```

验证您可以从 Docker 宿主环境访问指标服务器地址：

curl localhost:20241/diag/tunnel

该命令应返回一个 JSON：

{
  "tunnelID": "ef96b330-a7f5-4bce-a00e-827ce5be077f",
  "connectorID": "d236670a-9f74-422f-adf1-030f5c5f0523",
  "connections": [
    { "isConnected": true, "protocol": 1, "edgeAddress": "198.41.192.167"},
    {"isConnected": true, "protocol": 1, "edgeAddress": "198.41.200.113", "index": 1},
    {"isConnected": true, "protocol": 1, "edgeAddress": "198.41.192.47", "index": 2},
    {"isConnected": true, "protocol": 1, "edgeAddress": "198.41.200.73", "index": 3}
  ],
  "icmp_sources": ["192.168.1.243", "fe80::c59:bd4a:e815:ed6"]
}

使用本地指标地址和 Docker 容器 ID 运行诊断：
```
cloudflared tunnel diag --metrics localhost:20241 --diag-container-id=<containerID>
```
或者，您可以指定容器的名称而不是其 ID：
```
cloudflared tunnel diag --metrics localhost:20241 --diag-container-id=<containerName>
```
如果你在第 2 步中转发了其他本地端口，请将 20241 替换为该端口。

使用容器 ID 运行诊断命令允许 cloudflared 从 Docker 环境中收集信息，例如日志和容器详细信息。

此命令将输出每个诊断任务的状态，并在您的工作目录中放置一个 cloudflared-diag-YYYY-MM-DDThh-mm-ss.zip 文件。

Kubernetes 诊断

诊断功能将使用端口 20241 到 20245 从 Tunnel 指标服务器（tunnel metrics server）请求数据。您需要使用端口转发，以允许本地 cloudflared 实例在这些端口之一上连接到指标服务器。

确定 Tunnel 的指标服务器端口。
启用端口转发：
```
kubectl port-forward <pod> <diagnostic_port>:<metrics_port>
```
- <pod>：运行 Tunnel 的 pod 的名称
- <diagnostic_port> 是 20241 到 20245 范围内的任何本地端口。
- <metrics_port> 是您要诊断的 cloudflared 实例的 Kubernetes pod 端口（在步骤 1 中获取）。
例如，如果您将指标服务器地址设置为 0.0.0.0:12345：
```
kubectl port-forward cloudflared-6d4897585b-r8kfz 20244:12345
```
发送到本地端口 20244 的连接将转发到运行 Tunnel 的 pod 的端口 12345。
运行诊断：
```
cloudflared tunnel diag --diag-pod-id=<podID>
```
如果 pod 运行着多个应用程序/服务，且 cloudflared 不是 pod 中的第一个，您必须指定容器 ID 或名称：
```
cloudflared tunnel diag --diag-pod-id=<podID> --diag-container-id=<containerName>
```

此命令将输出每个诊断任务的状态，并在您的工作目录中放置一个 cloudflared-diag-YYYY-MM-DDThh-mm-ss.zip 文件。

诊断文件内容

cloudflared-diag-YYYY-MM-DDThh-mm-ss.zip 压缩包包含以下列出的文件。文件中的数据要么适用于正在接受诊断的 cloudflared 实例（diagnosee，被诊断实例）要么适用于触发诊断的实例（diagnoser，诊断发起实例）。例如，如果您的 Tunnel 在 Docker 容器中运行，则被诊断实例（diagnosee）是 Docker 实例，而诊断发起实例（diagnoser）是宿主机实例。

文件名	描述	实例
`cli-configuration.json`	启动 Tunnel 时使用的 Tunnel 运行参数	diagnosee
`cloudflared_logs.txt`	Tunnel 日志文件[^1]	diagnosee
`configuration.json`	Tunnel 配置参数	diagnosee
`goroutine.pprof`	由 `pprof` 提供的 goroutine 分析文件	diagnosee
`heap.pprof`	由 `pprof` 提供的 heap（堆）分析文件	diagnosee
`metrics.txt`	诊断时 Tunnel 指标的快照	diagnosee
`network.txt`	使用 IPv4 和 IPv6 到 Cloudflare 全球网络的 JSON 格式 traceroute 结果	diagnoser
`raw-network.txt`	使用 IPv4 和 IPv6 到 Cloudflare 全球网络的原始 traceroute 结果	diagnoser
`systeminformation.json`	操作系统信息和资源使用情况	diagnosee
`task-result.json`	每个诊断任务的结果	diagnoser
`tunnelstate.json`	诊断时的 Tunnel 连接情况	diagnosee

[^1]：如果日志文件为空，您可能需要在启动 Tunnel 时将 --loglevel 设置为 debug。只有当您从 CLI 使用 cloudflared tunnel run 命令运行 Tunnel 时，才需要 --loglevel 参数。如果 Tunnel 作为 Linux/macOS 服务运行，或者在 Docker/Kubernetes 中运行，则不需要此参数。