Skip to content

Commit 80e5147

Browse files
andre-j3susandre-j3sus
committed
[Radar] Update normalization methods and other minor fixes
1 parent 5fc2fb2 commit 80e5147

File tree

12 files changed

+238
-160
lines changed

12 files changed

+238
-160
lines changed

‎src/content/docs/radar/concepts/aggregation-intervals.mdx‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,3 +17,4 @@ For example, when requesting one day of data, the default aggregation interval i
1717
| `15m` | 15 minutes frequency. |
1818
| `1h` | One hour frequency. |
1919
| `1d` | One day frequency. |
20+
| `1w` | One week frequency. |

‎src/content/docs/radar/concepts/bot-classes.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ sidebar:
88

99
A bot class in Radar is a grouping of [bot scores](/bots/concepts/bot-score).
1010

11-
Scores between 1 to 29 are classified as bot traffic. Scores equal or above 30 are classified as non-bot/human traffic.
11+
Scores between 1 and 29 are classified as bot traffic. Scores equal or above 30 are classified as non-bot/human traffic.
1212

1313
| Class | Description |
1414
| -------------------- | ---------------------------- |

‎src/content/docs/radar/concepts/normalization.mdx‎

Lines changed: 8 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -12,12 +12,13 @@ Refer to the `result.meta.normalization` property in the response to check which
1212

1313
## Method
1414

