Skip to content

Latest commit

 

History

History
81 lines (63 loc) · 3.45 KB

npm_installation.md

File metadata and controls

81 lines (63 loc) · 3.45 KB
Raw

Installing as a JavaScript Module

The CloudWatch RUM web client can be built into the application's JavaScript bundle using the provided CommonJS or ES modules. The recommended method to consume and manage the web client dependency is to use the web client's NPM package.

Install the package from NPM

npm install --save aws-rum-web

Instrument the application

The following code shows an example of how to instrument an application. This code should run as early as possible in the application's lifecycle.

import { AwsRum, AwsRumConfig } from 'aws-rum-web';

try {
  const config: AwsRumConfig = {
    allowCookies: true,
    endpoint: "https://dataplane.rum.us-west-2.amazonaws.com",
    guestRoleArn: "arn:aws:iam::000000000000:role/RUM-Monitor-us-west-2-000000000000-00xx-Unauth",
    identityPoolId: "us-west-2:00000000-0000-0000-0000-000000000000",
    sessionSampleRate: 1,
    telemetries: ['errors', 'performance']
  };

  const APPLICATION_ID: string = '00000000-0000-0000-0000-000000000000';
  const APPLICATION_VERSION: string = '1.0.0';
  const APPLICATION_REGION: string = 'us-west-2';

  const awsRum: AwsRum = new AwsRum(
    APPLICATION_ID,
    APPLICATION_VERSION,
    APPLICATION_REGION,
    config
  );
} catch (error) {
  // Ignore errors thrown during CloudWatch RUM web client initialization
}

Modify the AwsRum constructor arguments to match your AppMonitor. See Arguments for details.

Modify the config object to configure how the web client should behave. For example, you should minimally configure (1) how the data will be authenticated, and (2) what aspects of the application will be monitored. See Configuration for details.

Arguments

Argument Name Type Description
AppMonitor ID String A globally unique identifier for the CloudWatch RUM AppMonitor which monitors your application.
Application Version String The application's semantic version. If you do not wish to use this field then add any placeholder, such as '0.0.0'.
Region String The AWS region of the AppMonitor. For example, 'us-east-1' or 'eu-west-2'.
Configuration Configuration The application-specific configuration for the web client.

Configuration

The application-specific web client configuration is a JavaScript object whose fields are all optional. While these fields are optional, depending on your application the web client may not function properly if certain fields are omitted. For example, identityPoolId and guestRoleArn are both required unless your application performs its own AWS authentication and passes the credentials to the web client using the command awsRum.setAwsCredentials({...});.

To get started, we recommend using the following configuration. The guestRoleArn and identityPoolId shown are dummy values. Modify these to match the resources created when setting up the AppMonitor:

const config: AwsRumConfig = {
    allowCookies: true,
    endpoint: "https://dataplane.rum.us-west-2.amazonaws.com",
    guestRoleArn: "arn:aws:iam::000000000000:role/RUM-Monitor-us-west-2-000000000000-00xx-Unauth",
    identityPoolId: "us-west-2:00000000-0000-0000-0000-000000000000",
    sessionSampleRate: 1,
    telemetries: ['errors', 'performance']
};

For a complete list of configuration options, see Application-specific Configurations.