跳转到内容
搜索文档
↵选择
↑↓导航
ESC关闭

GraphQL Analytics API

最后更新 查看 MarkdownAgent 设置

Privacy Proxy 通过 Cloudflare 的 GraphQL Analytics API 提供指标。所有指标均可通过单个端点进行查询：

POST https://api.cloudflare.com/client/v4/graphql

在开始之前，您需要：

  • API 令牌 — 创建一个具有 Account Analytics 读取权限的令牌。有关更多信息，请参阅我们的 Analytics API 令牌文档：配置 Analytics API 令牌。
  • 账户 ID — 您的 Cloudflare 账户 ID，在查询中作为 accountTag 传递。有关更多信息，请参阅 查找账户和区域 ID。

发送请求

以下示例显示如何使用 curl 查询您的 Privacy Proxy 指标每日请求量。请将占位符替换为您自己的值。

curl https://api.cloudflare.com/client/v4/graphql \
  --header "Authorization: Bearer <API_TOKEN>" \
  --header "Content-Type: application/json" \
  --data '{
    "query": "query DailyRequestVolume($accountTag: String!, $startDate: Date!, $endDate: Date!) { viewer { accounts(filter: { accountTag: $accountTag }) { privacyProxyRequestMetricsAdaptiveGroups(filter: { date_geq: $startDate, date_leq: $endDate }, limit: 10000, orderBy: [date_ASC]) { count dimensions { date } } } } }",
    "variables": {
      "accountTag": "<YOUR_ACCOUNT_TAG>",
      "startDate": "2026-04-04",
      "endDate": "2026-04-06"
    }
  }'

可用节点

提供了四个 GraphQL 节点。所有这四个节点都只返回聚合数据——不会公开任何每条连接的原始记录。

  1. privacyProxyRequestMetricsAdaptiveGroups — 查询聚合请求量和错误率，可按时间、位置、端点、状态码和代理状态维度进行过滤。
  2. privacyProxyIngressConnMetricsAdaptiveGroups — 查询客户端到代理的连接数、传输字节数和延迟百分位数，可按时间、位置、端点和传输维度进行过滤。
  3. privacyProxyEgressConnMetricsAdaptiveGroups — 查询代理到源站的连接数、传输字节数和延迟百分位数，可按时间、位置、端点和传输维度进行过滤。
  4. privacyProxyAuthMetricsAdaptiveGroups — 查询身份验证尝试次数，可按时间、位置、端点、身份验证方法和身份验证结果维度进行过滤。

模式

指标

总和字段

字段 类型 描述 节点
bytesSentToClient uint64 从代理发送回客户端的总字节数。 入口连接
bytesRecvdFromClient uint64 代理从客户端接收的总字节数。 入口连接
bytesSentToOrigin uint64 从代理发送到上游源站的总字节数。 出口连接
bytesRecvdFromOrigin uint64 代理从上游源站接收的总字节数。 出口连接
packetsSentToClient uint64 从代理发送回客户端的总数据包数。 入口连接
packetsRecvdFromClient uint64 代理从客户端接收的总数据包数。 入口连接
packetsSentToOrigin uint64 从代理发送到上游源站的总数据包数。 出口连接
packetsRecvdFromOrigin uint64 代理从上游源站接收的总数据包数。 出口连接

计数字段

所有四个节点都公开一个 count 字段，该字段返回与查询过滤器匹配的采样事件（请求、连接或验证尝试）的总数。

分位数字段

字段 类型 描述 节点
durationMsP50 float64 连接生命周期的中位数，以毫秒为单位。 入口和出口连接
durationMsP95 float64 第 95 百分位连接生命周期，以毫秒为单位。 入口和出口连接
durationMsP99 float64 第 99 百分位连接生命周期，以毫秒为单位。 入口和出口连接
handshakeDurationUsP50 float64 TCP+TLS/QUIC 握手时间中位数，以微秒为单位。 入口和出口连接
handshakeDurationUsP95 float64 第 95 百分位握手时间，以微秒为单位。 入口和出口连接
handshakeDurationUsP99 float64 第 99 百分位握手时间，以微秒为单位。 入口和出口连接
connectRequestHandlingDurationUsP50 float64 处理 CONNECT 请求的时间中位数，以微秒为单位。暂不可用。 请求
connectRequestHandlingDurationUsP95 float64 第 95 百分位处理 CONNECT 请求的时间，以微秒为单位。暂不可用。 请求
connectRequestHandlingDurationUsP99 float64 第 99 百分位处理 CONNECT 请求的时间，以微秒为单位。暂不可用。 请求
connectTunnelSetupDurationUsP50 float64 接收到 CONNECT 请求后建立隧道的耗时中位数，以微秒为单位。暂不可用。 请求
connectTunnelSetupDurationUsP95 float64 第 95 百分位隧道建立时间，以微秒为单位。暂不可用。 请求
connectTunnelSetupDurationUsP99 float64 第 99 百分位隧道建立时间，以微秒为单位。暂不可用。 请求

