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

分析

最后更新 查看 MarkdownAgent 设置

Cloudflare Realtime TURN 服务以字节为单位统计入网（ingress）和出网（egress）使用量。您可以使用 TURN 分析 API 访问此实时数据和历史数据。您可以查看时间序列或聚合形式的 TURN 使用量数据，从而显示随着时间推移以字节为单位的流量。

Cloudflare TURN 分析仅可通过 GraphQL API 获取。

可用的指标和维度

TURN 分析提供了丰富的数据，您可以通过各种方式进行查询和聚合。

指标

您可以查询以下指标：

  • egressBytes：从 TURN 服务器发送给客户端的总字节数
  • ingressBytes：TURN 服务器接收自客户端的总字节数
  • concurrentConnections：并发连接的平均数量

这些指标支持使用 sum 和 avg 函数进行聚合。

维度

您可以通过以下维度对数据进行细分：

  • 时间聚合：datetime、datetimeMinute、datetimeFiveMinutes、datetimeFifteenMinutes、datetimeHour
  • 地理信息：datacenterCity、datacenterCountry、datacenterRegion（Cloudflare 数据中心位置）
  • 标识信息：keyId、customIdentifier、username

过滤器

您可以在 TURN 分析中根据以下条件对数据进行过滤：

  • 日期时间范围
  • TURN 密钥 ID (Key ID)
  • TURN 用户名 (Username)
  • 自定义标识符 (Custom identifier)

GraphQL 客户端

GraphQL 是一种自文档化协议。您可以使用任何 GraphQL 客户端来浏览 schema 和可用字段。常用选择包括：

  • Altair ↗：一个功能丰富的 GraphQL 客户端，带有 schema 文档浏览器
  • GraphiQL ↗：原始的 GraphQL IDE
  • Postman ↗：支持带 schema 自省的 GraphQL 查询

要探索完整的 schema，请配置您的客户端，使用您的 API 凭据连接到 https://api.cloudflare.com/client/v4/graphql。有关详细说明，请参阅 探索 GraphQL schema。

实用的 TURN 分析查询

下面是一些常用场景的示例查询。您可以修改它们以适应您的具体用例，并获取分析数据的不同视图。

并发连接数与数据用量随时间的变化

这个综合查询展示了如何同时检索多个指标，包括以 5 分钟为间隔的并发连接数、出网和入网字节数。这对于构建仪表板和监控实时使用情况非常有用。

query concurrentConnections {
	viewer {
		accounts(filter: { accountTag: $accountId }) {
			callsTurnUsageAdaptiveGroups(
				limit: 10000
				filter: { date_geq: $dateFrom, date_leq: $dateTo }
			) {
				dimensions {
					datetimeFiveMinutes
				}
				avg {
					concurrentConnectionsFiveMinutes
				}
				sum {
					egressBytes
					ingressBytes
				}
			}
		}
	}
}

示例响应：

{
  "data": {
    "viewer": {
      "accounts": [
        {
          "callsTurnUsageAdaptiveGroups": [
            {
              "avg": {
                "concurrentConnectionsFiveMinutes": 816
              },
              "dimensions": {
                "datetimeFiveMinutes": "2025-12-02T03:45:00Z"
              },
              "sum": {
                "egressBytes": 207314144,
                "ingressBytes": 8534200
              }
            },
            {
              "avg": {
                "concurrentConnectionsFiveMinutes": 1945
              },
              "dimensions": {
                "datetimeFiveMinutes": "2025-12-02T16:00:00Z"
              },
              "sum": {
                "egressBytes": 462909020,
                "ingressBytes": 128434592
              }
            },

					]
				}
			]
		}
	]
}

按出网流量排名的 Top TURN 密钥

query egressByTurnKey{
  viewer {
    usage: accounts(filter: { accountTag: $accountId }) {
        callsTurnUsageAdaptiveGroups(
          filter: {
          date_geq: $dateFrom,
          date_leq: $dateTo
        }
          limit: 2
          orderBy: [sum_egressBytes_DESC]
        ) {
          dimensions {
            keyId
          }
          sum {
            egressBytes
          }
        }
      }
    },
		"errors": null
  }

示例响应：

{
  "data": {
    "viewer": {
      "usage": [
        {
          "callsTurnUsageAdaptiveGroups": [
            {
              "dimensions": {
                "keyId": "82a58d0aeabfa8f4a4e0c4a9efc9cda5"
              },
              "sum": {
                "egressBytes": 160040068147
              }
            }
          ]
        }
      ]
    }
  },
  "errors": null
}

按流量排名的 Top TURN 自定义标识符

query topTurnCustomIdentifiers {
	viewer {
		accounts(filter: { accountTag: $accountId }) {
			callsTurnUsageAdaptiveGroups(
				filter: { date_geq: $dateFrom, date_leq: $dateTo }
				limit: 1
				orderBy: [sum_egressBytes_DESC]
			) {
				dimensions {
					customIdentifier
				}
				sum {
					egressBytes
				}
			}
		}
	}
}

示例响应：

