API 参考

尽管大多数用法都是自动覆盖的，但 Elastic APM 还有一个公共 API，允许自定义用法。

控制代理何时启动和停止。

要创建和启动 ElasticAPM 代理，请使用 ElasticAPM.start

ElasticAPM.start(server_url: 'https://127.0.0.1:8200')

如果您正在使用Ruby on Rails，则会自动为您完成此操作。如果您选择不要求 elastic_apm gem，而是想手动启动代理并挂钩到 Rails，请参阅显式挂钩到 Rails。如果您未使用 Rails，请参阅Rack 入门。

停止当前正在运行的代理。在您的 Rack 应用中的 at_exit 中使用它以优雅地关闭。

如果代理已在运行，则此方法将停止并启动该代理。

如果代理尚未运行，则此方法将启动该代理。

可以将配置传递给该方法，该方法将用于启动代理。如果代理已在运行，并且没有将配置传递给 #restart 方法，则将使用正在运行的代理的配置。

返回 ElasticAPM 代理当前是否正在运行。

返回当前正在运行的代理，如果未运行则返回 nil。

返回当前的 ElasticAPM::Transaction，如果不存在则返回 nil。

启动一个事务，例如传入的 Web 请求或后台作业。

# call with block
ElasticAPM.start_transaction('Name')
do_work # ...
ElasticAPM.end_transaction('result')

参数

返回事务。

结束当前正在运行的事务。

参数

将块包装在事务中，并在块周围开始和结束

ElasticAPM.with_transaction 'Do things' do |transaction|
  do_work # ...

  transaction.result = 'success'
end

参数

返回给定块的返回值。

启动一个新的 span。

ElasticAPM.with_transaction 'Do things' do
  ElasticAPM.start_span 'Do one of the things'
  Database.query # ...
  ElasticAPM.end_span
end

参数

返回创建的 span。

如果您想创建异步 span，则必须将父 Span 或 Transaction 传递给 start_span 方法。如果您希望将 span 标记为异步，也可以将 sync 标志设置为 false。除了在 Elasticsearch 中可查询外，这没有任何影响。

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

结束当前正在运行的 span。

将块包装在 Span 中。

参数

返回给定块的返回值。

如果您想创建异步 span，则必须将父 Span 或 Transaction 传递给 with_span 方法。如果您希望将 span 标记为异步，也可以将 sync 标志设置为 false。

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

从 Rack env 构建一个新的上下文。

上下文提供有关当前请求、响应、用户等信息。

参数

返回构建的上下文。

手动启动代理并挂钩到 Rails。如果您跳过要求 gem 并使用 Railtie，这将很有用。

ElasticAPM::Rails.start(server_url: 'https://127.0.0.1:8200')

启动代理并挂钩到 Sinatra。

ElasticAPM::Sinatra.start(MySinatraApp, server_url: 'https://127.0.0.1:8200')

启动代理并挂钩到 Grape。

ElasticAPM::Grape.start(MyGrapeApp, server_url: 'https://127.0.0.1:8200')

将 Exception 发送到 Elastic APM。

如果在事务中报告，则会添加该事务中的上下文。

begin
  do_a_thing_and_fail
rescue Exception => e
  ElasticAPM.report(e)
end

参数

返回生成的 [ElasticAPM::Error] 对象的 [String] ID。

将自定义消息发送到 Elastic APM。

如果在事务中报告，则会添加该事务中的上下文。

ElasticAPM.report_message('This should probably never happen?!')

参数

返回生成的 [ElasticAPM::Error] 对象的 [String] ID。

向当前事务添加标签。标签是基本的键值对，在您的 Elasticsearch 数据库中被索引，因此可搜索。该值可以是字符串、nil、数字或布尔值。

before_action do
  ElasticAPM.set_label(:company_id, current_user.company.id)
end

参数

返回设置的 value。

将自定义上下文添加到当前事务。使用此方法进一步指定一个上下文，以帮助您跟踪或诊断应用程序内部发生的情况。

如果在事务期间多次调用，则自定义上下文将使用 merge! 进行破坏性合并。

before_action do
  ElasticAPM.set_custom_context(company: current_user.company.to_h)
end

参数

返回当前自定义上下文。

将当前用户添加到当前事务的上下文中。

参数

返回给定的用户

提供一个过滤器以在发送之前转换有效负载。

参数

返回更改后的有效负载。

如果返回 nil，则将跳过所有后续过滤器，并且将取消 post 请求。

示例

ElasticAPM.add_filter(:filter_pings) do |payload|
  payload[:transactions]&.reject! do |t|
    t[:name] == 'PingsController#index'
  end
  payload
end

ElasticAPM.transaction 返回一个 Transaction 对象（如果代理正在运行）。

表示事务是否被采样，例如，它是否包含其 Span 的堆栈跟踪。

如果事务尚未具有父 ID，则调用此方法会生成一个新的 ID，将其设置为此事务的父 ID，并将其作为 String 返回。

这使得可以将 JavaScript 真实用户监控 (RUM) 代理为初始页面加载创建的 Span 与后端服务的事务相关联。

如果您的服务动态生成 HTML 页面，则使用此方法的值初始化 JavaScript RUM 代理可以分析在浏览器中花费的时间与在后端服务中花费的时间。

要启用 JavaScript RUM 代理，请使用 Ruby 代理的当前事务初始化 RUM 代理

<script src="elastic-apm-js-base/dist/bundles/elastic-apm-js-base.umd.min.js"></script>
<script>
  var elasticApm = initApm({
    serviceName: '',
    serverUrl: 'https://127.0.0.1:8200',
    pageLoadTraceId: "<%= ElasticAPM.current_transaction&.trace_id %>",
    pageLoadSpanId: "<%= ElasticAPM.current_transaction&.ensure_parent_id %>",
    pageLoadSampled: <%= ElasticAPM.current_transaction&.sampled? %>
  })
</script>

有关更多信息，请参阅 JavaScript RUM 代理文档。