维度

所有节点

字段 类型 描述
date Date 日历日期（按天精度）。
datetimeMinute Time 截断到分钟的时间戳。
datetimeFiveMinutes Time 截断到五分钟间隔的时间戳。
datetimeFifteenMinutes Time 截断到十五分钟间隔的时间戳。
datetimeHour Time 截断到小时的时间戳。
coloCode string 处理请求的 Cloudflare 数据中心。
endpoint string 生成流量的 appId。

所有时间戳维度都指代每次连接或请求的结束，而不是开始。

仅请求节点

字段 类型 描述
statusCode uint16 代理返回给客户端的 HTTP 状态码。
proxyStatus string 代理级别的错误分类。未发生代理级别错误时为 null。请参阅 代理状态参考 获取可能的值。
tunnelType string 使用的隧道协议（connect-tcp、connect-udp、connect-ip）。暂不可用。

仅入口连接节点

字段 类型 描述
transport string 客户端到代理连接的传输协议（tcp、quic）。
tlsVersion string 客户端到代理连接上协商的 TLS 版本。暂不可用。

仅出口连接节点

字段 类型 描述
transport string 代理到源站连接的传输协议（tcp、quic）。

仅验证节点

字段 类型 描述
authMethod string 使用的身份验证方法（例如 Token、Psk）。
authResult string 身份验证结果（success、failure）。

参数

所有四个节点都共享相同的参数签名。

  • filter 必填 — 过滤您的数据。在过滤器内 accountTag 始终是必填的。
  • limit 选填 — 要返回的最大记录数。
  • orderBy 选填 — 结果的排序方式。

示例查询

privacyProxyRequestMetricsAdaptiveGroups 节点

请求量总览

获取指定日期范围内每日请求量的简要视图。

query DailyRequestVolume(
  $accountTag: String!
  $startDate: Date!
  $endDate: Date!
 ) {
  viewer {
    accounts(filter: { accountTag: $accountTag }) {
      privacyProxyRequestMetricsAdaptiveGroups(
        filter: {
          date_geq: $startDate
          date_leq: $endDate
        }
        limit: 10000
        orderBy: [date_ASC]
      ) {
        count
        dimensions {
          date
        }
      }
    }
  }
}
{
  "accountTag": "<YOUR_ACCOUNT_TAG>",
  "startDate": "2026-04-04",
  "endDate": "2026-04-06"
}

按状态码和代理状态细分的错误

识别正在发生的 HTTP 状态码和代理级别错误，以准确定位故障来源。

query ErrorBreakdown(
  $accountTag: String!
  $start: Time!
  $end: Time!
) {
  viewer {
    accounts(filter: { accountTag: $accountTag }) {
      privacyProxyRequestMetricsAdaptiveGroups(
        filter: {
          datetimeFifteenMinutes_geq: $start
          datetimeFifteenMinutes_leq: $end
          statusCode_geq: 400
        }
        limit: 10000
        orderBy: [datetimeFifteenMinutes_ASC]
      ) {
        count
        dimensions {
          datetimeFifteenMinutes
          statusCode
          proxyStatus
        }
      }
    }
  }
}
{
  "accountTag": "<YOUR_ACCOUNT_TAG>",
  "start": "2026-04-04T00:00:00Z",
  "end": "2026-04-06T23:59:59Z"
}

按频率排序的排前代理错误

对最频繁发生的代理错误类型进行排序，以确定排查的优先级。

query TopProxyErrors(
  $accountTag: String!
  $start: Date!
  $end: Date!
) {
  viewer {
    accounts(filter: { accountTag: $accountTag }) {
      privacyProxyRequestMetricsAdaptiveGroups(
        filter: {
          date_geq: $start
          date_leq: $end
          proxyStatus_neq: ""
        }
        limit: 10000
        orderBy: [count_DESC]
      ) {
        count
        dimensions {
          proxyStatus
          statusCode
        }
      }
    }
  }
}
{
  "accountTag": "<YOUR_ACCOUNT_TAG>",
  "start": "2026-04-04",
  "end": "2026-04-06"
}

