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 browser monitoring 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"
          ]
        }
      }
    }
  }
 "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"
      ]
    }
  }

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.

Tip

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

Browser agent version pinning

Step 1. Retrieve the current pinned version

Step 2. Review the available versions

Step 3. Pin the desired version

Tip

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