Skip to content
CA Experience Collector
Documentation powered by DocOps

Configure the Browser Agent Response Decoration

Last update February 15, 2018

You can modify the default monitoring to achieve the balance of visibility and performance that you require. The Browser Agent uses a response decoration to carry APM business transaction information and end-to-end APM transaction correlation.

As an administrator, understand the Browser Agent cookies and perform the optional configuration tasks.


Cookies and Header

The Browser Agent uses the following cookies between the browser client and the application server. All the cookies are UTF-8 encoded.

Note: For a list of supported browser platforms, see the Product Compatibility Matrix.

Cookie Description Origin Duration
x-apm-brtm-bt-p

This cookie maintains the browser type.

Browser Page session
x-apm-brtm-bt-pv

This cookie maintains the browser version.

Browser Page session
x-apm-brtm-gaptime This cookie contains the clock skew between the application server and the client. Browser Page session
x-apm-brtm-response-bt-id This cookie contains a unique ID to identify a Browser Agent AJAX request. Browser 2000 milliseconds
x-apm-ba-response-bt

This header contains the Browser Agent business transaction context information for a Browser Agent AJAX request. The uniqueID in the name of the cookie is identical to the value set in the cookie x-apm-brtm-response-bt-id.

Note: Some web applications prevent headers that are set by an agent from being exposed. In these cases, the Browser Agent cannot read and report correlation and agent information from headers set by the agent.

Application server  
x-apm-brtm-response-bt-page-<page URL> This cookie maintains the Browser Agent business transaction context information for the current web page. Application server 3000 milliseconds plus gap time
x-apm-brtm-servertime This cookie contains the application server time when the response was sent from the application server. Application server Page session

The Browser Agent uses the following request to the application server:

  • Application Response sent from the Application Server to the Browser Client
    When the Browser Agent is enabled, the application response inserts the JavaScript snippet file into the browser page. The application response also sends the following cookie or header back to the browser client:
    • CorBrowsGUID: ID to correlate the browser request with the application request (useful when a browser and application transaction traces are created)
    • startTime: start time of the application request
    • endTime: the time for sending the application response to the client
    • bs: Business Service that the Java agent identifies
    • bt: Business Transaction that the Java agent identifies
    • btc: Business Transaction Component that the Java agent identifies

The following cookie key provides the Browser Agent context on the APM transaction that is being monitored. This key allows browser metrics and transaction trace events to have the context of the APM transaction:

  • Application Request from the Browser Client to the Application Server
    With the Browser Agent enabled, the browser client sends back request cookies to the application server decorating the business transaction:
    • x-apm-brtm-bt-p: Platform type (Chrome, Firefox, Internet Explorer, Microsoft Edge, Safari) 
    • x-apm-brtm-bt-pv: Platform version (for the respective browser)

Note: When the introscope.agent.browseragent.response.decoration.enabled property is set to true and the request URL matches the introscope.agent.browseragent.response.decoration.includeURLsRegex property setting, then these actions occur:

    • Java agent adds a header to the webapp response

    • For a snippet-inserted response, the Java agent adds the x-apm-ba-response-bt field into the <script> tag in the response content. JavaScript reads the information from the <script> tag.

    • For a response with no snippet-insertion text/html content type, the Java agent adds a response cookie. The JavaScript reads the information from the response cookie. You can set text/html to another content type using the introscope.agent.browseragent.response.decoration.cookie.contenttype property.

Configure Business Transaction Matching and Transaction Trace Correlation

Configure business transaction matching support and end-to-end transaction trace correlation.

Follow these steps:

  1. Go to <Agent_Home>/core/config and open the IntroscopeAgent.profile file in a text editor.
  2. Enable the following property.

    introscope.agent.browseragent.response.decoration.enabled=true

    When this property is enabled, Browser Agent transaction traces are correlated with the server transaction trace that is generated by the agent only when the trace session is on. The last part of the URL is used as a key for the <page url> placeholder in the cookie name x-apm-brtm-response-bt-page-<page url>.

  3. Save and close the IntroscopeAgent.profile file.

Encrypt Transaction Information in the Java Agent Response Decoration

