Simplifying application onboarding with Amazon CodeGuru Profiler

Amazon CodeGuru Profiler provides recommendations to help you continuously fine-tune your application’s performance. It does this by collecting runtime performance data from your live applications. It looks for your most expensive lines of code continuously and provides intelligent recommendations. This helps you more easily understand your applications’ runtime behavior so you can optimize their performance, improve latency, and reduce infrastructure cost.

From a central dashboard, you get different visualizations of your profiling data and details to what CodeGuru Profiler recommends of your application’s performance profile. You also get a report with details on the impact of the issue on your application, what’s causing the issue, and a recommendation on what to change to resolve the issue.

In this post, I introduce you to two enhancements that make it even easier and faster for your applications to start using the machine learning (ML)-based capabilities of CodeGuru Profiler:

  • Resource-based authorizations – You can use resource-based permissions to authorize an identity in your code to upload the profiled data instead of manually configuring AWS Identity and Access Manager (IAM). If the role or user already exists in IAM, you simply select the role or user on the CodeGuru Profiler console.
  • Ability to start the profiler agent on the command line – You can now start the profiler agent on the command line using the -javaagent This means that you no longer need to recompile your application or set build dependencies; you simply download the latest JAR file and add the -javaagent switch to the command line and run. The whole process takes just minutes to complete.

What you can do with CodeGuru Profiler

CodeGuru Profiler is designed to run in your production environment with minimal CPU overhead to help improve your application’s performance and reduce infrastructure costs. With CodeGuru Profiler, you can:

  • Troubleshoot latency and CPU utilization issues in your application
  • Identify application performance issues
  • Identify cost optimization opportunities and where you can reduce the infrastructure costs of running your application

CodeGuru Profiler works with your applications that are hosted on Amazon Elastic Compute Cloud (Amazon EC2), serverless applications running on AWS Fargate and AWS Lambda, and containerized applications running on Amazon Elastic Container Service (Amazon ECS) and Amazon Elastic Kubernetes Service (Amazon EKS). CodeGuru Profiler also works on-premises. It currently supports applications written in all Java virtual machine (JVM) languages, such as Java, Kotlin, and Scala.

Profiling groups

In CodeGuru Profiler, a profiling group is a set of applications that are profiled together as a single unit. The profiling agent sends application data to a single profiling group, where data from all applications in the profiling group are aggregated and analyzed. Your groups are managed on the Profiling groups page on the CodeGuru console. You can see a list of all your profiling groups, their status, or create or delete profiling groups. For more information, see Setting up Amazon CodeGuru Profiler.

A profiling group can profile a single application running on multiple hosts. It can also profile different but related applications. You can profile an application, regardless of what repository the code is in.

Resource-based authorization enabled

The improvements made to application onboarding remove many manual steps, enable resource-based authorization, and remove the need to configure IAM permissions each time you add a new application for profiling. This new setup option helps reduce configuration errors and enables quick onboarding of your application into the profiling group.

In this section, we show you how to grant the required permissions on the CodeGuru Profiler console. The first time you onboard your application, your admin needs to create the IAM role or user that can submit profiling data and configure the agent. That way, the roles and users can appear in the permissions drop-down on the CodeGuru Profiler console. After this setup is complete, you don’t need to go on the IAM console to set permissions.

Creating a profiling group with resource-based authorization

To create a profiling group with resource-based authorization enabled, complete the following steps:

  1. On the CodeGuru Profiler console, choose Create profiling group.


  1. For Name, enter test-group.
  2. Choose Create.

We can now show you the resource-based authorization enhancement in action. Prior to the recent enhancement, you needed to set up access credentials to give an application permission to submit data to your account. You can now do this in a few clicks on the Profiling groups page.

  1. In the Set permissions section, choose Give access to users and roles.
  2. For Application permissions, choose the IAM users and roles that you want to give permissions to so they can submit data to CodeGuru Profiler.
  3. Choose Save.

That’s it! You have set permissions for users and roles in your profiling group.

Starting the profiler agent without modifying your application’s code

Next, we walk you through a use case to demonstrate how easy and quick it is to start the profiler agent without modifying the application code.


To complete this part of the post, you need the following:

  • AWS account
  • Laptop or desktop computer with internet access
  • Terminal emulator of your choice
  • Corretto 8 or JDK version 8 or later installed on your EC2 instance
  • Maven installed on your EC2 instance

You no longer need to modify your application code or add dependencies to run the agent. The benefit to starting the agent with the -javaagent parameter is that you can profile existing applications without recompiling or changing your application’s code. You can still use the previous approach to start the profiling agent. For example, this approach is applicable as the only option to use for Lambda and Spark jobs.

To onboard your application, you complete the following steps:

  1. Create your profiling group and set an environment variable for your Region.
  2. Download the latest Java JAR file from the CodeGuru Profiler console.
  3. Restart your JVM by running the -javaagent parameter

This post has some additional steps because we also set up the demo application to start profiling and onboard two different profiler groups: DemoApplication-WithIssues and DemoApplicationWithoutIssues.

Cloning the demo application

To clone the demo application to your EC2 instance, enter the following code:

git clone
cd aws-codeguru-profiler-demo-application 

After you change directories to aws-codeguru-profiler-demo-application, you should see the pom.xml file.

Creating a profiling group

