Skip to content

Adapt RUM server onboarding to include httpd #27435

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 9 commits into from
Feb 20, 2025
Merged

Adapt RUM server onboarding to include httpd #27435

Changes from all commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
bd5e9bf
Adapt RUM server onboarding to include httpd
pablomartinezbernardo Feb 4, 2025
c4e8f75
Annotation about specific parameters for all proxies
pablomartinezbernardo Feb 11, 2025
4ddd9e9
Remove redundancy for web server limitation
rtrieu Feb 12, 2025
6e414d2
Update content/en/real_user_monitoring/browser/setup/server.md
pablomartinezbernardo Feb 14, 2025
2beb895
Update content/en/real_user_monitoring/browser/setup/server.md
pablomartinezbernardo Feb 14, 2025
9fda97a
Remove confusing line
pablomartinezbernardo Feb 17, 2025
4a36228
Apply suggestions from code review
pablomartinezbernardo Feb 17, 2025
81f533b
Update content/en/real_user_monitoring/browser/setup/server.md
pablomartinezbernardo Feb 18, 2025
11709c2
Apply suggestions from code review
rtrieu Feb 20, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
128 changes: 106 additions & 22 deletions content/en/real_user_monitoring/browser/setup/server.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,8 +28,10 @@
The available functionality has the following important limitations:

- If proxying compressed traffic, the Auto-Instrumentation method is not able to inject the JS scriptlet into the HTML traffic.
- This instrumentation method does not support any [advanced RUM configurations][3]. However, `allowedTracingUrls` and `excludedActivityUrls` are supported for NGINX web servers.
- If NGINX or IIS is acting as a proxy and the upstream server has end-to-end encryption (like TLS) enabled, the module cannot inject RUM. Ensure the web server is set up for TLS origination for successful instrumentation.
- This instrumentation method does not support any [advanced RUM configurations][3]. However, `allowedTracingUrls` and `excludedActivityUrls` are supported.
- If the web server is acting as a proxy and the upstream server has end-to-end encryption (like TLS) or content compression (like gzip, zstd, or Brotli) enabled, the module may not inject the RUM Browser SDK. Ensure the following for successful instrumentation:
- Content compression is disabled on the upstream server.
- The web server is set up for TLS origination.
- (Windows IIS only) Configuration for Auto-Instrumentation is only available per Windows IIS site.

## Prerequisites
Expand All @@ -43,7 +45,7 @@
{{< tabs >}}
{{% tab "NGINX" %}}

The Auto-Instrumentation method leverages the [NGINX Dynamic Modules capability][1] to implement a response body filter. The filter injects the RUM SDK into the response body for responses
The Auto-Instrumentation method leverages the [NGINX Dynamic Modules capability][1] to implement a response body filter. The filter injects the RUM Browser SDK into the response body for responses
identified as HTML. For more granular control over how configuration files or permissions are handled, you can also install NGINX manually.

[1]: https://docs.nginx.com/nginx/admin-guide/dynamic-modules/dynamic-modules/
Expand Down Expand Up @@ -115,6 +117,75 @@

{{% /collapse-content %}}

{{% /tab %}}
{{% tab "Apache HTTP Server" %}}

The Auto-Instrumentation method leverages the [Apache httpd Modules capability][1] to implement a response body filter. The filter injects the RUM Browser SDK into the response body for responses
identified as HTML. For more granular control over how configuration files or permissions are handled, you can also install the module manually.

[1]: https://httpd.apache.org/modules/


{{% collapse-content title="Automatic installation (recommended)" level="h5" %}}

To automatically instrument your RUM application:

1. In Datadog, navigate to the [**Digital Experience > Add an Application Page**][1] and select the JavaScript (JS) application type.
2. Select **Auto-Instrumentation** and **httpd**.
3. Set your Session and Session Replay sample rates. See [guidance on configuring sampling][2].
4. Copy and run the installer command to load the Datadog httpd Module with the RUM SDK Injector onto httpd.
5. After the installer successfully installs the SDK Injector, restart Apache HTTP Server to begin collecting RUM sessions.
6. (Optional) To verify the module is successfully injecting the RUM Browser SDK into HTML pages, check the error logs for relevant messages. The module logs important steps during the injection process. Ensure that Apache HTTP Server is configured with at least the `info` log level.

[1]: https://app.datadoghq.com/rum/list
[2]: /real_user_monitoring/guide/sampling-browser-plans/

{{% /collapse-content %}}

{{% collapse-content title="Manual configuration" level="h5" %}}

### Download the module file

1. Download the [zipped module][1].
2. Extract the zip to obtain the `mod_datadog.so` file. Move it to a location that Apache HTTP Server has access to (referenced as `<RUM_MODULE_PATH>` in the steps below).

