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.start
edit
To create and start an ElasticAPM agent use ElasticAPM.start
:
ElasticAPM.start(server_url: 'http://localhost:8200')
-
config
: An optional hash orElasticAPM::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.
Instrumentationedit
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
: Atype
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 ofSpan::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.
Errorsedit
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 ofException
. 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]
.
Contextedit
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
Dataedit
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
Transactionedit
ElasticAPM.transaction
returns a Transaction
(if the agent is running).
Propertiesedit
-
name
: String -
type
: String
#release
edit
Makes sure the transaction is no longer ElasticAPM.current_transaction
.
#done(result)
edit
Args:
-
result
: String result of transaction, eg.success
. Default:nil
.
Ends the transaction, settings its duration
to µs since it began and sets its result.
Returns self
.
#done?
edit
Returns whether the transaction is done.
#submit(result, status:, headers:)
edit
Args:
-
result
: String result of transaction, eg.success
. Default:nil
. -
status
: HTTP status code (for request transactions). Default:nil
. -
headers
: HTTP headers (for request transactions). Default:{}
.
Ends transaction with done, adds HTTP request information, releases it and submits it to the queue of transactions waiting to be sent to APM Server.
Returns self
.
#sampled?edit
Whether the transaction is sampled eg. it includes stacktraces for its spans.
Spanedit
Propertiesedit
-
name
: String -
type
: String
Contextedit
A Context
provides more information to transactions. Build one with ElasticAPM.build_context
.