API referenceedit
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 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.
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.start_transaction
edit
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
: Atype
for your transaction eg.db.postgresql.sql
. -
context:
: An optional Context used to enrich the transaction with information about the current request. -
trace_context:
: An optionalTraceContext
object for Distributed Tracing.
Returns the transaction.
ElasticAPM.end_transaction
edit
Ends the currently running transaction.
Arguments:
-
result
: AString
result of the transaction, eg.'success'
.
ElasticAPM.with_transaction
edit
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
: Atype
for your transaction eg.db.postgresql.sql
. -
context:
: An optional Context used to enrich the transaction with information about the current request. -
trace_context:
: An optionalTraceContext
object for Distributed Tracing. -
&block
: A block to wrap. Optionally yields the transaction.
Returns the return value of the given block.
ElasticAPM.start_span
edit
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 span eg.db
. -
subtype
: The subtype of span eg.postgresql
. -
action
: The action type of span eg.connect
orquery
. -
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.
Returns the created span.
ElasticAPM.end_span
edit
Ends the currently running span.
ElasticAPM.with_span
edit
Wraps a block in a Span.
Arguments:
-
name
: A name for your span. Required. -
type
: The type of span eg.db
. -
subtype
: The subtype of span eg.postgresql
. -
action
: The action type of span eg.connect
orquery
. -
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.
Returns 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 -
for_type
: Symbol representing type of event, eg.:transaction
orerror
Returns the built context.
Manually hooking into Railsedit
Start the agent and hook into Rails explicitly. This is useful if you skip requiring
the gem and using the Railtie
.
ElasticAPM::Rails.start(server_url: 'http://localhost:8200')
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 [String]
ID of the generated [ElasticAPM::Error]
object.
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 [String]
ID of the generated [ElasticAPM::Error]
object.
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. The value will always be converted to a String.
Before using custom tags, ensure you understand the different types of metadata that are available.
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
.
Be aware that tags are indexed in Elasticsearch. Using too many unique keys will result in Mapping explosion.
This method has been deprecated in favor of set_label
, which does not convert values to Strings.
ElasticAPM.set_label
edit
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 using custom labels, ensure you understand the different types of metadata that are available.
before_action do ElasticAPM.set_label(:company_id, current_user.company.id) end
Arguments:
-
key
: A string key. Note that.
,*
or"
will be converted to_
. -
value
: A value.
Returns the set value
.
Be aware that labels 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.
Before using custom context, ensure you understand the different types of metadata that are available.
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 -
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