›

API 参考

API 参考编辑

虽然大多数用法都是自动覆盖的，但 Elastic APM 还提供了一个公共 API，允许自定义使用。

代理生命周期编辑

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

`ElasticAPM.start`编辑

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

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

config: 一个可选的哈希或 ElasticAPM::Config 实例，其中包含配置选项。请参阅配置。

如果您使用的是 Ruby on Rails，则会自动为您完成此操作。如果您选择不使用 elastic_apm gem，而是希望手动启动代理并连接到 Rails，请参阅显式连接到 Rails。如果您没有使用 Rails，请参阅 Rack 入门。

`ElasticAPM.stop`编辑

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

`ElasticAPM.restart`编辑

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

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

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

`ElasticAPM.running?`编辑

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

`ElasticAPM.agent`编辑

返回当前正在运行的代理或 nil。

仪器编辑

`ElasticAPM.current_transaction`编辑

返回当前的 ElasticAPM::Transaction 或 nil。

`ElasticAPM.start_transaction`编辑

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

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

参数

name: 事务的名称。事务按名称分组。必需.
type: 事务的 type，例如 db.postgresql.sql。
context:: 一个可选的上下文，用于使用有关当前请求的信息来丰富事务。
trace_context:: 用于分布式跟踪的可选 TraceContext 对象。

返回事务。

`ElasticAPM.end_transaction`编辑

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

参数

result: 事务的 String 结果，例如 'success'。

`ElasticAPM.with_transaction`编辑

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

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

  transaction.result = 'success'
end

参数

name: 事务的名称。事务按名称分组。必需.
type: 事务的 type，例如 db.postgresql.sql。
context:: 一个可选的上下文，用于使用有关当前请求的信息来丰富事务。
trace_context:: 用于分布式跟踪的可选 TraceContext 对象。
&block: 要包装的块。可以选择性地生成事务。

返回给定块的返回值。

`ElasticAPM.start_span`编辑

启动一个新的跨度。

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

参数

name: 跨度的名称。必需.
type: 跨度的类型，例如 db。
subtype: 跨度的子类型，例如 postgresql。
action: 跨度的操作类型，例如 connect 或 query。
context: Span::Context 的实例。
include_stacktrace: 是否收集堆栈跟踪。
trace_context:: 用于分布式跟踪的可选 TraceContext 对象。
parent:: 可选的父事务或跨度。当跨度在另一个线程中创建时相关。
sync:: 一个布尔值，用于指示跨度是同步创建还是异步创建。
&block: 一个可选的块，用于使用跨度包装。该块将跨度作为可选参数传递。

返回创建的跨度。

如果您想创建一个异步跨度，则必须将父 Span 或 Transaction 传递给 start_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

`ElasticAPM.end_span`编辑

结束当前正在运行的跨度。

`ElasticAPM.with_span`编辑

将一个块包装在一个跨度中。

参数

name: 跨度的名称。必需.
type: 跨度的类型，例如 db。
subtype: 跨度的子类型，例如 postgresql。
action: 跨度的操作类型，例如 connect 或 query。
context: Span::Context 的实例。
include_stacktrace: 是否收集堆栈跟踪。
trace_context:: 用于分布式跟踪的可选 TraceContext 对象。
parent:: 可选的父事务或跨度。当跨度在另一个线程中创建时相关。
sync:: 一个布尔值，用于指示跨度是同步创建还是异步创建。
&block: 一个可选的块，用于使用跨度包装。该块将跨度作为可选参数传递。

返回给定块的返回值。

如果您想创建一个异步跨度，则必须将父 Span 或 Transaction 传递给 with_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

`ElasticAPM.build_context`编辑

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

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

参数

rack_env: Rack::Env 的实例
for_type: 表示事件类型的符号，例如 :transaction 或 error

返回构建的上下文。

Rails编辑

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

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

Sinatra编辑

启动代理并连接到 Sinatra。

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

Grape编辑