[1]: https://rum-auto-instrumentation.s3.amazonaws.com/httpd/latest/mod_datadog-amd64.zip

### Update Apache HTTP server configuration

Check warning on line 154 in content/en/real_user_monitoring/browser/setup/server.md

View workflow job for this annotation

GitHub Actions / vale

Datadog.headings 

'Update Apache HTTP server configuration' should use sentence-style capitalization.
1. Locate the configuration file. You can use `apachectl -V` to find the default configuration path. Add the following line to load the module:

```javascript
LoadModule datadog_module <RUM_MODULE_PATH>
```

2. Within the appropriate **root or location** section, add the following:

```javascript
# APM Tracing is enabled by default. The following line disables APM Tracing
DatadogTracing Off
DatadogRum On
<DatadogRumSettings>
DatadogRumOption "applicationId" "<DATADOG_APPLICATION_ID>"
DatadogRumOption "clientToken" "<DATADOG_CLIENT_TOKEN>"
DatadogRumOption "site" "<DATADOG_SITE>"
DatadogRumOption "service" "my-web-application"
DatadogRumOption "env" "production"
DatadogRumOption "version" "1.0.0"
DatadogRumOption "sessionSampleRate" "100"
DatadogRumOption "sessionReplaySampleRate" "100"
DatadogRumOption "trackResources" "true"
DatadogRumOption "trackLongTasks" "true"
DatadogRumOption "trackUserInteractions" "true"
</DatadogRumSettings>
```

### Restart your server

1. Restart the Apache HTTP 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 httpd error logs for relevant messages. The module logs important steps during the injection process. Ensure that Apache HTTP Server is configured with at least the `info` log level.

{{% /collapse-content %}}

{{% /tab %}}
{{% tab "Windows IIS" %}}

Expand Down Expand Up @@ -162,7 +233,19 @@

1. Go to your RUM application from the [Application Management][1] list.
2. On the Instrument your application page, adjust the slider or enter a specific percentage in the input box for Session Sampling or Session Replay Sampling.
3. Copy and run the installer command in your `NGINX.conf` file.
3. Copy and paste the configuration snippet to your `NGINX.conf` file.

[1]: https://app.datadoghq.com/rum/list

{{% /tab %}}

{{% tab "Apache HTTP Server" %}}

To update your RUM Application:

1. Go to your RUM application from the [Application Management][1] list.
2. On the Instrument your application page, adjust the slider or enter a specific percentage in the input box for Session Sampling or Session Replay Sampling.
3. Copy and paste the configuration snippet to your `/opt/datadog-httpd/datadog.conf` file.

[1]: https://app.datadoghq.com/rum/list

Expand Down Expand Up @@ -195,7 +278,7 @@
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.
- **Content compression by upstream server**: If NGINX is acting as a proxy and the upstream server has content compression (like gzip, zstd, or Brotli) enabled, the module may not inject RUM. Ensure that content compression is disabled on the upstream server and configure NGINX to compress the content.
- **Upstream server has end-to-end encryption or content compression**: See [Limitations][41].

## Reference