At the command line, enter the following commands, starting with the steps that you always need to perform to onboard the profiler (with aws configure, set up your AWS credentials and default Region, which are the same credentials you created the resource policies for):

aws codeguruprofiler create-profiling-group --profiling-group-name DemoApplication-WithIssues
aws codeguruprofiler create-profiling-group --profiling-group-name DemoApplication-WithoutIssues

Setting up the demo application

To complete the project, you create an Amazon Simple Storage Service (Amazon S3) bucket and an Amazon Simple Queue Service (Amazon SQS) queue. Creating an S3 bucket and SQS queue aren’t part of the onboarding process; you use these services for business logic. The SQS queue is polled for names of images to process and the images get loaded into an S3 bucket, does some image transformation, and then the results back to the S3 bucket.

To create these resources, enter the following code:

aws s3 mb s3://demo-application-test-bucket-YOUR BUCKET NAME
aws sqs create-queue --queue-name DemoApplicationQueue

For this post, replace YOUR BUCKET NAME with a random set of numbers. This helps make sure that your bucket contains a globally unique name.

Next, we set the environment variables by using the following commands. These steps are necessary for this particular application and not related to onboarding the profiler. Also, don’t forget to use your test-bucket name. Replace the referenced Amazon SQS URL with your Amazon SQS URL, which you can find on the Details tab for the queue on the Amazon SQS console.

export DEMO_APP_BUCKET_NAME="demo-application-test-bucket-10245"
export DEMO_APP_SQS_URL=""

Downloading the Java agent JAR file

First, set the environment variable:

export AWS_CODEGURU_PROFILER_GROUP_NAME=DemoApplication-WithIssues

To create a JAR file in the target directory, enter the following code:

mvn clean install

The process can take up to 1 minute to complete.

For this post, you don’t need to download the CodeGuru Profiler Java agent JAR file. It’s included with the demo application that you downloaded from GitHub. However, when you onboard your application for profiling, you need to download the JAR file from the CodeGuru Profiler console. See the following screenshot.

Running the demo application

Next, you restart your JVM by running the -javaagent switch. Make sure that the application file name is included in the command. When you run this project, the JAR file version may have been updated from the version you see in the following code:

java -javaagent:codeguru-profiler-java-agent-standalone-1.0.0.jar 
-jar target/DemoApplication-1.0-jar-with-dependencies.jar with-issues

The profiling group setup is successful when you see the following message:

INFO: Profiling scheduled, sampling rate is PT1S

You will see messages running on the screen for several minutes. You have the option to enter exit, enter on your keyboard. If you do that, reconnect back into your EC2 instance through SSH to verify that the application is still running in the background, using the following command:

ps -ef |grep javaagent

Checking the CodeGuru console for the profiling group

To verify that your application is profiling, return to the CodeGuru console. You should see the profiling group go from Inactive to Pending status, and then end in Profiling status.

When your profiling group shows the status Profiling, you can visualize the application’s runtime data. It takes about 5 minutes for the CodeGuru Profiling agent to submit code review data. After about 10 more minutes, you can see the flame graph visualizations. Within 1 hour, you have your first recommendation report.

If you want to run this project again, without issues, repeat the previous steps with the following changes:

  • Set the export variables per your setup. As we discussed earlier when running the demo app WithIssues, these environment variables are specific to running the demo app and not part of the profiler onboarding.
    export DEMO_APP_SQS_URL=
    export DEMO_APP_BUCKET_NAME=demo-application-test-bucket-1092734-YOUR-BUCKET-NAME

  • Run the demo application with the following code:
    export AWS_CODEGURU_PROFILER_GROUP_NAME=DemoApplication-WithoutIssues
    mvn clean install ## This command will generate the DemoApplication-1.0-jar-with-dependencies.jar
    java -javaagent:codeguru-profiler-java-agent-standalone-1.0.0.jar 
      -jar target/DemoApplication-1.0-jar-with-dependencies.jar without-issues

For more information about visualizations in CodeGuru Profiler, see the section Understanding CodeGuru Profiler’s visualizations in Optimizing application performance with Amazon CodeGuru Profiler.

Cleaning up

To avoid incurring any future charges, delete the resources you created with this project:

  • Profiling group DemoApplication-WithIssues
  • SQS queue and the S3 bucket
  • EC2 instance


We’re excited to help you make it even quicker and easier to onboard your applications using CodeGuru Profiler. In this post, we reviewed and learned how to use two recent enhancements to CodeGuru Profiler: resource-based permission setting and starting the profiler agent using the -javaagent switch, without needing to modify your application’s code.

CodeGuru Profiler is part of Amazon CodeGuru (Preview), an ML-based service that performs automated code reviews and application performance recommendations. It finds issues in your code and deviations from performance engineering best practices using AWS APIs, SDKs, and a variety of libraries to make specific recommendations to remediate identified issues. CodeGuru is powered by ML capabilities, best practices, and lessons learned from millions of code reviews and thousands of applications profiled on both open-source projects and internally at Amazon.

We hope that you find that using these feature enhancements is straightforward, quick, and easy. Let us know your progress on our GitHub project page!

About the Author

Charles Gibson is an Enterprise Transformation Architect in Professional Services at Amazon Web Services. He helps customers migrate and modernize their businesses on the AWS Cloud. Charles enjoys cooking Northern Italian food for friends and family.





Read More