隧道类型分布

监控随时间推移的 connect-tcp、connect-udp 和 connect-ip 的混合情况，以了解客户端的连接方式。

query TunnelTypeDistribution(
  $accountTag: String!
  $startDate: Date!
  $endDate: Date!
) {
  viewer {
    accounts(filter: { accountTag: $accountTag }) {
      privacyProxyRequestMetricsAdaptiveGroups(
        filter: {
          date_geq: $startDate
          date_leq: $endDate
        }
        limit: 10000
        orderBy: [date_ASC]
      ) {
        count
        dimensions {
          date
          tunnelType
        }
      }
    }
  }
}
{
  "accountTag": "<YOUR_ACCOUNT_TAG>",
  "startDate": "2026-04-04",
  "endDate": "2026-04-06"
}

privacyProxyIngressConnMetricsAdaptiveGroups 节点

连接量和入口字节数总览

获取每日入口连接数和传输字节数的简要视图。

query IngressTrafficOverview(
  $accountTag: String!
  $startDate: Date!
  $endDate: Date!
) {
  viewer {
    accounts(filter: { accountTag: $accountTag }) {
      privacyProxyIngressConnMetricsAdaptiveGroups(
        filter: {
          date_geq: $startDate
          date_leq: $endDate
        }
        limit: 10000
        orderBy: [date_ASC]
      ) {
        count
        sum {
          bytesSentToClient
          bytesRecvdFromClient
        }
        dimensions {
          date
        }
      }
    }
  }
}
{
  "accountTag": "<YOUR_ACCOUNT_TAG>",
  "startDate": "2026-04-04",
  "endDate": "2026-04-06"
}

按数据中心细分的连接持续时间

比较不同数据中心的客户端到代理连接持续时间，以识别具有长连接或停滞连接的区域。

query IngressDurationByColo(
  $accountTag: String!
  $startDate: Date!
  $endDate: Date!
) {
  viewer {
    accounts(filter: { accountTag: $accountTag }) {
      privacyProxyIngressConnMetricsAdaptiveGroups(
        filter: {
          date_geq: $startDate
          date_leq: $endDate
        }
        limit: 10000
        orderBy: [quantiles_durationMsP50_DESC]
      ) {
        quantiles {
          durationMsP50
          durationMsP95
          durationMsP99
        }
        dimensions {
          coloCode
        }
      }
    }
  }
}
{
  "accountTag": "<YOUR_ACCOUNT_TAG>",
  "startDate": "2026-04-04",
  "endDate": "2026-04-06"
}

协议和 TLS 版本分布

了解您的客户端使用的传输协议（QUIC 与 TCP）和 TLS 版本，有助于您规划废弃计划、检测配置错误的客户端并验证流量是否符合您的安全要求。

query IngressProtocolDistribution(
  $accountTag: String!
  $start: Time!
  $end: Time!
) {
  viewer {
    accounts(filter: { accountTag: $accountTag }) {
      privacyProxyIngressConnMetricsAdaptiveGroups(
        filter: {
          datetimeFifteenMinutes_geq: $start
          datetimeFifteenMinutes_leq: $end
        }
        limit: 10000
        orderBy: [datetimeFifteenMinutes_ASC]
      ) {
        count
        dimensions {
          datetimeFifteenMinutes
          transport
          tlsVersion
        }
      }
    }
  }
}
{
  "accountTag": "<YOUR_ACCOUNT_TAG>",
  "start": "2026-04-04T00:00:00Z",
  "end": "2026-04-06T23:59:59Z"
}

privacyProxyEgressConnMetricsAdaptiveGroups 节点

出口字节数总览

获取代理与上游源站之间每日流动字节数的简要视图。

query EgressBytesOverview(
  $accountTag: String!
  $startDate: Date!
  $endDate: Date!
) {
  viewer {
    accounts(filter: { accountTag: $accountTag }) {
      privacyProxyEgressConnMetricsAdaptiveGroups(
        filter: {
          date_geq: $startDate
          date_leq: $endDate
        }
        limit: 10000
        orderBy: [date_ASC]
      ) {
        count
        sum {
          bytesSentToOrigin
          bytesRecvdFromOrigin
        }
        dimensions {
          date
        }
      }
    }
  }
}
{
  "accountTag": "<YOUR_ACCOUNT_TAG>",
  "startDate": "2026-04-04",
  "endDate": "2026-04-06"
}