The Java agent uses a response cookie and header to send CA APM transaction information to the Browser Agent. 

You can enable the Java agent to gather and encrypt CA APM transaction information. The Java agent embeds the encrypted information into a response cookie and header, and sends the cookie and header to the Browser Agent. The Browser Agent passes the information to the Digital Experience Collector, which decrypts and reports on the transaction information. This process takes place within a single request and response transaction as follows: 

  1. When the introscope.agent.decorator.userid.cookie.name is set in the agent profile, the Java agent reads the user ID value from the cookie.
  2. The Java agent gathers and encrypts the user ID, agent name, agent host, agent process, servlet name, and web application name.
    Each Java agent field is encrypted separately 
  3. The Java agent adds the encrypted information into the response cookie and header, and sends the cookie and header to the browser.
  4. The Browser Agent extracts the Java agent information when creating a JSON object. The Browser Agent then sends the object to the Digital Experience Collector.
  5. The Digital Experience Collector parses the JSON object to decrypt the Java agent information.
  6. The Digital Experience Collector sends the decrypted Java agent information to the Enterprise Manager for use in transaction traces.
    When a Java agent field is empty during encryption, then there is no value to decrypt for Enterprise Manager use. For example, the user ID field is empty during encryption. The Digital Experience Collector cannot send a user ID value to the Enterprise Manager. This situation results in no value for the User ID column in the WebView transaction trace Trace view.

Follow these steps:

  1. Go to <Agent_Home>/core/config and open the IntroscopeAgent.profile file in a text editor.

  2. Go to this section:

    ###############################################

    Browser Agent Business Transaction Monitoring properties

  3. Add these properties to the section:

    introscope.agent.decorator.userid.cookie.name=

    introscope.agent.browseragent.response.decoration.apmData.enabled

  4. Configure these properties:

    introscope.agent.decorator.userid.cookie.name=<cookie_name>

    introscope.agent.browseragent.response.decoration.apmData.enabled=<true/false>

    introscope.agent.browseragent.response.decoration.enabled=<true/false>

    1. Ensure that the introscope.agent.browseragent.response.decoration.enabled property is set to true.

    2. Specify the introscope.agent.decorator.userid.cookie.name property value.

    3. Specify introscope.agent.browseragent.response.decoration.includeURLsRegex property value to match the request URL.
  5. Save and close the file.
    To confirm that the response cookie data is encrypted, look at either the x-apm-brtm-response-bt-page-<page URL> or the x-apm-ba-response-bt response header value.

Control the Browser Agent Response Decoration

The response decoration carries APM business transaction information and end-to-end APM transaction correlation. However, too many requests that occur in a close time frame can cause a client cookie explosion. A cookie explosion might result in authentication issues or the client displaying a 413 Request Entity Too Large response error. To solve the problem, you can control the Browser Agent response cookie.

Follow these steps:

  1. Do one of the following actions:
    For Digital Experience Insights and the CA APM Command Center package, go to extensions/browser-agent-ext-<hash>-<version> and open the bundle.properties file in a text editor.
    For the APM noninstaller package, go to <Agent_Home>/core/config and open the IntroscopeAgent.profile file in a text editor.
  2. Go to this section:

    ###############################################

    Browser Agent Business Transaction Monitoring properties

  3. Modify the following properties and specify values:

    introscope.agent.browseragent.response.decoration.cookie.expirationTime=<integer in seconds>

    introscope.agent.browseragent.response.decoration.includeURLsRegex=<regular expression>

    introscope.agent.browseragent.response.decoration.enabled=<true/false>

    The following example matches all URLs with path "/mypage.jsp":

    introscope.agent.browseragent.response.decoration.includeURLsRegex=.*/mypage.jsp
  4. Save and close the file.

Was this helpful?

Please log in to post comments.

  1. Jose Vicente Espinosa
    2019-05-06 01:04

    On x-apm-ba-response-bt header, a further explanation about CORS headers introduced by BrowserAgent should noted.

    1. Wren Withers
      2019-05-08 11:14

      Thanks for your suggestion Jose. We'll look into it.

      Wren