From 6a57019ac8a869411c83746d6bdd079811389ce0 Mon Sep 17 00:00:00 2001 From: kaumnen Date: Thu, 31 Oct 2024 16:59:51 +0100 Subject: [PATCH 1/7] initial version --- .../automated-analytics-reporting/index.mdx | 407 ++++++++++++++++++ 1 file changed, 407 insertions(+) create mode 100644 src/content/docs/workers/tutorials/automated-analytics-reporting/index.mdx diff --git a/src/content/docs/workers/tutorials/automated-analytics-reporting/index.mdx b/src/content/docs/workers/tutorials/automated-analytics-reporting/index.mdx new file mode 100644 index 000000000000000..4f36d6799e1e353 --- /dev/null +++ b/src/content/docs/workers/tutorials/automated-analytics-reporting/index.mdx @@ -0,0 +1,407 @@ +--- +updated: 2024-10-31 +difficulty: Beginner +content_type: 📝 Tutorial +pcx_content_type: tutorial +title: Automated Analytics Reporting with Cloudflare Workers and Email Routing +products: + - Workers + - Email Routing +languages: + - JavaScript +--- + +import { Render, PackageManagers } from "~/components"; +import { TabItem, Tabs } from "~/components"; + +In this tutorial, you will create a [Cloudflare Worker](https://workers.cloudflare.com/) that fetches analytics data about your account from Cloudflare's [GraphQL Analytics API](https://developers.cloudflare.com/analytics/graphql-api/). You will be able to view the account analytics data in your browser and receive a scheduled email report. + +You will learn: + +1. How to create a Worker using the `c3` CLI. +2. How to fetch analytics data from Cloudflare's GraphQL Analytics API. +3. How to send an email with a Worker. +4. How to schedule the Worker to run at a specific time. +5. How to store secrets and environment variables in your Worker. +6. How to test the Worker locally. +7. How to deploy the Worker to Cloudflare's edge network. + +## Prerequisites + +Before you start, make sure you: + + + +3. [Add a domain](https://developers.cloudflare.com/fundamentals/setup/manage-domains/add-site/) to your Cloudflare account. +4. [Enable Email Routing](https://developers.cloudflare.com/email-routing/get-started/enable-email-routing/) for your domain. +5. Create Cloudflare's [Analytics API token](https://developers.cloudflare.com/analytics/graphql-api/getting-started/authentication/api-token-auth/). + +## Create a Worker + +While you can create a Worker using the Cloudflare dashboard, creating a Worker using the `c3` CLI is recommended as it provides a more streamlined development experience and allows you to test your Worker locally. + +First, use the `c3` CLI to create a new Cloudflare Workers project. + + + +In this tutorial, we will name our Worker `account-analytics`. + + + +Now, the worker is set up. Move into that project directory. + +```sh +cd account-analytics +``` + +Before we continue with the tutorial, let's install [`mimetext`](https://www.npmjs.com/package/mimetext) package. + + + +```sh +pnpm install mimetext +``` + + + +```sh +npm install mimetext +``` + + + +```sh +yarn add mimetext +``` + + + +## Update wrangler.toml + +[`wrangler.toml`](https://developers.cloudflare.com/workers/wrangler/configuration/) is the configuration file for your Worker. It was created when you ran `c3` CLI. Open `wrangler.toml` in your code editor and update it with the following configuration: + +```toml +name = "account-analytics" +main = "src/index.js" + +# Set to the current date +compatibility_date = "<>" +compatibility_flags = ["nodejs_compat"] + +# Set destination_address to the email address where you want to receive the report +send_email = [ + {name = "ANALYTICS_EMAIL", destination_address = "<>"} +] + +# Schedule the Worker to run every day at 10:00 AM +[triggers] +crons = ["0 10 * * *"] + +# Enable observability to view Worker logs +[observability] +enabled = true + +[vars] +# This value shows the name of the sender in the email +SENDER_NAME = "Cloudflare Analytics Worker" + +# This email address will be used as the sender of the email +SENDER_EMAIL = "<>" + +# This email address will be used as the recipient of the email +RECIPIENT_EMAIL = "<>" + +# This value will be used as the subject of the email +EMAIL_SUBJECT = "Cloudflare Analytics Report" +``` + +Before you continue, update the following: + +1. `compatibility_date` with the current date. +2. `destination_address` with the email address where you want to receive the analytics report. +3. `[VARS]` with the environment variable values you want to use in your Worker. + +:::note[IMPORTANT] +`destination_address` and `RECIPIENT_EMAIL` **must** contain [Email Routing verified email](https://developers.cloudflare.com/email-routing/get-started/enable-email-routing/) address. + +`SENDER_EMAIL` **must** be address on a domain that: + +1. Is added to your Cloudflare domain +2. Has Email Routing enabled. + ::: + +## Update the Worker code + +While you are in your project directory, open `src/index.js` in your code editor and update it with the following code: + +```js +import { EmailMessage } from "cloudflare:email"; +import { createMimeMessage } from "mimetext"; + +export default { + async fetch(request, env, ctx) { + try { + const analyticsData = await fetchAnalytics(env); + const formattedContent = formatContent( + analyticsData.data, + analyticsData.formattedDate, + ); + return new Response(formattedContent, { + headers: { "Content-Type": "text/plain" }, + }); + } catch (error) { + console.error("Error:", error); + return new Response(`Error: ${error.message}`, { + status: 500, + headers: { "Content-Type": "text/plain" }, + }); + } + }, + + async scheduled(event, env, ctx) { + try { + const analyticsData = await fetchAnalytics(env); + const formattedContent = formatContent( + analyticsData.data, + analyticsData.formattedDate, + ); + await sendEmail(env, formattedContent); + console.log("Analytics email sent successfully"); + } catch (error) { + console.error("Failed to send analytics email:", error); + } + }, +}; + +async function fetchAnalytics(env) { + const yesterday = new Date(); + yesterday.setDate(yesterday.getDate() - 1); + const dateString = yesterday.toISOString().split("T")[0]; + const formattedDate = yesterday.toLocaleDateString("en-US", { + weekday: "long", + year: "numeric", + month: "long", + day: "numeric", + }); + + const response = await fetch(`https://api.cloudflare.com/client/v4/graphql`, { + method: "POST", + headers: { + Authorization: `Bearer ${env.CF_API_TOKEN}`, + "Content-Type": "application/json", + }, + body: JSON.stringify({ + query: ` + query GetAnalytics($accountTag: String!, $date: String!) { + viewer { + accounts(filter: { accountTag: $accountTag }) { + httpRequests1dGroups(limit: 1, filter: { date: $date }) { + sum { + requests + pageViews + bytes + encryptedRequests + encryptedBytes + cachedRequests + cachedBytes + threats + browserMap { + pageViews + uaBrowserFamily + } + responseStatusMap { + requests + edgeResponseStatus + } + clientHTTPVersionMap { + requests + clientHTTPProtocol + } + } + } + } + } + } + `, + variables: { + accountTag: env.CF_ACCOUNT_ID, + date: dateString, + }, + }), + }); + + const data = await response.json(); + if (data.errors) { + throw new Error(`GraphQL Error: ${JSON.stringify(data.errors)}`); + } + + return { data, formattedDate }; +} + +function formatContent(analyticsData, formattedDate) { + const stats = + analyticsData.data.viewer.accounts[0].httpRequests1dGroups[0].sum; + + const formatBytes = (bytes) => { + if (bytes === 0) return "0 Bytes"; + const k = 1024; + const sizes = ["Bytes", "KB", "MB", "GB", "TB"]; + const i = Math.floor(Math.log(bytes) / Math.log(k)); + return parseFloat((bytes / Math.pow(k, i)).toFixed(2)) + " " + sizes[i]; + }; + + const browserData = stats.browserMap + .sort((a, b) => b.pageViews - a.pageViews) + .map((b) => ` ${b.uaBrowserFamily}: ${b.pageViews} views`) + .join("\n"); + + const statusData = stats.responseStatusMap + .sort((a, b) => b.requests - a.requests) + .map((s) => ` ${s.edgeResponseStatus}: ${s.requests} requests`) + .join("\n"); + + const httpVersionData = stats.clientHTTPVersionMap + .sort((a, b) => b.requests - a.requests) + .map((h) => ` ${h.clientHTTPProtocol}: ${h.requests} requests`) + .join("\n"); + + return ` +CLOUDFLARE ANALYTICS REPORT +========================== +Generated for: ${formattedDate} + +TRAFFIC OVERVIEW +--------------- + Total Requests: ${stats.requests.toLocaleString()} + Page Views: ${stats.pageViews.toLocaleString()} + Security Threats Blocked: ${stats.threats.toLocaleString()} + +BANDWIDTH +--------- + Total Bandwidth: ${formatBytes(stats.bytes)} + Encrypted Bandwidth: ${formatBytes(stats.encryptedBytes)} + Cached Bandwidth: ${formatBytes(stats.cachedBytes)} + +CACHING & ENCRYPTION +------------------- + Total Requests: ${stats.requests.toLocaleString()} + Encrypted Requests: ${stats.encryptedRequests.toLocaleString()} + Cached Requests: ${stats.cachedRequests.toLocaleString()} + Encryption Rate: ${((stats.encryptedRequests / stats.requests) * 100).toFixed(1)}% + Cache Rate: ${((stats.cachedRequests / stats.requests) * 100).toFixed(1)}% + +BROWSERS +-------- +${browserData} + +HTTP STATUS CODES +--------------- +${statusData} + +HTTP VERSIONS +------------ +${httpVersionData} +`; +} + +async function sendEmail(env, content) { + const msg = createMimeMessage(); + + msg.setSender({ + name: env.SENDER_NAME, + addr: env.SENDER_EMAIL, + }); + + msg.setRecipient(env.RECIPIENT_EMAIL); + msg.setSubject(env.EMAIL_SUBJECT); + + msg.addMessage({ + contentType: "text/plain", + data: content, + }); + + const message = new EmailMessage( + env.SENDER_EMAIL, + env.RECIPIENT_EMAIL, + msg.asRaw(), + ); + + try { + await env.ANALYTICS_EMAIL.send(message); + } catch (error) { + throw new Error(`Failed to send email: ${error.message}`); + } +} +``` + +## Test the Worker + +Now that you have updated the Worker code, you can test it locally using the `wrangler dev` command. This command starts a local server that runs your Worker code. + +Before you run the Worker, you need to add two Worker secrets: + +- `CF_API_TOKEN`: Cloudflare GraphQL Analytics API token you created earlier. +- `CF_ACCOUNT_ID`: Your Cloudflare account ID. Can be found in the Cloudflare dashboard under the Workers & Pages Overview tab. + +Let's create `.dev.vars` file in the root of your project directory and add the following: + +```sh +CF_API_TOKEN=YOUR_CLOUDFLARE_API_TOKEN +CF_ACCOUNT_ID=YOUR_CLOUDFLARE_ACCOUNT_ID +``` + +Now, run the Worker locally: + +```sh +npx wrangler dev --remote +``` + +Open your browser and visit `http://localhost:8787`. You should see the analytics data displayed in your browser. + +## Deploy the Worker and Worker secrets + +Once you have tested the Worker locally, you can deploy it to Cloudflare's edge network: + +```sh +npx wrangler deploy +``` + +CLI command will output the URL where your Worker is deployed. Before you can visit this URL in your browser to view the analytics data, you need to add two Worker secrets you already have locally to your deployed Worker: + +```sh +npx wrangler secret put +``` + +Change `` with the name of the secret you want to add. Repeat this command for `CF_API_TOKEN` and `CF_ACCOUNT_ID` secrets. + +Once you put the secrets, visit the `account-analytics..workers.dev` to view the analytics data. You will also receive an email report to the specified recipient email address every day at 10:00 AM. + +If you want to disable a public URL for your Worker, you can do so by following these steps: + +1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com). + +2. In Account Home, select **Workers & Pages**, and then select `account-analytics` Worker. + +3. Go to **Settings** - **Domains & Routes** + +4. Click 'Disable' to disable the public `account-analytics..workers.dev` URL. + +You have successfully created, tested and deployed a Worker that fetches analytics data from Cloudflare’s GraphQL Analytics API and sends an email report via Email Routing. + +## Related resources + +To build more with Workers, refer to [Tutorials](/workers/tutorials/). + +If you have any questions, need assistance, or would like to share your project, join the Cloudflare Developer community on [Discord](https://discord.cloudflare.com) to connect with other developers and the Cloudflare team. From dcbc3cf36793192bfdaa5fe2a25f8271ad27ecd6 Mon Sep 17 00:00:00 2001 From: kaumnen Date: Thu, 31 Oct 2024 17:14:00 +0100 Subject: [PATCH 2/7] fix link checks, other minor fixes --- .../automated-analytics-reporting/index.mdx | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/src/content/docs/workers/tutorials/automated-analytics-reporting/index.mdx b/src/content/docs/workers/tutorials/automated-analytics-reporting/index.mdx index 4f36d6799e1e353..a140746a5837cbd 100644 --- a/src/content/docs/workers/tutorials/automated-analytics-reporting/index.mdx +++ b/src/content/docs/workers/tutorials/automated-analytics-reporting/index.mdx @@ -32,9 +32,9 @@ Before you start, make sure you: -3. [Add a domain](https://developers.cloudflare.com/fundamentals/setup/manage-domains/add-site/) to your Cloudflare account. -4. [Enable Email Routing](https://developers.cloudflare.com/email-routing/get-started/enable-email-routing/) for your domain. -5. Create Cloudflare's [Analytics API token](https://developers.cloudflare.com/analytics/graphql-api/getting-started/authentication/api-token-auth/). +3. [Add a domain](/fundamentals/setup/manage-domains/add-site/) to your Cloudflare account. +4. [Enable Email Routing](/email-routing/get-started/enable-email-routing/) for your domain. +5. Create Cloudflare's [Analytics API token](/analytics/graphql-api/getting-started/authentication/api-token-auth/). ## Create a Worker @@ -60,7 +60,7 @@ In this tutorial, we will name our Worker `account-analytics`. }} /> -Now, the worker is set up. Move into that project directory. +Now, the Worker is set up. Move into that project directory. ```sh cd account-analytics @@ -134,7 +134,7 @@ Before you continue, update the following: 3. `[VARS]` with the environment variable values you want to use in your Worker. :::note[IMPORTANT] -`destination_address` and `RECIPIENT_EMAIL` **must** contain [Email Routing verified email](https://developers.cloudflare.com/email-routing/get-started/enable-email-routing/) address. +`destination_address` and `RECIPIENT_EMAIL` **must** contain [Email Routing verified email](/email-routing/get-started/enable-email-routing/) address. `SENDER_EMAIL` **must** be address on a domain that: @@ -398,7 +398,7 @@ If you want to disable a public URL for your Worker, you can do so by following 4. Click 'Disable' to disable the public `account-analytics..workers.dev` URL. -You have successfully created, tested and deployed a Worker that fetches analytics data from Cloudflare’s GraphQL Analytics API and sends an email report via Email Routing. +You have successfully created, tested and deployed a Worker that fetches analytics data from Cloudflare's GraphQL Analytics API and sends an email report via Email Routing. ## Related resources From 505456b7f9c2b7e888e12925dfb59d5475895767 Mon Sep 17 00:00:00 2001 From: kaumnen Date: Fri, 1 Nov 2024 18:01:17 +0100 Subject: [PATCH 3/7] update wrangler code section. other minor changes --- .../automated-analytics-reporting/index.mdx | 68 ++++++++++++++++++- 1 file changed, 66 insertions(+), 2 deletions(-) diff --git a/src/content/docs/workers/tutorials/automated-analytics-reporting/index.mdx b/src/content/docs/workers/tutorials/automated-analytics-reporting/index.mdx index a140746a5837cbd..52939f90f76a3fd 100644 --- a/src/content/docs/workers/tutorials/automated-analytics-reporting/index.mdx +++ b/src/content/docs/workers/tutorials/automated-analytics-reporting/index.mdx @@ -1,5 +1,5 @@ --- -updated: 2024-10-31 +updated: 2024-11-01 difficulty: Beginner content_type: 📝 Tutorial pcx_content_type: tutorial @@ -144,13 +144,19 @@ Before you continue, update the following: ## Update the Worker code +You will now add the code step by step to the `src/index.js` file. We will explain each part of the code as we go along. + +### Add the required modules and Handlers + While you are in your project directory, open `src/index.js` in your code editor and update it with the following code: ```js +// Import required modules for email handling import { EmailMessage } from "cloudflare:email"; import { createMimeMessage } from "mimetext"; export default { + // HTTP request handler - This Handler is invoked when the Worker is accessed via HTTP async fetch(request, env, ctx) { try { const analyticsData = await fetchAnalytics(env); @@ -170,6 +176,7 @@ export default { } }, + // Scheduled task handler - This Handler is invoked via a Cron Trigger async scheduled(event, env, ctx) { try { const analyticsData = await fetchAnalytics(env); @@ -184,8 +191,20 @@ export default { } }, }; +``` + +In the code above, we have defined two [Worker Handlers](/workers/runtime-apis/handlers/): + +- `fetch`: This Handler executes when the Worker is accessed via HTTP. It fetches the analytics data, formats it and returns it as a response. +- `scheduled`: This Handler executes at the scheduled time. It fetches the analytics data, formats it and sends an email with the analytics data. + +### Add the analytics fetching function +Add the following function to the `src/index.js` file, below the Handlers: + +```js async function fetchAnalytics(env) { + // Calculate yesterday's date for the report and format it for display const yesterday = new Date(); yesterday.setDate(yesterday.getDate() - 1); const dateString = yesterday.toISOString().split("T")[0]; @@ -196,6 +215,7 @@ async function fetchAnalytics(env) { day: "numeric", }); + // Fetch analytics data from Cloudflare's GraphQL Analytics API const response = await fetch(`https://api.cloudflare.com/client/v4/graphql`, { method: "POST", headers: { @@ -249,11 +269,35 @@ async function fetchAnalytics(env) { return { data, formattedDate }; } +``` + +In the code above, we have defined a function `fetchAnalytics` that fetches analytics data from Cloudflare's GraphQL Analytics API. The function calculates yesterday's date, formats it for display, and sends a GraphQL query to the Analytics API to fetch the analytics data. + +:::note +`env.CF_API_TOKEN` and `env.CF_ACCOUNT_ID` are [Worker Secrets](/workers/configuration/secrets/). These variables are used to authenticate the request and fetch the analytics data for the specified account. You will add these secrets to your Worker after the code is complete. +::: + +This function returns the **raw** data for the previous day, including: +- Traffic overview data (Total requests, Page views and Blocked threats) +- Bandwidth data (Total bandwidth, Encrypted bandwidth and Cached bandwidth) +- Caching & Encryption data (Encrypted requests, Cached requests, Encryption rate and Cache rate) +- Browser data (Page views by browser) +- HTTP status code data (Requests by status code) +- HTTP version data (Requests by HTTP version) + +This data will be used to generate the analytics report. Let's add the function that formats this data. + +### Add the data formatting function + +Add the following function to the `src/index.js` file, below the `fetchAnalytics` function: + +```js function formatContent(analyticsData, formattedDate) { const stats = analyticsData.data.viewer.accounts[0].httpRequests1dGroups[0].sum; + // Helper function to format bytes into human-readable format const formatBytes = (bytes) => { if (bytes === 0) return "0 Bytes"; const k = 1024; @@ -262,21 +306,25 @@ function formatContent(analyticsData, formattedDate) { return parseFloat((bytes / Math.pow(k, i)).toFixed(2)) + " " + sizes[i]; }; + // Format browser statistics const browserData = stats.browserMap .sort((a, b) => b.pageViews - a.pageViews) .map((b) => ` ${b.uaBrowserFamily}: ${b.pageViews} views`) .join("\n"); + // Format HTTP status code statistics const statusData = stats.responseStatusMap .sort((a, b) => b.requests - a.requests) .map((s) => ` ${s.edgeResponseStatus}: ${s.requests} requests`) .join("\n"); + // Format HTTP version statistics const httpVersionData = stats.clientHTTPVersionMap .sort((a, b) => b.requests - a.requests) .map((h) => ` ${h.clientHTTPProtocol}: ${h.requests} requests`) .join("\n"); + // Return formatted report return ` CLOUDFLARE ANALYTICS REPORT ========================== @@ -315,8 +363,17 @@ HTTP VERSIONS ${httpVersionData} `; } +``` +At this point, you have defined the `fetchAnalytics` function that fetches raw analytics data from Cloudflare's GraphQL Analytics API and the `formatContent` function that formats the analytics data into a human-readable report. + +### Add the email sending function + +Add the following function to the `src/index.js` file, below the `formatContent` function: + +```js async function sendEmail(env, content) { + // Create and configure email message const msg = createMimeMessage(); msg.setSender({ @@ -332,6 +389,7 @@ async function sendEmail(env, content) { data: content, }); + // Send email using Cloudflare Email Routing service const message = new EmailMessage( env.SENDER_EMAIL, env.RECIPIENT_EMAIL, @@ -346,6 +404,12 @@ async function sendEmail(env, content) { } ``` +This function sends an email with the formatted analytics data to the specified recipient email address using Cloudflare's Email Routing service. + +:::note +`sendEmail` function uses multiple environment variables that are set in the `wrangler.toml` file. +::: + ## Test the Worker Now that you have updated the Worker code, you can test it locally using the `wrangler dev` command. This command starts a local server that runs your Worker code. @@ -384,7 +448,7 @@ CLI command will output the URL where your Worker is deployed. Before you can vi npx wrangler secret put ``` -Change `` with the name of the secret you want to add. Repeat this command for `CF_API_TOKEN` and `CF_ACCOUNT_ID` secrets. +Replace `` with the name of the secret you want to add. Repeat this command for `CF_API_TOKEN` and `CF_ACCOUNT_ID` secrets. Once you put the secrets, visit the `account-analytics..workers.dev` to view the analytics data. You will also receive an email report to the specified recipient email address every day at 10:00 AM. From 7f5a44fda177912cfb1955140896f57940923859 Mon Sep 17 00:00:00 2001 From: kaumnen Date: Wed, 6 Nov 2024 17:11:59 +0100 Subject: [PATCH 4/7] rewording and style fixes --- .../automated-analytics-reporting/index.mdx | 56 +++++++++---------- 1 file changed, 27 insertions(+), 29 deletions(-) diff --git a/src/content/docs/workers/tutorials/automated-analytics-reporting/index.mdx b/src/content/docs/workers/tutorials/automated-analytics-reporting/index.mdx index 52939f90f76a3fd..2d156c9414e56fa 100644 --- a/src/content/docs/workers/tutorials/automated-analytics-reporting/index.mdx +++ b/src/content/docs/workers/tutorials/automated-analytics-reporting/index.mdx @@ -36,7 +36,7 @@ Before you start, make sure you: 4. [Enable Email Routing](/email-routing/get-started/enable-email-routing/) for your domain. 5. Create Cloudflare's [Analytics API token](/analytics/graphql-api/getting-started/authentication/api-token-auth/). -## Create a Worker +## 1. Create a Worker While you can create a Worker using the Cloudflare dashboard, creating a Worker using the `c3` CLI is recommended as it provides a more streamlined development experience and allows you to test your Worker locally. @@ -48,7 +48,7 @@ First, use the `c3` CLI to create a new Cloudflare Workers project. args={"account-analytics"} /> -In this tutorial, we will name our Worker `account-analytics`. +In this tutorial, name your Worker as `account-analytics`. -Now, the Worker is set up. Move into that project directory. +Now, the Worker is set up. Move into your project directory: ```sh cd account-analytics ``` -Before we continue with the tutorial, let's install [`mimetext`](https://www.npmjs.com/package/mimetext) package. +To continue with this tutorial, install the [`mimetext`](https://www.npmjs.com/package/mimetext) package: @@ -88,7 +88,7 @@ yarn add mimetext -## Update wrangler.toml +## 2. Update wrangler.toml file [`wrangler.toml`](https://developers.cloudflare.com/workers/wrangler/configuration/) is the configuration file for your Worker. It was created when you ran `c3` CLI. Open `wrangler.toml` in your code editor and update it with the following configuration: @@ -129,22 +129,20 @@ EMAIL_SUBJECT = "Cloudflare Analytics Report" Before you continue, update the following: -1. `compatibility_date` with the current date. -2. `destination_address` with the email address where you want to receive the analytics report. -3. `[VARS]` with the environment variable values you want to use in your Worker. +1. `compatibility_date`: Enter the current date. +2. `destination_address`: Enter the email address where you want to receive the analytics report. +3. `[VARS]`: Enter the environment variable values you want to use in your Worker. :::note[IMPORTANT] `destination_address` and `RECIPIENT_EMAIL` **must** contain [Email Routing verified email](/email-routing/get-started/enable-email-routing/) address. -`SENDER_EMAIL` **must** be address on a domain that: +`SENDER_EMAIL` **must** be an email address on a domain that is added to your Cloudflare domain and has Email Routing enabled. -1. Is added to your Cloudflare domain -2. Has Email Routing enabled. - ::: +::: -## Update the Worker code +## 3. Update the Worker code -You will now add the code step by step to the `src/index.js` file. We will explain each part of the code as we go along. +You will now add the code step by step to the `src/index.js` file. This tutorial will explain each part of the code. ### Add the required modules and Handlers @@ -193,7 +191,7 @@ export default { }; ``` -In the code above, we have defined two [Worker Handlers](/workers/runtime-apis/handlers/): +The code above defines two [Worker Handlers](/workers/runtime-apis/handlers/): - `fetch`: This Handler executes when the Worker is accessed via HTTP. It fetches the analytics data, formats it and returns it as a response. - `scheduled`: This Handler executes at the scheduled time. It fetches the analytics data, formats it and sends an email with the analytics data. @@ -271,7 +269,7 @@ async function fetchAnalytics(env) { } ``` -In the code above, we have defined a function `fetchAnalytics` that fetches analytics data from Cloudflare's GraphQL Analytics API. The function calculates yesterday's date, formats it for display, and sends a GraphQL query to the Analytics API to fetch the analytics data. +In the code above, the `fetchAnalytics` function fetches analytics data from Cloudflare's GraphQL Analytics API. The `fetchAnalytics` function calculates yesterday's date, formats the date for display, and sends a GraphQL query to the Analytics API to fetch the analytics data. :::note `env.CF_API_TOKEN` and `env.CF_ACCOUNT_ID` are [Worker Secrets](/workers/configuration/secrets/). These variables are used to authenticate the request and fetch the analytics data for the specified account. You will add these secrets to your Worker after the code is complete. @@ -281,12 +279,12 @@ This function returns the **raw** data for the previous day, including: - Traffic overview data (Total requests, Page views and Blocked threats) - Bandwidth data (Total bandwidth, Encrypted bandwidth and Cached bandwidth) -- Caching & Encryption data (Encrypted requests, Cached requests, Encryption rate and Cache rate) +- Caching and Encryption data (Encrypted requests, Cached requests, Encryption rate and Cache rate) - Browser data (Page views by browser) - HTTP status code data (Requests by status code) - HTTP version data (Requests by HTTP version) -This data will be used to generate the analytics report. Let's add the function that formats this data. +This data will be used to generate the analytics report. In the following step, you will add the function that formats this data. ### Add the data formatting function @@ -410,16 +408,16 @@ This function sends an email with the formatted analytics data to the specified `sendEmail` function uses multiple environment variables that are set in the `wrangler.toml` file. ::: -## Test the Worker +## 4. Test the Worker Now that you have updated the Worker code, you can test it locally using the `wrangler dev` command. This command starts a local server that runs your Worker code. Before you run the Worker, you need to add two Worker secrets: - `CF_API_TOKEN`: Cloudflare GraphQL Analytics API token you created earlier. -- `CF_ACCOUNT_ID`: Your Cloudflare account ID. Can be found in the Cloudflare dashboard under the Workers & Pages Overview tab. +- `CF_ACCOUNT_ID`: Your Cloudflare account ID. You can find your account ID in the Cloudflare dashboard under the **Workers & Pages** Overview tab. -Let's create `.dev.vars` file in the root of your project directory and add the following: +Create a `.dev.vars` file in the root of your project directory and add the following: ```sh CF_API_TOKEN=YOUR_CLOUDFLARE_API_TOKEN @@ -432,17 +430,17 @@ Now, run the Worker locally: npx wrangler dev --remote ``` -Open your browser and visit `http://localhost:8787`. You should see the analytics data displayed in your browser. +Open the `http://localhost:8787` URL on your browser. The browser will display analytics data. -## Deploy the Worker and Worker secrets +## 5. Deploy the Worker and Worker secrets -Once you have tested the Worker locally, you can deploy it to Cloudflare's edge network: +Once you have tested the Worker locally, you can deploy your Worker to Cloudflare's edge network: ```sh npx wrangler deploy ``` -CLI command will output the URL where your Worker is deployed. Before you can visit this URL in your browser to view the analytics data, you need to add two Worker secrets you already have locally to your deployed Worker: +CLI command will output the URL where your Worker is deployed. Before you can use this URL in your browser to view the analytics data, you need to add two Worker secrets you already have locally to your deployed Worker: ```sh npx wrangler secret put @@ -450,17 +448,17 @@ npx wrangler secret put Replace `` with the name of the secret you want to add. Repeat this command for `CF_API_TOKEN` and `CF_ACCOUNT_ID` secrets. -Once you put the secrets, visit the `account-analytics..workers.dev` to view the analytics data. You will also receive an email report to the specified recipient email address every day at 10:00 AM. +Once you put the secrets, preview your analytics data at `account-analytics..workers.dev`. You will also receive an email report to the specified recipient email address every day at 10:00 AM. If you want to disable a public URL for your Worker, you can do so by following these steps: 1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com). -2. In Account Home, select **Workers & Pages**, and then select `account-analytics` Worker. +2. In Account Home, select **Workers & Pages**, then select `account-analytics` Worker. -3. Go to **Settings** - **Domains & Routes** +3. Go to **Settings** > **Domains & Routes**. -4. Click 'Disable' to disable the public `account-analytics..workers.dev` URL. +4. Select **Disable** to disable the public `account-analytics..workers.dev` URL. You have successfully created, tested and deployed a Worker that fetches analytics data from Cloudflare's GraphQL Analytics API and sends an email report via Email Routing. From 4ccfbc2c53824ae90d3d5ab7150dd358e84b5769 Mon Sep 17 00:00:00 2001 From: kaumnen Date: Thu, 7 Nov 2024 12:39:36 +0100 Subject: [PATCH 5/7] title update --- .../workers/tutorials/automated-analytics-reporting/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/workers/tutorials/automated-analytics-reporting/index.mdx b/src/content/docs/workers/tutorials/automated-analytics-reporting/index.mdx index 2d156c9414e56fa..19cd774577e6970 100644 --- a/src/content/docs/workers/tutorials/automated-analytics-reporting/index.mdx +++ b/src/content/docs/workers/tutorials/automated-analytics-reporting/index.mdx @@ -3,7 +3,7 @@ updated: 2024-11-01 difficulty: Beginner content_type: 📝 Tutorial pcx_content_type: tutorial -title: Automated Analytics Reporting with Cloudflare Workers and Email Routing +title: Automate analytics reporting with Cloudflare Workers and email routing products: - Workers - Email Routing From 1925c4cb39d972d61673438b4fe484ba9a79f335 Mon Sep 17 00:00:00 2001 From: kaumnen Date: Wed, 20 Nov 2024 18:15:37 +0100 Subject: [PATCH 6/7] update compatibility_date --- .../tutorials/automated-analytics-reporting/index.mdx | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/src/content/docs/workers/tutorials/automated-analytics-reporting/index.mdx b/src/content/docs/workers/tutorials/automated-analytics-reporting/index.mdx index 19cd774577e6970..c44cc11956e2dfc 100644 --- a/src/content/docs/workers/tutorials/automated-analytics-reporting/index.mdx +++ b/src/content/docs/workers/tutorials/automated-analytics-reporting/index.mdx @@ -1,5 +1,5 @@ --- -updated: 2024-11-01 +updated: 2024-11-20 difficulty: Beginner content_type: 📝 Tutorial pcx_content_type: tutorial @@ -96,8 +96,7 @@ yarn add mimetext name = "account-analytics" main = "src/index.js" -# Set to the current date -compatibility_date = "<>" +compatibility_date = "2024-11-01" compatibility_flags = ["nodejs_compat"] # Set destination_address to the email address where you want to receive the report @@ -129,9 +128,8 @@ EMAIL_SUBJECT = "Cloudflare Analytics Report" Before you continue, update the following: -1. `compatibility_date`: Enter the current date. -2. `destination_address`: Enter the email address where you want to receive the analytics report. -3. `[VARS]`: Enter the environment variable values you want to use in your Worker. +1. `destination_address`: Enter the email address where you want to receive the analytics report. +2. `[VARS]`: Enter the environment variable values you want to use in your Worker. :::note[IMPORTANT] `destination_address` and `RECIPIENT_EMAIL` **must** contain [Email Routing verified email](/email-routing/get-started/enable-email-routing/) address. From 75b226e165803fc039d502324ec60d12a614e69c Mon Sep 17 00:00:00 2001 From: db-cloudflare <125887610+db-cloudflare@users.noreply.github.com> Date: Mon, 25 Nov 2024 14:20:57 +0000 Subject: [PATCH 7/7] Update src/content/docs/workers/tutorials/automated-analytics-reporting/index.mdx Add author credit --- .../workers/tutorials/automated-analytics-reporting/index.mdx | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/src/content/docs/workers/tutorials/automated-analytics-reporting/index.mdx b/src/content/docs/workers/tutorials/automated-analytics-reporting/index.mdx index c44cc11956e2dfc..a651200d606aa14 100644 --- a/src/content/docs/workers/tutorials/automated-analytics-reporting/index.mdx +++ b/src/content/docs/workers/tutorials/automated-analytics-reporting/index.mdx @@ -7,6 +7,10 @@ title: Automate analytics reporting with Cloudflare Workers and email routing products: - Workers - Email Routing +spotlight: + author: Aleksej Komnenovic + author_bio_link: https://www.linkedin.com/in/komnenovic/ + author_bio_source: LinkedIn languages: - JavaScript ---