This is the CloudWatch RUM React client source code repository. It hosts a React library which performs real user monitoring (RUM) telemetry on web applications. Data collected by the RUM React client includes page load timing, JavaScript errors, and HTTP requests.
aws-rum-react
is an open source, community-driven package for
aws-rum-web
. It is neither
created nor vended by Amazon or Amazon CloudWatch.
The CloudWatch RUM React client can be built into the application's JavaScript bundle using the provided CommonJS or ECMAScript modules. The recommended method to consume and manage the React client dependency is to use the React client's Node module.
npm install --save aws-rum-react aws-rum-web
# or
yarn add aws-rum-react aws-rum-web
The following code shows an example of how to instrument an application. This component should wrap as much of the application as possible.
import { AwsRumProvider } from 'aws-rum-react';
import { StrictMode } from 'react';
import ROOT from './constants/root';
import App from './features/app';
ROOT.render(
<StrictMode>
<AwsRumProvider
allowCookies
endpoint="https://dataplane.rum.us-west-2.amazonaws.com"
guestRoleArn="arn:aws:iam::000000000000:role/RUM-Monitor-us-west-2-000000000000-00xx-Unauth"
id="00000000-0000-0000-0000-000000000000"
identityPoolId="us-west-2:00000000-0000-0000-0000-000000000000"
region="us-west-2"
sessionSampleRate={1}
telemetries={['errors', 'performance']}
version="1.0.0"
>
<App />
</AwsRumProvider>
</StrictMode>,
);
Modify the AwsRumProvider
component props to match your AppMonitor. See
Props for details.
Prop name | Type | Description |
---|---|---|
id |
string | a globally unique ID for the AppMonitor |
region |
string | the AWS region of the AppMonitor |
version |
string | the application's semantic version |
You may pass any application-specific React client configuration as additional
props which are all optional. While these fields are optional, depending on your
application, the React client may not function properly if certain fields are
omitted. For example, guestRoleArn
and identityPoolId
are both required
unless your application performs its own AWS authentication and passes the
credentials to the web client using the command setAwsCredentials(...)
.
To get started, we recommend the props in the above sample. The guestRoleArn
and identityPoolId
shown are dummy values. Modify these to match the resources
created when setting up the AppMonitor:
For a complete list of configuration options, see Application-specific Configurations.
You can use hooks to interact with the RUM client directly.
You may access the Amazon CloudWatch RUM client directly, though it's not recommended. This hook is provided to unblock you in edge cases where custom functionality is desired.
import { useAwsRum } from 'aws-rum-react';
function MyComponent() {
// Access the client directly (not recommended).
const client = useAwsRum();
const handleDisable = useCallback(() => {
client.disable();
}, [client]);
const handleEnable = useCallback(() => {
client.enable();
}, [client]);
// ...
}
You may access the recordError
method via the useRecordError
hook.
import { useRecordError } from 'aws-rum-react';
function MyComponent() {
// Record an error.
const recordError = useRecordError();
const [error, setError] = useState(null);
useEffect(() => {
if (error !== null) {
recordError(error);
}
}, [error, recordError]);
// ...
}
You may access the recordEvent
method via the useRecordEvent
hook.
import { useRecordEvent } from 'aws-rum-react';
function MyComponent({ onSubmit }) {
// Record an event.
const recordEvent = useRecordEvent();
const [state, setState] = useState({});
const handleSubmit = useCallback(() => {
onSubmit(state);
recordEvent('MySubmitEvent', state);
}, [recordEvent]);
// ...
}
You may access the recordPageView
API via the useRecordPageView
hook.
import { useRecordPageView } from 'aws-rum-react';
function MyComponent() {
// Record a page view.
const recordPageView = useRecordPageView();
const pageAttributes = usePageAttributes();
useEffect(() => {
recordPageView(pageAttributes);
}, [pageAttributes, recordPageView]);
// ...
}
You may use the withAwsRum
HOC and withRecordError
HOC to access the AWS RUM
instance and the recordError
utility function respectively.
This is particularly useful for mounting your Error Boundaries.
import { withRecordError } from 'aws-rum-react';
import { PureComponent } from 'react';
interface Props {
readonly recordError: (error: unknown) => void;
}
class ErrorBoundary extends PureComponent<Props> {
public componentDidCatch(err: Error): void {
this.props.recordError(err);
}
}
export default withRecordError(ErrorBoundary);
When writing unit tests, a real client cannot be instantiated. You may use the utility provider as demonstrated below.
// MyComponent.ts
import { useRecordError } from 'aws-rum-react';
import { useEffect } from 'react';
function MyComponent(): null {
const recordError = useRecordError();
useEffect((): void => {
recordError('Hello world!');
}, [recordError]);
return null;
}
// MyComponent.test.ts
import { render } from '@testing-library/react';
import { MockAwsRumProvider } from 'aws-rum-react';
import type { PropsWithChildren, ReactElement } from 'react';
import { vi } from 'vitest';
import MyComponent from './MyComponent';
describe('MyComponent', (): void => {
it('should record an error', (): void => {
const TEST_RECORD_ERROR = vi.fn();
render(<MyComponent />, {
wrapper({ children }: PropsWithChildren): ReactElement {
return (
<MockAwsRumProvider recordError={TEST_RECORD_ERROR}>
{children}
</MockAwsRumProvider>
);
},
});
expect(TEST_RECORD_ERROR).toHaveBeenCalledTimes(1);
expect(TEST_RECORD_ERROR).toHaveBeenLastCalledWith('Hello world!');
});
});
Use the following community resources for getting help with the SDK. We use the GitHub issues for tracking bugs and feature requests.
- View the CloudWatch RUM documentation.
- Ask a question in the Amazon CloudWatch forum.
- Open a support ticket with AWS Support.
- If you think you may have found a bug:
- open an issue with
aws-rum-react
, or - open an issue with
aws-rum-web
.
- open an issue with
We support and accept pull requests from the community.
See CONTRIBUTING.