NerdGraph tutorial: Browser agent monitoring examples

Here are some examples of various browser configurations you can make with GraphQL.

Create a new browser application

You can create browser applications using our NerdGraph API instead of using the UI. The advantage to this is that when it's time to instrument your browser application with New Relic, you can programmatically create and retrieve the JavaScript snippet to copy and paste into your browser app.

For how to use npm to set up for multiple applications, see Instrument multiple apps with npm.

Here's an example mutation to create a new browser application with default settings.

Mutation:

mutation CreateExampleBrowserApplication(
  $accountId: Int!
  $name: String!
  $settings: AgentApplicationBrowserSettingsInput
) {
  agentApplicationCreateBrowser(
    accountId: $accountId
    name: $name
    settings: $settings
  ) {
    guid
    name
    settings {
      cookiesEnabled
      distributedTracingEnabled
      loaderScript
      loaderType
    }
  }
}

Variables:

{
  "accountId": Int!,
  "name": String!,
  "settings": {
    "cookiesEnabled": Boolean,
    "distributedTracingEnabled": Boolean,
    "loaderType": AgentApplicationBrowserLoader
  }
}

Retrieve the JavaScript snippet

You can retrieve the JavaScript snippet to copy/paste into your application. Note that the returned snippet is a JSON encoded string that will need to be parsed before it can be copy/pasted.

Query:

query FetchBrowserJavaScriptSnippet($guid: EntityGuid!) {
  actor {
    entity(guid: $guid) {
      ... on BrowserApplicationEntity {
        guid
        name
        browserProperties {
          jsLoaderScript
        }
      }
    }
  }
}

Variables:

{
  "guid": EntityGuid!
}

Examples of configuring browser monitoring

Browser settings can be configured through NerdGraph. Here is an example mutation that changes the apdex of an application.

Mutation:

mutation UpdateBrowserApdexTarget(
  $guid: EntityGuid!
  $settings: AgentApplicationSettingsUpdateInput!
) {
  agentApplicationSettingsUpdate(guid: $guid, settings: $settings) {
    browserSettings {
      browserConfig {
        apdexTarget
      }
    }
    errors {
      description
      errorClass
      field
    }
  }
}

Variables:

{
  "guid": EntityGuid!,
  "settings": {
    "browserConfig": {
      "apdexTarget": Float
    }
  }
}

For more information on what browser settings can be updated via NerdGraph, reference the following mutation. Documentation for each field can be found in the NerdGraph explorer.

Mutation:

mutation UpdateBrowserSettingsExample(
  $guid: EntityGuid!
  $settings: AgentApplicationSettingsUpdateInput!
) {
  agentApplicationSettingsUpdate(guid: $guid, settings: $settings) {
    browserSettings {
      browserConfig {
        apdexTarget
      }
      browserMonitoring {
        ajax {
          denyList
        }
        distributedTracing {
          allowedOrigins
          corsEnabled
          corsUseNewrelicHeader
          corsUseTracecontextHeaders
          enabled
          excludeNewrelicHeader
        }
        loader
        privacy {
          cookiesEnabled
        }
      }
      dataManagement {
        sendTransactionEventsToInternalStream
      }
    }
    errors {
      description
      errorClass
      field
    }
  }
}

Variables:

{
  "guid": EntityGuid!,
  "settings": {
    "browserConfig": {
      "apdexTarget": Float
    },
    "browserMonitoring": {
      "ajax": {
        "denyList": [String!]
      },
      "distributedTracing": {
        "allowedOrigins": [String!],
        "corsEnabled": Boolean,
        "corsUseNewrelicHeader": Boolean,
        "corsUseTracecontextHeaders": Boolean,
        "enabled": Boolean,
        "excludeNewrelicHeader": Boolean
      }
      "loader": AgentApplicationSettingsBrowserLoaderInput,
      "privacy": {
        "cookiesEnabled": Boolean
      }
    }
    "dataManagement": {
      "sendTransactionEventsToInternalStream": Boolean
    }
  }
}

Retrieve the application configuration

You can retrieve the browser application configuration to use with the npm package installation method. Depending on your needs, the configuration can be returned in two different formats:

a JSON encoded string for injection into the head element of your webpage.
an object that can be used as is in your application source code.

Query:

query FetchBrowserConfiguration($guid: EntityGuid!) {
  actor {
    entity(guid: $guid) {
      ... on BrowserApplicationEntity {
        guid
        name
        browserProperties {
          jsConfig
          jsConfigScript
        }
      }
    }
  }
}

