Overview

RUM Auto-Instrumentation works by injecting the RUM Browser SDK into the HTML responses being served through a web server or proxy. This method leverages the NGINX Dynamic Modules capability to implement a response body filter. The filter injects the RUM Browser SDK into the response body for responses identified as HTML. After auto-instrumentation is set up, you can manage configurations from the UI.

To understand important limitations and compatibility requirements, see Limitations.

Prerequisites

The Datadog Agent is installed and configured.

Set up your RUM application

To automatically instrument your RUM application:

1. In Datadog, navigate to the Digital Experience > Manage Applications Page, click on New Application, and select the JavaScript (JS) application type.

2. Select Auto-Instrumentation and NGINX.

3. Configure your application parameters. See guidance on configuring sampling.

4. Copy and run the installer command to load the Datadog NGINX Module with the RUM SDK Injector onto NGINX.

5. After the installer successfully installs the SDK Injector, restart NGINX to begin collecting RUM sessions.

6. (Optional) To verify the module is successfully injecting the RUM Browser SDK into HTML pages, check the NGINX error logs for relevant messages. The module logs important steps during the injection process. Ensure that NGINX is configured with at least the INFO log level with the following:

   error_log <file> info;
   

Alternatively, you can manually install and configure the module.

Updating your RUM application

You can update your RUM application settings at any time. From the Application Management list, select your RUM application and navigate to the SDK Configuration page. Click Save Changes after making updates.

Sampling rates

Adjust the slider or enter a specific percentage in the input box for Session Sampling or Session Replay Sampling. Copy and paste the configuration snippet to your nginx.conf file.

Advanced configuration

After you have RUM Auto-Instrumentation set up, configure User Attributes and Allowed Tracing URLs directly from the Datadog UI without modifying your application code.

User attributes

User Attributes allow you to associate RUM sessions with specific users, enabling you to:

• Track individual user journeys across your application
• Filter and search sessions by user details
• Gain insights into user-specific issues and behaviors

Configure three user properties: User ID, User Name, and User Email.

Source types

For each user attribute, select how the RUM SDK should extract the value:

Regex extractor (optional)

Use a regex pattern to extract specific values when your source contains extra characters. For example:

• Source value: user_id=12345;session=abc
• Regex pattern: user_id=(\d+)
• Extracted value: 12345

If your regex pattern includes a capture group (parentheses), the SDK extracts that value. Otherwise, it extracts the entire matched string.

Allowed tracing URLs

Configure allowed tracing URLs to connect your RUM sessions to backend APM traces. This provides end-to-end visibility from the browser to your backend services.

When a user’s browser makes a request to an allowed URL, the RUM SDK injects trace headers. Your backend APM agent reads these headers and links the backend trace to the RUM session.

Configuration

Add the URLs of your backend services that you want to connect to RUM:

Learn more

See Connect RUM and Traces for detailed information about RUM and APM integration.

Troubleshooting

NGINX stops responding

If NGINX stops serving requests, specifically after installation, contact Datadog support with the following information to help us investigate and resolve the issue:

• Your NGINX configuration file
• Any relevant error logs

RUM is not injected

If you notice that RUM is not being injected into HTML pages, consider the following potential causes:

• Content-Type mismatch: RUM is injected only into HTML pages. If the Content-Type header does not correctly indicate text/html, the injection is skipped.

Limitations

See other Limitations.

Uninstall

To manually remove RUM from your auto-instrumented web server:

1. Locate the NGINX configuration file by running nginx -T. For example: /etc/nginx/nginx.conf.

2. At the beginning of the file, remove the line: load_module /opt/datadog-nginx/ngx_http_datadog_module.so;.

3. In the file, remove all existing datadog_* sections from within the http directive. The sections look similar to the following, depending on your system configuration:

   datadog_agent_url http://datadog-agent:8126;
   datadog_tracing off;
   datadog_rum on;
   datadog_rum_config {
     # ... specific RUM configuration
   }
   

4. Delete the directory /opt/datadog-nginx/ and all of its contents.

5. Restart or reload your NGINX web server.

Alternative installation method

If you need finer control over more parameters than what the automatic instrumentation provides, you can manually load the module onto your web server instead of running the installation script.

To manually instrument your RUM application:

Download the appropriate .tgz file

1. Use the .tgz file corresponding to your version of NGINX. You can find all the relevant .tgz files listed by NGINX version under Reference.
2. Extract the tarball to extract the ngx_http_datadog_module.so file. Move it to a location that NGINX has access to (referenced as <RUM_MODULE_PATH> in the steps below).

Update NGINX configuration

1. The nginx.conf file is usually located in NGINX’s configuration directory. Add the following line to load the module:

   load_module <RUM_MODULE_PATH>;
   

2. Then in the http/server/location section, add the following:

   # APM Tracing is enabled by default. The following line disables APM Tracing.
   datadog_disable;
   datadog_rum on;
   datadog_rum_config "v5" {
     "applicationId" "<DATADOG_APPLICATION_ID>";
     "clientToken" "<DATADOG_CLIENT_TOKEN>";
     "site" "<DATADOG_SITE>";
     "service" "my-web-application";
     "env" "production";
     "version" "1.0.0";
     "sessionSampleRate" "100";
     "sessionReplaySampleRate" "100";
     "trackResources" "true";
     "trackLongTasks" "true";
     "trackUserInteractions" "true";
   }
   

Restart your server

1. Restart the NGINX server to begin collecting data for your Datadog RUM application. By default, the RUM SDK is injected to all HTML documents. You may need to clear your browser cache.

2. (Optional) To verify the module is successfully injecting the RUM Browser SDK into HTML pages, check the NGINX error logs for relevant messages. The module logs important steps during the injection process. Ensure that NGINX is configured with at least the INFO log level with the following:

   error_log <file> info;
   

Reference

NGINX modules

Further reading

Additional helpful documentation, links, and articles:

Browser Monitoring Auto-InstrumentationDOCUMENTATION