Disclaimer! I work at Grafana Labs and am writing this in my personal time to explore the product

I want to monitor traffic to this site and do it in a way that maintains privacy. In the past I’ve used Google Analytics, which I’m opting not to use due to the amount of data collected.

Here are some of the things I’d like to track:

• How many users visited my website, broken down by page
• How long does a user stay?
• How much data is transmitted?
• How well does the page perform?

Since I work at Grafana, I am biased towards using Grafana Faro.

How do I add Grafana Faro to a Hugo site #

Main docs for Faro: https://grafana.com/docs/grafana-cloud/monitor-applications/frontend-observability/instrument/faro/

The steps are:

1. create an app in grafana cloud
2. inject the faro sdk into the web app via
   1. importing NodeJS module
   2. downloading via CDN directly

I think for Hugo, CDN makes the most sense. The pertinent code that needs to be invoked is:

<script>
  (function () {
    // Create a script tag for loading the library
    var script = document.createElement("script");

    // Initialize the Web SDK at the onLoad event of the script element so it is called when the library is loaded.
    script.onload = () => {
      window.GrafanaFaroWebSdk.initializeFaro({
        // Mandatory, the URL of the Grafana Cloud collector with embedded application key.
        // Copy from the configuration page of your application in Grafana.
        url: "http://faro-collector-us-central-0.grafana.net/collect/{app-key}",

        // Mandatory, the identification label(s) of your application
        app: {
          name: "my-app",
          version: "1.0.0", // Optional, but recommended
        },
      });
    };

    // Set the source of the script tag to the CDN
    script.src =
      "https://unpkg.com/@grafana/faro-web-sdk@^1.0.0-beta/dist/bundle/faro-web-sdk.iife.js";

    // Append the script tag to the head of the HTML document
    document.head.appendChild(script);
  })();
</script>

My main question is how can you add this to a website generated by Hugo? Hugo supports the ability to edit themes by copying the ${theme_sub_directory}/theme/partials to your local /theme/partials folder. You can edit the header.html partial after copying the themes partials over and append the script from above.

Note: Applications created in Grafana Cloud have a better script

After adding the Faro script to the header, deploy your changes and you should start collecting sessions.

Note: If you have ublock origin, or anything else that blocks tracking, you should disable that for the site :grimacing:

Recap #

It was fairly easy to get this blog instrumented with Faro. Now I need to explore the data collected and see how I can answer the questions posed at the top.

LLM usage notice #

I wrote all of the content of this article. At no point did I use an LLM to formulate any of the paragraphs.

I did get stuck on how to figure out how to edit a theme in hugo. At first it recommended that I edit the submodule directly, and I had to remind it that is not good practice. Other then that, Grafana documentation got and my own thought contributed to the rest.