Variables:

{
  "guid": EntityGuid!
}

Group your data with browser segments

You can group your browser monitoring results by browser segments to get more meaningful data. Instead of doing this in the UI, you can do it with GraphQL.

List segments

Get started by listing existing segments:

{
  actor {
    entity(guid: "YOUR_GUID") {
      ... on BrowserApplicationEntity {
        segmentAllowListAggregate {
          segments
        }
      }
    }
  }
}

Here's the response:

{
  "data": {
    "actor": {
      "entity": {
        "segmentAllowListAggregate": {
          "segments": ["urlsegment1", "urlsegment2"]
        }
      }
    }
  }
}

Create segments

Create browser segments using the agentApplicationSegmentsReplaceAllBrowserSegmentAllowList mutation:

mutation {
  agentApplicationSegmentsReplaceAllBrowserSegmentAllowList(
    entityGuid: "YOUR_GUID"
    allowList: { segments: ["urlsegment1", "urlsegment2", "urlsegment3"] }
  ) {
    segments
  }
}

Here's the response:

{
  "data": {
    "agentApplicationSegmentsReplaceAllBrowserSegmentAllowList": {
      "segments": ["urlsegment3", "urlsegment2", "urlsegment1"]
    }
  }
}

Create obfuscation rules

You can mask sensitive data before it's harvested by creating ingest obfuscation rules directly from the New Relic platform or NerdGraph. These rules apply to all browser events. Rules configured via the platform or NerdGraph apply to APM-injected applications, copy/paste installations, and NPM installations. To create rules via platform or JavaScript, see Obfuscate sensitive data in the browser agent.

To create obfuscation rules via NerdGraph:

Retrieve the current obfuscation rules for your browser application using the following query:

actor {
      entities(guids: "YOUR_BROWSER_APP_GUID") {
        ... on BrowserApplicationEntity {
          browserSettings {
            browserObfuscation {
              rules {
                regex
                replacement
                eventFilter
              }
            }
          }
        }
      }
    }

重要

You must retrieve the current rules before updating them, as the agentApplicationSettingsUpdate mutation will overwrite any existing rules with the new set of rules you provide. If you want to keep any existing rules, be sure to include them in the new set of rules you send in the mutation.

Update the obfuscation rules using the agentApplicationSettingsUpdate mutation. You can add new rules or modify existing ones by defining the following properties:

regex: The regular expression pattern to match the data you want to obfuscate. For example, you can use \b\d{3}-?\d{2}-?\d{4}\b to match Social Security numbers.
replacement: The string that will replace the matched data. For example, you can use XXX-XX-XXXX to mask Social Security numbers.
eventFilter: An array of browser event types to which the rule should be applied. For example, you can specify ["AjaxRequest"] to apply the rule only to AJAX request events.

mutation {
  agentApplicationSettingsUpdate(
    guid: "YOUR_BROWSER_APP_GUID"
    settings: {
      browserObfuscation: {
        rules: [
          {
            regex: "YOUR_REGEX_HERE"
            replacement: "XXX-XX-XXXX"
            eventFilter: ["AjaxRequest"]
          }
        ]
      }
    }
  ) {
    browserSettings {
      browserObfuscation {
        rules {
          regex
          replacement
          eventFilter
        }
      }
    }
  }
}

Configure AJAX payload capture

You can retrieve and update the AJAX payload capture setting for your browser application using NerdGraph. This setting controls whether request and response payloads are captured for AJAX calls and corresponds to the payload capture option in your application settings.

You can enable payload capture settings in two steps:

Retrieve the current payload capture settings.
Set the capturePayloads mode to one of the following values:
- none: No payload data will be captured.
- failures: Captures payloads only for requests with a status code of 0, a code of 400 or higher, or a GraphQL error signature in the response body.
- all: Captures payloads for all requests.

Retrieve the current payload capture setting for your browser application using the following query:

query FetchBrowserAjaxPayloadCapture {
  actor {
    user {
      name
    }
    entity(guid: "YOUR_ENTITY_GUID") {
      ... on BrowserApplicationEntity {
        guid
        name
        browserSettings {
          browserMonitoring {
            ajax {
              capturePayloads
            }
          }
        }
      }
    }
  }
}

Update the payload capture setting using the agentApplicationSettingsUpdate mutation:

mutation UpdateBrowserAjaxPayloadCapture(
  $guid: EntityGuid!
  $settings: AgentApplicationSettingsUpdateInput!
) {
  agentApplicationSettingsUpdate(guid: $guid, settings: $settings) {
    browserSettings {
      browserMonitoring {
        ajax {
          capturePayloads
        }
      }
    }
    errors {
      description
      errorClass
      field
    }
  }
}

