Ingest application traces with Elastic Agent

Example security settings

For testing purposes, you can use the following settings to get started quickly, but make sure you properly secure the Elastic Stack before sending real data.

elasticsearch.yml example:

xpack.security.enabled: true
xpack.security.authc.api_key.enabled: true

kibana.yml example:

elasticsearch.username: "kibana_system" 
xpack.encryptedSavedObjects.encryptionKey: "something_at_least_32_characters"

Elastic Cloud runs a hosted version of Integrations Server that includes Fleet Server. No extra setup is required unless you want to scale your deployment.

To confirm that an Integrations Server is available in your deployment:

Don’t see the agent? Make sure your deployment includes an Integrations Server instance. This instance is required to use Fleet.

To deploy a self-managed Fleet Server, you install an Elastic Agent and enroll it in an agent policy containing the Fleet Server integration.

Notes:

If installation is successful, you’ll see confirmation that Fleet Server connected. Click Continue enrolling Elastic Agent to begin enrolling your agents in Fleet Server.

Install the agent

Install the APM agent packages for Go.

go get go.elastic.co/apm

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.

# Initialize using environment variables:

# 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.
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
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.

import (
	"net/http"

	"go.elastic.co/apm/module/apmhttp"
)

func main() {
	mux := http.NewServeMux()
	...
	http.ListenAndServe(":8080", apmhttp.Wrap(mux))
}

Learn more in the agent reference

Add the agent dependency to your project

Add the Elastic APM iOS Agent as a package dependency to your Xcode project or your Package.swift:

Package(
    dependencies:[
        .package(name: "iOSAgent", url: "[email protected]:elastic/apm-agent-ios.git", .branch("main")),
    ],
  targets:[
    .target(
        name: "MyApp",
        dependencies: [
            .product(name: "iOSAgent", package: "iOSAgent")
        ]
    ),
])

Initialize the agent

If you’re using SwiftUI to build your app, add the following to App.swift:

import SwiftUI
import iOSAgent

@main
struct MyApp: App {
    init() {
        var config = AgentConfiguration()
        config.collectorAddress = "127.0.0.1" 
        config.collectorPort = 8200 
        config.collectorTLS = false 
        config.secretToken = "<secret token>" 
        Agent.start(with: config)
    }
    var body: some Scene {
        WindowGroup {
            ContentView()
        }
    }
}

If you’re not using SwiftUI, you can add the same thing to your AppDelegate file:

AppDelegate.swift

import UIKit
import iOSAgent
@main
class AppDelegate: UIResponder, UIApplicationDelegate {
    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        var config = AgentConfiguration()
        config.collectorAddress = "127.0.0.1" 
        config.collectorPort = 8200 
        config.collectorTLS = false 
        config.secretToken = "<secret token>" 
        Agent.start(with: config)
        return true
    }
}

Download the APM agent

Download the agent jar from Maven Central. Do not add the agent as a dependency to your application.

Start your application with the javaagent flag

Add the -javaagent flag and configure the agent with system properties.

java -javaagent:/path/to/elastic-apm-agent-<version>.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

Learn more in the agent reference

Download the APM agent

Add the agent packages from 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 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 Elastic.Apm.AspNetCore package for just ASP.NET Core monitoring, or the 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 Elastic.Apm package.

Add the agent to the application

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:

public class Startup
{
  public void Configure(IApplicationBuilder app, IHostingEnvironment env)
  {
    app.UseAllElasticApm(Configuration);
    //…rest of the method
  }
  //…rest of the class
}

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:

{
    "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.

Learn more in the agent reference

Install the APM agent

Install the APM agent for Node.js as a dependency to your application.

npm install elastic-apm-node --save

Configure the agent

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.

// Add this to the VERY top of the first file loaded in your app
var apm = require('elastic-apm-node').start({
  // Override service name from package.json
  // Allowed characters: a-z, A-Z, 0-9, -, _, and space
  serviceName: '',

  // Use if APM Server requires a token
  secretToken: '',

  // Set custom APM Server URL (default: http://localhost:8200)
  serverUrl: ''
})

Learn more in the agent reference

Install the agent

Install the PHP agent using one of the published packages.

To use the RPM Package (RHEL/CentOS and Fedora):

rpm -ivh <package-file>.rpm

To use the DEB package (Debian and Ubuntu):

dpkg -i <package-file>.deb

To use the APK package (Alpine):

apk add --allow-untrusted <package-file>.apk

If you can’t find your distribution, you can install the agent by building it from the source.

Configure the agent

Configure your agent inside of the php.ini file:

elastic_apm.server_url=http://localhost:8200
elastic_apm.secret_token=SECRET_TOKEN
elastic_apm.service_name="My-service"

Learn more in the agent reference

Learn more in the agent reference

Install the APM agent

Add the agent to your Gemfile.

gem 'elastic-apm'

Configure the agent

Learn more in the agent reference

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.

Set up the agent

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 <script> tags.

Set up the agent as a dependency

You can install the agent as a dependency to your application with npm install @elastic/apm-rum --save.

The agent can then be initialized and configured in your application like this:

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',

  // Set custom APM Server URL (default: http://localhost:8200)
  serverUrl: '',

  // Set service version (required for source map feature)
  serviceVersion: ''
})

Framework integrations, like React or Angular, have custom dependencies. See framework integrations for more information.

Set up the agent with <script> tags

Alternatively, you can use <script> tags to set up and configure the agent. Add a <script> tag to the HTML page and use the elasticApm global object to load and initialize the agent. Don’t forget to download the latest version of the RUM agent from GitHub or UNPKG, and host the file on your Server/CDN before deploying to production.

<script src="https://your-cdn-host.com/path/to/elastic-apm-rum.umd.min.js" crossorigin></script>
<script>
  elasticApm.init({
    serviceName: 'your-app-name',
    serverUrl: 'http://localhost:8200',
  })
</script>

Learn more in the agent reference

To export traces and metrics to APM Server, instrument your services and applications with the OpenTelemetry API, SDK, or both. For example, if you are a Java developer, you need to instrument your Java app with the OpenTelemetry agent for Java. See the OpenTelemetry Instrumentation guides to download the OpenTelemetry Agent or SDK for your language.

Define the following environment variables to configure the OpenTelemetry agent and enable communication with Elastic APM.

export OTEL_RESOURCE_ATTRIBUTES=service.name=checkoutService,service.version=1.1,deployment.environment=production
export OTEL_EXPORTER_OTLP_ENDPOINT=https://apm_server_url:8200
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer an_apm_secret_token"
export OTEL_METRICS_EXPORTER="otlp" \
export OTEL_LOGS_EXPORTER="otlp" \
java -javaagent:/path/to/opentelemetry-javaagent-all.jar \
     -classpath lib/*:classes/ \
     com.mycompany.checkout.CheckoutServiceServer

Additional boostrap code may be required. See the Elastic OpenTelemetry guide for more information, configuration options, and limitations of this feature.