elastic-apm 4.7.3 → 4.8.0

data/docs/advanced.asciidoc

@@ -1,14 +0,0 @@
-ifdef::env-github[]
-NOTE: For the best reading experience,
-please view this documentation at
-https://www.elastic.co/guide/en/apm/agent/ruby/current/introduction.html[elastic.co]
-endif::[]
-
-[[advanced]]
-== Advanced Topics
-
-* <<context>>
-* <<custom-instrumentation>>
-
-include::./context.asciidoc[]
-include::./custom-instrumentation.asciidoc[]

data/docs/api.asciidoc

@@ -1,487 +0,0 @@
-ifdef::env-github[]
-NOTE: For the best reading experience,
-please view this documentation at
-https://www.elastic.co/guide/en/apm/agent/ruby/current/introduction.html[elastic.co]
-endif::[]
-
-[[api]]
-== API reference
-
-Although most usage is covered automatically, Elastic APM also has a public
-API that allows custom usage.
-
-[float]
-[[agent-life-cycle]]
-=== Agent life cycle
-
-Controlling when the agent starts and stops.
-
-[float]
-[[api-agent-start]]
-==== `ElasticAPM.start`
-
-To create and start an ElasticAPM agent use `ElasticAPM.start`:
-
-[source,ruby]
-----
-ElasticAPM.start(server_url: 'http://localhost:8200')
-----
-
-  * `config`: An optional hash or `ElasticAPM::Config` instance with configuration
-  options.  See <<configuration,Configuration>>.
-
-If you are using <<getting-started-rails,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 <<rails-start,hooking into Rails explicitly>>.
-If you're not using Rails, see <<getting-started-rack,Getting started with Rack>>.
-
-[float]
-[[api-agent-stop]]
-==== `ElasticAPM.stop`
-
-Stop the currently running agent. Use this inside `at_exit` in your
-<<getting-started-rack,Rack app>> to gracefully shut down.
-
-[float]
-[[api-agent-restart]]
-==== `ElasticAPM.restart`
-
-If the agent is already running, this method will stop and start the agent.
-
-If the agent is not already running, this method will start the agent.
-
-A config can be passed to the method that will be used to start the agent. If the agent
-is already running and no config is passed to the `#restart` method, the running agent's
-config will be used.
-
-[float]
-[[api-agent-running]]
-==== `ElasticAPM.running?`
-
-Returns whether the ElasticAPM Agent is currently running.
-
-[float]
-[[api-agent-agent]]
-==== `ElasticAPM.agent`
-
-Returns the currently running agent or nil.
-
-[float]
-=== Instrumentation
-
-[float]
-[[api-agent-current-transaction]]
-==== `ElasticAPM.current_transaction`
-
-Returns the current `ElasticAPM::Transaction` or nil.
-
-[float]
-[[api-agent-start_transaction]]
-==== `ElasticAPM.start_transaction`
-
-Start a _transaction_ eg. an incoming web request or a background job.
-
-[source,ruby]
-----
-# 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 <<api-context,Context>> used to enrich the
-  transaction with information about the current request.
-  * `trace_context:`: An optional `TraceContext` object for Distributed Tracing.
-
-Returns the transaction.
-
-[float]
-[[api-agent-end_transaction]]
-==== `ElasticAPM.end_transaction`
-
-Ends the currently running transaction.
-
-Arguments:
-
-  * `result`: A `String` result of the transaction, eg. `'success'`.
-
-[float]
-[[api-agent-with_transaction]]
-==== `ElasticAPM.with_transaction`
-
-Wrap a block in a Transaction, starting and ending around the block
-
-[source,ruby]
-----
-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 <<api-context,Context>> used to enrich the
-  transaction with information about the current request.
-  * `trace_context:`: An optional `TraceContext` object for Distributed Tracing.
-  * `&block`: A block to wrap. Optionally yields the transaction.
-
-Returns the return value of the given block.
-
-[float]
-[[api-agent-start_span]]
-==== `ElasticAPM.start_span`
-
-Start a new span.
-
-[source,ruby]
-----
-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` or `query`.
-  * `context`: An instance of `Span::Context`.
-  * `include_stacktrace`: Whether or not to collect a Stacktrace.
-  * `trace_context:`: An optional `TraceContext` object for Distributed Tracing.
-  * `parent:`: An optional parent transaction or span. Relevant when the span is created in another thread.
-  * `sync:`: An boolean to indicate whether the span is created synchronously or not.
-  * `&block`: An optional block to wrap with the span.
-  The block is passed the span as an optional argument.
-
-Returns the created span.
-
-If you'd like to create an asynchronous span, you have to pass the parent `Span` or `Transaction` to the `start_span` method.
-You can also set the `sync` flag to `false`, if you'd like the span to be marked as asynchronous. This has no effect other than being queryable in Elasticsearch.
-
-[source,ruby]
-----
-transaction = ElasticAPM.current_transaction # or start one with `.start_transaction`
-Thread.new do
-  ElasticAPM.start_span(
-    'job 1',
-    parent: transaction,
-    sync: false
-  ) { Worker.perform }
-  ElasticAPM.end_span
-end
-----
-
-[float]
-[[api-agent-end_span]]
-==== `ElasticAPM.end_span`
-
-Ends the currently running span.
-
-[float]
-[[api-agent-with_span]]
-==== `ElasticAPM.with_span`
-
-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` or `query`.
-  * `context`: An instance of `Span::Context`.
-  * `include_stacktrace`: Whether or not to collect a Stacktrace.
-  * `trace_context:`: An optional `TraceContext` object for Distributed Tracing.
-  * `parent:`: An optional parent transaction or span. Relevant when the span is created in another thread.
-  * `sync:`: An boolean to indicate whether the span is created synchronously or not.
-  * `&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.
-
-If you'd like to create an asynchronous span, you have to pass the parent `Span` or `Transaction` to the `with_span` method.
-You can also set the `sync` flag to `false`, if you'd like the span to be marked as asynchronous.
-
-[source,ruby]
-----
-transaction = ElasticAPM.current_transaction # or start one with `.start_transaction`
-Thread.new do
-  ElasticAPM.with_span(
-    'job 1',
-    parent: transaction,
-    sync: false
-  ) { Worker.perform }
-end
-----
-
-[float]
-[[api-agent-build-context]]
-==== `ElasticAPM.build_context`
-
-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` or `error`
-
-Returns the built context.
-
-[float]
-[[rails-start]]
-=== Rails
-
-Start the agent and hook into Rails manually. This is useful if you skip requiring
-the gem and using the `Railtie`.
-
-[source,ruby]
-----
-ElasticAPM::Rails.start(server_url: 'http://localhost:8200')
-----
-
-[float]
-[[sinatra-start]]
-=== Sinatra
-
-Start the agent and hook into Sinatra.
-
-[source,ruby]
-----
-ElasticAPM::Sinatra.start(MySinatraApp, server_url: 'http://localhost:8200')
-----
-
-[float]
-[[grape-start]]
-=== Grape
-
-Start the agent and hook into Grape.
-
-[source,ruby]
-----
-ElasticAPM::Grape.start(MyGrapeApp, server_url: 'http://localhost:8200')
-----
-
-[float]
-=== Errors
-
-[float]
-[[api-agent-report]]
-==== `ElasticAPM.report`
-
-Send an `Exception` to Elastic APM.
-
-If reported inside a transaction, the context from that will be added.
-
-[source,ruby]
-----
-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 `[String]` ID of the generated `[ElasticAPM::Error]` object.
-
-[float]
-[[api-agent-report-message]]
-==== `ElasticAPM.report_message`
-
-Send a custom message to Elastic APM.
-
-If reported inside a transaction, the context from that will be added.
-
-[source,ruby]
-----
-ElasticAPM.report_message('This should probably never happen?!')
-----
-
-Arguments:
-
-  * `message`: A custom error string. **Required**.
-
-Returns `[String]` ID of the generated `[ElasticAPM::Error]` object.
-
-[float]
-[[api-context]]
-=== Context
-
-[float]
-[[api-agent-set-label]]
-==== `ElasticAPM.set_label`
-
-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.
-
-TIP: Before using custom labels, ensure you understand the different types of
-{apm-guide-ref}/data-model-metadata.html[metadata] that are available.
-
-[source,ruby]
-----
-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`.
-
-WARNING: Be aware that labels are indexed in Elasticsearch. Using too many unique keys will result in *https://www.elastic.co/blog/found-crash-elasticsearch#mapping-explosion[Mapping explosion]*.
-
-[float]
-[[api-agent-set-custom-context]]
-==== `ElasticAPM.set_custom_context`
-
-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.
-
-TIP: Before using custom context, ensure you understand the different types of
-{apm-guide-ref}/data-model-metadata.html[metadata] that are available.
-
-If called several times during a transaction the custom context will be destructively
-merged with `merge!`.
-
-[source,ruby]
-----
-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.
-
-[float]
-[[api-agent-set-user]]
-==== `ElasticAPM.set_user`
-
-Add the current user to the current transaction's context.
-
-Arguments:
-
-  * `user`: An object representing the user
-
-Returns the given user
-
-[float]
-=== Data
-
-[float]
-[[api-agent-add-filter]]
-==== `ElasticAPM.add_filter`
-
-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:
-
-[source,ruby]
-----
-ElasticAPM.add_filter(:filter_pings) do |payload|
-  payload[:transactions]&.reject! do |t|
-    t[:name] == 'PingsController#index'
-  end
-  payload
-end
-----
-
-[float]
-[[api-transaction]]
-=== Transaction
-
-`ElasticAPM.transaction` returns a `Transaction` (if the agent is running).
-
-[float]
-==== Properties
-
-- `name`: String
-- `type`: String
-- `result`: String
-- `outcome`: String ('unknown', 'success', 'failure', nil)
-- `trace_id`: String (readonly)
-
-[float]
-[[api-transaction-sampled_]]
-==== `#sampled?`
-
-Whether the transaction is _sampled_ eg. it includes stacktraces for its spans.
-
-[float]
-[[api-transaction-ensure_parent_id]]
-==== `#ensure_parent_id`
-
-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, initialize the RUM agent with the Ruby
-agent's current transaction:
-
-[source,html]
-----
-<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 {apm-rum-ref}[JavaScript RUM agent documentation] for more information.
-
-[float]
-[[api-span]]
-=== Span
-
-[float]
-==== Properties
-
-- `name`: String
-- `type`: String