From 165788ee9a28d460fb5ee42b7e06a3b271059186 Mon Sep 17 00:00:00 2001 From: Yo'av Moshe Date: Thu, 14 Nov 2024 14:55:32 +0100 Subject: [PATCH 1/5] Zaraz Monitoring API --- .../{monitoring.mdx => monitoring/index.mdx} | 3 +- .../docs/zaraz/monitoring/monitoring-api.mdx | 202 ++++++++++++++++++ 2 files changed, 204 insertions(+), 1 deletion(-) rename src/content/docs/zaraz/{monitoring.mdx => monitoring/index.mdx} (92%) create mode 100644 src/content/docs/zaraz/monitoring/monitoring-api.mdx diff --git a/src/content/docs/zaraz/monitoring.mdx b/src/content/docs/zaraz/monitoring/index.mdx similarity index 92% rename from src/content/docs/zaraz/monitoring.mdx rename to src/content/docs/zaraz/monitoring/index.mdx index c9f67606f657058..de77ddcdbdd9af0 100644 --- a/src/content/docs/zaraz/monitoring.mdx +++ b/src/content/docs/zaraz/monitoring/index.mdx @@ -1,6 +1,6 @@ --- pcx_content_type: how-to -title: Zaraz Monitoring +title: Monitoring sidebar: order: 7 --- @@ -21,3 +21,4 @@ To use Zaraz Monitoring: - **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/). - **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. - **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. +- **Server-side requests**: tracks the status codes returned from server-side requests that Zaraz makes to your third-party tools. diff --git a/src/content/docs/zaraz/monitoring/monitoring-api.mdx b/src/content/docs/zaraz/monitoring/monitoring-api.mdx new file mode 100644 index 000000000000000..9917166ad32be7b --- /dev/null +++ b/src/content/docs/zaraz/monitoring/monitoring-api.mdx @@ -0,0 +1,202 @@ +--- +pcx_content_type: how-to +title: Monitoring API +sidebar: + order: 2 +--- + +import { TabItem, Tabs } from "~/components"; + +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 + +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/). + +## Key Entities + +The Monitoring API includes the following core entities, which each provide distinct insights: + +- **zarazTrackAdaptiveGroups**: Contains data on Zaraz events, such as event counts and timestamps. +- **zarazActionsAdaptiveGroups**: Provides information on Zaraz Actions. +- **zarazTriggersAdaptiveGroups**: Tracks data on Zaraz Triggers. +- **zarazFetchAdaptiveGroups**: Captures server-side request data, including URLs and returning status codes for third-party requests made by Zaraz. + +## Example GraphQL Queries + +You can construct any query you'd like using the above datasets, but here are some example queries you can use. + + + +Query for the count of Zaraz events, grouped by time. + +```graphql +query AllEvents( + $zoneTag: string + $limit: uint64! + $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 + } + } + } + } +} +``` + + + +Query for the count of Zaraz loads, grouped by time. + +```graphql +query ZarazLoads( + $zoneTag: string + $limit: uint64! + $start: Date + $end: Date + $orderBy: [ZoneZarazTriggersAdaptiveGroupsOrderBy!] +) { + viewer { + zones(filter: { zoneTag: $zoneTag }) { + data: zarazTriggersAdaptiveGroups( + limit: $limit + filter: { date_geq: $start, date_leq: $end, triggerName: Pageview } + orderBy: [$orderBy] + ) { + count + dimensions { + ts: date + } + } + } + } +} +``` + + + +Query for the total execution count of each trigger processed by Zaraz. + +```graphql +query ZarazTriggers( + $zoneTag: string + $limit: uint64! + $start: Date + $end: Date + $orderBy: [uint64!] +) { + viewer { + zones(filter: { zoneTag: $zoneTag }) { + data: zarazTriggersAdaptiveGroups( + limit: $limit + filter: { date_geq: $start, date_leq: $end } + orderBy: [count_DESC] + ) { + count + dimensions { + name: triggerName + } + } + } + } +} +``` + + + +Query for the count of 400 server-side responses, grouped by time and URL. + +```graphql +query SucessfulGA4Requests( + $zoneTag: string + $limit: uint64! + $start: Date + $end: Date + $orderBy: [ZoneZarazTriggersAdaptiveGroupsOrderBy!] +) { + viewer { + zones(filter: { zoneTag: $zoneTag }) { + data: zarazFetchAdaptiveGroups( + limit: $limit + filter: { + datetimeHour_geq: $start + datetimeHour_leq: $end + url_neq: "" + OR: [{ AND: [{ status: 400 }] }] + } + orderBy: [$orderBy] + ) { + count + dimensions { + ts: datetimeHour + name: url + } + } + } + } +} +``` + + + +### Variables Example + +```json +{ + "zoneTag": "d6dfdf32c704a77ac227243a5eb5ca61", + "start": "2025-01-01T00:00:00Z", + "end": "2025-01-30T00:00:00Z", + "limit": 10000, + "orderBy": "datetimeHour_ASC" +} +``` + +Be sure to customize the zoneTag to match your specific zone, along with setting the desired start and end dates + +### Explanation of Parameters + +- **zoneTag**: Unique identifier of your Cloudflare zone. +- **limit**: Maximum number of results to return. +- **start** and **end**: Define the date range for the query in ISO 8601 format. +- **orderBy**: Determines the sorting order, such as by ascending or descending datetime. + +## Example `curl` Request + +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. + +```bash +curl -X POST https://api.cloudflare.com/client/v4/graphql \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $TOKEN" \ + -d '{ + "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 } } } } }", + "variables": { + "zoneTag": "$ZONE_TAG", + "start": "2025-01-01T00:00:00Z", + "end": "2025-01-30T00:00:00Z", + "limit": 10000, + "orderBy": "datetimeHour_ASC" + } + }' +``` + +### Explanation of the `curl` Components + +- **Authorization**: The `Authorization` header requires a Bearer token. Replace `$TOKEN` with your actual API token. +- **Content-Type**: Set to `application/json` to indicate a JSON payload. +- **Data Payload**: This payload includes the GraphQL query and variable parameters, such as `zoneTag`, `start`, `end`, `limit`, and `orderBy`. + +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. + +## Additional Resources + +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. From 32b714579bd01d315f885cb1af14156d99247527 Mon Sep 17 00:00:00 2001 From: Yo'av Moshe Date: Thu, 14 Nov 2024 15:02:27 +0100 Subject: [PATCH 2/5] Update src/content/docs/zaraz/monitoring/monitoring-api.mdx Co-authored-by: hyperlint-ai[bot] <154288675+hyperlint-ai[bot]@users.noreply.github.com> --- src/content/docs/zaraz/monitoring/monitoring-api.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/zaraz/monitoring/monitoring-api.mdx b/src/content/docs/zaraz/monitoring/monitoring-api.mdx index 9917166ad32be7b..acefc9489f29741 100644 --- a/src/content/docs/zaraz/monitoring/monitoring-api.mdx +++ b/src/content/docs/zaraz/monitoring/monitoring-api.mdx @@ -9,7 +9,7 @@ import { TabItem, Tabs } from "~/components"; 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 -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/). +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/). ## Key Entities From 7e8b3da3fc8679999c1edec562742dbe304cc34f Mon Sep 17 00:00:00 2001 From: Yo'av Moshe Date: Thu, 14 Nov 2024 15:02:37 +0100 Subject: [PATCH 3/5] Update src/content/docs/zaraz/monitoring/monitoring-api.mdx Co-authored-by: hyperlint-ai[bot] <154288675+hyperlint-ai[bot]@users.noreply.github.com> --- src/content/docs/zaraz/monitoring/monitoring-api.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/zaraz/monitoring/monitoring-api.mdx b/src/content/docs/zaraz/monitoring/monitoring-api.mdx index acefc9489f29741..33c147358cf485b 100644 --- a/src/content/docs/zaraz/monitoring/monitoring-api.mdx +++ b/src/content/docs/zaraz/monitoring/monitoring-api.mdx @@ -192,7 +192,7 @@ curl -X POST https://api.cloudflare.com/client/v4/graphql \ ### Explanation of the `curl` Components - **Authorization**: The `Authorization` header requires a Bearer token. Replace `$TOKEN` with your actual API token. -- **Content-Type**: Set to `application/json` to indicate a JSON payload. +- **Content-Type**: Set `application/json` to indicate a JSON payload. - **Data Payload**: This payload includes the GraphQL query and variable parameters, such as `zoneTag`, `start`, `end`, `limit`, and `orderBy`. 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. From cc818dcdb614fcd448ce1ead178dfd8e4deec870 Mon Sep 17 00:00:00 2001 From: Yo'av Moshe Date: Thu, 14 Nov 2024 16:06:14 +0100 Subject: [PATCH 4/5] Update src/content/docs/zaraz/monitoring/monitoring-api.mdx Co-authored-by: Victor Berchet --- src/content/docs/zaraz/monitoring/monitoring-api.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/zaraz/monitoring/monitoring-api.mdx b/src/content/docs/zaraz/monitoring/monitoring-api.mdx index 33c147358cf485b..b55e4322d72810a 100644 --- a/src/content/docs/zaraz/monitoring/monitoring-api.mdx +++ b/src/content/docs/zaraz/monitoring/monitoring-api.mdx @@ -29,7 +29,7 @@ You can construct any query you'd like using the above datasets, but here are so Query for the count of Zaraz events, grouped by time. ```graphql -query AllEvents( +query ZarazEvents( $zoneTag: string $limit: uint64! $start: Date From 2e8b7bba922f89374e58ccb186a8d4879841e27b Mon Sep 17 00:00:00 2001 From: Yo'av Moshe Date: Thu, 14 Nov 2024 16:06:28 +0100 Subject: [PATCH 5/5] Update src/content/docs/zaraz/monitoring/monitoring-api.mdx Co-authored-by: Victor Berchet --- src/content/docs/zaraz/monitoring/monitoring-api.mdx | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/src/content/docs/zaraz/monitoring/monitoring-api.mdx b/src/content/docs/zaraz/monitoring/monitoring-api.mdx index b55e4322d72810a..1e7032316f19a71 100644 --- a/src/content/docs/zaraz/monitoring/monitoring-api.mdx +++ b/src/content/docs/zaraz/monitoring/monitoring-api.mdx @@ -7,7 +7,7 @@ sidebar: import { TabItem, Tabs } from "~/components"; -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 +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. 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/). @@ -34,7 +34,7 @@ query ZarazEvents( $limit: uint64! $start: Date $end: Date - $orderBy: [ZoneZarazTriggersAdaptiveGroupsOrderBy!] + $orderBy: [ZoneZarazTrackAdaptiveGroupsOrderBy!] ) { viewer { zones(filter: { zoneTag: $zoneTag }) { @@ -116,12 +116,12 @@ query ZarazTriggers( Query for the count of 400 server-side responses, grouped by time and URL. ```graphql -query SucessfulGA4Requests( +query ErroneousResponses( $zoneTag: string $limit: uint64! $start: Date $end: Date - $orderBy: [ZoneZarazTriggersAdaptiveGroupsOrderBy!] + $orderBy: [ZoneZarazFetchAdaptiveGroupsOrderBy!] ) { viewer { zones(filter: { zoneTag: $zoneTag }) { @@ -131,7 +131,7 @@ query SucessfulGA4Requests( datetimeHour_geq: $start datetimeHour_leq: $end url_neq: "" - OR: [{ AND: [{ status: 400 }] }] + status: 400 } orderBy: [$orderBy] ) {