INTEGRITY Документация

← Cloudflare Realtime / realtime / turn

Аналитика

Служба Cloudflare Realtime TURN учитывает объем входящего и исходящего трафика в байтах. Эти данные, как в реальном времени, так и исторические, доступны через API аналитики TURN. Данные об использовании TURN можно просматривать в виде временного ряда или агрегированных значений, отражающих трафик в байтах с течением времени.

Аналитика Cloudflare TURN доступна только через GraphQL API.

Доступные метрики и измерения

Аналитика TURN предоставляет обширные данные, которые можно запрашивать и агрегировать различными способами.

Метрики

Вы можете запрашивать следующие метрики:

Эти метрики поддерживают агрегации с использованием sum и avg функции.

Измерения

Данные можно разбить по следующим измерениям:

Фильтры

Вы можете фильтровать данные в TURN-аналитике по:

GraphQL-клиенты

GraphQL является самодокументируемым протоколом. Изучить схему и доступные поля можно с помощью любого GraphQL-клиента. Среди популярных вариантов:

Чтобы изучить полную схему, настройте клиент для подключения к https://api.cloudflare.com/client/v4/graphql с вашими учётными данными API. См. Изучите схему GraphQL для подробных инструкций.

Полезные запросы для аналитики 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
              }
            },

					]
				}
			]
		}
	]
}

Ключи 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
}

Наиболее часто используемые пользовательские идентификаторы 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
              }
            },
            ... (more data here)
           ]
        }
      ]
    }
  },
  "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
}

Варианты агрегации по времени

В зависимости от задач анализа можно выбрать разные интервалы агрегации по времени:

Пример запроса с почасовой агрегацией:

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
}

Выявление основных потребителей

Чтобы узнать, какие ключи или пользовательские идентификаторы потребляют больше всего трафика:

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
}

Изучение схемы

GraphQL Analytics API является самодокументируемым: с помощью интроспекции можно узнать все доступные поля, фильтры и возможности для callsTurnUsageAdaptiveGroups. С помощью клиента GraphQL, например Altair или GraphiQL, можно интерактивно просматривать схему и находить дополнительные измерения и метрики, полезные для вашего конкретного случая использования.

Подробнее об интроспекции GraphQL и изучении схемы см. ниже: