Skip to content

Commit c541b98

Browse files
upmanupman
committed
docs: add HyperDX RUM configuration guide
1 parent 8670c91 commit c541b98

3 files changed

Lines changed: 239 additions & 0 deletions

File tree

‎content/docs/configuration/dotenv.mdx‎

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -345,6 +345,83 @@ Note:
345345

346346
Note: `DEBUG_CONSOLE` is not recommended, as the outputs can be quite verbose, and so it's disabled by default.
347347

348+
### Real User Monitoring (Browser)
349+
350+
Browser-side Real User Monitoring (RUM) can send frontend performance and interaction telemetry to HyperDX. RUM is disabled by default. See [Real User Monitoring](/docs/configuration/rum) for setup guidance, authentication modes, trace propagation, and privacy controls.
351+
352+
<OptionTable
353+
options={[
354+
['RUM_ENABLED', 'boolean', 'Enable browser Real User Monitoring.', 'RUM_ENABLED=false'],
355+
[
356+
'RUM_PROVIDER',
357+
'string',
358+
'RUM provider. Currently supports `hyperdx`.',
359+
'RUM_PROVIDER=hyperdx',
360+
],
361+
[
362+
'RUM_URL',
363+
'string',
364+
'OTLP HTTP ingest URL for browser telemetry.',
365+
'RUM_URL=http://localhost:4318',
366+
],
367+
[
368+
'RUM_SERVICE_NAME',
369+
'string',
370+
'Service name attached to browser telemetry.',
371+
'RUM_SERVICE_NAME=librechat-web',
372+
],
373+
[
374+
'RUM_ENVIRONMENT',
375+
'string',
376+
'Environment name attached to browser telemetry.',
377+
'RUM_ENVIRONMENT=production',
378+
],
379+
[
380+
'RUM_AUTH_MODE',
381+
'string',
382+
'Authentication mode for browser telemetry: `publicToken` or `userJwt`.',
383+
'RUM_AUTH_MODE=publicToken',
384+
],
385+
[
386+
'RUM_PUBLIC_TOKEN',
387+
'string',
388+
'Browser-safe ingest token used when `RUM_AUTH_MODE=publicToken`.',
389+
'RUM_PUBLIC_TOKEN=your-browser-ingest-token',
390+
],
391+
[
392+
'RUM_AUTH_HEADER_SCHEME',
393+
'string',
394+
'Authorization header scheme used with `userJwt` mode.',
395+
'RUM_AUTH_HEADER_SCHEME=Bearer',
396+
],
397+
[
398+
'RUM_TRACE_PROPAGATION_TARGETS',
399+
'string',
400+
'Comma-separated HTTPS origins or URL prefixes that should receive browser trace context headers.',
401+
'RUM_TRACE_PROPAGATION_TARGETS=https://api.example.com',
402+
],
403+
['RUM_DISABLE_REPLAY', 'boolean', 'Disable session replay capture.', 'RUM_DISABLE_REPLAY=true'],
404+
[
405+
'RUM_CONSOLE_CAPTURE',
406+
'boolean',
407+
'Enable browser console capture. Disabled by default.',
408+
'RUM_CONSOLE_CAPTURE=false',
409+
],
410+
[
411+
'RUM_ADVANCED_NETWORK_CAPTURE',
412+
'boolean',
413+
'Enable advanced network capture. Disabled by default.',
414+
'RUM_ADVANCED_NETWORK_CAPTURE=false',
415+
],
416+
[
417+
'RUM_SAMPLE_RATE',
418+
'number',
419+
'Client-side RUM sample rate between 0 and 1.',
420+
'RUM_SAMPLE_RATE=1',
421+
],
422+
]}
423+
/>
424+
348425
### Permission
349426

350427
> UID and GID are numbers assigned by Linux to each user and group on the system. If you have permission problems, set here the UID and GID of the user running the Docker Compose command. The applications in the container will run with these UID/GID.

‎content/docs/configuration/meta.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,7 @@
2020
"mod_system",
2121
"langfuse",
2222
"logging",
23+
"rum",
2324
"metrics",
2425
"meilisearch",
2526
"---UI---",

‎content/docs/configuration/rum.mdx‎

