IMPORTANT: No additional bug fixes or documentation updates will be released for this version. For the latest information, see the current release documentation.

« Debugging APM

›

Public API

edit

Public API

edit

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

Agent life cycle

edit

Controlling when the agent starts and stops.

`ElasticAPM.start`

edit

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

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

config: An optional hash or ElasticAPM::Config instance with configuration options. See Configuration.

If you are using Ruby on Rails this is done automatically for you. If not see Getting started with Rack.

`ElasticAPM.stop`

edit

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

`ElasticAPM.running?`

edit

Returns whether the ElasticAPM Agent is currently running.

`ElasticAPM.agent`

edit

Returns the currently running agent or nil.

Instrumentation

edit

`ElasticAPM.current_transaction`

edit

Returns the current ElasticAPM::Transaction or nil.

`ElasticAPM.transaction`

edit

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

If called without a block you are expected to end the transaction yourself. If given a block, the code inside will be wrapped in a transaction.

You need to submit it yourself with transaction.submit(status).

# call with block
transaction = ElasticAPM.transaction('Do things') do
  do_work # ...
end # .done is called when block ends

transaction.submit(200)

# without block
transaction = ElasticAPM.transaction('Do things')
do_work
transaction.submit(200) # .submit(result) will also .done(result)

Arguments:

name: A name for your transaction. Transactions are grouped by name. Required.
type: A type for your transaction eg. db.postgresql.sql.
context:: An optional Context used to enrich the transaction with information about the current request.
&block: An optional block to wrap with the transaction. The block is passed the transaction as an optional argument.

Returns the transaction.

`ElasticAPM.span`

edit

Most transactions have nested spans signifying work of a specific sort eg. database queries or external web requests.

If given a block, wrap the code inside in a span. If not you are expected to close the span yourself with span.done(result).

ElasticAPM.transaction 'Do things' do
  ElasticAPM.span 'Do one of the things' do
    Database.query # ...
  end
end

Arguments:

name: A name for your span. Required.
type: The type of work eg. db.postgresql.query.
context: An instance of Span::Context.
include_stacktrace: Whether or not to collect a Stacktrace.
&block: An optional block to wrap with the span. The block is passed the span as an optional argument.

Return the span or the return value of the given block.

`ElasticAPM.build_context`

edit

Build a new Context from a Rack env.

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

Arguments:

rack_env: An instance of Rack::Env

Returns the built context.

Errors

edit

`ElasticAPM.report`

edit

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:

exception: An instance of Exception. Required.
handled: Whether the error was handled eg. wasn’t rescued and was represented to the user. Default: true.

Returns [ElasticAPM::Error].

`ElasticAPM.report_message`

edit

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:

message: A custom error string. Required.

Returns [ElasticAPM::Error].

Context

edit

`ElasticAPM.set_tag`

edit

Add a tag to the current transaction. Tags are basic key-value pairs that are indexed in your Elasticsearch database and therefore searchable.

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

Arguments:

key: A string key.
value: A string value.

Returns the set value.

Be aware that tags are indexed in Elasticsearch. Using too many unique keys will result in Mapping explosion.

`ElasticAPM.set_custom_context`

edit

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:

context: A hash of JSON-compatible key-values. Can be nested.

Returns current custom context.

`ElasticAPM.set_user`

edit

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

Arguments:

user: An object representing the user

Returns the given user

Data

edit

`ElasticAPM.add_filter`

edit

Provide a filter to transform payloads before sending.

Arguments:

key: A unique key identifying the filter
callable: An object or proc (responds to .call(payload))

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