Setting Up And Using the Elastic APM on Alfresco

Installing the Elastic APM

Elastic APM provides an open source tool to quickly and easily visualize the health of our Alfresco installations. To use, you must first install:

1. ElasticSearch
2. Kibana
3. APM Server

Once that is complete, you must download the proper version of the java agent from Maven Central. You won't be adding this jar as a dependency, but instead placing it on the Alfresco server and referencing it in your java options. Add the below to your Alfresco's java options (removing the brackets).

• -javaagent:<path_to_java_agent_jar>
• -Delastic.apm.service_name=<desired_service_name> - for example your server name or "edge2", "release2", etc.
• -Delastic.apm.application_packages=com.tsgrp
• -Delastic.apm.server_urls=<url_of_apm_server> - for example, http://localhost:8200 locally

Now when Alfresco is started it will send data to the APM Server for all REST Controllers in com.tsgrp packages. View this by going to your Kibana installation and clicking on the APM tab.

APM Index/Server Maintenance

Create and Apply Index Lifecycle Policy

If left alone, the APM indices will continue to grow until the server runs out of space (new indices are created every day). To combat this, use the built-in Index Lifecycle Management API to automatically delete indices when they reach a certain size or age. This example shows deleting APM-related indices after 30 days.

1. Navigate to the "Dev Tools" tab
2. Create a lifecycle policy

   PUT _ilm/policy/apm_policy   
   {
     "policy": {                       
       "phases": {
         "delete": {
           "min_age": "30d",           
           "actions": {
             "delete": {}              
           }
         }
       }
     }
   }

3. Show existing index templates. Ensure the response includes a template that starts with "apm-".

   GET _cat/templates

4. Apply policy created to indices that start with "apm-"

   PUT _template/apm_template
   {
     "index_patterns": ["apm-*"],
     "settings": {
       "number_of_shards": 1,
       "number_of_replicas": 1,
       "index.lifecycle.name": "apm_policy",
       "index.lifecycle.rollover_alias": "apm"
     }
   }

5. All new APM indices created will now have the lifecycle applied.

Apply policies to existing APM indices

If several APM indices have already been created before the policy was applied to the APM template, the existing indices will not be managed by the lifecycle automatically. To add them:

1. Check the lifecycle status of the existing indices. Any that with the status "managed" : false are not currently managed.

   GET apm-*/_ilm/explain
   

2. Set indices to non-read-only

   PUT apm-*/_settings
   {
     "index.blocks.read_only_allow_delete": "false"
   }
   

3. Set the lifecycle policy

   PUT apm-*/_settings
   {
     "index.lifecycle.name": "apm_policy"
   }
   

4. Set indices back to read-only

   PUT apm-*/_settings
   {
     "index.blocks.read_only_allow_delete": "true"
   }
   

5. Run the explain API again to ensure indices are now managed.