Lines changed: 161 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,161 @@
1+
---
2+
title: Real User Monitoring
3+
icon: Activity
4+
description: Configure browser-side real user monitoring for LibreChat.
5+
---
6+
7+
Real User Monitoring (RUM) sends browser performance and interaction telemetry to an observability backend. LibreChat supports HyperDX through the browser startup configuration served by the API.
8+
9+
RUM is disabled by default. Enable it only after you have chosen an ingest endpoint and authentication mode.
10+
11+
## HyperDX Setup
12+
13+
For a local HyperDX collector, use:
14+
15+
```bash filename=".env"
16+
RUM_ENABLED=true
17+
RUM_PROVIDER=hyperdx
18+
RUM_URL=http://localhost:4318
19+
RUM_SERVICE_NAME=librechat-web
20+
RUM_ENVIRONMENT=development
21+
RUM_AUTH_MODE=publicToken
22+
RUM_PUBLIC_TOKEN=local-dev-token
23+
```
24+
25+
For hosted or production collectors, use an HTTPS collector URL:
26+
27+
```bash filename=".env"
28+
RUM_ENABLED=true
29+
RUM_PROVIDER=hyperdx
30+
RUM_URL=https://rum.example.com/v1/traces
31+
RUM_SERVICE_NAME=librechat-web
32+
RUM_ENVIRONMENT=production
33+
```
34+
35+
## Authentication Modes
36+
37+
### Public Token
38+
39+
Use `publicToken` when your collector expects a browser-safe ingest token:
40+
41+
```bash filename=".env"
42+
RUM_AUTH_MODE=publicToken
43+
RUM_PUBLIC_TOKEN=your-browser-ingest-token
44+
```
45+
46+
This is the easiest mode for OSS deployments because it does not depend on LibreChat user authentication.
47+
48+
### User JWT
49+
50+
Use `userJwt` when your collector is behind infrastructure that accepts the current LibreChat user JWT:
51+
52+
```bash filename=".env"
53+
RUM_AUTH_MODE=userJwt
54+
RUM_AUTH_HEADER_SCHEME=Bearer
55+
RUM_URL=https://rum.example.com/otlp/v1/traces
56+
```
57+
58+
When `userJwt` is used, LibreChat only returns the RUM config to authenticated users. The user JWT is attached only to requests sent to the configured `RUM_URL`, so use this mode only with a trusted HTTPS collector endpoint.
59+
60+
## Trace Propagation
61+
62+
You can opt in to browser trace context propagation for your own HTTPS services:
63+
64+
```bash filename=".env"
65+
RUM_TRACE_PROPAGATION_TARGETS=https://api.example.com,https://gateway.example.com
66+
```
67+
68+
Do not add third-party AI provider APIs to this list. LibreChat filters unsafe targets to avoid propagating browser trace headers to model providers.
69+
70+
## Privacy Controls
71+
72+
RUM uses conservative defaults:
73+
74+
- Session replay is disabled by default.
75+
- Console capture is disabled by default.
76+
- Advanced network capture is disabled by default.
77+
- User attributes avoid names, emails, prompts, and message content.
78+
79+
You can override these defaults if your deployment has appropriate consent and data-handling controls:
80+
81+
```bash filename=".env"
82+
RUM_DISABLE_REPLAY=true
83+
RUM_CONSOLE_CAPTURE=false
84+
RUM_ADVANCED_NETWORK_CAPTURE=false
85+
RUM_SAMPLE_RATE=1
86+
```
87+
88+
## Environment Variables
89+
90+
<OptionTable
91+
options={[
92+
['RUM_ENABLED', 'boolean', 'Enable browser Real User Monitoring.', 'RUM_ENABLED=false'],
93+
[
94+
'RUM_PROVIDER',
95+
'string',
96+
'RUM provider. Currently supports `hyperdx`.',
97+
'RUM_PROVIDER=hyperdx',
98+
],
99+
[
100+
'RUM_URL',
101+
'string',
102+
'OTLP HTTP ingest URL for browser telemetry.',
103+
'RUM_URL=http://localhost:4318',
104+
],
105+
[
106+
'RUM_SERVICE_NAME',
107+
'string',
108+
'Service name attached to browser telemetry.',
109+
'RUM_SERVICE_NAME=librechat-web',
110+
],
111+
[
112+
'RUM_ENVIRONMENT',
113+
'string',
114+
'Environment name attached to browser telemetry.',
115+
'RUM_ENVIRONMENT=production',
116+
],
117+
[
118+
'RUM_AUTH_MODE',
119+
'string',
120+
'Authentication mode for browser telemetry: `publicToken` or `userJwt`.',
121+
'RUM_AUTH_MODE=publicToken',
122+
],
123+
[
124+
'RUM_PUBLIC_TOKEN',
125+
'string',
126+
'Browser-safe ingest token used when `RUM_AUTH_MODE=publicToken`.',
127+
'RUM_PUBLIC_TOKEN=your-browser-ingest-token',
128+
],
129+
[
130+
'RUM_AUTH_HEADER_SCHEME',
131+
'string',
132+
'Authorization header scheme used with `userJwt` mode.',
133+
'RUM_AUTH_HEADER_SCHEME=Bearer',
134+
],
135+
[
136+
'RUM_TRACE_PROPAGATION_TARGETS',
137+
'string',
138+
'Comma-separated HTTPS origins or URL prefixes that should receive browser trace context headers.',
139+
'RUM_TRACE_PROPAGATION_TARGETS=https://api.example.com',
140+
],
141+
['RUM_DISABLE_REPLAY', 'boolean', 'Disable session replay capture.', 'RUM_DISABLE_REPLAY=true'],
142+
[
143+
'RUM_CONSOLE_CAPTURE',
144+
'boolean',
145+
'Enable browser console capture. Disabled by default.',
146+
'RUM_CONSOLE_CAPTURE=false',
147+
],
148+
[
149+
'RUM_ADVANCED_NETWORK_CAPTURE',
150+
'boolean',
151+
'Enable advanced network capture. Disabled by default.',
152+
'RUM_ADVANCED_NETWORK_CAPTURE=false',
153+
],
154+
[
155+
'RUM_SAMPLE_RATE',
156+
'number',
157+
'Client-side RUM sample rate between 0 and 1.',
158+
'RUM_SAMPLE_RATE=1',
159+
],
160+
]}
161+
/>

0 commit comments

Comments
 (0)