{
  "data": {
    "viewer": {
      "accounts": [
        {
          "callsTurnUsageAdaptiveGroups": [
            {
              "dimensions": {
                "customIdentifier": "some identifier"
              },
              "sum": {
                "egressBytes": 160040068147
              }
            }
          ]
        }
      ]
    }
  },
  "errors": null
}

特定自定义标识符的使用情况

query {
	viewer {
		accounts(filter: { accountTag: $accountId }) {
			callsTurnUsageAdaptiveGroups(
				filter: {
					date_geq: $dateFrom
					date_leq: $dateTo
					customIdentifier: "tango"
				}
				limit: 100
				orderBy: []
			) {
				dimensions {
					keyId
					customIdentifier
				}
				sum {
					egressBytes
				}
			}
		}
	}
}

示例响应：

{
  "data": {
    "viewer": {
      "usage": [
        {
          "callsTurnUsageAdaptiveGroups": [
            {
              "dimensions": {
                "customIdentifier": "tango",
                "keyId": "74007022d80d7ebac4815fb776b9d3ed"
              },
              "sum": {
                "egressBytes": 162641324
              }
            }
          ]
        }
      ]
    }
  },
  "errors": null
}

作为时间序列的使用情况（用于图表）

query {
	viewer {
		accounts(filter: { accountTag: $accountId }) {
			callsTurnUsageAdaptiveGroups(
				filter: { date_geq: $dateFrom, date_leq: $dateTo }
				limit: 100
				orderBy: [datetimeMinute_ASC]
			) {
				dimensions {
					datetimeMinute
				}
				sum {
					egressBytes
				}
			}
		}
	}
}

示例响应：

{
  "data": {
    "viewer": {
      "accounts": [
        {
          "callsTurnUsageAdaptiveGroups": [
            {
              "dimensions": {
                "datetimeMinute": "2025-12-01T00:00:00Z"
              },
              "sum": {
                "egressBytes": 159512
              }
            },
            {
              "dimensions": {
                "datetimeMinute": "2025-12-01T00:01:00Z"
              },
              "sum": {
                "egressBytes": 133818
              }
            },
            ... (此行包含更多数据)
           ]
        }
      ]
    }
  },
  "errors": null
}

按地理位置进行的使用情况细分

您可以按 Cloudflare 数据中心位置对使用情况数据进行细分，以了解您的 TURN 流量在何处提供服务。这对于优化区域容量和了解用户的地理分布非常有用。

query {
	viewer {
		accounts(filter: { accountTag: $accountId }) {
			callsTurnUsageAdaptiveGroups(
				limit: 100
				filter: { date_geq: $dateFrom, date_leq: $dateTo }
				orderBy: [sum_egressBytes_DESC]
			) {
				dimensions {
					datacenterCity
					datacenterCode
					datacenterRegion
					datacenterCountry
				}
				sum {
					egressBytes
					ingressBytes
				}
				avg {
					concurrentConnectionsFiveMinutes
				}
			}
		}
	}
}

示例响应：

{
  "data": {
    "viewer": {
      "accounts": [
        {
          "callsTurnUsageAdaptiveGroups": [
            {
              "avg": {
                "concurrentConnectionsFiveMinutes": 3135
              },
              "dimensions": {
                "datacenterCity": "Columbus",
                "datacenterCode": "CMH",
                "datacenterCountry": "US",
                "datacenterRegion": "ENAM"
              },
              "sum": {
                "egressBytes": 47720931316,
                "ingressBytes": 19351966366
              }
            },
            ...
          ]
        }
      ]
    }
  },
  "errors": null
}

根据特定密钥或标识符进行过滤

您可以过滤数据以分析特定的 TURN 密钥或自定义标识符。这对于调试特定连接或分析特定客户端的使用模式非常有用。

query {
	viewer {
		accounts(filter: { accountTag: $accountId }) {
			callsTurnUsageAdaptiveGroups(
				limit: 1000
				filter: {
					keyId: "82a58d0aeabfa8f4a4e0c4a9efc9cda5"
					date_geq: $dateFrom
					date_leq: $dateTo
				}
				orderBy: [datetimeFiveMinutes_ASC]
			) {
				dimensions {
					datetimeFiveMinutes
					keyId
				}
				sum {
					egressBytes
					ingressBytes
				}
				avg {
					concurrentConnectionsFiveMinutes
				}
			}
		}
	}
}

示例响应：

{
  "data": {
    "viewer": {
      "accounts": [
        {
          "callsTurnUsageAdaptiveGroups": [
            {
              "avg": {
                "concurrentConnectionsFiveMinutes": 130
              },
              "dimensions": {
                "datetimeFiveMinutes": "2025-12-01T00:00:00Z",
                "keyId": "82a58d0aeabfa8f4a4e0c4a9efc9cda5"
              },
              "sum": {
                "egressBytes": 609156,
                "ingressBytes": 464326
              }
            },
            {
              "avg": {
                "concurrentConnectionsFiveMinutes": 118
              },
              "dimensions": {
                "datetimeFiveMinutes": "2025-12-01T00:05:00Z",
                "keyId": "82a58d0aeabfa8f4a4e0c4a9efc9cda5"
              },
              "sum": {
                "egressBytes": 534948,
                "ingressBytes": 401286
              }
            },
            ...
          ]
        }
      ]
    }
  },
  "errors": null
}

