diff --git a/docs/en/observability/apm/tab-widgets/install-agents.asciidoc b/docs/en/observability/apm/tab-widgets/install-agents.asciidoc index 20fd80bb47..71c9753bf2 100644 --- a/docs/en/observability/apm/tab-widgets/install-agents.asciidoc +++ b/docs/en/observability/apm/tab-widgets/install-agents.asciidoc @@ -1,5 +1,5 @@ // tag::android[] -*Add the agent to your project* +*1. Add the agent to your project* First, add the https://plugins.gradle.org/plugin/co.elastic.apm.android[Elastic APM agent plugin] to your application's `build.gradle` file as shown below: @@ -13,10 +13,10 @@ plugins { ---- <1> The Elastic plugin declaration must be added below the Android app plugin declaration (`com.android.application`) and below the Kotlin plugin declaration (if used). -*Configure the agent* +*2. Configure the agent* After adding the agent plugin, configure it. -A minimal configuration sets the Elastic APM Server endpoint as shown below: +A minimal configuration sets the Elastic APM integration endpoint as shown below: [source,groovy] ---- @@ -46,7 +46,7 @@ More info on API Keys {ref}/security-api-create-api-key.html[here]. NOTE: When both `secretToken` and `apiKey` are provided, apiKey has priority and secretToken is ignored. -*Initialize the agent* +*3. Initialize the agent* After syncing your project with the Gradle changes above, the Elastic APM agent needs to be initialized within your https://developer.android.com/reference/android/app/Application[Application class]. This example shows the simplest way to configure the agent: @@ -75,53 +75,41 @@ Read more in the {apm-android-ref}/intro.html[APM Android Agent Reference]. // end::android[] // tag::go[] -*Install the agent* +*1. Install the agent* -Install the {apm-agent} packages for Go. +Install the Elastic APM Go agent package using `go get`: -[source,go] +[source,bash] ---- -go get go.elastic.co/apm +go get -u go.elastic.co/apm/v2 ---- -*Configure the agent* +*2. Configure the agent* -Agents are libraries that run inside of your application process. -APM services are created programmatically based on the executable file name, or the `ELASTIC_APM_SERVICE_NAME` environment variable. +To simplify development and testing, +the agent defaults to sending data to the Elastic APM integration at `http://localhost:8200`. +To send data to an alternative location, you must configure `ELASTIC_APM_SERVER_URL`. [source,go] ---- -# Initialize using environment variables: +# The APM integration host and port +export ELASTIC_APM_SERVER_URL= -# Set the service name. Allowed characters: a-z, A-Z, 0-9, -, _, and space. -# If ELASTIC_APM_SERVICE_NAME is not specified, the executable name will be used. +# If you do not specify `ELASTIC_APM_SERVICE_NAME`, the Go agent will use the +# executable name. For example, if your executable is called "my-app.exe", then your +# service will be identified as "my-app". export ELASTIC_APM_SERVICE_NAME= -# Set custom APM Server URL. Default: http://localhost:8200. -export ELASTIC_APM_SERVER_URL= - -# Use if APM Server requires a token +# Secret tokens are used to authorize requests to the APM integration export ELASTIC_APM_SECRET_TOKEN= ---- -*Instrument your application* - -Instrument your Go application by using one of the provided instrumentation modules or by using the tracer API directly. +*3. Instrument your application* -[source,go] ----- -import ( - "net/http" - - "go.elastic.co/apm/module/apmhttp" -) +Instrumentation is the process of extending your application’s code to report trace data to Elastic APM. Go applications must be instrumented manually at the source code level. To instrument your applications, use one of the following approaches: -func main() { - mux := http.NewServeMux() - ... - http.ListenAndServe(":8080", apmhttp.Wrap(mux)) -} ----- +* {apm-go-ref-v}/builtin-modules.html[Built-in instrumentation modules]. +* {apm-go-ref-v}/custom-instrumentation.html[Custom instrumentation] and context propagation with the Go Agent API. *Learn more in the agent reference* @@ -135,46 +123,56 @@ func main() { // tag::ios[] -*Add the agent dependency to your project* +*1. Add the agent dependency to your project* -Add the Elastic APM iOS Agent as a -https://developer.apple.com/documentation/swift_packages/adding_package_dependencies_to_your_app[package dependency] -to your Xcode project or your `Package.swift`: +Add the Elastic APM iOS Agent to your Xcode project or your `Package.swift`. -[source,swift,linenums,highlight=2;10] +Here are instructions for adding a https://developer.apple.com/documentation/swift_packages/adding_package_dependencies_to_your_app[package dependency] to a standard Xcode project. + +Refer to https://developer.apple.com/documentation/xcode/creating_a_standalone_swift_package_with_xcode#3578941['Add a Dependency on Another Swift Package'] for details about adding dependencies to your `Package.swift`. +Here is a helpful code-snippet: + +[source,swift] ---- Package( dependencies:[ - .package(name: "iOSAgent", url: "git@github.com:elastic/apm-agent-ios.git", .branch("main")), + .package(name: "apm-agent-ios", url: "https://github.com/elastic/apm-agent-ios.git", from: "1.0.0"), ], targets:[ .target( name: "MyApp", dependencies: [ - .product(name: "iOSAgent", package: "iOSAgent") + .product(name: "ElasticApm", package: "apm-agent-ios") ] ), ]) ---- -*Initialize the agent* +*2. Initialize the agent* -If you're using `SwiftUI` to build your app, add the following to `App.swift`: +If you're using `SwiftUI` to build your app, add the following to your `App.swift`: -[source,swift,linenums,swift,highlight=2;7..12] +[source,swift] ---- import SwiftUI -import iOSAgent +import ElasticApm + +class AppDelegate : NSObject, UIApplicationDelegate { + func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey : Any]? = nil) -> Bool { + var config = AgentConfigBuilder() + .withServerUrl(URL(string:"http://127.0.0.1:8200")) <1> + .withSecretToken("") <2> + .build() + + ElasticApmAgent.start(with: config) + return true + } +} @main struct MyApp: App { + @UIApplicationDelegateAdaptor(AppDelegate.self) var appDelegate init() { - var config = AgentConfiguration() - config.collectorAddress = "127.0.0.1" <1> - config.collectorPort = 8200 <2> - config.collectorTLS = false <3> - config.secretToken = "" <4> - Agent.start(with: config) } var body: some Scene { WindowGroup { @@ -183,35 +181,29 @@ struct MyApp: App { } } ---- -<1> APM Server URL or IP address -<2> APM Server port number -<3> Enable TLS for Open telemetry exporters -<4> Set secret token for APM server connection +<1> The APM integration host and port +<2> Secret token for APM integration connection -If you're not using `SwiftUI`, you can add the same thing to your `AppDelegate` file: +If you're not using `SwiftUI`, you can alternatively add the same thing to your `AppDelegate.swift` file: -`AppDelegate.swift` -[source,swift,linenums,highlight=2;9..14] +[source,swift] ---- import UIKit -import iOSAgent +import ElasticApm @main class AppDelegate: UIResponder, UIApplicationDelegate { func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool { - var config = AgentConfiguration() - config.collectorAddress = "127.0.0.1" <1> - config.collectorPort = 8200 <2> - config.collectorTLS = false <3> - config.secretToken = "" <4> - Agent.start(with: config) +var config = AgentConfigBuilder() + .withServerUrl(URL(string:"http://127.0.0.1:8200")) <1> + .withSecretToken("") <2> + .build() + ElasticApmAgent.start(with: config) return true } } ---- -<1> APM Server URL or IP address -<2> APM Server port number -<3> Enable TLS for Open telemetry exporters -<4> Set secret token for APM server connection +<1> The APM integration host and port +<2> Secret token for APM integration connection *Learn more in the agent reference* @@ -222,92 +214,70 @@ Read more in the {apm-ios-ref}/intro.html[APM iOS Agent Reference]. // *************************************************** // tag::java[] +Manually set up and configure the agent with the `-javaagent` JVM option. No application code change is required, but this requires an +application restart. See below for more information on this setup method. -*Download the {apm-agent}* - -Download the agent jar from http://search.maven.org/#search%7Cga%7C1%7Ca%3Aelastic-apm-agent[Maven Central]. -Do not add the agent as a dependency to your application. - -*Start your application with the `javaagent` flag* +*1. Download the {apm-agent}* -Add the `-javaagent` flag and configure the agent with system properties. +The first step in getting started with the Elastic APM Java agent is to retrieve a copy of the agent JAR. +Java agent releases are published to https://repo.maven.apache.org/maven2/[Maven central]. In order to get a copy you can either: -* Set required service name -* Set custom APM Server URL (default: http://localhost:8200) -* Set the base package of your application - -[source,java] +- download the link:https://oss.sonatype.org/service/local/artifact/maven/redirect?r=releases&g=co.elastic.apm&a=elastic-apm-agent&v=LATEST[latest agent] +or link:https://mvnrepository.com/artifact/co.elastic.apm/elastic-apm-agent[previous releases] from Maven central. +- download with `curl`: ++ +[source,bash] ---- -java -javaagent:/path/to/elastic-apm-agent-.jar \ - -Delastic.apm.service_name=my-application \ - -Delastic.apm.server_urls=http://localhost:8200 \ - -Delastic.apm.secret_token= \ - -Delastic.apm.application_packages=org.example \ - -jar my-application.jar +curl -o 'elastic-apm-agent.jar' -L 'https://oss.sonatype.org/service/local/artifact/maven/redirect?r=releases&g=co.elastic.apm&a=elastic-apm-agent&v=LATEST' ---- -*Learn more in the agent reference* +*2. Add `-javaagent` flag* -* {apm-java-ref-v}/supported-technologies-details.html[Supported technologies] -* {apm-java-ref-v}/configuration.html[Advanced configuration] -// end::java[] +When starting your application, add the JVM flag `-javaagent:/path/to/elastic-apm-agent-.jar` -// *************************************************** -// *************************************************** +*3. Configure* -// tag::net[] -*Download the {apm-agent}* +Different application servers have different ways of setting the `-javaagent` flag and system properties. +Start your application (for example a Spring Boot application or other embedded servers) and add the `-javaagent` JVM flag. +Use the `-D` prefix to configure the agent using system properties: -Add the agent packages from https://www.nuget.org/packages?q=Elastic.apm[NuGet] to your .NET application. -There are multiple NuGet packages available for different use cases. - -For an ASP.NET Core application with Entity Framework Core, download the -https://www.nuget.org/packages/Elastic.Apm.NetCoreAll[Elastic.Apm.NetCoreAll] package. -This package will automatically add every agent component to your application. - -To minimize the number of dependencies, you can use the -https://www.nuget.org/packages/Elastic.Apm.AspNetCore[Elastic.Apm.AspNetCore] package for just ASP.NET Core monitoring, or the -https://www.nuget.org/packages/Elastic.Apm.EntityFrameworkCore[Elastic.Apm.EfCore] package for just Entity Framework Core monitoring. - -If you only want to use the public agent API for manual instrumentation, use the -https://www.nuget.org/packages/Elastic.Apm[Elastic.Apm] package. +[source,bash] +---- +java -javaagent:/path/to/elastic-apm-agent-.jar -Delastic.apm.service_name=my-cool-service -Delastic.apm.application_packages=org.example,org.another.example -Delastic.apm.server_url=http://127.0.0.1:8200 -jar my-application.jar +---- -*Add the agent to the application* +Refer to {apm-java-ref-v}/setup-javaagent.html[Manual setup with `-javaagent` flag] to learn more. -For an ASP.NET Core application with the `Elastic.Apm.NetCoreAll` package, -call the `UseAllElasticApm` method in the `Configure` method within the `Startup.cs` file: +*Alternate setup methods* -[source,dotnet] ----- -public class Startup -{ - public void Configure(IApplicationBuilder app, IHostingEnvironment env) - { - app.UseAllElasticApm(Configuration); - //…rest of the method - } - //…rest of the class -} ----- +* **Automatic setup with `apm-agent-attach-cli.jar`** + + Automatically set up the agent without needing to alter the configuration of your JVM or application server. This method requires no changes to application code + or JVM options, and allows attaching to a running JVM. Refer to the {apm-java-ref-v}/setup-attach-cli.html[Java agent documentation] for more information on this setup method. +* **Programmatic API setup to self-attach** + + Set up the agent with a one-line code change and an extra `apm-agent-attach` dependency. This method requires no changes to JVM options, and + the agent artifact is embedded within the packaged application binary. Refer to the {apm-java-ref-v}/setup-attach-api.html[Java agent documentation] for more information on this setup method. -Passing an `IConfiguration` instance is optional and by doing so, -the agent will read config settings through this `IConfiguration` instance, for example, -from the `appsettings.json` file: +// end::java[] -[source,json] ----- -{ - "ElasticApm": { - "SecretToken": "", - "ServerUrls": "http://localhost:8200", //Set custom APM Server URL (default: http://localhost:8200) - "ServiceName" : "MyApp", //allowed characters: a-z, A-Z, 0-9, -, _, and space. Default is the entry assembly of the application - } -} ----- +// *************************************************** +// *************************************************** -If you don’t pass an `IConfiguration` instance to the agent, for example, in a non-ASP.NET Core application, -you can configure the agent with environment variables. -See the agent reference for more information. +// tag::net[] +*Set up the {apm-agent}* + +The .NET agent can be added to an application in a few different ways: + +* **Profiler runtime instrumentation**: +The agent supports auto instrumentation without any code change and without +any recompilation of your projects. See {apm-dotnet-ref-v}/setup-auto-instrumentation.html[Profiler auto instrumentation]. +* **NuGet packages**: +The agent ships as a set of {apm-dotnet-ref-v}/packages.html[NuGet packages] available on https://nuget.org[nuget.org]. +You can add the Agent and specific instrumentations to a .NET application by +referencing one or more of these packages and following the package documentation. +* **Host startup hook**: +On .NET Core 3.0+ or .NET 5+, the agent supports auto instrumentation without any code change and without +any recompilation of your projects. See {apm-dotnet-ref-v}/setup-dotnet-net-core.html[Zero code change setup on .NET Core] +for more details. *Learn more in the agent reference* @@ -319,7 +289,7 @@ See the agent reference for more information. // *************************************************** // tag::node[] -*Install the {apm-agent}* +*1. Install the {apm-agent}* Install the {apm-agent} for Node.js as a dependency to your application. @@ -328,10 +298,13 @@ Install the {apm-agent} for Node.js as a dependency to your application. npm install elastic-apm-node --save ---- -*Configure the agent* +*2. Initialization* + +It's important that the agent is started before you require *any* other modules in your Node.js application - i.e. before `http` and before your router etc. -Agents are libraries that run inside of your application process. APM services are created programmatically based on the `serviceName`. -This agent supports a variety of frameworks but can also be used with your custom stack. +This means that you should probably require and start the agent in your application's main file (usually `index.js`, `server.js` or `app.js`). + +Here's a simple example of how Elastic APM is normally required and started: [source,js] ---- @@ -341,14 +314,19 @@ var apm = require('elastic-apm-node').start({ // Allowed characters: a-z, A-Z, 0-9, -, _, and space serviceName: '', - // Use if APM Server requires a token + // Use if APM integration requires a token secretToken: '', - // Set custom APM Server URL (default: http://localhost:8200) - serverUrl: '' + // Use if APM integration uses API keys for authentication + apiKey: '', + + // Set custom APM integration host and port (default: http://127.0.0.1:8200) + serverUrl: '', }) ---- +The agent will now monitor the performance of your application and record any uncaught exceptions. + *Learn more in the agent reference* * {apm-node-ref-v}/supported-technologies.html[Supported technologies] @@ -362,43 +340,70 @@ var apm = require('elastic-apm-node').start({ // tag::php[] -*Install the agent* +*1. Install the agent* -Install the PHP agent using one of the https://github.com/elastic/apm-agent-php/releases[published packages]. +Install the agent using one of the https://github.com/elastic/apm-agent-php/releases/latest[packages for supported platforms]. To use the RPM Package (RHEL/CentOS and Fedora): -[source,php] +[source,bash] ---- rpm -ivh .rpm ---- To use the DEB package (Debian and Ubuntu): -[source,php] +[source,bash] ---- dpkg -i .deb ---- To use the APK package (Alpine): -[source,php] +[source,bash] ---- apk add --allow-untrusted .apk ---- -If you can’t find your distribution, -you can install the agent by {apm-php-ref-v}/setup.html[building it from the source]. +If you can’t find your distribution, you can install the agent by building it from the source. +The following instructions will build the APM agent using the same docker environment that Elastic uses to build our official packages. + +NOTE: The agent is currently only available for Linux operating system. + +1. Download the agent source from https://github.com/elastic/apm-agent-php/. +2. Execute the following commands to build the agent and install it: + +[source,bash] +---- +cd apm-agent-php +# for linux glibc - libc distributions (Ubuntu, Redhat, etc) +export BUILD_ARCHITECTURE=linux-x86-64 +# for linux with musl - libc distributions (Alpine) +export BUILD_ARCHITECTURE=linuxmusl-x86-64 +# provide a path to php-config tool +export PHP_CONFIG=php-config + +# build extensions +make -f .ci/Makefile build + +# run extension tests +PHP_VERSION=`$PHP_CONFIG --version | cut -d'.' -f 1,2` make -f .ci/Makefile run-phpt-tests + +# install agent extensions +sudo cp agent/native/_build/${BUILD_ARCHITECTURE}-release/ext/elastic_apm-*.so `$PHP_CONFIG --extension-dir` -*Configure the agent* +# install automatic loader +sudo cp agent/native/_build/${BUILD_ARCHITECTURE}-release/loader/code/elastic_apm_loader.so `$PHP_CONFIG --extension-dir` +---- + +*2. Enable and configure the APM agent* -Configure your agent inside of the `php.ini` file: +Enable and configure your agent inside of the `php.ini` file: [source,ini] ---- -elastic_apm.server_url=http://localhost:8200 -elastic_apm.secret_token=SECRET_TOKEN -elastic_apm.service_name="My-service" +extension=elastic_apm_loader.so +elastic_apm.bootstrap_php_part_file=/agent/php/bootstrap_php_part.php ---- *Learn more in the agent reference* @@ -414,7 +419,7 @@ elastic_apm.service_name="My-service" // tag::python[] Django:: + -*Install the {apm-agent}* +*1. Install the {apm-agent}* + Install the {apm-agent} for Python as a dependency. + @@ -423,7 +428,7 @@ Install the {apm-agent} for Python as a dependency. $ pip install elastic-apm ---- + -*Configure the agent* +*2. Configure the agent* + Agents are libraries that run inside of your application process. APM services are created programmatically based on the `SERVICE_NAME`. @@ -441,10 +446,10 @@ ELASTIC_APM = { # a-z, A-Z, 0-9, -, _, and space 'SERVICE_NAME': '', - # Use if APM Server requires a token + # Use if APM integration requires a token 'SECRET_TOKEN': '', - # Set custom APM Server URL (default: http://localhost:8200) + # Set custom APM integration host and port (default: http://localhost:8200) 'SERVER_URL': '', } @@ -457,7 +462,7 @@ MIDDLEWARE = ( Flask:: + -*Install the {apm-agent}* +*1. Install the {apm-agent}* + Install the {apm-agent} for Python as a dependency. + @@ -466,7 +471,7 @@ Install the {apm-agent} for Python as a dependency. $ pip install elastic-apm[flask] ---- + -*Configure the agent* +*2. Configure the agent* + Agents are libraries that run inside of your application process. APM services are created programmatically based on the `SERVICE_NAME`. @@ -485,10 +490,10 @@ app.config['ELASTIC_APM'] = { # a-z, A-Z, 0-9, -, _, and space 'SERVICE_NAME': '', - # Use if APM Server requires a token + # Use if APM integration requires a token 'SECRET_TOKEN': '', - # Set custom APM Server URL (default: http://localhost:8200) + # Set custom APM integration host and port (default: http://localhost:8200) 'SERVER_URL': '', } @@ -506,7 +511,7 @@ apm = ElasticAPM(app) // *************************************************** // tag::ruby[] -*Install the {apm-agent}* +*1. Install the {apm-agent}* Add the agent to your Gemfile. @@ -514,7 +519,7 @@ Add the agent to your Gemfile. ---- gem 'elastic-apm' ---- -*Configure the agent* +*2. Configure the agent* Ruby on Rails:: + @@ -529,10 +534,10 @@ Configure the agent by creating the config file `config/elastic_apm.yml`: # Defaults to the name of your Rails app service_name: 'my-service' -# Use if APM Server requires a token +# Use if APM integration requires a token secret_token: '' -# Set custom APM Server URL (default: http://localhost:8200) +# Set custom APM integration host and port (default: http://localhost:8200) server_url: 'http://localhost:8200' ---- @@ -543,22 +548,22 @@ For Rack or a compatible framework, like Sinatra, include the middleware in your [source,ruby] ---- # config.ru - require 'sinatra/base' - class MySinatraApp < Sinatra::Base - use ElasticAPM::Middleware +app = lambda do |env| + [200, {'Content-Type' => 'text/plain'}, ['ok']] +end - # ... - end +# Wraps all requests in transactions and reports exceptions +use ElasticAPM::Middleware - ElasticAPM.start( - app: MySinatraApp, # required - config_file: '' # optional, defaults to config/elastic_apm.yml - ) +# Start an instance of the Agent +ElasticAPM.start(service_name: 'NothingButRack') - run MySinatraApp +run app - at_exit { ElasticAPM.stop } +# Gracefully stop the agent when process exits. +# Makes sure any pending transactions are sent. +at_exit { ElasticAPM.stop } ---- + *Create a config file* @@ -573,10 +578,10 @@ Create a config file config/elastic_apm.yml: # Defaults to the name of your Rack app's class. service_name: 'my-service' -# Use if APM Server requires a token +# Use if APM integration requires a token secret_token: '' -# Set custom APM Server URL (default: http://localhost:8200) +# Set custom APM integration host and port (default: http://localhost:8200) server_url: 'http://localhost:8200' ---- @@ -591,60 +596,75 @@ server_url: 'http://localhost:8200' // *************************************************** // tag::rum[] -*Enable Real User Monitoring support in APM Server* - -APM Server disables RUM support by default. -To enable it, set `apm-server.rum.enabled: true` in your APM Server configuration file. +*1. Enable Real User Monitoring (RUM)* -*Set up the agent* +RUM is disabled by default. Enable it by setting `Enable RUM` to `true`. -Once RUM support enabled, you can set up the RUM agent. -There are two ways to do this: add the agent as a dependency, -or set it up with ` + ---- -import { init as initApm } from '@elastic/apm-rum' -var apm = initApm({ - // Set required service name (allowed characters: a-z, A-Z, 0-9, -, _, and space) - serviceName: 'your-app-name', +_Asynchronous / Non-Blocking Pattern_ - // Set custom APM Server URL (default: http://localhost:8200) - serverUrl: '', +Loading the script asynchronously ensures the agent script will not block other +resources on the page, however, it will still block browsers `onload` event. - // Set service version (required for source map feature) - serviceVersion: '' -}) +[source,html] +---- + ---- -Framework integrations, like React or Angular, have custom dependencies. -See {apm-rum-ref-v}/framework-integrations.html[framework integrations] for more information. +_Using Bundlers_ -*Set up the agent with ` - +import { init as initApm } from '@elastic/apm-rum' + +const apm = initApm({ + + // Set required service name (allowed characters: a-z, A-Z, 0-9, -, _, and space) + serviceName: '', + + // Set custom APM integration host and port (default: http://localhost:8200) + serverUrl: 'http://localhost:8200', + + // Set service version (required for sourcemap feature) + serviceVersion: '' +}) ---- *Learn more in the agent reference*