--- title: Instrumenting NGINX Server description: >- Configure NGINX server to automatically inject RUM Browser SDK into HTML responses using the Datadog dynamic module. breadcrumbs: >- Docs > RUM & Session Replay > Application Monitoring > RUM Browser Monitoring > Browser Monitoring Setup > Auto-Instrumentation > Instrumenting NGINX Server --- > For the complete documentation index, see [llms.txt](https://docs.datadoghq.com/llms.txt). # Instrumenting NGINX Server {% callout %} # Important note for users on the following Datadog sites: app.ddog-gov.com, us2.ddog-gov.com {% alert level="danger" %} This product is not supported for your selected [Datadog site](https://docs.datadoghq.com/getting_started/site.md). ({% placeholder "user-datadog-site-name" /%}). {% /alert %} {% /callout %} ## Overview{% #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 uses the [NGINX Dynamic Modules capability](https://docs.nginx.com/nginx/admin-guide/dynamic-modules/dynamic-modules/) 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. ## Limitations{% #limitations %} Auto-instrumentation for this server has the following limitations. If your use case requires more control, use [client-side instrumentation](https://docs.datadoghq.com/real_user_monitoring/application_monitoring/browser/setup/client.md) instead. - This instrumentation method **does not support all [advanced RUM configurations](https://docs.datadoghq.com/real_user_monitoring/application_monitoring/browser/advanced_configuration.md)**. - If your web server is acting as a proxy and the upstream server uses **end-to-end encryption** (TLS) or **content compression** (gzip, zstd, Brotli), the RUM Browser SDK **cannot be injected**. For proper instrumentation: - **Disable content compression** on the upstream server. - **Enable TLS origination** on the web server. ## Prerequisites{% #prerequisites %} The [Datadog Agent](https://docs.datadoghq.com/agent.md) is installed and configured. ## Setup{% #setup %} Choose your preferred setup method. **Note**: NGINX must be restarted regardless of which instrumentation method is used. {% tab title="Single-Step Instrumentation" %} Enables RUM Browser monitoring with [Single Step Instrumentation (SSI)](https://docs.datadoghq.com/tracing/trace_collection/single-step-apm.md). When you run the Agent installation with RUM enabled, Datadog: - Loads the NGINX module into your NGINX server through SSI - Creates a RUM application for you - Configures the NGINX module with the required RUM settings **This approach requires no code changes and no manual NGINX configuration.** 1. Go to the [**Agent Installation**](https://app.datadoghq.com/fleet/install-agent/latest?platform=overview) page. 1. Select your platform (for example, Linux). 1. In the **Customize your observability coverage** section, enable **Real User Monitoring** under **Application Observability**. A RUM application is automatically created for you when you enable this option. 1. Copy the generated installation command and run it on your host. 1. Restart NGINX to begin collecting RUM sessions. {% /tab %} {% tab title="Managed Instrumentation" %} Use this method if you need to configure sampling rates or application settings before deploying. 1. In Datadog, navigate to **Digital Experience > Manage Applications**, click **Set up Manually**, and select the JavaScript (JS) application type. 1. Select **Auto-Instrumentation** and **NGINX**. 1. Configure your application parameters. See [guidance on configuring sampling](https://docs.datadoghq.com/real_user_monitoring/guide/sampling-browser-plans.md). 1. Copy and run the installer command to load the Datadog NGINX module with the RUM SDK Injector into your NGINX server. 1. Restart NGINX to begin collecting RUM sessions. 1. (Optional) To verify the module is successfully injecting the RUM Browser SDK into HTML pages, check the [NGINX error logs](https://nginx.org/en/docs/ngx_core_module.html#error_log) for relevant messages. The module logs important steps during the injection process. Confirm that NGINX is configured with at least the `INFO` log level with the following: ```javascript error_log info; ``` {% /tab %} {% tab title="Manual Instructions" %} Use this method if you cannot run the installation script or need full control over the NGINX configuration. ### Download the appropriate `.tgz` file{% #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. 1. Extract the tarball to extract the `ngx_http_datadog_module.so` file. Move it to a location that NGINX has access to (referenced as `` in the steps below). ### Update NGINX configuration{% #update-nginx-configuration %} 1. The `nginx.conf` file is usually located in NGINX's configuration directory. Add the following line to load the module: ```javascript load_module ; ``` 1. Then in the **http/server/location** section, add the following: ```javascript # APM Tracing is enabled by default. The following line disables APM Tracing. datadog_disable; datadog_rum on; datadog_rum_config "v5" { "applicationId" ""; "clientToken" ""; "site" ""; "service" "my-web-application"; "env" "production"; "version" "1.0.0"; "sessionSampleRate" "100"; "sessionReplaySampleRate" "100"; "trackResources" "true"; "trackLongTasks" "true"; "trackUserInteractions" "true"; } ``` ### Restart NGINX{% #restart-nginx %} 1. Restart the NGINX server to begin collecting data for your Datadog RUM application. By default, the RUM SDK is injected into all HTML documents. You may need to clear your browser cache. 1. (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. Confirm that NGINX is configured with at least the `INFO` log level with the following: ```javascript error_log info; ``` {% /tab %} ## Updating your RUM application{% #updating-your-rum-application %} You can update your RUM application settings at any time. From the [Application Management](https://app.datadoghq.com/rum/list) list, select your RUM application and navigate to the **SDK Configuration** page. Click **Save Changes** after making updates. ### Sampling rates{% #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{% #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 %} 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{% #source-types %} For each user attribute, select how the RUM SDK should extract the value: | Source | Description | Example | | -------------- | ----------------------------------------------------- | ------------------------------------------------- | | **JavaScript** | Read from a JavaScript variable on the page | `window.currentUser.id` or `dataLayer.user.email` | | **Cookie** | Read from a browser cookie | Cookie name: `user_session` | | **DOM** | Read from an HTML element's text content or attribute | CSS selector: `#user-id` or `[data-user-email]` | #### Regex extractor (optional){% #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{% #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{% #configuration %} Add the URLs of your backend services that you want to connect to RUM: | Field | Description | | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **URL** | The backend URL to trace. Use an exact URL (for example, `https://api.example.com`) or enable **Regex** for pattern matching (for example, `https://.*\.example\.com`). | | **Propagator Type** | The trace header format your backend expects. Options: `datadog`, `tracecontext` (W3C), `b3`, `b3multi`. Select multiple if needed. | {% alert level="info" %} Tracing requires a configured **service name**. Set this in the App Attributes section. {% /alert %} #### Learn more{% #learn-more %} See [Connect RUM and Traces](https://docs.datadoghq.com/real_user_monitoring/platform/connect_rum_and_traces.md) for detailed information about RUM and APM integration. ## Troubleshooting{% #troubleshooting %} ### NGINX stops responding{% #nginx-stops-responding %} If NGINX stops serving requests after installation, contact [Datadog support](https://docs.datadoghq.com/help) with the following information: - Your NGINX configuration file - Any relevant error logs ### RUM is not injected{% #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. ## Uninstall{% #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`. 1. At the beginning of the file, remove the line: `load_module /opt/datadog-nginx/ngx_http_datadog_module.so;`. 1. 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 } ``` 1. Delete the directory `/opt/datadog-nginx/` and all of its contents. 1. Restart or reload your NGINX web server. ## Reference{% #reference %} ### NGINX modules{% #nginx-modules %} | NGINX version | amd64 | arm 64 | | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | 1.25.0 | [ngx_http_datadog-amd64-1.25.0](https://rum-auto-instrumentation.s3.amazonaws.com/nginx/latest/ngx_http_datadog_module-amd64-1.25.0.so.tgz) | [ngx_http_datadog-arm64-1.25.0](https://rum-auto-instrumentation.s3.amazonaws.com/nginx/latest/ngx_http_datadog_module-arm64-1.25.0.so.tgz) | | 1.25.1 | [ngx_http_datadog-amd64-1.25.1](https://rum-auto-instrumentation.s3.amazonaws.com/nginx/latest/ngx_http_datadog_module-amd64-1.25.1.so.tgz) | [ngx_http_datadog-arm64-1.25.1](https://rum-auto-instrumentation.s3.amazonaws.com/nginx/latest/ngx_http_datadog_module-arm64-1.25.1.so.tgz) | | 1.25.2 | [ngx_http_datadog-amd64-1.25.2](https://rum-auto-instrumentation.s3.amazonaws.com/nginx/latest/ngx_http_datadog_module-amd64-1.25.2.so.tgz) | [ngx_http_datadog-arm64-1.25.2](https://rum-auto-instrumentation.s3.amazonaws.com/nginx/latest/ngx_http_datadog_module-arm64-1.25.2.so.tgz) | | 1.25.3 | [ngx_http_datadog-amd64-1.25.3](https://rum-auto-instrumentation.s3.amazonaws.com/nginx/latest/ngx_http_datadog_module-amd64-1.25.3.so.tgz) | [ngx_http_datadog-arm64-1.25.3](https://rum-auto-instrumentation.s3.amazonaws.com/nginx/latest/ngx_http_datadog_module-arm64-1.25.3.so.tgz) | | 1.25.4 | [ngx_http_datadog-amd64-1.25.4](https://rum-auto-instrumentation.s3.amazonaws.com/nginx/latest/ngx_http_datadog_module-amd64-1.25.4.so.tgz) | [ngx_http_datadog-arm64-1.25.4](https://rum-auto-instrumentation.s3.amazonaws.com/nginx/latest/ngx_http_datadog_module-arm64-1.25.4.so.tgz) | | 1.25.5 | [ngx_http_datadog-amd64-1.25.5](https://rum-auto-instrumentation.s3.amazonaws.com/nginx/latest/ngx_http_datadog_module-amd64-1.25.5.so.tgz) | [ngx_http_datadog-arm64-1.25.5](https://rum-auto-instrumentation.s3.amazonaws.com/nginx/latest/ngx_http_datadog_module-arm64-1.25.5.so.tgz) | | 1.26.0 | [ngx_http_datadog-amd64-1.26.0](https://rum-auto-instrumentation.s3.amazonaws.com/nginx/latest/ngx_http_datadog_module-amd64-1.26.0.so.tgz) | [ngx_http_datadog-arm64-1.26.0](https://rum-auto-instrumentation.s3.amazonaws.com/nginx/latest/ngx_http_datadog_module-arm64-1.26.0.so.tgz) | | 1.26.1 | [ngx_http_datadog-amd64-1.26.1](https://rum-auto-instrumentation.s3.amazonaws.com/nginx/latest/ngx_http_datadog_module-amd64-1.26.1.so.tgz) | [ngx_http_datadog-arm64-1.26.1](https://rum-auto-instrumentation.s3.amazonaws.com/nginx/latest/ngx_http_datadog_module-arm64-1.26.1.so.tgz) | | 1.26.2 | [ngx_http_datadog-amd64-1.26.2](https://rum-auto-instrumentation.s3.amazonaws.com/nginx/latest/ngx_http_datadog_module-amd64-1.26.2.so.tgz) | [ngx_http_datadog-arm64-1.26.2](https://rum-auto-instrumentation.s3.amazonaws.com/nginx/latest/ngx_http_datadog_module-arm64-1.26.2.so.tgz) | | 1.26.3 | [ngx_http_datadog-amd64-1.26.3](https://rum-auto-instrumentation.s3.amazonaws.com/nginx/latest/ngx_http_datadog_module-amd64-1.26.3.so.tgz) | [ngx_http_datadog-arm64-1.26.3](https://rum-auto-instrumentation.s3.amazonaws.com/nginx/latest/ngx_http_datadog_module-arm64-1.26.3.so.tgz) | | 1.27.0 | [ngx_http_datadog-amd64-1.27.0](https://rum-auto-instrumentation.s3.amazonaws.com/nginx/latest/ngx_http_datadog_module-amd64-1.27.0.so.tgz) | [ngx_http_datadog-arm64-1.27.0](https://rum-auto-instrumentation.s3.amazonaws.com/nginx/latest/ngx_http_datadog_module-arm64-1.27.0.so.tgz) | | 1.27.1 | [ngx_http_datadog-amd64-1.27.1](https://rum-auto-instrumentation.s3.amazonaws.com/nginx/latest/ngx_http_datadog_module-amd64-1.27.1.so.tgz) | [ngx_http_datadog-arm64-1.27.1](https://rum-auto-instrumentation.s3.amazonaws.com/nginx/latest/ngx_http_datadog_module-arm64-1.27.1.so.tgz) | | 1.27.2 | [ngx_http_datadog-amd64-1.27.2](https://rum-auto-instrumentation.s3.amazonaws.com/nginx/latest/ngx_http_datadog_module-amd64-1.27.2.so.tgz) | [ngx_http_datadog-arm64-1.27.2](https://rum-auto-instrumentation.s3.amazonaws.com/nginx/latest/ngx_http_datadog_module-arm64-1.27.2.so.tgz) | | 1.27.3 | [ngx_http_datadog-amd64-1.27.3](https://rum-auto-instrumentation.s3.amazonaws.com/nginx/latest/ngx_http_datadog_module-amd64-1.27.3.so.tgz) | [ngx_http_datadog-arm64-1.27.3](https://rum-auto-instrumentation.s3.amazonaws.com/nginx/latest/ngx_http_datadog_module-arm64-1.27.3.so.tgz) | | 1.27.4 | [ngx_http_datadog-amd64-1.27.4](https://rum-auto-instrumentation.s3.amazonaws.com/nginx/latest/ngx_http_datadog_module-amd64-1.27.4.so.tgz) | [ngx_http_datadog-arm64-1.27.4](https://rum-auto-instrumentation.s3.amazonaws.com/nginx/latest/ngx_http_datadog_module-arm64-1.27.4.so.tgz) | | 1.27.5 | [ngx_http_datadog-amd64-1.27.5](https://rum-auto-instrumentation.s3.amazonaws.com/nginx/latest/ngx_http_datadog_module-amd64-1.27.5.so.tgz) | [ngx_http_datadog-arm64-1.27.5](https://rum-auto-instrumentation.s3.amazonaws.com/nginx/latest/ngx_http_datadog_module-arm64-1.27.5.so.tgz) | | 1.28.0 | [ngx_http_datadog-amd64-1.28.0](https://rum-auto-instrumentation.s3.amazonaws.com/nginx/latest/ngx_http_datadog_module-amd64-1.28.0.so.tgz) | [ngx_http_datadog-arm64-1.28.0](https://rum-auto-instrumentation.s3.amazonaws.com/nginx/latest/ngx_http_datadog_module-arm64-1.28.0.so.tgz) | | 1.28.1 | [ngx_http_datadog-amd64-1.28.1](https://rum-auto-instrumentation.s3.amazonaws.com/nginx/latest/ngx_http_datadog_module-amd64-1.28.1.so.tgz) | [ngx_http_datadog-arm64-1.28.1](https://rum-auto-instrumentation.s3.amazonaws.com/nginx/latest/ngx_http_datadog_module-arm64-1.28.1.so.tgz) | | 1.28.2 | [ngx_http_datadog-amd64-1.28.2](https://rum-auto-instrumentation.s3.amazonaws.com/nginx/latest/ngx_http_datadog_module-amd64-1.28.2.so.tgz) | [ngx_http_datadog-arm64-1.28.2](https://rum-auto-instrumentation.s3.amazonaws.com/nginx/latest/ngx_http_datadog_module-arm64-1.28.2.so.tgz) | | 1.28.3 | [ngx_http_datadog-amd64-1.28.3](https://rum-auto-instrumentation.s3.amazonaws.com/nginx/latest/ngx_http_datadog_module-amd64-1.28.3.so.tgz) | [ngx_http_datadog-arm64-1.28.3](https://rum-auto-instrumentation.s3.amazonaws.com/nginx/latest/ngx_http_datadog_module-arm64-1.28.3.so.tgz) | | 1.29.0 | [ngx_http_datadog-amd64-1.29.0](https://rum-auto-instrumentation.s3.amazonaws.com/nginx/latest/ngx_http_datadog_module-amd64-1.29.0.so.tgz) | [ngx_http_datadog-arm64-1.29.0](https://rum-auto-instrumentation.s3.amazonaws.com/nginx/latest/ngx_http_datadog_module-arm64-1.29.0.so.tgz) | | 1.29.1 | [ngx_http_datadog-amd64-1.29.1](https://rum-auto-instrumentation.s3.amazonaws.com/nginx/latest/ngx_http_datadog_module-amd64-1.29.1.so.tgz) | [ngx_http_datadog-arm64-1.29.1](https://rum-auto-instrumentation.s3.amazonaws.com/nginx/latest/ngx_http_datadog_module-arm64-1.29.1.so.tgz) | | 1.29.2 | [ngx_http_datadog-amd64-1.29.2](https://rum-auto-instrumentation.s3.amazonaws.com/nginx/latest/ngx_http_datadog_module-amd64-1.29.2.so.tgz) | [ngx_http_datadog-arm64-1.29.2](https://rum-auto-instrumentation.s3.amazonaws.com/nginx/latest/ngx_http_datadog_module-arm64-1.29.2.so.tgz) | | 1.29.3 | [ngx_http_datadog-amd64-1.29.3](https://rum-auto-instrumentation.s3.amazonaws.com/nginx/latest/ngx_http_datadog_module-amd64-1.29.3.so.tgz) | [ngx_http_datadog-arm64-1.29.3](https://rum-auto-instrumentation.s3.amazonaws.com/nginx/latest/ngx_http_datadog_module-arm64-1.29.3.so.tgz) | | 1.29.4 | [ngx_http_datadog-amd64-1.29.4](https://rum-auto-instrumentation.s3.amazonaws.com/nginx/latest/ngx_http_datadog_module-amd64-1.29.4.so.tgz) | [ngx_http_datadog-arm64-1.29.4](https://rum-auto-instrumentation.s3.amazonaws.com/nginx/latest/ngx_http_datadog_module-arm64-1.29.4.so.tgz) | | 1.29.5 | [ngx_http_datadog-amd64-1.29.5](https://rum-auto-instrumentation.s3.amazonaws.com/nginx/latest/ngx_http_datadog_module-amd64-1.29.5.so.tgz) | [ngx_http_datadog-arm64-1.29.5](https://rum-auto-instrumentation.s3.amazonaws.com/nginx/latest/ngx_http_datadog_module-arm64-1.29.5.so.tgz) | | 1.29.6 | [ngx_http_datadog-amd64-1.29.6](https://rum-auto-instrumentation.s3.amazonaws.com/nginx/latest/ngx_http_datadog_module-amd64-1.29.6.so.tgz) | [ngx_http_datadog-arm64-1.29.6](https://rum-auto-instrumentation.s3.amazonaws.com/nginx/latest/ngx_http_datadog_module-arm64-1.29.6.so.tgz) | | 1.29.7 | [ngx_http_datadog-amd64-1.29.7](https://rum-auto-instrumentation.s3.amazonaws.com/nginx/latest/ngx_http_datadog_module-amd64-1.29.7.so.tgz) | [ngx_http_datadog-arm64-1.29.7](https://rum-auto-instrumentation.s3.amazonaws.com/nginx/latest/ngx_http_datadog_module-arm64-1.29.7.so.tgz) | | 1.29.8 | [ngx_http_datadog-amd64-1.29.8](https://rum-auto-instrumentation.s3.amazonaws.com/nginx/latest/ngx_http_datadog_module-amd64-1.29.8.so.tgz) | [ngx_http_datadog-arm64-1.29.8](https://rum-auto-instrumentation.s3.amazonaws.com/nginx/latest/ngx_http_datadog_module-arm64-1.29.8.so.tgz) | | 1.30.0 | [ngx_http_datadog-amd64-1.30.0](https://rum-auto-instrumentation.s3.amazonaws.com/nginx/latest/ngx_http_datadog_module-amd64-1.30.0.so.tgz) | [ngx_http_datadog-arm64-1.30.0](https://rum-auto-instrumentation.s3.amazonaws.com/nginx/latest/ngx_http_datadog_module-arm64-1.30.0.so.tgz) | ## Further reading{% #further-reading %} - [Browser Monitoring Auto-Instrumentation](https://docs.datadoghq.com/real_user_monitoring/application_monitoring/browser/setup/server.md)