时间聚合选项

您可以根据您的分析需求选择不同的时间聚合间隔：

  • datetimeMinute：1 分钟间隔（最细粒度）
  • datetimeFiveMinutes：5 分钟间隔（推荐用于仪表板）
  • datetimeFifteenMinutes：15 分钟间隔
  • datetimeHour：小时间隔（最适合长期趋势）

带小时间隔聚合的示例查询：

query {
	viewer {
		accounts(filter: { accountTag: $accountId }) {
			callsTurnUsageAdaptiveGroups(
				limit: 1000
				filter: {
					keyId: "82a58d0aeabfa8f4a4e0c4a9efc9cda5"
					date_geq: $dateFrom
					date_leq: $dateTo
				}
				orderBy: [datetimeFiveMinutes_ASC]
			) {
				dimensions {
					datetimeFiveMinutes
					keyId
				}
				sum {
					egressBytes
					ingressBytes
				}
				avg {
					concurrentConnectionsFiveMinutes
				}
			}
		}
	}
}

示例响应：

{
  "data": {
    "viewer": {
      "accounts": [
        {
          "callsTurnUsageAdaptiveGroups": [
            {
              "avg": {
                "concurrentConnectionsFiveMinutes": 130
              },
              "dimensions": {
                "datetimeFiveMinutes": "2025-12-01T00:00:00Z",
                "keyId": "82a58d0aeabfa8f4a4e0c4a9efc9cda5"
              },
              "sum": {
                "egressBytes": 609156,
                "ingressBytes": 464326
              }
            },
            {
              "avg": {
                "concurrentConnectionsFiveMinutes": 118
              },
              "dimensions": {
                "datetimeFiveMinutes": "2025-12-01T00:05:00Z",
                "keyId": "82a58d0aeabfa8f4a4e0c4a9efc9cda5"
              },
              "sum": {
                "egressBytes": 534948,
                "ingressBytes": 401286
              }
            },
            ...
          ]
        }
      ]
    }
  },
  "errors": null
}

高级使用场景

结合多个维度

您可以在单个查询中结合多个维度，以获得更详细的细分。例如，要查看按时间和位置分类的用量：

query {
	viewer {
		accounts(filter: { accountTag: $accountId }) {
			callsTurnUsageAdaptiveGroups(
				limit: 10000
				filter: { date_geq: $dateFrom, date_leq: $dateTo }
				orderBy: [datetimeHour_ASC, sum_egressBytes_DESC]
			) {
				dimensions {
					datetimeHour
					datacenterCity
					datacenterCountry
				}
				sum {
					egressBytes
					ingressBytes
				}
			}
		}
	}
}

示例响应：

{
  "data": {
    "viewer": {
      "accounts": [
        {
          "callsTurnUsageAdaptiveGroups": [
            {
              "dimensions": {
                "datacenterCity": "Chennai",
                "datacenterCountry": "IN",
                "datetimeHour": "2025-12-01T00:00:00Z"
              },
              "sum": {
                "egressBytes": 3416216,
                "ingressBytes": 498927214
              }
            },
            {
              "dimensions": {
                "datacenterCity": "Mumbai",
                "datacenterCountry": "IN",
                "datetimeHour": "2025-12-01T00:00:00Z"
              },
              "sum": {
                "egressBytes": 1267076,
                "ingressBytes": 1140140
              }
            },
						...
          ]
        }
      ]
    }
  },
  "errors": null
}

识别 Top 消费者

要查找哪些密钥或自定义标识符消耗了最多的带宽：

query {
	viewer {
		accounts(filter: { accountTag: $accountId }) {
			callsTurnUsageAdaptiveGroups(
				limit: 10
				filter: { date_geq: $dateFrom, date_leq: $dateTo }
				orderBy: [sum_egressBytes_DESC, sum_ingressBytes_DESC]
			) {
				dimensions {
					keyId
					customIdentifier
				}
				sum {
					egressBytes
					ingressBytes
				}
				avg {
					concurrentConnectionsFiveMinutes
				}
			}
		}
	}
}

示例响应：

{
	"data": {
		"viewer": {
			"accounts": [
				{
					"callsTurnUsageAdaptiveGroups": [
						{
							"avg": {
								"concurrentConnectionsFiveMinutes": 837305
							},
							"dimensions": {
								"customIdentifier": "",
								"keyId": "82a58d0aeabfa8f4a4e0c4a9efc9cda5"
							},
							"sum": {
								"egressBytes": 160040068147,
								"ingressBytes": 154955460564
							}
						}
					]
				}
			]
		}
	},
	"errors": null
}

探索 Schema

GraphQL Analytics API 是自文档化的。您可以使用自省功能发现 callsTurnUsageAdaptiveGroups 的所有可用字段、过滤器和功能。使用 Altair 或 GraphiQL 等 GraphQL 客户端，您可以交互式地浏览 schema，以查找可能对您的特定用例有用的其他维度和指标。

有关 GraphQL 自省和 schema 探索的更多信息，请参阅：

这篇文档对您有帮助吗？