Set the guid and capturePayloads options in the Variables:

{
  "guid": "YOUR_BROWSER_APP_GUID",
  "settings": {
    "browserMonitoring": {
      "ajax": {
        "capturePayloads": "failures"
      }
    }
  }
}

Browser agent version pinning

New Relic's GraphQL API provides you a method to "pin" a specific version of the New Relic Browser agent, ensuring it remains consistent within your platform. By pinning a version, you can prevent automatic updates that might introduce unexpected changes or behaviors. The key benefits this feature include these:

Control: Retain autonomy over when and how updates are applied.
Confidence: Ensure that a tested and approved version of the agent is running at all times.
Testability: Easily test new versions in isolated environments before deciding to update.
Stability: Minimize unexpected disruptions and maintain consistent application behavior.
Efficiency: Reduce deploy time and mitigate deployment difficulties.

Here is an overview of how to use the Browser Agent Version Pinning API:

Use this NerdGraph query to determine which agent type your browser application uses as well as if a specific version is already pinned.

query FetchBrowserMonitoringAgentSettings {
  actor {
    entity(guid: "YOUR_BROWSER_APP_GUID") {
      ... on BrowserApplicationEntity {
        guid
        name
        browserSettings {
          browserMonitoring {
            loader
            pinnedVersion
          }
        }
      }
    }
  }
}

An example response to the above query:

{
  "data": {
    "actor": {
      "entity": {
        "browserSettings": {
          "browserMonitoring": {
            "loader": "SPA",
            "pinnedVersion": null
          }
        },
        "guid": "YOUR_BROWSER_APP_GUID",
        "name": "Example Single Page App"
      }
    }
  }
}

In this example, the loader is SPA type and the pinnedVersion is null, which indicates that there is no version pinned.

You may run this query at any time to verify your combination of loader and pinned version.

Once you've identified the version you want to pin, use the following GraphQL mutation to set it.

ヒント

Make sure to use the semantic version of the browser agent that you would like your app to use. Leave this blank to use the most recent version. Use 'x' in place of a numeric digit to represent the latest release within the version range (for example, '1.x.x').

mutation {
  agentApplicationSettingsUpdate(
    guid: "YOUR_BROWSER_APP_GUID"
    settings: { browserMonitoring: { pinnedVersion: "1.229.0" } }
  ) {
    browserProperties {
      jsLoaderScript
    }
    browserSettings {
      browserMonitoring {
        loader
        pinnedVersion
      }
    }
  }
}

Note that the return fields for this mutation will contain the updated pinnedVersion value, as well as the updated jsLoaderScript.

Changing the loader value to NONE will remove any pinned semantic version.

For applications using the copy/paste method, replace the existing JavaScript snippet with the new, decoded <script>. Then re-deploy your application.

For applications that have browser monitoring via a backend-installed agent (such as Ruby, Python, etc.), the agent will need to be restarted in order to fetch the new values.

In either case, the next time your application serves a browser page, it should be using the pinned agent version to report data to your New Relic account.

Remember that you can check the pinned version and loader type by using the query in the first step.

NerdGraph tutorial: Browser agent monitoring examples

Create a new browser application

Retrieve the JavaScript snippet

Examples of configuring browser monitoring

Retrieve the application configuration

Group your data with browser segments

List segments

Create segments

Create obfuscation rules

Step 1: Retrieve obfuscation rules

重要

Step 2: Update obfuscation rules

Configure AJAX payload capture

Query the payload capture setting

Update the payload capture setting

Browser agent version pinning

Step 1. Retrieve the current pinned version

Step 2. Review the available versions

Step 3. Pin the desired version

ヒント

Step 4. Re-deploy your application or restart your agent

NerdGraph tutorial: Browser agent monitoring examples

Create a new browser application .css-21sua1{background:none;border:none;width:0;padding:0;}

Retrieve the JavaScript snippet

Examples of configuring browser monitoring

Retrieve the application configuration

Group your data with browser segments

List segments

Create segments

Create obfuscation rules

Step 2: Update obfuscation rules

Configure AJAX payload capture

Query the payload capture setting

Update the payload capture setting

Browser agent version pinning

Step 1. Retrieve the current pinned version

Step 2. Review the available versions

Step 3. Pin the desired version

Step 4. Re-deploy your application or restart your agent

Create a new browser application