API reference

Although most usage is covered automatically, Elastic APM also has a public API that allows custom usage.

Controlling when the agent starts and stops.

To create and start an ElasticAPM agent use ElasticAPM.start:

ElasticAPM.start(server_url: 'http://localhost:8200')

If you are using Ruby on Rails this is done automatically for you. If you choose not to require the elastic_apm gem and instead want to start the agent and hook into Rails manually, see hooking into Rails explicitly. If you’re not using Rails, see Getting started with Rack.

Stop the currently running agent. Use this inside at_exit in your Rack app to gracefully shut down.

If the agent is already running, this method will stop and start the agent.

If the agent is not already running, this method will start the agent.

A config can be passed to the method that will be used to start the agent. If the agent is already running and no config is passed to the #restart method, the running agent’s config will be used.

Returns whether the ElasticAPM Agent is currently running.

Returns the currently running agent or nil.

Returns the current ElasticAPM::Transaction or nil.

Start a transaction eg. an incoming web request or a background job.

# call with block
ElasticAPM.start_transaction('Name')
do_work # ...
ElasticAPM.end_transaction('result')

Arguments:

Returns the transaction.

Ends the currently running transaction.

Arguments:

Wrap a block in a Transaction, starting and ending around the block

ElasticAPM.with_transaction 'Do things' do |transaction|
  do_work # ...

  transaction.result = 'success'
end

Arguments:

Returns the return value of the given block.

Start a new span.

ElasticAPM.with_transaction 'Do things' do
  ElasticAPM.start_span 'Do one of the things'
  Database.query # ...
  ElasticAPM.end_span
end

Arguments:

Returns the created span.

If you’d like to create an asynchronous span, you have to pass the parent Span or Transaction to the start_span method. You can also set the sync flag to false, if you’d like the span to be marked as asynchronous. This has no effect other than being queryable in Elasticsearch.

transaction = ElasticAPM.current_transaction # or start one with `.start_transaction`
Thread.new do
  ElasticAPM.start_span(
    'job 1',
    parent: transaction,
    sync: false
  ) { Worker.perform }
  ElasticAPM.end_span
end

Ends the currently running span.

Wraps a block in a Span.

Arguments:

Returns the return value of the given block.

If you’d like to create an asynchronous span, you have to pass the parent Span or Transaction to the with_span method. You can also set the sync flag to false, if you’d like the span to be marked as asynchronous.

transaction = ElasticAPM.current_transaction # or start one with `.start_transaction`
Thread.new do
  ElasticAPM.with_span(
    'job 1',
    parent: transaction,
    sync: false
  ) { Worker.perform }
end

Build a new Context from a Rack env.

A context provides information about the current request, response, user and more.

Arguments:

Returns the built context.

Start the agent and hook into Rails manually. This is useful if you skip requiring the gem and using the Railtie.

ElasticAPM::Rails.start(server_url: 'http://localhost:8200')

Start the agent and hook into Sinatra.

ElasticAPM::Sinatra.start(MySinatraApp, server_url: 'http://localhost:8200')

Start the agent and hook into Grape.

ElasticAPM::Grape.start(MyGrapeApp, server_url: 'http://localhost:8200')

Send an Exception to Elastic APM.

If reported inside a transaction, the context from that will be added.

begin
  do_a_thing_and_fail
rescue Exception => e
  ElasticAPM.report(e)
end

Arguments:

Returns [String] ID of the generated [ElasticAPM::Error] object.

Send a custom message to Elastic APM.

If reported inside a transaction, the context from that will be added.

ElasticAPM.report_message('This should probably never happen?!')

Arguments:

Returns [String] ID of the generated [ElasticAPM::Error] object.

Add a label to the current transaction. Labels are basic key-value pairs that are indexed in your Elasticsearch database and therefore searchable. The value can be a string, nil, numeric or boolean.

before_action do
  ElasticAPM.set_label(:company_id, current_user.company.id)
end

Arguments:

Returns the set value.

Add custom context to the current transaction. Use this to further specify a context that will help you track or diagnose what’s going on inside your app.

If called several times during a transaction the custom context will be destructively merged with merge!.

before_action do
  ElasticAPM.set_custom_context(company: current_user.company.to_h)
end

Arguments:

Returns current custom context.

Add the current user to the current transaction’s context.

Arguments:

Returns the given user

Provide a filter to transform payloads before sending.

Arguments:

Return the altered payload.

If nil is returned all subsequent filters will be skipped and the post request cancelled.

Example:

ElasticAPM.add_filter(:filter_pings) do |payload|
  payload[:transactions]&.reject! do |t|
    t[:name] == 'PingsController#index'
  end
  payload
end

ElasticAPM.transaction returns a Transaction (if the agent is running).

Whether the transaction is sampled eg. it includes stacktraces for its spans.

If the transaction does not have a parent-ID yet, calling this method generates a new ID, sets it as the parent-ID of this transaction, and returns it as a String.

This enables the correlation of the spans the JavaScript Real User Monitoring (RUM) agent creates for the initial page load with the transaction of the backend service.

If your service generates the HTML page dynamically, initializing the JavaScript RUM agent with the value of this method allows analyzing the time spent in the browser vs in the backend services.

To enable the JavaScript RUM agent, initialize the RUM agent with the Ruby agent’s current transaction:

<script src="elastic-apm-js-base/dist/bundles/elastic-apm-js-base.umd.min.js"></script>
<script>
  var elasticApm = initApm({
    serviceName: '',
    serverUrl: 'http://localhost:8200',
    pageLoadTraceId: "<%= ElasticAPM.current_transaction&.trace_id %>",
    pageLoadSpanId: "<%= ElasticAPM.current_transaction&.ensure_parent_id %>",
    pageLoadSampled: <%= ElasticAPM.current_transaction&.sampled? %>
  })
</script>

See the JavaScript RUM agent documentation for more information.