Skip to content

Commit e63eae4

Browse files
bjesushyperlint-ai[bot]vicb
authored
Zaraz Monitoring API (#18168)
* Zaraz Monitoring API * Update src/content/docs/zaraz/monitoring/monitoring-api.mdx Co-authored-by: hyperlint-ai[bot] <154288675+hyperlint-ai[bot]@users.noreply.github.com> * Update src/content/docs/zaraz/monitoring/monitoring-api.mdx Co-authored-by: hyperlint-ai[bot] <154288675+hyperlint-ai[bot]@users.noreply.github.com> * Update src/content/docs/zaraz/monitoring/monitoring-api.mdx Co-authored-by: Victor Berchet <[email protected]> * Update src/content/docs/zaraz/monitoring/monitoring-api.mdx Co-authored-by: Victor Berchet <[email protected]> --------- Co-authored-by: hyperlint-ai[bot] <154288675+hyperlint-ai[bot]@users.noreply.github.com> Co-authored-by: Victor Berchet <[email protected]>
1 parent a4fed01 commit e63eae4

File tree

2 files changed

+204
-1
lines changed

2 files changed

+204
-1
lines changed

‎src/content/docs/zaraz/monitoring.mdx‎ renamed to ‎src/content/docs/zaraz/monitoring/index.mdx‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
pcx_content_type: how-to
3-
title: Zaraz Monitoring
3+
title: Monitoring
44
sidebar:
55
order: 7
66
---
@@ -21,3 +21,4 @@ To use Zaraz Monitoring:
2121
- **Events**: Counts how many times a specific event was tracked by Zaraz. It includes the [Pageview event](/zaraz/get-started/), [Track events](/zaraz/web-api/track/), and [E-commerce events](/zaraz/web-api/ecommerce/).
2222
- **Triggers**: Counts how many times a specific trigger was activated. It includes the built-in [Pageview trigger](/zaraz/custom-actions/create-trigger/) and any other trigger you set in Zaraz.
2323
- **Actions**: Counts how many times a [specific action](/zaraz/custom-actions/) was activated. It includes the pre-configured Pageview action, and any other actions you set in Zaraz.
24+
- **Server-side requests**: tracks the status codes returned from server-side requests that Zaraz makes to your third-party tools.

‎src/content/docs/zaraz/monitoring/monitoring-api.mdx‎

Lines changed: 202 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,202 @@
1+
---
2+
pcx_content_type: how-to
3+
title: Monitoring API
4+
sidebar:
5+
order: 2
6+
---
7+
8+
import { TabItem, Tabs } from "~/components";
9+
10+
The **Zaraz Monitoring API** allows users to retrieve detailed data on Zaraz events through the **GraphQL Analytics API**. Using this API, you can monitor events, pageviews, triggers, actions, and server-side request statuses, including any errors and successes. The data available through the API mirrors what is shown on the Zaraz Monitoring page in the dashboard, but with the API, you can query it programmatically to create alerts and notifications for unexpected deviations.
11+
12+
To get started, you'll need to generate an Analytics API token by following the [API token authentication guide](/analytics/graphql-api/getting-started/authentication/api-token-auth/).
13+
14+
## Key Entities
15+
16+
The Monitoring API includes the following core entities, which each provide distinct insights:
17+
18+
- **zarazTrackAdaptiveGroups**: Contains data on Zaraz events, such as event counts and timestamps.
19+
- **zarazActionsAdaptiveGroups**: Provides information on Zaraz Actions.
20+
- **zarazTriggersAdaptiveGroups**: Tracks data on Zaraz Triggers.
21+
- **zarazFetchAdaptiveGroups**: Captures server-side request data, including URLs and returning status codes for third-party requests made by Zaraz.
22+
23+
## Example GraphQL Queries
24+
25+
You can construct any query you'd like using the above datasets, but here are some example queries you can use.
26+
27+
<Tabs syncKey="GQLExamples"><TabItem label="Events">
28+
29+
Query for the count of Zaraz events, grouped by time.
30+
31+
```graphql
32+
query ZarazEvents(
33+
$zoneTag: string
34+
$limit: uint64!
35+
$start: Date
36+
$end: Date
37+
$orderBy: [ZoneZarazTrackAdaptiveGroupsOrderBy!]
38+
) {
39+
viewer {
40+
zones(filter: { zoneTag: $zoneTag }) {
41+
data: zarazTrackAdaptiveGroups(
42+
limit: $limit
43+
filter: { datetimeHour_geq: $start, datetimeHour_leq: $end }
44+
orderBy: [$orderBy]
45+
) {
46+
count
47+
dimensions {
48+
ts: datetimeHour
49+
}
50+
}
51+
}
52+
}
53+
}
54+
```
55+
56+
</TabItem><TabItem label="Loads">
57+
58+
Query for the count of Zaraz loads, grouped by time.
59+
60+
```graphql
61+
query ZarazLoads(
62+
$zoneTag: string
63+
$limit: uint64!
64+
$start: Date
65+
$end: Date
66+
$orderBy: [ZoneZarazTriggersAdaptiveGroupsOrderBy!]
67+
) {
68+
viewer {
69+
zones(filter: { zoneTag: $zoneTag }) {
70+
data: zarazTriggersAdaptiveGroups(
71+
limit: $limit
72+
filter: { date_geq: $start, date_leq: $end, triggerName: Pageview }
73+
orderBy: [$orderBy]
74+
) {
75+
count
76+
dimensions {
77+
ts: date
78+
}
79+
}
80+
}
81+
}
82+
}
83+
```
84+
85+
</TabItem> <TabItem label="Triggers">
86+
87+
Query for the total execution count of each trigger processed by Zaraz.
88+
89+
```graphql
90+
query ZarazTriggers(
91+
$zoneTag: string
92+
$limit: uint64!
93+
$start: Date
94+
$end: Date
95+
$orderBy: [uint64!]
96+
) {
97+
viewer {
98+
zones(filter: { zoneTag: $zoneTag }) {
99+
data: zarazTriggersAdaptiveGroups(
100+
limit: $limit
101+
filter: { date_geq: $start, date_leq: $end }
102+
orderBy: [count_DESC]
103+
) {
104+
count
105+
dimensions {
106+
name: triggerName
107+
}
108+
}
109+
}
110+
}
111+
}
112+
```
113+
114+
</TabItem><TabItem label="Erroneous responses">
115+
116+
Query for the count of 400 server-side responses, grouped by time and URL.
117+
118+
```graphql
119+
query ErroneousResponses(
120+
$zoneTag: string
121+
$limit: uint64!
122+
$start: Date
123+
$end: Date
124+
$orderBy: [ZoneZarazFetchAdaptiveGroupsOrderBy!]
125+
) {
126+
viewer {
127+
zones(filter: { zoneTag: $zoneTag }) {
128+
data: zarazFetchAdaptiveGroups(
129+
limit: $limit
130+
filter: {
131+
datetimeHour_geq: $start
132+
datetimeHour_leq: $end
133+
url_neq: ""
134+
status: 400
135+
}
136+
orderBy: [$orderBy]
137+
) {
138+
count
139+
dimensions {
140+
ts: datetimeHour
141+
name: url
142+
}
143+
}
144+
}
145+
}
146+
}
147+
```
148+
149+
</TabItem></Tabs>
150+
151+
### Variables Example
152+
153+
```json
154+
{
155+
"zoneTag": "d6dfdf32c704a77ac227243a5eb5ca61",
156+
"start": "2025-01-01T00:00:00Z",
157+
"end": "2025-01-30T00:00:00Z",
158+
"limit": 10000,
159+
"orderBy": "datetimeHour_ASC"
160+
}
161+
```
162+
163+
Be sure to customize the zoneTag to match your specific zone, along with setting the desired start and end dates
164+
165+
### Explanation of Parameters
166+
167+
- **zoneTag**: Unique identifier of your Cloudflare zone.
168+
- **limit**: Maximum number of results to return.
169+
- **start** and **end**: Define the date range for the query in ISO 8601 format.
170+
- **orderBy**: Determines the sorting order, such as by ascending or descending datetime.
171+
172+
## Example `curl` Request
173+
174+
Use this `curl` command to query the Zaraz Monitoring API for the number of events processed by Zaraz. Replace `$TOKEN` with your API token, `$ZONE_TAG` with your zone tag, and adjust the start and end dates as needed.
175+
176+
```bash
177+
curl -X POST https://api.cloudflare.com/client/v4/graphql \
178+
-H "Content-Type: application/json" \
179+
-H "Authorization: Bearer $TOKEN" \
180+
-d '{
181+
"query": "query AllEvents($zoneTag: String!, $limit: Int!, $start: Date, $end: Date, $orderBy: [ZoneZarazTriggersAdaptiveGroupsOrderBy!]) { viewer { zones(filter: { zoneTag: $zoneTag }) { data: zarazTrackAdaptiveGroups( limit: $limit filter: { datetimeHour_geq: $start datetimeHour_leq: $end } orderBy: [$orderBy] ) { count dimensions { ts: datetimeHour } } } } }",
182+
"variables": {
183+
"zoneTag": "$ZONE_TAG",
184+
"start": "2025-01-01T00:00:00Z",
185+
"end": "2025-01-30T00:00:00Z",
186+
"limit": 10000,
187+
"orderBy": "datetimeHour_ASC"
188+
}
189+
}'
190+
```
191+
192+
### Explanation of the `curl` Components
193+
194+
- **Authorization**: The `Authorization` header requires a Bearer token. Replace `$TOKEN` with your actual API token.
195+
- **Content-Type**: Set `application/json` to indicate a JSON payload.
196+
- **Data Payload**: This payload includes the GraphQL query and variable parameters, such as `zoneTag`, `start`, `end`, `limit`, and `orderBy`.
197+
198+
This `curl` example will return a JSON response containing event counts and timestamps within the specified date range. Modify the `variables` values as needed for your use case.
199+
200+
## Additional Resources
201+
202+
Refer to the [full GraphQL Analytics API documentation](/analytics/graphql-api/) for more details on available fields, filters, and further customization options for Zaraz Monitoring API queries.

0 commit comments

Comments
 (0)