How to Add Elastic RUM Monitoring to a Hugo Site

Elastic RUM (Real User Monitoring) is the real‑time user‑experience monitoring feature of Elastic Observability, part of the Elastic Stack (Elasticsearch, Logstash, Kibana, Beats). It captures performance data, user interactions, and errors from browsers, enabling developers and operations teams to diagnose and improve web‑app performance.

Key Benefits of Elastic RUM

Real‑time performance monitoring : Detect and resolve performance issues as they happen.

End‑to‑end observability : Integrates with other Elastic Stack components for unified logs, metrics, and traces.

User‑behavior analysis : Capture navigation, clicks, and resource loading to understand user journeys.

Customizability : Configure the agent to match specific business needs.

Elasticsearch integration : Leverage powerful search and visualization capabilities.

Preparing the JavaScript Agent

The Elastic RUM JavaScript agent can be added to a web project in two ways:

Install via npm ( npm install @elastic/apm‑rum --save) and import the module. This works for most modern front‑end projects but is unnecessary for static site generators like Hugo.

Copy the pre‑built script tag provided by Elastic Cloud into the site’s HTML. This is the approach used for Hugo.

Integration Steps for a Hugo Site

1. Download the RUM script (e.g., elastic-apm‑rum.umd.min‑5.15.0.js) and place it in the static/js directory of the Hugo project.

2. Create the file layouts/partials/footer/custom.html (or edit the existing footer partial) and insert the following code:

<script src="/js/elastic-apm-rum.umd.min-5.15.0.js" crossorigin></script>
<script>
elasticApm.init({
  serviceName: 'martin-blog',
  environment: 'production',
  serviceVersion: '1.5.0',
  serverUrl: 'https://d4c649267e404779a895b41199d5db98.apm.ap-east-1.aws.elastic-cloud.com:443'
});
</script>

3. Adjust the parameters (serviceName, environment, serviceVersion, serverUrl) to match your deployment. 4. Rebuild the Hugo site and deploy it. The agent will start sending RUM data to the configured Elastic Cloud APM instance.

Configuration Parameters Explained

serviceName

: Identifier for the monitored service (e.g., the site name). environment: Deployment environment such as production or staging. serviceVersion: Version string of the site or application. serverUrl: URL of the Elastic Cloud APM endpoint that receives the data. src (script tag): Path to the downloaded RUM bundle.

Viewing Collected Data

After the site is live, open the Elastic Cloud Kibana UI and navigate to the User Experience dashboard under the APM app. You will see metrics such as page‑load duration, First Contentful Paint (FCP), Largest Contentful Paint (LCP), First Input Delay (FID), Cumulative Layout Shift (CLS), and error breakdowns.

Key User‑Experience Metrics

First Contentful Paint (FCP) : Time until the first piece of content is rendered.

Total Blocking Time (TBT) : Sum of long‑task durations between FCP and transaction completion.

Long Tasks : Tasks blocking the UI thread for >50 ms.

Largest Contentful Paint (LCP) : Perceived load speed of the main content.

First Input Delay (FID) : Delay between user interaction and browser response.

Cumulative Layout Shift (CLS) : Visual stability measured by unexpected layout movements.

Practical Findings

Using Elastic RUM, the author discovered that some images hosted on a Tencent Cloud object storage bucket failed to load due to an overdue account, causing broken images on the blog. The RUM error alerts highlighted this issue, prompting a quick fix.

Conclusion

Integrating Elastic RUM into a Hugo static site provides real‑time visibility into user experience, performance bottlenecks, and errors without requiring a backend. The same approach can be adapted to other static site generators or front‑end projects, offering a powerful observability layer for web applications.