Expand All @@ -205,22 +288,22 @@
|---------------|-------|--------|
| 1.22.0 | [ngx_http_datadog-amd64-1.22.0][5] | [ngx_http_datadog-arm64-1.22.0][6] |
| 1.22.1 | [ngx_http_datadog-amd64-1.22.1][7] | [ngx_http_datadog-arm64-1.22.1][8] |
| 1.23.0 | [ngx_http_datadog-amd64-1.23.0][9] | [ngx_http_datadog-arm64-1.23.0][10] |
| 1.23.1 | [ngx_http_datadog-amd64-1.23.1][11] | [ngx_http_datadog-arm64-1.23.1][12] |
| 1.23.2 | [ngx_http_datadog-amd64-1.23.2][13] | [ngx_http_datadog-arm64-1.23.2][14] |
| 1.23.3 | [ngx_http_datadog-amd64-1.23.3][15] | [ngx_http_datadog-arm64-1.23.3][16] |
| 1.23.4 | [ngx_http_datadog-amd64-1.23.4][17] | [ngx_http_datadog-arm64-1.23.4][18] |
| 1.24.0 | [ngx_http_datadog-amd64-1.24.0][19] | [ngx_http_datadog-arm64-1.24.0][20] |
| 1.25.0 | [ngx_http_datadog-amd64-1.25.0][21] | [ngx_http_datadog-arm64-1.25.0][22] |
| 1.25.1 | [ngx_http_datadog-amd64-1.25.1][23] | [ngx_http_datadog-arm64-1.25.1][24] |
| 1.25.2 | [ngx_http_datadog-amd64-1.25.2][25] | [ngx_http_datadog-arm64-1.25.2][26] |
| 1.25.3 | [ngx_http_datadog-amd64-1.25.3][27] | [ngx_http_datadog-arm64-1.25.3][28] |
| 1.25.4 | [ngx_http_datadog-amd64-1.25.4][29] | [ngx_http_datadog-arm64-1.25.4][30] |
| 1.25.5 | [ngx_http_datadog-amd64-1.25.5][31] | [ngx_http_datadog-arm64-1.25.5][32] |
| 1.26.0 | [ngx_http_datadog-amd64-1.26.0][33] | [ngx_http_datadog-arm64-1.26.0][34] |
| 1.26.1 | [ngx_http_datadog-amd64-1.26.1][35] | [ngx_http_datadog-arm64-1.26.1][36] |
| 1.26.2 | [ngx_http_datadog-amd64-1.26.2][37] | [ngx_http_datadog-arm64-1.26.2][38] |
| 1.27.0 | [ngx_http_datadog-amd64-1.27.0][39] | [ngx_http_datadog-arm64-1.27.0][40] |
| 1.23.0 | [ngx_http_datadog-amd64-1.23.0][9] | [ngx_http_datadog-arm64-1.23.0][10] |
| 1.23.1 | [ngx_http_datadog-amd64-1.23.1][11] | [ngx_http_datadog-arm64-1.23.1][12] |
| 1.23.2 | [ngx_http_datadog-amd64-1.23.2][13] | [ngx_http_datadog-arm64-1.23.2][14] |
| 1.23.3 | [ngx_http_datadog-amd64-1.23.3][15] | [ngx_http_datadog-arm64-1.23.3][16] |
| 1.23.4 | [ngx_http_datadog-amd64-1.23.4][17] | [ngx_http_datadog-arm64-1.23.4][18] |
| 1.24.0 | [ngx_http_datadog-amd64-1.24.0][19] | [ngx_http_datadog-arm64-1.24.0][20] |
| 1.25.0 | [ngx_http_datadog-amd64-1.25.0][21] | [ngx_http_datadog-arm64-1.25.0][22] |
| 1.25.1 | [ngx_http_datadog-amd64-1.25.1][23] | [ngx_http_datadog-arm64-1.25.1][24] |
| 1.25.2 | [ngx_http_datadog-amd64-1.25.2][25] | [ngx_http_datadog-arm64-1.25.2][26] |
| 1.25.3 | [ngx_http_datadog-amd64-1.25.3][27] | [ngx_http_datadog-arm64-1.25.3][28] |
| 1.25.4 | [ngx_http_datadog-amd64-1.25.4][29] | [ngx_http_datadog-arm64-1.25.4][30] |
| 1.25.5 | [ngx_http_datadog-amd64-1.25.5][31] | [ngx_http_datadog-arm64-1.25.5][32] |
| 1.26.0 | [ngx_http_datadog-amd64-1.26.0][33] | [ngx_http_datadog-arm64-1.26.0][34] |
| 1.26.1 | [ngx_http_datadog-amd64-1.26.1][35] | [ngx_http_datadog-arm64-1.26.1][36] |
| 1.26.2 | [ngx_http_datadog-amd64-1.26.2][37] | [ngx_http_datadog-arm64-1.26.2][38] |
| 1.27.0 | [ngx_http_datadog-amd64-1.27.0][39] | [ngx_http_datadog-arm64-1.27.0][40] |

## Further reading

Expand Down Expand Up @@ -265,4 +348,5 @@
[37]: https://ddagent-windows-unstable.s3.amazonaws.com/inject-browser-sdk/nginx/latest/ngx_http_datadog_module-amd64-1.26.2.so.tgz
[38]: https://ddagent-windows-unstable.s3.amazonaws.com/inject-browser-sdk/nginx/latest/ngx_http_datadog_module-arm64-1.26.2.so.tgz
[39]: https://ddagent-windows-unstable.s3.amazonaws.com/inject-browser-sdk/nginx/latest/ngx_http_datadog_module-amd64-1.27.0.so.tgz
[40]: https://ddagent-windows-unstable.s3.amazonaws.com/inject-browser-sdk/nginx/latest/ngx_http_datadog_module-arm64-1.27.0.so.tgz
[40]: https://ddagent-windows-unstable.s3.amazonaws.com/inject-browser-sdk/nginx/latest/ngx_http_datadog_module-arm64-1.27.0.so.tgz
[41]: /real_user_monitoring/browser/setup/server/#limitations
Loading