In part II of this series, I outlined how to monitor your AEM infrastructure.  In part III of this series, I’ll outline how to monitor AEM applications.

Monitoring “Why” it is Happening

To get details on “why” your AEM application is performing in a certain way, application performance management vendors provide a java agent that is used to monitor the Java processes within AEM.  This exposes details of happening within the JVM so you can speak to “why” the basic apm metrics such as cpu are high.  While different APM vendors track different information with their java agents, typically they will also expose information related to several of the following:

  • Java Heap – APM software will typically show the state of your java heap, including the size of each generation, and how much cpu is being used for Java garbage collection.
  • External Services – If your application makes http calls to 3rd parties, it will monitor when these calls are made and how long they take.  This information is grouped in a way that easily exposes the slowest and most frequent calls.
  • Errors – When AEM returns a non 200 response code, APM software can record the response code and the text of the error, and is grouped in a way that is easily sortable for analysis.
  • Transactions – Within APM, a transaction is equivalent to a web request.  APM software can record each pageview rendered by AEM, how long it took to render, as well as how long it takes components within a page to render.  This information can be grouped by transaction name, and is a great way to find performance bottlenecks in your code.

This information answers “why” an application for example is consuming so much CPU.  One can look at the java heap, and see if there too much garbage collection occurring pointing at a memory leak, or can analyze the transactions (aka pages) being rendered by AEM to see if there is an increase in throughput to AEM or poorly performing code within a certain page or component.

For AEM, APM software typically does a great job on it’s own of monitoring the above by just installing the java agent, with the exception of transactions.

Capturing Transaction Names with APM Software

Why doesn’t APM software typically do a good job of capturing transaction names within AEM?  Apache Sling uses resource types to decide how to render content, and most APM software will only know the url or generic information about the page being rendered, but not information around the resource type or template being used to render the page.

For example, take a look at the We.Retail site.  The site uses a generic sling:resourceType for all pages, but different types of pages each use their own cq:template.  In We.Retail, some of the templates used are:

  • Hero template- for homepages and long form content pages
  • Section template – for section pages
  • Experience template- for experience pages
  • Product template – for product pages
  • Social template – for social pages

When viewing information about transactions in APM software, there is not much value in providing generic information of what was rendered by AEM. One can see pages are slow in general, but that doesn’t expose if on average, product templates are X times slower to render than other types of templates.

Here is a quick example of what New Relic and Elastic APM will capture for transactions out of the box.  To generate this data, I recorded a web test while clicking on a variety of different pages in the We.Retail site, which sent requests to AEM to render pages and servlet endpoints via ajax.  I then replayed the test several times concurrently to generate some traffic.  This test isn’t a real world scenario as it bypasses the dispatchers, but is a great way to generate sample data.

New Relic has some logic built into it’s java agent to try to create a transaction name.  For pages, one generic transaction is logged: /libs/cq/Page/Page.jsp.

That name isn’t helpful.  Whether viewing a landing page, product page, experience page, or something else, New Relic always uses the same transaction name, so one can’t see details about specific types of pages.

New Relic is also logging any servlet called via ajax as /DispatcherServlet.  This also isn’t helpful as one can’t see information about each servlet endpoint called.

Elastic APM it isn’t any better at transaction names:

Elastic APM’s Java agent has logic that records the transaction name as DispatcherServlet#doGet.  This also isn’t helpful as any page viewed by an editor will use the same transaction name, and one can’t tell how different types of pages perform.

So how does an engineer glean meaningful information out of transactions?  Read part IV of this series to learn how the Sling APM Framework solves this problem.

If you are interested in collecting java agent APM metrics using New Relic or Elastic, continue reading to learn how to install and configure each product.

New Relic APM

To install the New Relic APM agent, it is best to refer to the New Relic documentation.  I’ve provided a quick start guide below to get engineers started.

First, download the New Relic Java agent zip file from the New Relic site.  Extract the zip file in the same directory that has the crx-quickstart folder, it will create a folder named newrelic with files within it.  Make sure the owner of the directory and files is the same as the user that runs AEM.  Edit the newrelic.yml file in the newrelic folder by updating the following lines:


license_key: '<YOUR_NEW_RELIC_LICENSE_KEY>'



app_name: AEM <ENVIRONMENT> <INSTANCE_TYPE>

Use your New Relic license key for the <YOUR_NEW_RELIC_LICENSE_KEY>.  For <ENVIRONMENT>, enter the name of your AEM environment, for example, qa or production.  For <INSTANCE_TYPE>, use author or publish depending on what this AEM instance is.

By setting your New Relic application name following this pattern, your APM data will be combined into one view for all clustered authors and separately for all publishers for each environment, which provides the most value when analyzing APM data.

Finally, update your startscript for AEM so the CQ_JVM_OPTSvariable includes the following:

-javaagent:/your/path/newrelic/newrelic.jar

Where /your/path/ is the path to where your extracted the newrelic folder.

Upon starting AEM, you should see messages like this indicating the New Relic java agent is active:


com.newrelic INFO: Using default collector host: collector.newrelic.com
com.newrelic INFO: New Relic Agent: Writing to log file: /path/to/log/newrelic_agent.log

Elastic APM

To install the Elastic APM agent, it is best to refer to the Elastic APM documentation.  I’ve provided a quick start guide below to get engineers started.

First, download the Elastic APM agent jar file from the Elastic site.  Place the jar file in the same directory that has the crx-quickstart folder.  Make sure the owner of the jar file is the same as the user that runs AEM.

Next, update your startscript for AEM so the CQ_JVM_OPTSvariable includes the following:

-javaagent:/your/path/to/elastic_apm.jar -Delastic.apm.service_name=AEM-<ENVIRONMENT>-<INSTANCE_TYPE> -Delastic.apm.application_packages=* -Delastic.apm.server_urls=<YOUR_APM_SERVER_URL>

Where:

  •  /your/path/to/elastic_apm.jar – is the path to where your extracted the Elastic APM agent.
  • <ENVIRONMENT> – Your AEM environment, for example QA or PRODUCTION
  • <INSTANCE_TYPE> – The type of your AEM instance, either author or publish
  • <YOUR_APM_SERVER_URL> – Elastic APM also requires you run an APM server.  Setting up the APM server is outside the scope of this tutorial, but you can find information on setting it up here.

Upon starting AEM, you should see messages like this indicating the Elastic APM java agent is active:


[main] INFO co.elastic.apm.configuration.StartupInfo - Starting Elastic APM 1.0.1 as AEM-QA-Publish on Java 1.8.0_131 (Oracle Corporation) Windows 10 10.0
[apm-server-healthcheck] INFO co.elastic.apm.report.ApmServerHealthChecker - Elastic APM server is available: {"ok":{"build_date":"2018-11-09T17:48:30Z","build_sha":"2c46a2919dbe06767caeacbffd0055aab1493991","version":"6.5.0"}}

Ready to learn how to customize your transaction names?  Read part IV of this series to learn how use the Sling APM Framework to set transaction names.

Are you new to APM with AEM and are looking for assistance? Contact Freed Technologies to learn how we can kick start your APM efforts for AEM.