15-
| Method | Description |
16-
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
17-
| `PERCENTAGE` | Values represent percentages. |
18-
| `PERCENTAGE_CHANGE` | Values represent a [percentage change](https://en.wikipedia.org/wiki/Relative_change_and_difference#Percentage_change) from a baseline period. |
19-
| `MIN_MAX` | Values have been normalized using [min-max](https://en.wikipedia.org/wiki/Feature_scaling#Rescaling_\(min-max_normalization\)). |
20-
| `MIN0_MAX` | Values have been normalized using min-max, but setting the minimum value to `0`. Equivalent to a proportion of the maximum value in the entire response, scaled between 0 and 1. |
21-
| `RAW_VALUES` | Values are raw and have not been changed. |
15+
| Method | Description |
16+
| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
17+
| `PERCENTAGE` | Values represent percentages. |
18+
| `PERCENTAGE_CHANGE` | Values represent a [percentage change](https://en.wikipedia.org/wiki/Relative_change_and_difference#Percentage_change) from a baseline period. |
19+
| `OVERLAPPED_PERCENTAGE` | Values represent percentages that exceed 100% due to overlap. |
20+
| `MIN_MAX` | Values have been normalized using [min-max](https://en.wikipedia.org/wiki/Feature_scaling#Rescaling_\(min-max_normalization\)). |
21+
| `MIN0_MAX` | Values have been normalized using min-max, but setting the minimum value to `0`. Equivalent to a proportion of the maximum value in the entire response, scaled between 0 and 1. |
22+
| `RAW_VALUES` | Values are raw and have not been changed. |
2223

2324
If you want to compare values across locations/time ranges/etc., in endpoints that normalize values using min-max, you must do so in the same request. This is done by asking for multiple series. All values will then be normalized using the same minimum and maximum value and can safely be compared against each other. Refer to [Make comparisons](/radar/get-started/making-comparisons/) for more information.

‎src/content/docs/radar/get-started/error-codes.mdx‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,11 @@
11
---
22
pcx_content_type: reference
3-
title: Radar API Error Codes
3+
title: Radar API error codes
44
sidebar:
55
order: 3
66
head:
77
- tag: title
8-
content: Radar API Error Codes
8+
content: Radar API error codes
99

1010
---
1111

‎src/content/docs/radar/get-started/making-comparisons.mdx‎

Lines changed: 11 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,7 @@ The second series has the following parameters:
2727

2828
`name=pt_data&dateRange=7d&location=PT`
2929

30-
All of these parameters are arrays and it is the position in the array that defines the series the filter belongs to. Refer to [NetFlow's endpoint](/api/resources/radar/subresources/netflows/methods/timeseries/) for more information on the available parameters.
30+
All of these parameters are arrays, and it is the position in the array that defines the series the filter belongs to. Refer to [NetFlow's endpoint](/api/resources/radar/subresources/netflows/methods/timeseries/) for more information on the available parameters.
3131

3232
The response (shortened below for brevity) uses the provided `name` property to wrap the timestamps and corresponding values. If we chart this data, it becomes obvious that Cloudflare received much less traffic from Portugal than from the United States.
3333

@@ -49,7 +49,8 @@ The response (shortened below for brevity) uses the provided `name` property to
4949
"startTime": "2022-10-26T17:00:00Z",
5050
"endTime": "2022-11-02T17:00:00Z"
5151
},
52-
"aggInterval": "ONE_HOUR"
52+
"aggInterval": "ONE_HOUR",
53+
...
5354
}
5455
}
5556
}
@@ -114,18 +115,14 @@ The `result` property should return a response like this:
114115

115116
```json
116117
{
117-
"success": true,
118-
"errors": [],
119-
"result": {
120-
"tonga": {
121-
"timestamps": ["2022-10-15T02:00:00Z", "2022-10-15T03:00:00Z", "2022-10-15T04:00:00Z", "2022-10-15T05:00:00Z"],
122-
"values": ["1.0", "0.832473", "0.820083", "0.79408"]
123-
},
124-
"tonga_outage": {
125-
"timestamps": ["2022-01-15T02:00:00Z", "2022-01-15T03:00:00Z", "2022-01-15T04:00:00Z", "2022-01-15T05:00:00Z"],
126-
"values": ["0.354105", "0.357287", "0.181811", "0.044198"]
127-
}
128-
}
118+
"tonga": {
119+
"timestamps": ["2022-10-15T02:00:00Z", "2022-10-15T03:00:00Z", "2022-10-15T04:00:00Z", "2022-10-15T05:00:00Z"],
120+
"values": ["1.0", "0.832473", "0.820083", "0.79408"]
121+
},
122+
"tonga_outage": {
123+
"timestamps": ["2022-01-15T02:00:00Z", "2022-01-15T03:00:00Z", "2022-01-15T04:00:00Z", "2022-01-15T05:00:00Z"],
124+
"values": ["0.354105", "0.357287", "0.181811", "0.044198"]
125+
}
129126
}
130127
```
131128

‎src/content/docs/radar/glossary.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -162,7 +162,7 @@ The Post-Quantum Encryption Adoption graph shows the share of HTTPS requests to
162162

163163
A [robots.txt](https://www.cloudflare.com/learning/bots/what-is-robots-txt/) file contains instructions for bots that tell them which webpages they can and cannot access.
164164

165-
The data displayed for robots.txt is based on successfully parsed robots.txt files from the top 10,000 domains (should we link to somewhere). From these files, we count the occurrences of each user agent under the "Allow" and "Disallow" directives. A user agent is classified as "fully allowed" or "fully disallowed" if the directive value is "*". Otherwise, if the user agent is only allowed or disallowed to crawl specific paths, it is classified as "partially allowed" or "partially disallowed."
165+
The data displayed for robots.txt is based on successfully parsed robots.txt files from the top 10,000 domains. From these files, we count the occurrences of each user agent under the "Allow" and "Disallow" directives. A user agent is classified as "fully allowed" or "fully disallowed" if the directive value is "*". Otherwise, if the user agent is only allowed or disallowed to crawl specific paths, it is classified as "partially allowed" or "partially disallowed."
166166

167167
Currently, we only include AI-focused user agents listed in the [ai.robots.txt](https://github.com/ai-robots-txt/ai.robots.txt) repository.
168168

‎src/content/docs/radar/investigate/application-layer-attacks.mdx‎

Lines changed: 104 additions & 72 deletions
Original file line numberDiff line numberDiff line change
@@ -30,7 +30,7 @@ Like in [HTTP requests](/radar/investigate/http-requests), these endpoints can b
3030
Let us examine the global distribution of mitigated requests by product.
3131

3232
```bash
33-
curl "https://api.cloudflare.com/client/v4/radar/attacks/layer7/timeseries_groups?aggInterval=1h&dateRange=1d&name=attacks&format=json" \
33+
curl "https://api.cloudflare.com/client/v4/radar/attacks/layer7/timeseries_groups/mitigation_product?aggInterval=1h&dateRange=1d&name=attacks&format=json" \
3434
--header "Authorization: Bearer <API_TOKEN>"
3535
```
3636

@@ -56,6 +56,7 @@ From the abbreviated response below, we can conclude that distributed denial-of-
5656
"startTime": "2022-11-05T11:00:00Z",
5757
"endTime": "2022-11-06T11:00:00Z"
5858
},
59+
...
5960
}
6061
}
6162
}
@@ -75,14 +76,23 @@ curl "https://api.cloudflare.com/client/v4/radar/attacks/layer7/summary?location
7576
```
7677

7778
```json
78-
"attacks_gb": {
79-
"waf": "75.012138",
80-
"ddos": "18.539149",
81-
"ip_reputation": "5.721021",
82-
"access_rules": "0.592515",
83-
"bot_management": "0.131998",
84-
"api_shield": "0.003178",
85-
"data_loss_prevention": "0.0"
79+
{
80+
"success": true,
81+
"errors": [],
82+
"result": {
83+
"attacks_gb": {
84+
"waf": "75.012138",
85+
"ddos": "18.539149",
86+
"ip_reputation": "5.721021",
87+
"access_rules": "0.592515",
88+
"bot_management": "0.131998",
89+
"api_shield": "0.003178",
90+
"data_loss_prevention": "0.0"
91+
},
92+
"meta": {
93+
...
94+
}
95+
}
8696
}
8797
```
8898

@@ -106,37 +116,44 @@ curl "https://api.cloudflare.com/client/v4/radar/attacks/layer7/top/locations/ta
106116
"success": true,
107117
"errors": [],
108118
"result": {
109-
"attacks_target": [{
110-
"targetCountryName": "Belgium",
111-
"targetCountryAlpha2": "BE",
112-
"value": "18.536740",
113-
"rank": 1
114-
}, {
115-
"targetCountryName": "United States",
116-
"targetCountryAlpha2": "US",
117-
"value": "16.116210",
118-
"rank": 2
119-
}, {
120-
"targetCountryName": "China",
121-
"targetCountryAlpha2": "CN",
122-
"value": "13.864696",
123-
"rank": 3
124-
}, {
125-
"targetCountryName": "India",
126-
"targetCountryAlpha2": "IN",
127-
"value": "4.344139",
128-
"rank": 4
129-
}, {
130-
"targetCountryName": "Germany",
131-
"targetCountryAlpha2": "DE",
132-
"value": "4.182777",
133-
"rank": 5
134-
}],
119+
"attacks_target": [
120+
{
121+
"targetCountryName": "Belgium",
122+
"targetCountryAlpha2": "BE",
123+
"value": "18.536740",
124+
"rank": 1
125+
},
126+
{
127+
"targetCountryName": "United States",
128+
"targetCountryAlpha2": "US",
129+
"value": "16.116210",
130+
"rank": 2
131+
},
132+
{
133+
"targetCountryName": "China",
134+
"targetCountryAlpha2": "CN",
135+
"value": "13.864696",
136+
"rank": 3
137+
},
138+
{
139+
"targetCountryName": "India",
140+
"targetCountryAlpha2": "IN",
141+
"value": "4.344139",
142+
"rank": 4
143+
},
144+
{
145+
"targetCountryName": "Germany",
146+
"targetCountryAlpha2": "DE",
147+
"value": "4.182777",
148+
"rank": 5
149+
}
150+
],
135151
"meta": {
136152
"dateRange": {
137153
"startTime": "2022-11-05T12:00:00Z",
138154
"endTime": "2022-11-06T12:00:00Z"
139155
},
156+
...
140157
}
141158
}
142159
}
@@ -159,43 +176,58 @@ curl "https://api.cloudflare.com/client/v4/radar/attacks/layer7/top/attacks?limi
159176

160177
A typical response will be similar to the following:
161178

162-
```
163-
[{
164-
"originCountryName": "United States",
165-
"originCountryAlpha2": "US",
166-
"targetCountryName": "United States",
167-
"targetCountryAlpha2": "US",
168-
"value": "3.790724",
169-
"rank": 1
170-
}, {
171-
"originCountryName": "United States",
172-
"originCountryAlpha2": "US",
173-
"targetCountryName": "Belgium",
174-
"targetCountryAlpha2": "BE",
175-
"value": "3.602177",
176-
"rank": 2
177-
}, {
178-
"originCountryName": "China",
179-
"originCountryAlpha2": "CN",
180-
"targetCountryName": "Netherlands",
181-
"targetCountryAlpha2": "NL",
182-
"value": "3.017341",
183-
"rank": 3
184-
}, {
185-
"originCountryName": "China",
186-
"originCountryAlpha2": "CN",
187-
"targetCountryName": "China",
188-
"targetCountryAlpha2": "CN",
189-
"value": "2.472068",
190-
"rank": 4
191-
}, {
192-
"originCountryName": "Indonesia",
193-
"originCountryAlpha2": "ID",
194-
"targetCountryName": "China",
195-
"targetCountryAlpha2": "CN",
196-
"value": "2.056729",
197-
"rank": 5
198-
}]
179+
```json
180+
{
181+
"success": true,
182+
"errors": [],
183+
"result": {
184+
"top_0": [
185+
{
186+
"originCountryName": "United States",
187+
"originCountryAlpha2": "US",
188+
"targetCountryName": "United States",
189+
"targetCountryAlpha2": "US",
190+
"value": "3.790724",
191+
"rank": 1
192+
},
193+
{
194+
"originCountryName": "United States",
195+
"originCountryAlpha2": "US",
196+
"targetCountryName": "Belgium",
197+
"targetCountryAlpha2": "BE",
198+
"value": "3.602177",
199+
"rank": 2
200+
},
201+
{
202+
"originCountryName": "China",
203+
"originCountryAlpha2": "CN",
204+
"targetCountryName": "Netherlands",
205+
"targetCountryAlpha2": "NL",
206+
"value": "3.017341",
207+
"rank": 3
208+
},
209+
{
210+
"originCountryName": "China",
211+
"originCountryAlpha2": "CN",
212+
"targetCountryName": "China",
213+
"targetCountryAlpha2": "CN",
214+
"value": "2.472068",
215+
"rank": 4
216+
},
217+
{
218+
"originCountryName": "Indonesia",
219+
"originCountryAlpha2": "ID",
220+
"targetCountryName": "China",
221+
"targetCountryAlpha2": "CN",
222+
"value": "2.056729",
223+
"rank": 5
224+
}
225+
],
226+
"meta": {
227+
...
228+
}
229+
}
230+
}
199231
```
200232

201233
This means that 3.79% of all mitigated requests are from and to the US, 3.6% of all mitigated requests are from the US to Belgium, etc..

‎src/content/docs/radar/investigate/dns.mdx‎

Lines changed: 39 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -25,13 +25,25 @@ The response shows that most queries come from the United States and Brazil:
2525

2626
```json
2727
{
28-
"clientCountryAlpha2": "US",
29-
"clientCountryName": "United States",
30-
"value": "43.474518"
31-
}, {
32-
"clientCountryAlpha2": "BR",
33-
"clientCountryName": "Brazil",
34-
"value": "10.772799"
28+
"success": true,
29+
"errors": [],
30+
"result": {
31+
"top_0": [
32+
{
33+
"clientCountryAlpha2": "US",
34+
"clientCountryName": "United States",
35+
"value": "43.474518"
36+
},
37+
{
38+
"clientCountryAlpha2": "BR",
39+
"clientCountryName": "Brazil",
40+
"value": "10.772799"
41+
}
42+
],
43+
"meta": {
44+
...
45+
}
46+
}
3547
}
3648
```
3749

@@ -46,21 +58,33 @@ Returns the following response:
4658

4759
```json
4860
{
49-
"clientCountryAlpha2": "RU",
50-
"clientCountryName": "Russian Federation",
51-
"value": "73.710495"
52-
}, {
53-
"clientCountryAlpha2": "DE",
54-
"clientCountryName": "Germany",
55-
"value": "5.518052"
61+
"success": true,
62+
"errors": [],
63+
"result": {
64+
"top_0": [
65+
{
66+
"clientCountryAlpha2": "RU",
67+
"clientCountryName": "Russian Federation",
68+
"value": "73.710495"
69+
},
70+
{
71+
"clientCountryAlpha2": "DE",
72+
"clientCountryName": "Germany",
73+
"value": "5.518052"
74+
}
75+
],
76+
"meta": {
77+
...
78+
}
79+
}
5680
}
5781
```
5882

5983
As expected, most queries come from Russia.
6084

6185
:::note
6286

63-
Note that these examples return the total number of DNS queries from a location to a hostname, *out* of the total DNS queries to a given hostname. In this sense, it is expected that locations with higher population numbers — like the United States — frequently appear in the top spots, even if the actual percentage is low.
87+
Note that these examples return the total number of DNS queries from a location to a hostname, *out* of the total DNS queries to a given hostname. In this sense, it is expected that locations with higher population numbers — like the United States — frequently appear in the top spots, even if the actual percentage is low.
6488
:::
6589

6690
You can also provide multiple hostnames. Refer to [Get DNS top locations](/api/resources/radar/subresources/dns/subresources/top/methods/locations/) for more information. This is useful when the application you want to explore uses several hostnames to serve its content (like a hostname for the main website, another hostname dedicated to its API, etc.).

0 commit comments

Comments
 (0)