Public APIedit

Although most usage is covered automatically, Elastic APM 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: 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.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.start_transactionedit

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:

  • 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.
  • traceparent:: An optional Traceparent object for Distributed Tracing.

Returns the transaction.

ElasticAPM.end_transactionedit

Ends the currently running transaction.

Arguments:

  • result: A String result of the transaction, eg. 'success'.

ElasticAPM.with_transactionedit

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:

  • 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.
  • traceparent:: An optional Traceparent object for Distributed Tracing.
  • &block: A block to wrap. Optionally yields the transaction.

Returns the return value of the given block.

ElasticAPM.start_spanedit

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:

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

Returns the created span.

ElasticAPM.end_spanedit

Ends the currently running span.

ElasticAPM.with_spanedit

Wraps a block in a Span.

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.

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

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. Note that ., * or " will be converted to _.
  • value: A string value.

Returns the set value.

Warning

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

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

Dataedit

ElasticAPM.add_filteredit

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

Transactionedit

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

Propertiesedit

  • name: String
  • type: String
  • result: String
  • trace_id: String (readonly)

#sampled?edit

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

#ensure_parent_idedit

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, initilialize the RUM agent with the Ruby agent’a 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.

Spanedit

Propertiesedit

  • name: String
  • type: String

Contextedit