按数据中心细分的代理到源站延迟

比较不同数据中心的代理到源站握手时间，以识别源站可达性降低的区域。

query EgressLatencyByColo(
  $accountTag: String!
  $startDate: Date!
  $endDate: Date!
) {
  viewer {
    accounts(filter: { accountTag: $accountTag }) {
      privacyProxyEgressConnMetricsAdaptiveGroups(
        filter: {
          date_geq: $startDate
          date_leq: $endDate
        }
        limit: 10000
        orderBy: [quantiles_handshakeDurationUsP50_DESC]
      ) {
        quantiles {
          handshakeDurationUsP50
          handshakeDurationUsP95
          handshakeDurationUsP99
        }
        dimensions {
          coloCode
        }
      }
    }
  }
}
{
  "accountTag": "<YOUR_ACCOUNT_TAG>",
  "startDate": "2026-04-04",
  "endDate": "2026-04-06"
}

出口性能趋势

在特定时间窗口内，以精细粒度跟踪代理到源站的握手延迟。

query EgressPerformanceTrend(
  $accountTag: String!
  $start: Time!
  $end: Time!
) {
  viewer {
    accounts(filter: { accountTag: $accountTag }) {
      privacyProxyEgressConnMetricsAdaptiveGroups(
        filter: {
          datetimeFiveMinutes_geq: $start
          datetimeFiveMinutes_leq: $end
        }
        limit: 10000
        orderBy: [datetimeFiveMinutes_ASC]
      ) {
        quantiles {
          handshakeDurationUsP50
          handshakeDurationUsP95
          handshakeDurationUsP99
        }
        count
        dimensions {
          datetimeFiveMinutes
        }
      }
    }
  }
}
{
  "accountTag": "<YOUR_ACCOUNT_TAG>",
  "start": "2026-04-04T08:00:00Z",
  "end": "2026-04-06T14:00:00Z"
}

privacyProxyAuthMetricsAdaptiveGroups 节点

按方法细分的身份验证量

跟踪每种方法的每日身份验证量，以了解采用情况并发现异常。

query AuthVolumeByMethod(
  $accountTag: String!
  $startDate: Date!
  $endDate: Date!
) {
  viewer {
    accounts(filter: { accountTag: $accountTag }) {
      privacyProxyAuthMetricsAdaptiveGroups(
        filter: {
          date_geq: $startDate
          date_leq: $endDate
        }
        limit: 10000
        orderBy: [date_ASC]
      ) {
        count
        dimensions {
          date
          authMethod
        }
      }
    }
  }
}
{
  "accountTag": "<YOUR_ACCOUNT_TAG>",
  "startDate": "2026-04-04",
  "endDate": "2026-04-06"
}

身份验证失败峰值检测

检测身份验证失败的激增，并识别是哪种验证方法失败。

query AuthFailureSpike(
  $accountTag: String!
  $start: Time!
  $end: Time!
) {
  viewer {
    accounts(filter: { accountTag: $accountTag }) {
      privacyProxyAuthMetricsAdaptiveGroups(
        filter: {
          datetimeMinute_geq: $start
          datetimeMinute_leq: $end
          authResult: "failure"
        }
        limit: 10000
        orderBy: [datetimeFiveMinutes_ASC]
      ) {
        count
        dimensions {
          datetimeFiveMinutes
          authMethod
        }
      }
    }
  }
}
{
  "accountTag": "<YOUR_ACCOUNT_TAG>",
  "start": "2026-04-04T10:00:00Z",
  "end": "2026-04-06T14:00:00Z"
}

身份验证成功率

比较每小时成功数与失败数，以计算身份验证成功率并发现恶化趋势。

query AuthSuccessRate(
  $accountTag: String!
  $start: Time!
  $end: Time!
) {
  viewer {
    accounts(filter: { accountTag: $accountTag }) {
      privacyProxyAuthMetricsAdaptiveGroups(
        filter: {
          datetimeHour_geq: $start
          datetimeHour_leq: $end
        }
        limit: 10000
        orderBy: [datetimeHour_ASC]
      ) {
        count
        dimensions {
          datetimeHour
          authResult
        }
      }
    }
  }
}
{
  "accountTag": "<YOUR_ACCOUNT_TAG>",
  "start": "2026-04-04T00:00:00Z",
  "end": "2026-04-06T23:59:59Z"
}

相关资源

这篇文档对您有帮助吗？