启动代理并连接到 Grape。

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

错误编辑

`ElasticAPM.report`编辑

将 Exception 发送到 Elastic APM。

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

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

参数

exception: Exception 的实例。必需.
handled: 错误是否已处理，例如没有被救援并且被呈现给用户。默认值：true。

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

`ElasticAPM.report_message`编辑

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

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

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

参数

message: 自定义错误字符串。必需.

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

上下文编辑

`ElasticAPM.set_label`编辑

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

在使用自定义标签之前，请确保您了解可用的不同类型的元数据。

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

参数

key: 字符串键。请注意，.、* 或 " 将被转换为 _。
value: 值。

返回设置的 value。

请注意，标签在 Elasticsearch 中被索引。使用太多唯一的键会导致映射爆炸。

`ElasticAPM.set_custom_context`edit

向当前事务添加自定义上下文。使用它来进一步指定上下文，这将帮助您跟踪或诊断应用程序内部发生的情况。

在使用自定义上下文之前，请确保您了解可用的不同类型的元数据。

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

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

参数

context: JSON 兼容键值对的哈希。可以嵌套。

返回当前自定义上下文。

`ElasticAPM.set_user`edit

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

参数

user: 表示用户的对象

返回给定的用户

数据edit

`ElasticAPM.add_filter`edit

提供一个过滤器来转换有效负载，然后再发送。

参数

key: 用于标识过滤器的唯一键
callable: 对象或 proc（响应 .call(payload)）

返回修改后的有效负载。

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

示例

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

事务edit

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

属性edit

name: 字符串
type: 字符串
result: 字符串
outcome: 字符串（unknown、success、failure、nil）
trace_id: 字符串（只读）

`#sampled?`edit

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

`#ensure_parent_id`edit

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

这使得能够将 JavaScript 实时用户监控 (RUM) 代理为初始页面加载创建的跨度与后端服务的交易相关联。

如果您的服务动态生成 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 代理文档。

跨度edit

属性edit

name: 字符串
type: 字符串

« 自定义仪器指标 »

API 参考

API 参考编辑

代理生命周期编辑

ElasticAPM.start编辑

ElasticAPM.stop编辑

ElasticAPM.restart编辑

ElasticAPM.running?编辑

ElasticAPM.agent编辑

仪器编辑

ElasticAPM.current_transaction编辑

ElasticAPM.start_transaction编辑

ElasticAPM.end_transaction编辑

ElasticAPM.with_transaction编辑

ElasticAPM.start_span编辑

ElasticAPM.end_span编辑

ElasticAPM.with_span编辑

ElasticAPM.build_context编辑

Rails编辑

Sinatra编辑

Grape编辑

错误编辑

ElasticAPM.report编辑

ElasticAPM.report_message编辑

上下文编辑

ElasticAPM.set_label编辑

ElasticAPM.set_custom_contextedit

ElasticAPM.set_useredit

数据edit

ElasticAPM.add_filteredit

事务edit

属性edit

#sampled?edit

#ensure_parent_idedit

跨度edit

属性edit

`ElasticAPM.start`编辑

`ElasticAPM.stop`编辑

`ElasticAPM.restart`编辑

`ElasticAPM.running?`编辑

`ElasticAPM.agent`编辑

`ElasticAPM.current_transaction`编辑

`ElasticAPM.start_transaction`编辑

`ElasticAPM.end_transaction`编辑

`ElasticAPM.with_transaction`编辑

`ElasticAPM.start_span`编辑

`ElasticAPM.end_span`编辑

`ElasticAPM.with_span`编辑

`ElasticAPM.build_context`编辑

`ElasticAPM.report`编辑

`ElasticAPM.report_message`编辑

`ElasticAPM.set_label`编辑

`ElasticAPM.set_custom_context`edit

`ElasticAPM.set_user`edit

`ElasticAPM.add_filter`edit

`#sampled?`edit

`#ensure_parent_id`edit