# Integrating with your JVM-based application To start profiling your application, enable the CodeGuru Profiler agent to be loaded and started when your JVM-based application starts. After the agent starts, it automatically sends profiles to CodeGuru Profiler service. You’ll see continuous updates and recommendations. The following sections explain which environments and languages are supported by CodeGuru Profiler. **Topics** + [Choosing the right integration option](#choosing-the-right-integration-option) + [Profiling your applications that run on AWS Lambda](setting-up-lambda.md) + [Enabling the agent from the command line](enabling-the-agent-with-command-line.md) + [Enabling the agent with code](enabling-the-agent-with-code.md) ## Choosing the right integration option You can load the CodeGuru Profiler agent into your JVM-based application in two ways: 1. **Command line** – Use the `-javaagent` command line option when starting your application. 1. **Code** – Add the CodeGuru Profiler agent into your application code. The same functionality is available in either option. Choosing the right option for your situation depends on the following: To quickly start profiling your existing JVM-based application, the command line option might be best because it doesn't require recompiling your application. For more control over when to start profiling, or in rare cases where you need to provide a custom authentication provider, you might want to choose the code option. The following table helps summarize these options. | Option | Command line | Code | | --- | --- | --- | | Profile existing application | Yes | No (requires re-compile) | | Custom authentication provider | No | Yes | | Control when profiling starts | No (profiling begins at startup) | Yes | You can always choose a different option later. All of the profiling data is stored in the CodeGuru Profiler service, and is available even when switching the CodeGuru Profiler agent. # Profiling your applications that run on AWS Lambda To start CodeGuru Profiler in your application running on AWS Lambda, you can either update your Lambda function configuration or modify your application code. The former option is available only for Java 8 on Amazon Linux 2 and Java 11 and Java 17 (Corretto) runtimes, while the latter is available for all Java runtimes. If you enabled profiling in the Lambda console, you don't have to complete the procedure outlined in the following sections. To learn more about enabling profiling from the Lambda console, see [Set up in the Lambda console](setting-up-short.md). **Note** You can profile your Lambda functions running in Java if they are called often enough for CodeGuru Profiler to gather enough samples. CodeGuru Profiler collects data once per second, aggregated into 5-minute sampling buckets. For Lambda functions running for fewer than 5 minutes, your application must run multiple times so CodeGuru Profiler can collect enough data. If it runs too infrequently, CodeGuru Profiler can't generate enough data to provide recommendations and flame graphs. For long-running Lambda applications, processing can take up to 15 minutes to display graphs and information. If you are running your application in shorter durations, processing takes longer to display information. **Topics** + [All Java runtimes](lambda-custom.md) + [Easier option for Java 8 on Amazon Linux 2 and Java 11 and Java 17 (Corretto) runtimes](lambda-simple.md) # All Java runtimes If you're profiling applications that run on AWS Lambda, add the following environment variables to your Lambda function. + `AWS_CODEGURU_PROFILER_GROUP_ARN` – Identifies the profiling group ARN. + `AWS_CODEGURU_PROFILER_ENABLED` – Enables profiling when set to `TRUE`. To disable profiling, set this variable to `FALSE`. Default value is `TRUE`. For information about setting environment variables in the Lambda console, see [Using AWS Lambda environment variables](https://docs.aws.amazon.com/lambda/latest/dg/configuration-envvars.html). Add a dependency to the CodeGuru Profiler profiling agent library. You can do this manually by adding a dependency in your Maven or Gradle configuration files. For more information about adding dependencies, see [Enabling the agent with code](https://docs.aws.amazon.com/codeguru/latest/profiler-ug/enabling-the-agent-with-code). ## Make code changes to start profiling your AWS Lambda functions If you have been using handlers provided by AWS Lambda, then you can alter your code to use handlers provided by CodeGuru to enable profiling. For information about your Lambda function's header, see [AWS Lambda function handler in Java](https://docs.aws.amazon.com/lambda/latest/dg/java-handler.html). **Note** No need to change your Lambda configuration\$1 The handler function should still be `handleRequest`. This function is implemented by the CodeGuru class and calls the `requestHandler` after setting up the profiler. If your Lambda function uses Lambda’s `RequestHandler`, you can replace it with CodeGuru Profiler's `RequestHandlerWithProfiling` to enable profiling by default. `RequestHandlerWithProfiling` is a generic type that takes two parameters: the input type and the output type. Both types must be objects. When you use `RequestHandlerWithProfiling`, the Java runtime deserializes the event into an object with the input type, and serializes the output into text. Use this interface when the built-in serialization works with your input and output types. The following example provides a sample code snippet to enable profiling by default. ``` package example; import java.util.Map; import com.amazonaws.services.lambda.runtime.Context; import software.amazon.codeguruprofilerjavaagent.RequestHandlerWithProfiling; public class Handler extends RequestHandlerWithProfiling, String> { @Override public String requestHandler(Map input, Context context) { // Your function code here } } ``` If you are using `RequestStreamHandler`, then you can replace it with CodeGuru Profiler's `RequestStreamHandlerWithProfiling`. To use your own serialization, implement the `RequestStreamHandlerWithProfiling` interface, with which Lambda passes your handler an input stream and output stream. The handler reads bytes from the input stream, writes to the output stream, and returns void. ``` package example; import java.io.IOException; import java.io.InputStream; import java.io.OutputStream; import com.amazonaws.services.lambda.runtime.Context; import software.amazon.codeguruprofilerjavaagent.RequestStreamHandlerWithProfiling; public class StreamHandler extends RequestStreamHandlerWithProfiling { @Override public void requestHandler(InputStream input, OutputStream output, Context context) throws IOException { // Your function code here } } ``` If you don't use handlers provided by AWS Lambda, then add the following code to start profiling your AWS Lambda functions. Wrap your AWS Lambda function’s logic inside a utility from the CodeGuru Profiler profiling agent. ``` package example; import com.amazonaws.services.lambda.runtime.Context; import software.amazon.codeguruprofilerjavaagent.LambdaProfiler; public class MyHandler { // This is the handler function we use in the lambda public Output handleRequest(Input input, Context context) { return LambdaProfiler.profile(input, context, this::myHandlerFunction); } private Output myHandlerFunction(Input input, Context context) { // your function code here } } ``` Your Lambda function runs the way it typically does, while the CodeGuru Profiler profiling agent runs in parallel. After running for 5 minutes, the agent submits your first profile. Processing can take up to 15 minutes. # Easier option for Java 8 on Amazon Linux 2 and Java 11 and Java 17 (Corretto) runtimes You can enable CodeGuru Profiler from the AWS console by setting environment variables and updating configuration for your AWS Lambda function. This method works for Java 8 on Amazon Linux 2 and Java 11 and Java 17 (Corretto) runtimes. If you're profiling applications that run on Lambda, set the following environment variables to your Lambda function. + `AWS_CODEGURU_PROFILER_GROUP_NAME` – Identifies the profiling group name. + `AWS_CODEGURU_PROFILER_TARGET_REGION` – Identifies the target region of the profiling group. + `AWS_CODEGURU_PROFILER_HEAP_SUMMARY_ENABLED` – Optional. Set this variable to `true` to enable heap summary. The default is `false`. + `JAVA_TOOL_OPTIONS` – Set this variable to `-javaagent:/opt/codeguru-profiler-java-agent-standalone.jar`. For information about setting environment variables in the AWS Lambda console, see [Using AWS Lambda environment variables](https://docs.aws.amazon.com/lambda/latest/dg/configuration-envvars.html). Add a layer to your Lambda function using the following layer ARN. For more information on Lambda layers, see [AWS Lambda Layers](https://docs.aws.amazon.com/lambda/latest/dg/configuration-layers.html#configuration-layers-using). ``` arn:aws:lambda:LAMBDA-FUNCTION-REGION-CODE:157417159150:layer:AWSCodeGuruProfilerJavaAgentLayer:11 ``` For example, if your Lambda function is in Region `us-east-1`, then the ARN would be the following. ``` arn:aws:lambda:us-east-1:157417159150:layer:AWSCodeGuruProfilerJavaAgentLayer:11 ``` The CodeGuru Profiler heap summary is an optional feature that shows your application's heap usage over time. For more information on the heap summary, see [Understanding the heap summary](working-with-visualizations-heap-summary.md). Your Lambda function runs normally with the CodeGuru Profiler agent running in parallel. The agent submits your first profile after running for a total of 5 minutes. Processing can take up to 15 minutes. # Enabling the agent from the command line The command line option for integrating the CodeGuru Profiler agent is the easiest way to start profiling your application, because it doesn't require recompiling and redeploying your application. Add the appropriate command line options to your JVM-based runtime environment and you’re ready to go. ## Installation Download the [Amazon CodeGuru Profiler agent .jar file](https://d1osg35nybn3tt.cloudfront.net/com/amazonaws/codeguru-profiler-java-agent-standalone/1.2.4/codeguru-profiler-java-agent-standalone-1.2.4.jar). Save this to a location that is accessible from your JVM-based application. ## Configuration The only required configuration option to start the CodeGuru Profiler agent is the profiling group name. You can find this in the **Settings** section of your profiling group on the CodeGuru Profiler console. You can use the credential path parameter to have the agent use credentials that are different from the default credentials. The path must point to a valid AWS credentials file. For more information about credentials, see [Configuration and credential file settings](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html). The CodeGuru Profiler heap summary shows your application's heap usage over time. For more information on the heap summary, see [Understanding the heap summary](working-with-visualizations-heap-summary.md). Opt in to heap summary data collection by adding `heapSummaryEnabled:true`. The following example shows how to enable heap summary collection. ``` -javaagent:/path/to/codeguru-profiler-java-agent-standalone-1.2.4.jar="profilingGroupName:myProfilingGroup,heapSummaryEnabled:true" ``` You can specify these options as an environment variable or as a command line option. | Option | Environment variable | Command line option | | --- | --- | --- | | Profiling group name (required) | `AWS_CODEGURU_PROFILER_GROUP_NAME` | `profilingGroupName` | | Credential path | `AWS_CODEGURU_PROFILER_CREDENTIAL_PATH` | `credentialPath` | | Region | `AWS_CODEGURU_PROFILER_TARGET_REGION` | `region` | | Heap summary data collection | `AWS_CODEGURU_PROFILER_HEAP_SUMMARY_ENABLED` | `heapSummaryEnabled` | Your startup script using environment variables might look like the following. ``` #!/bin/bash export AWS_CODEGURU_PROFILER_GROUP_NAME=MyProfilingGroup export AWS_CODEGURU_PROFILER_TARGET_REGION=us-west-2 java -javaagent:/path/to/codeguru-profiler-java-agent-standalone-1.2.4.jar -jar MyApplication.jar ``` Alternatively, you can specify the configuration options by using the command line directly, as follows. ``` java -javaagent:/path/to/codeguru-profiler-java-agent-standalone-1.2.4.jar=profilingGroupName:MyProfilingGroup,region:us-west-2 -jar MyApplication.jar ``` The argument string can contain multiple parameters. Separate parameters with a comma (`,`). Each parameter is a key-value pair. **Note** Your command must either be on one continuous line or a line-continuation option appropriate for your command shell. ## Supported runtime environments Most JVM-based application runtime environments support a mechanism to specify and customize JVM startup parameters to include the CodeGuru Profiler agent in the runtime startup. This section summarizes some of the popular runtime environments that we have verified to support this option. All the examples assume that you have set the profiling group name with an environment variable: `export AWS_CODEGURU_PROFILER_GROUP_NAME=MyProfilingGroupName`. **Topics** + [Java](#javaagent-java) + [Scala](#javaagent-scala) + [Jython](#javaagent-jython) + [ColdFusion](#javaagent-coldfusion) + [Geronimo](#javaagent-geronimo) + [SOLR](#javaagent-solr) + [Tomcat](#javaagent-tomcat) + [Glassfish](#javaagent-glassfish) + [Grails](#javaagent-grails) + [Jetty](#javaagent-jetty) + [Play](#javaagent-play) + [Resin](#javaagent-resin) + [Spring Boot](#javaagent-spring-boot) + [Tanuki Wrapper](#javaagent-tanuki-wrapper) + [Websphere Liberty Profile](#javaagent-websphere) + [Spark](#javaagent-spark) + [Other runtime environments](#javaagent-other) ### Java If you start your application using the `java` command, you can enable the CodeGuru Profiler agent in your application by adding the following `-javaagent` command line option. ``` java -javaagent:/path/to/codeguru-profiler-java-agent-standalone-1.2.4.jar -jar MyApplication.jar ``` ### Scala If you start your application using the `scala` command, you can enable the CodeGuru Profiler agent in your application by adding the following `-J-javaagent` command line option. ``` scala -J-javaagent:/path/to/codeguru-profiler-java-agent-standalone-1.2.4.jar -jar MyScalaApplication.jar ``` ### Jython If you start your application using the `Jython` command, you can enable the CodeGuru Profiler agent in your application by adding the following `-J-javaagent` command line option. ``` jython -J-javaagent:/path/to/codeguru-profiler-java-agent-standalone-1.2.4.jar -jar MyJythonApplication.jar ``` ### ColdFusion Enable profiling for ColdFusion applications by adding the `-javaagent` option to the JVM parameters in the administrator console. 1. Navigate to your ColdFusion administrator console. 1. From the left menu, choose **SERVER SETTINGS**. 1. From the top bar, choose **Java and JVM**. 1. In the **JVM Arguments** field, add the following `-javaagent` argument. ``` -javaagent:/path/to/codeguru-profiler-java-agent-standalone-1.2.4.jar ``` 1. Choose **Submit changes**, then restart your ColdFusion server. ### Geronimo Add the CodeGuru Profiler agent to the Geronimo startup options by adding the `-javaagent` command line option to the `JAVA_OPTS` environment variable before starting your Geronimo instance. ``` export JAVA_OPTS="$JAVA_OPTS -javaagent:/path/to/codeguru-profiler-java-agent-standalone-1.2.4.jar" geronimo run ``` ### SOLR Add the `-javaagent` command line option to the `SOLR_OPTS` variable in your SOLR startup configuration script, `/path/to/solr/bin/solr.in.sh`, by appending the following lines to it and adjusting them to your environment. ``` SOLR_OPTS="$SOLR_OPTS -javaagent:/path/to/codeguru-profiler-java-agent-standalone-1.2.4.jar" ``` ### Tomcat Add the `-javaagent` command line option to the `JAVA_HOME` environment variable in Tomcat’s startup script, `/path/to/tomcat/bin/catalina.sh`. ``` JAVA_OPTS="$JAVA_OPTS -javaagent:/path/to/codeguru-profiler-java-agent-standalone-1.2.4.jar" ``` ### Glassfish 1. Add `-javaagent:~/codeguru-profiler-java-agent-standalone-1.2.4.jar` below the `java-config` tag. 1. Start your domain, `./bin/asadmin start-domain domain1`. If you have JDK version 1.8 or later and are running Glassfish version 5.0 or later, you receive the following error. ``` java.lang.NoSuchMethodError: sun.security.ssl.Handshaker.receiveChangeCipherSpec() ``` ### Grails 1. Add the following to `/appName/build.groovy`. ``` tasks.withType(JavaExec) { jvmArgs "-javaagent:/path/to/codeguru-profiler-java-agent-standalone-1.2.4.jar" } ``` 1. Start the **grails run-app** application. ### Jetty + Append `-javaagent:~/codeguru-profiler-java-agent-standalone-1.2.4.jar` to the startup script. ### Play + Append the following to your startup script, and then run the following. ``` ./sbt -J-javaagent:~/codeguru-profiler-java-agent-standalone-1.2.4.jar "run 8080" ``` ### Resin + Add the following to your configuration file. ``` -javaagent:~/codeguru-profiler-java-agent-standalone-1.2.4.jar ``` ### Spring Boot + Run the server with the `javaagent`. ``` java -javaagent:~/codeguru-profiler-java-agent-standalone-1.2.4.jar -jar demo-0.0.1-SNAPSHOT.jar ``` ### Tanuki Wrapper + Add the following code to `wrapper.conf`. ``` =-javaagent:~/codeguru-profiler-java-agent-standalone-1.2.4.jar ``` ### Websphere Liberty Profile + Append the following path to `jvm.options`. ``` -javaagent:~/codeguru-profiler-java-agent-standalone-1.2.4.jar ``` ### Spark There is a Spark plugin to profile with CodeGuru Profiler. See [A new Spark plugin for CPU and memory profiling](https://aws.amazon.com/blogs/devops/a-new-spark-plugin-for-cpu-and-memory-profiling/). CodeGuru Profiler supports Spark, but does not have `-javaagent` support. The agent is part of your .jar package file when you use CodeGuru Profiler in Spark. It doesn't matter if the agent is the worker or the primary as long as your code takes care of starting and stopping the agent when a job begins and ends. If a job is shorter than one minute, the agent won't report recommendations. To provide enough samples per worker, run the agent on long-running jobs. see [Enabling the agent with code](enabling-the-agent-with-code.md) ### Other runtime environments You can start any Java-based application by using the `-javaagent` command line option. If your runtime environment or hosting environment uses Java, consult your documentation to see how to customize the startup parameters for Java. # Enabling the agent with code You can enable the Amazon CodeGuru Profiler agent in your application by adding code inside the startup routine of your application. In addition to adding code, you also need to add a dependency to the agent library in your build steps. For this you can use a package manager such as Maven or Gradle. ## Installation To include the agent in your application, you need to tell your build system how to access the agent library. You can do this manually by adding a dependency in your Maven or Gradle configuration files. ### Maven To add a dependency to the agent, add the following sections to your pom.xml file. if you already have a `repositories` or `dependencies` element in your POM, add the individual `repositories` or `dependencies` elements inside the existing outer elements. ``` ... codeguru-profiler codeguru-profiler https://d1osg35nybn3tt.cloudfront.net ... com.amazonaws codeguru-profiler-java-agent 1.2.4 ... ``` For more information about configuring repositories in Maven, see [Setting up Multiple Repositories](https://maven.apache.org/guides/mini/guide-multiple-repositories.html) in the Maven documentation. ### Gradle To add a dependency to the agent, add the following sections to your Gradle file. If you already have a `repositories` or `dependencies` element in your Gradle file, add the individual subelements into the existing outer elements. ``` repositories { maven { url = uri("https://d1osg35nybn3tt.cloudfront.net") } } dependencies { implementation("com.amazonaws:codeguru-profiler-java-agent:1.2.4") } ``` For more information about creating a custom Gradle repository, see [ Declaring a custom repository by URL](https://docs.gradle.org/current/userguide/declaring_repositories.html#sec:declaring_custom_repository). For examples, see examples 18 and 19 in [ Supported repository transport protocols](https://docs.gradle.org/current/userguide/declaring_repositories.html#sec:plugin-vs-build-repos). ## Configuration You can configure the agent by using explicit API calls to the `Profiler.Builder` class. The following table shows the available options. The profiling group name is required to start the CodeGuru Profiler agent. The CodeGuru Profiler heap summary shows your application's heap usage over time. For more information on the heap summary, see [Understanding the heap summary](working-with-visualizations-heap-summary.md). **Important** It is not recommended to enable heap summary data collection in your production environments, as it might increase latency in your application. | Type | API call | | --- | --- | | Profiling group name (required) | `.profilingGroupName(String)` | | AWS Credentials Provider | `.awsCredentialsProvider(AwsCredentialsProvider)` | | Region | `.awsRegionToReportTo(Region)` | | Heap summary data collection (optional) | `.withHeapSummary(Boolean)` | The following is an example of command line API calls. ``` Profiler.builder() .profilingGroupName(“MyProfilingGroup”) .withHeapSummary(true) // optional - to start without heap profiling, set to false or remove line
 .build() .start(); ``` We recommend that you configure and start the agent inside the startup or `main` function. The following example shows how to add the configuration to the `main` function. ``` import software.amazon.codeguruprofilerjavaagent.Profiler; class MyApplication { public static void main(String[] args) { Profiler.builder() .profilingGroupName("MyProfilingGroup") .withHeapSummary(true) .build() .start(); ... } } ``` If you don't have access to a startup or `main` function, you can add a static initializer to your `main` class to configure and start the agent. This configures and starts the agent during the first time your application class is used inside the application container, as shown in the following example. ``` import software.amazon.codeguruprofilerjavaagent.Profiler; class MyClass { static { Profiler.builder() .profilingGroupName("MyProfilingGroup") .build() .start(); } ... } ``` When your application is running, data is available in the CodeGuru Profiler console. To view your profiling data, choose **Profiler** in the navigation pane, choose **Profiling groups**, and then select your profiling group. After your application has run for more than 15 minutes, data is available for you to visualize. For example, you can use an **Overview** visualization to identify code paths that are executed frequently. For more information about visualizations, see [Working with visualizations](working-with-visualizations.md). When your application has run for an hour, the first **Recommendations** report is available. After the first report, new reports are generated hourly. For more information, see [Working with anomalies and recommendation reports](working-with-recommendation-reports.md). **Note** If you don't want to use the default credentials to run the profiler, you can provide custom credentials by using following code. For more information about custom credentials, see [Supplying and Retrieving AWS Credentials](https://docs.aws.amazon.com/sdk-for-java/v2/developer-guide/credentials.html). ``` public static void main(String[] args) { Profiler.builder() .profilingGroupName("MyProfilingGroup") .awsCredentialsProvider(myAwsCredentialsProvider).build().start(); } ``` ## Supported languages The following topics provide code that you can add to your application to enable the Amazon CodeGuru Profiler agent. **Topics** + [Java](java-language-support.md) + [Scala](scala-language-support.md) + [Kotlin](kotlin-language-support.md) + [Groovy](groovy-language-support.md) + [Jython](jython-language-support.md) + [JRuby](jruby-language-support.md) + [Clojure](clojure-language-support.md) # Java You can add support for the CodeGuru Profiler agent into your Java application by adding the following lines into your startup or `main` function. ``` import software.amazon.codeguruprofilerjavaagent.Profiler; class MyClass { public static void main(String[] args) { Profiler.builder() .profilingGroupName("MyProfilingGroup") .build() .start(); ... } } ``` You need to [add a dependency](enabling-the-agent-with-code.md) to the agent .jar file. # Scala You can add support for the CodeGuru Profiler agent into your Scala application by adding the following lines into your startup or `main` function. ``` import software.amazon.codeguruprofilerjavaagent.Profiler object MyObject { def main(args: Array[String]) = { Profiler.builder() .profilingGroupName("MyProfilingGroup") .build() .start() ... } } ``` you need to [add a dependency](enabling-the-agent-with-code.md) to the agent .jar file. # Kotlin You can add support for the CodeGuru Profiler agent into your Kotlin application by adding the following lines into your startup or `main` function. ``` import software.amazon.codeguruprofilerjavaagent.Profiler fun main() { Profiler.builder() .profilingGroupName("MyProfilingGroup") .build() .start() ... } ``` You need to [add a dependency](enabling-the-agent-with-code.md) to the agent .jar file. # Groovy You can add support for the CodeGuru Profiler agent into your Groovy application by adding the following lines into your startup or `main` function. ``` import software.amazon.codeguruprofilerjavaagent.Profiler Profiler.builder() .profilingGroupName("MyProfilingGroup") .build() .start() ... ``` You need to [add a dependency](enabling-the-agent-with-code.md) to the agent .jar file. # Jython You can add support for the CodeGuru Profiler agent into your Jython application by adding the following lines into your startup or `main` function. ``` import sys sys.path.append("/path/to/codeguru-profiler-java-agent-1.2.4.jar") from software.amazon.codeguruprofilerjavaagent import Profiler Profiler.builder() .profilingGroupName("MyProfilingGroup") .build() .start() ... ``` You need to [add a dependency](enabling-the-agent-with-code.md) to the agent .jar file. # JRuby You can add support for the CodeGuru Profiler agent into your JRuby application by adding the following lines into your startup or `main` function. ``` Java::SoftwareAmazonCodeguruprofilerjavaagent::Profiler .builder .profiling_group_name("MyProfilingGroup") .aws_credentials_provider(myAwsCredentialsProvider) # optional .build .start ... ``` You need to [add a dependency](enabling-the-agent-with-code.md) to the agent .jar file. # Clojure You can add support for the CodeGuru Profiler agent into your Clojure application by adding the following lines into your startup or `main` function. ``` (-> (software.amazon.codeguruprofilerjavaagent.Profiler/builder) (.profilingGroupName "MyProfilingGroup") (.awsCredentialsProvider myAwsCredentialsProvider) ; optional (.build) (.start)) ... ``` You need to [add a dependency](enabling-the-agent-with-code.md) to the agent .jar file.