Public APIedit

Although most usage is covered automatically when using the APM Agent it also has a public API that allows custom usage.

Agent life cycleedit

Controlling when the agent starts and stops.

ElasticAPM.startedit

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

ElasticAPM.start(server_url: 'http://localhost:8200')
  • config: A hash or ElasticAPM::Config instance with configuration options. See Configuration.

If you are using Rails this is done automatically for you.

ElasticAPM expects a single instance of the Agent.

ElasticAPM.stopedit

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

Returns the currently running agent or nil.

Instrumentationedit

ElasticAPM.current_transactionedit

Returns the current ElasticAPM::Transaction or nil.

ElasticAPM.transactionedit

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

If called without a block you are expected to end and submit the transaction yourself. If given a block, the code inside will be wrapped in a transaction. You still need to submit it yourself with transaction.submit(status).

transaction = ElasticAPM.transaction('Do things') do
  # ...
end

transaction.submit(200)

Arguments:

  • name: A name for your transaction. Transactions are grouped by name. Required.
  • type: A type for your transaction eg. db.postgresql.sql.
  • rack_env: env: An optional Rack env 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.spanedit

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.
  • &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_contextedit

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.

Errorsedit

ElasticAPM.reportedit

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_messageedit

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.
  • handled: Whether the error was handled eg. wasn’t rescued and was represented to the user. Default: true.

Returns [ElasticAPM::Error].

Contextedit

ElasticAPM.set_tagedit

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.

ElasticAPM.set_custom_contextedit

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_useredit

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

Arguments:

  • user: An object representing the user

Returns the given user