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

代理 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+ 开始，标签也会添加到 span 中。

标签是 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 span）。有关检测列表，请参阅支持的技术。
  • 在任何给定时间只能有一个托管事务 — 启动第二个托管事务将结束前一个事务。非托管事务没有限制。

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

apm.startSpan()

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

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

参数

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

  • options - 支持以下选项

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

在少数情况下，当应用程序包含许多代理无法跟踪的异步活动时，阻止的 span 允许用户控制托管事务的提前关闭。

如果禁用 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 的队列之前触发。

这些事件的回调函数接收相应的事务对象作为其唯一参数。可以通过 Transaction 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 »