« API 参考 Transaction API »
Elastic 文档 › ›API 参考

Agent API

编辑

Agent API编辑

您可以在初始化代理后访问代理 API

var apm = require('@elastic/apm-rum').init(...)

apm.init([config])编辑

使用给定的 配置 初始化代理并返回自身。在幕后，init 会执行以下操作

  • 注册一个全局 error 监听器来跟踪页面上的 JavaScript 错误。
  • 添加一个 onload 事件监听器来收集页面加载指标。

当代理处于非活动状态时，error 和 onload 监听器都不会在页面上注册。

XHR 和 Fetch API 在代理脚本在页面上执行后立即被修补，即使代理处于非活动状态也不会改变。原因是允许用户在页面上异步初始化代理。

apm.setUserContext()编辑

apm.setUserContext(context)

调用此方法以使用有关用户的信息丰富收集的性能数据和错误。

给定的 context 参数必须是一个对象，并且可以包含以下属性（全部可选）

  • id - 用户的 ID
  • username - 用户的用户名
  • email - 用户的电子邮件

提供的用户上下文存储在 Elasticsearch 中的 context.user 下，无论是在错误还是事务中。

可以在同一个活动事务的范围内多次调用此函数。对于每次调用，上下文参数的属性都会与之前给定的上下文进行浅合并。

apm.setCustomContext()编辑

apm.setCustomContext(context)

调用此方法以使用您认为有助于调试性能问题或错误的任何信息丰富收集的错误和事务。

提供的自定义上下文存储在 Elasticsearch 中的 context.custom 下，无论是在错误还是事务中。

可以在同一个活动事务的范围内多次调用此函数。对于每次调用，上下文参数的属性都会与之前给定的上下文进行浅合并。

给定的 context 参数必须是一个对象，并且可以包含任何可以 JSON 编码的属性。

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

apm.addLabels()编辑

apm.addLabels({ [name]: value })

在事务和错误上设置标签。从 APM Server 7.6+ 开始，标签也会添加到跨度中。

标签是键值对，由 Elasticsearch 索引，因此可搜索（与通过 apm.setCustomContext() 设置的数据不同）。您可以设置多个标签。

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

参数

  • name - 任何字符串。所有句点 (.)、星号 (*) 和双引号 (") 将被替换为下划线 (_)，因为这些字符在 Elasticsearch 中具有特殊含义
  • value - 任何字符串、布尔值或数字。所有其他数据类型将在发送到 APM Server 之前转换为字符串。

避免定义太多用户指定的标签。在索引中定义太多唯一字段会导致 映射爆炸。

apm.addFilter()编辑

过滤器可用于在将 APM 负载发送到 apm-server 之前修改它。这在例如从负载中删除敏感信息时很有用

apm.addFilter(function (payload) {
  if (payload.errors) {
    payload.errors.forEach(function (error) {
      error.exception.message = error.exception.message.replace('secret', '[REDACTED]')
    })
  }
  if (payload.transactions) {
    payload.transactions.forEach(function (tr) {
      tr.spans.forEach(function (span) {
        if (span.context && span.context.http && span.context.http.url) {
          var url = new URL(span.context.http.url)
          if (url.searchParams.get('token')) {
            url.searchParams.set('token', 'REDACTED')
          }
          span.context.http.url = url.toString()
        }
      })
    })
  }
  // Make sure to return the payload
  return payload
})

如果其中一个过滤器返回一个假值，则负载将被丢弃。

apm.startTransaction()编辑

const transaction = apm.startTransaction(name, type, options)

启动并返回一个新的事务。

参数

  • name - 事务的名称（字符串）。默认为 Unknown
  • type - 事务的类型（字符串）。默认为 custom

  • options - 用于修改创建的事务的选项（对象）。此参数是可选的。支持以下选项

    • managed - 控制事务是否由代理管理。默认为 false。

使用此方法创建自定义事务。

默认情况下，自定义事务不会由代理管理，但是，您可以通过将 { managed: true } 作为 options 参数传递来启动一个受管理的事务。

受管理事务和不受管理事务之间存在一些差异

  • 对于受管理的事务，代理会在事务的生命周期内跟踪相关任务，并在所有任务完成后自动结束它。不受管理的事务需要通过调用 end 方法手动结束。
  • 受管理的事务包括通过我们的自动检测捕获的信息（例如 XHR 跨度）。有关检测列表，请参阅 支持的技术。
  • 在任何给定时间只能有一个受管理的事务——启动第二个受管理的事务将结束上一个事务。不受管理的事务没有限制。

如果 apm 被禁用或如果 active 标志在配置中设置为 false，则此方法将返回 undefined。

apm.startSpan()编辑

const span = apm.startSpan(name, type, options)

启动并返回与当前活动事务关联的新跨度。

参数

  • name - 跨度的名称（字符串）。默认为 Unknown
  • type - 跨度的类型（字符串）。默认为 custom

  • options - 支持以下选项

    • blocking - 阻止关联的事务结束，直到此跨度结束。阻塞的跨度会自动创建一个内部任务。默认为 false。
    • parentId - 与新跨度关联的父 ID。默认为当前事务 ID
    • sync - 表示跨度是同步的还是异步的。默认为 null

阻塞的跨度允许用户在某些情况下控制 受管理的事务 的提前关闭，当应用程序包含大量代理无法跟踪的异步活动时。

如果 apm 被禁用或如果 active 标志在配置中设置为 false，则此方法将返回 undefined。

apm.setInitialPageLoadName()编辑

apm.setInitialPageLoadName(name)

参数

  • name - 页面加载事务的名称（字符串）。

使用此方法设置在页面加载事件上自动发送的 page-load 事务的名称。有关更多详细信息，请参阅 自定义初始页面加载事务名称 文档。

apm.getCurrentTransaction()编辑

apm.getCurrentTransaction()

使用此方法获取当前活动事务。如果没有活动事务，它将返回 undefined。

apm.captureError()编辑

apm.captureError(error)

参数

  • error - Error 的实例。

使用此方法手动将错误发送到 APM Server

apm.captureError(new Error('<error-message>'))

apm.observe()编辑

apm.observe(name, callback)

参数

  • name - 事件的名称。
  • callback - 事件触发后要执行的回调函数。

使用此方法监听 RUM 代理内部事件。

支持以下事件以进行事务生命周期

  • transaction:start 事件在每次事务开始时触发。
  • transaction:end 事件在事务结束时触发，并且在将其添加到队列以发送到 APM Server 之前触发。

这些事件的回调函数接收相应的交易对象作为其唯一参数。交易对象可以通过交易 API中记录的方法和属性进行修改。

apm.observe('transaction:start', function (transaction) {
  if (transaction.type === 'custom') {
    transaction.name = window.document.title
    transaction.addLabels({ 'custom-label': 'custom-value' })
  }
})
« API 参考 Transaction API »