# @dynatrace/oneagent-sdk 中文文档

规范地址：https://npmcn.com/package/%40dynatrace/oneagent-sdk/

版本：1\.5\.0
npm 元数据更新时间：2023-02-23T15:20:08.582Z
中文译文更新时间：2026-11-13T02:34:01.635Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40dynatrace/oneagent-sdk
原文对照：https://npmcn.com/package/%40dynatrace/oneagent-sdk/?lang=original
项目主页：https://www.dynatrace.com/technologies/nodejs-monitoring/
源码仓库：https://github.com/Dynatrace/OneAgent-SDK-for-NodeJs

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：96.3 kB，11 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>= 10\.0\.0
- 运行依赖：0 个
- 首次发布：2018-02-01T16:29:24.973Z
- 最新版本发布：2023-02-23T15:20:08.419Z
- 近 30 天下载量：47183（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：11（近 12 个月 0 个）

## 中文简介

Dynatrace One Agent 的节点.js SDK

## 安装

```sh
npm install @dynatrace/oneagent-sdk
```

也可以使用：`pnpm add @dynatrace/oneagent-sdk`、`yarn add @dynatrace/oneagent-sdk`、`bun add @dynatrace/oneagent-sdk`

## README

# 用于节点的 Dynatrace One Agent SDK

这个SDK允许Dynatrace客户使用仪器节点.js应用程序. 这有助于为目前没有直接支持的模块添加服务级别洞察力 [一号代理](https://www.dynatrace.com/technologies/nodejs-monitoring/) 脱出一出.

这是正式的节点Js执行 [单代理 SDK](https://github.com/Dynatrace/OneAgent-SDK)。 。 。 .

## 目录

-   [软件包内容](https://npmcn.com/package/%40dynatrace/oneagent-sdk/#readme-package-contents)
-   [所需资源](https://npmcn.com/package/%40dynatrace/oneagent-sdk/#readme-requirements)
-   [一体化](https://npmcn.com/package/%40dynatrace/oneagent-sdk/#readme-integration)
    -   [安装](https://npmcn.com/package/%40dynatrace/oneagent-sdk/#readme-installation)
    -   [解决问题](https://npmcn.com/package/%40dynatrace/oneagent-sdk/#readme-troubleshooting)
-   [API 概念](https://npmcn.com/package/%40dynatrace/oneagent-sdk/#readme-api-concepts)
    -   [One AgentSDK 对象](https://npmcn.com/package/%40dynatrace/oneagent-sdk/#readme-oneagentsdk-object)
    -   [追踪器](https://npmcn.com/package/%40dynatrace/oneagent-sdk/#readme-tracers)
-   [特征](https://npmcn.com/package/%40dynatrace/oneagent-sdk/#readme-features)
    -   [跟踪往来远程电话](https://npmcn.com/package/%40dynatrace/oneagent-sdk/#readme-trace-incoming-and-outgoing-remote-calls)
    -   [追踪消息](https://npmcn.com/package/%40dynatrace/oneagent-sdk/#readme-trace-messaging)
    -   [追踪 SQL 数据库请求](https://npmcn.com/package/%40dynatrace/oneagent-sdk/#readme-trace-sql-database-requests)
    -   [设置自定义请求属性](https://npmcn.com/package/%40dynatrace/oneagent-sdk/#readme-set-custom-request-attributes)
    -   [计量(过期)](https://npmcn.com/package/%40dynatrace/oneagent-sdk/#readme-metrics)
    -   [跟踪上下文](https://npmcn.com/package/%40dynatrace/oneagent-sdk/#readme-trace-context)
-   [行政辅助](https://npmcn.com/package/%40dynatrace/oneagent-sdk/#readme-administrative-apis)
    -   [当前 SDK 状态](https://npmcn.com/package/%40dynatrace/oneagent-sdk/#readme-current-sdk-state)
    -   [设置记录的回调](https://npmcn.com/package/%40dynatrace/oneagent-sdk/#readme-set-callbacks-for-logging)
-   [常数](https://npmcn.com/package/%40dynatrace/oneagent-sdk/#readme-constants)
    -   [频道类型](https://npmcn.com/package/%40dynatrace/oneagent-sdk/#readme-channel-type)
    -   [数据库供应商](https://npmcn.com/package/%40dynatrace/oneagent-sdk/#readme-database-vendors)
    -   [信件目标类型](https://npmcn.com/package/%40dynatrace/oneagent-sdk/#readme-message-destination-type)
    -   [信息系统供应商](https://npmcn.com/package/%40dynatrace/oneagent-sdk/#readme-message-system-vendors)
-   [传出上下文](https://npmcn.com/package/%40dynatrace/oneagent-sdk/#readme-pass-context)
-   [进一步阅读](https://npmcn.com/package/%40dynatrace/oneagent-sdk/#readme-further-readings)
-   [帮助支持( S)](https://npmcn.com/package/%40dynatrace/oneagent-sdk/#readme-help--support)
-   [发布注释](https://npmcn.com/package/%40dynatrace/oneagent-sdk/#readme-release-notes)

## 软件包内容

-   `samples`: 样品应用,可以证明SDK的用法. 见 [读取我](https://npmcn.com/package/%40dynatrace/oneagent-sdk/samples/README.md) 在样本目录中提供更详细的信息
-   `src`: SDK 的源代码
-   `test`: 单位测试
-   `LICENSE`: 发布整个SDK和样本应用程序的许可证

## 所需资源

-   在通过 OneAgent 装入时 [一个代理国家预防机制单元](https://www.npmjs.com/package/@dynatrace/oneagent) 或类似工具,在“单一代理”之后确保要求SDK
-   Dynatrace OneAgent( 需要的版本见下文)
-   OneAgent SDK不支持在无服务器代码模块上,包括用于AWS Lambda的. 在这些设想中,考虑使用 [打开几何](https://www.dynatrace.com/support/help/shortlink/opentel-lambda) 换句话说.

| One Agent SDK 用于节点.js | 所需的一个代理版本 | 支助状况 |
| :-- | :-- | :-- |
| 1.5.x (中文(简体) ) | 1.259 国家 | 支助 |
| 1.4.x (中文(简体) ) | 1.179 (中文(简体) ) | 支助 |
| 1.3.x (单位:千美元) | 1.165 国 家 | 以2023-08-01结束的支持折旧 |
| 1.2.x (单位:千美元) | \>= 1.145 | 以2023-08-01结束的支持折旧 |
| 1.1.x (单位:千美元) | \>= 1.143 | 以2023-08-01结束的支持折旧 |
| 1.0.x (中文(简体) ) | 第1.137号决定 | 以2023-08-01结束的支持折旧 |

## 一体化

如果不存在OneAgent,使用此模块不应产生任何错误(例如在测试中).

确保此模块在 Dynatrace OneAgent 后加载 .

### 安装

`npm install --save @dynatrace/oneagent-sdk`

### 解决问题

如果 SDK 无法连接到 OneAgent ([当前 SDK 状态](https://npmcn.com/package/%40dynatrace/oneagent-sdk/#readme-current-sdk-state) 没有 `ACTIVE`)验证使用了匹配的 OneAgent 版本 _并在之前装入_ sDK模块.

核实One Agent是否按预期工作(见 [一号代理](https://www.dynatrace.com/technologies/nodejs-monitoring/)) (中文(简体) ).

您应该确保您已经设置 [日志 回电](https://npmcn.com/package/%40dynatrace/oneagent-sdk/#readme-set-callbacks-for-logging)。 。 。 .

透明包装 _支持_ 添加上下文信息的库。 目前每个 _不支持_ 模块 [传出上下文](https://npmcn.com/package/%40dynatrace/oneagent-sdk/#readme-pass-context) 可用于为回调提供交易上下文.

## API 概念

Dynatrace OneAgent SDK的共同概念在下文中作了解释 [Dynatrace OneAgent SDK 存储器](https://github.com/Dynatrace/OneAgent-SDK)。 。 。 .

### One AgentSDK 对象

第一步是通过调用获取 OneAgent SDK API 对象 `createInstance()`。产生的对象持有创建跟踪器的方法、管理方法(例如检查SDK状态、安装日志回调)和 `passContext()`。每次呼叫 `createInstance()` 将返回一个新的 API 对象,允许用户为单独的使用大小写安装单独的登录回调.

```js
const Sdk = require('@dynatrace/oneagent-sdk');
const Api = Sdk.createInstance();
```

### 追踪器

追踪器的生命周期如下:

1.  使用 `traceXXX` 方法匹配您的使用大小写。 对于进入的可标记标记,将收到的 Dynatrace 标记(如果在) 传递到 `traceXXX` 方法.
2.  开始追踪, 追踪又会引用和重复给定的处理器功能 .
3.  对于正在发送的可标记跟踪, 获取 Dynatrace 标记并将其包含到正在发送的信件中 .
4.  通过调用可选择标记追踪操作失败 `error()`
5.  行动完成后结束追踪. 对于出处的痕迹,您可能会通过回调以包含在这个痕迹中 .

每个追踪器提供以下方法:

-   `start(handler, ...args)` 启动一个跟踪并用提供的参数调用指定的处理器函数 。 返回处理器的返回值.
-   `startWithContext(handler, thisObj, ...args)` 喜欢 `start()` 但允许指定 `this` 上下文.
-   `error(err)` 将跟踪标记为失败并附加一个错误对象 。 每次追踪最多一次 不要结束追踪! 返回追踪器本身.
-   `end()` 结束追踪.

发出请求的追踪器还提供了更好的方法,以结束追踪,从而能够包括后续召回这一追踪的纯正部分.

-   `end(callback, ...args)` 结束追踪像 `end()` 但又用给定的论据 调用通过回话 回调的回调值将转发给 `end`。 。 。 .
-   `endWithContext(callback, thisObj, ...args)` 喜欢 `end()` 以上,但有可能具体说明 `this` 上下文.

发出可标记请求的追踪器 _dynathrace 标签_ 在追踪开始后发送到远程服务 :

-   `getDynatraceStringTag()` 返回编码为 `string`
-   `getDynatraceByteTag()` 返回编码为 `Buffer`

这个 Dynatrace 标记需要嵌入发送到远程服务的信件中 。 这个 `string` 或二进制表示可能更适合,取决于所使用的具体协议。 由用户决定使用哪种变体. 输入服务时, 此标签需要用户提取并传递给相应的 `traceXXX` 方法 `dynatraceTag` 参数的属性,以便连接出处和相应的出处.

以上方法返回的跟踪对象始终是有效的,即使不存在一个代理人,或者无论出于何种原因都不存在跟踪。 在这种情况下,仍然存在着避免需要额外检查客户代码的方法.

请注意,OneAgent使用指定函数的名称 `start()` 财务报告和审定财务报表 `end()` 以命名纯派节点。 因此,我们建议选择命名函数而不是匿名函数,以给你更高的质量痕迹.

## 特征

功能集与每种语言的应用略有不同。 随着时间的推移将增加更多的功能,参见 [OneAgent SDK的计划特性](https://community.dynatrace.com/t5/Feedback-channel/Planned-features-for-OneAgent-SDK/m-p/147331) 详细介绍即将到来的特性.

关于特征的更详细说明可见于 [单代理 SDK](https://github.com/Dynatrace/OneAgent-SDK)。 。 。 .

| 特性 | 节点版所需的 OneAgent SDK |
| :-- | :-- |
| 跟踪往来远程电话 | (单位:千美元) |
| 追踪 SQL 数据库请求 | (单位:千美元) |
| 在 SQL 数据库请求中设置结果数据 | 页:1 |
| 设置自定义请求属性 | (单位:千美元) |
| 追踪消息 | \>= 1.3.0 |
| 计量(过期) | \>= 1.4.0 |
| 跟踪上下文 | \>= 1.5.0 |

### 跟踪往来远程电话

#### 追踪正在发送的远程呼叫

发送的远程呼叫通过呼叫追踪 `traceOutgoingRemoteCall()` 传递对象,其属性如下:

-   `serviceMethod` 强制 - 持有所取远程方法名称的字符串
-   `serviceName` 强制 - 有远程服务名称的字符串
-   `serviceEndpoint` 强制 - 描述远程服务的逻辑端点的字符串 。 在组装/负载平衡服务的情况下 `serviceEndpoint` 代表共同的逻辑终点(例如:register://staging-environment/myservices/ serviceA),而连接Info则描述实际的通信终点. 因此,单一服务端点可以有许多连接.
-   `protocolName` 可选 - 描述所使用的协议的字符串( 如 Protobuf, GIOP,...), 仅用于显示目的

此外,它还拥有下列特性,说明与远程服务的联系。 根据连接类型,应设定相应的财产/财产. 如果没有像主机/ socketPath/... 这样的特定信息, 属性 `channelType` 应定.

-   `host` 在 TCP/ IP 连接时使用指定服务器侧主机名/ IP 的字符串( 注意 OneAgent 可以尝试解决主机名)
-   `port` TCP/IP 端口( 可选)
-   `socketPath` 指定 UNIX 域名套接字文件的字符串
-   `pipeName` 指定管道名称的字符串
-   `channelType` 指定用作通信信道的协议(如TCP/IP,IN PROCESS,.)。 有效值可通过 [频道类型](https://npmcn.com/package/%40dynatrace/oneagent-sdk/#readme-channel-type)(中文(简体) )

结果是: `traceOutgoingRemoteCall()` 是一个用于与此跟踪相关的进一步操作的跟踪对象(参见 [追踪器](https://npmcn.com/package/%40dynatrace/oneagent-sdk/#readme-tracers) 详细情况请查阅. 外传的远程呼叫是 _可标记_ a Dynatrace 标记必须在其启动并嵌入到远程调用消息内容后从跟踪器创建.

**示例(见 [正在发送中](https://npmcn.com/package/%40dynatrace/oneagent-sdk/samples/RemoteCall/OutgoingRemoteCallSample.js) 详情如下:**

```js
// Issue a traced outgoing remote call
async function tracedOutgoingRemoteCall(method, data) {
  const tracer = Api.traceOutgoingRemoteCall({
    serviceEndpoint: "ChildProcess",
    serviceMethod: method,  // the name of the remote method called
    serviceName: "StringManipulator",
    channelType: Sdk.ChannelType.NAMED_PIPE
  });

  try {
    // start tracer, get dynatrace tag and trigger sending via doOutgoingRemoteCall()
    return await tracer.start(function triggerTaggedRemoteCall() {
      // getting a tag from tracer needs to be done after start()
      const dtTag = tracer.getDynatraceStringTag();
      // now trigger the actual remote call
      return doOutgoingRemoteCall(method, data, dtTag);
    });
  } catch (e) {
    tracer.error(e);
    throw e;
  } finally {
    tracer.end();
  }
}
```

#### 追踪收到的远程呼叫

一个远程呼叫通过呼叫追踪 `traceIncomingRemoteCall()` 传递对象,其属性如下:

-   `serviceMethod` 强制 - 持有所取远程方法名称的字符串
-   `serviceName` 强制 - 有远程服务名称的字符串
-   `serviceEndpoint` 强制 - 描述远程服务在服务器一侧的逻辑部署端点的字符串
-   `protocolName` 可选 - 描述所使用的协议的字符串( 如 Protobuf, GIOP,...), 仅用于显示目的
-   `dynatraceTag` - 一个 `string` 或者说 `Buffer` 持有收到的 Dynatrace 标签

此调用的结果是一个用于与此调用相关的进一步操作的跟踪对象(参见: [追踪器](https://npmcn.com/package/%40dynatrace/oneagent-sdk/#readme-tracers)) (中文(简体) ).

**示例(见 [(原始内容存档于2018-10-21) (英语). Incoming Remote CallSample.js](https://npmcn.com/package/%40dynatrace/oneagent-sdk/samples/RemoteCall/IncomingRemoteCallSample.js) 详情如下:**

```js
// trace and handle incoming messages
async function tracedMessageHandler(message) {
  const tracer = Api.traceIncomingRemoteCall({
    serviceEndpoint: "ChildProcess",
    serviceMethod: message.method,
    serviceName: "StringManipulator",
    dynatraceTag: message.traceTag,   // extract and set the dynatrace tag
    protocolName: "Json"              // optional
  });

  try {
    // start tracer and trigger actual message processing via processMessage(message)
    const result = await tracer.start(processMessage, message);

    // send result calculated by processMessage() back to caller
    process.send({ result: result, id: message.id });

    // end tracer
    tracer.end();
  } catch (e) {
    // send error back
    process.send({ error: e.message, id: message.id });

    // set error and end tracer
    tracer.error(e).end();
  }
}
```

### 追踪消息

#### 追踪寄出的信件

发送的消息通过呼叫追踪 `traceOutgoingMessage()` 传递对象,其属性如下:

-   `vendorName` 强制 - 持有消息系统供应商名的字符串(例如:RabbitMq,Apache Kafka,.),可以是用户定义的名称. 如果可能,使用定义在 [信件系统版本](https://npmcn.com/package/%40dynatrace/oneagent-sdk/#readme-message-system-vendors)。 。 。 .
-   `destinationName` 强制 - 持有目的名的字符串( 如队列名, 主题名) .
-   `destinationType` 强制性 - 指定目的地类型。 有效值可通过 [信件存储类型](https://npmcn.com/package/%40dynatrace/oneagent-sdk/#readme-message-destination-type)

此外,它还拥有下列属性,说明与邮件服务的联系。 根据连接类型,应设定相应的财产/财产. 如果没有像主机/ socketPath/... 这样的特定信息, 属性 `channelType` 应定.

-   `host` 在 TCP/ IP 连接时使用指定服务器侧主机名/ IP 的字符串( 注意 OneAgent 可以尝试解决主机名)
-   `port` TCP/IP 端口( 可选)
-   `socketPath` 指定 UNIX 域名套接字文件的字符串
-   `pipeName` 指定管道名称的字符串
-   `channelType` 指定用作通信信道的协议(如TCP/IP,IN PROCESS,.)。 有效值可通过 [频道类型](https://npmcn.com/package/%40dynatrace/oneagent-sdk/#readme-channel-type)(中文(简体) )

结果是: `traceOutgoingMessage()` 是一个用于与此跟踪相关的进一步操作的跟踪对象(参见 [追踪器](https://npmcn.com/package/%40dynatrace/oneagent-sdk/#readme-tracers) 详细情况请查阅. 传出的信息是 _可标记_ a Dynatrace 标记在启动并嵌入到信件内容后,应从追踪器创建.

除了外出追踪器常用的API外,该追踪器还提供了其他方法 `setVendorMessageId()` 财务报告和审定财务报表 `setCorrelationId()` 用于更详细地说明发送的信息。 两个API都收到 `string` 作为通过 `correlationId` 或者说 `vendorMessageId` 由短信系统提供.

**示例(见 [通讯Sample.js](https://npmcn.com/package/%40dynatrace/oneagent-sdk/samples/Messaging/MessagingSample.js) 详情如下:**

```js
function traceOutgoingMessage(name, data, corrId) {
  // create a tracer instance and start the trace
  const tracer = Api.traceOutgoingMessage(systemInfo);
  tracer.start(function sendTaggedMessage() {
    // getting a tag from tracer needs to be done after start()
    const dtTag = tracer.getDynatraceStringTag();
    try {
      // now trigger the actual sending of the message
      const messageId = sendMessage(name, data, corrId, dtTag);

      // optional: set correlationId/vendorMessageId if present/relevant
      tracer.setCorrelationId(corrId).setVendorMessageId(`${messageId}`);
    } catch (e) {
      tracer.error(e);
      throw e;
    } finally {
      tracer.end();
    }
  });
}
```

#### 追踪收到的消息

发送的消息通过呼叫追踪 `traceIncomingMessage()` 传递对象,其属性如下:

-   `vendorName` 强制 - 持有消息系统供应商名的字符串(例如:RabbitMq,Apache Kafka,.),可以是用户定义的名称. 如果可能,使用定义在 [信件系统版本](https://npmcn.com/package/%40dynatrace/oneagent-sdk/#readme-message-system-vendors)。 。 。 .
-   `destinationName` 强制 - 持有目的名的字符串( 如队列名, 主题名) .
-   `destinationType` 强制性 - 指定目的地类型。 有效值可通过 [信件存储类型](https://npmcn.com/package/%40dynatrace/oneagent-sdk/#readme-message-destination-type)
-   `dynatraceTag` - 字符串或缓冲器持有收到的 Dynatrace 标签

此外,它还拥有下列属性,说明与邮件服务的联系。 根据连接类型,应设定相应的财产/财产. 如果没有像主机/ socketPath/... 这样的特定信息, 属性 `channelType` 应定.

-   `host` 在 TCP/ IP 连接时使用指定服务器侧主机名/ IP 的字符串( 注意 OneAgent 可以尝试解决主机名)
-   `port` TCP/IP 端口( 可选)
-   `socketPath` 指定 UNIX 域名套接字文件的字符串
-   `pipeName` 指定管道名称的字符串
-   `channelType` 指定用作通信信道的协议(如TCP/IP,IN PROCESS,.)。 有效值可通过 [频道类型](https://npmcn.com/package/%40dynatrace/oneagent-sdk/#readme-channel-type)(中文(简体) )

结果是: `traceIncomingMessage()` 是一个用于与此跟踪相关的进一步操作的跟踪对象(参见 [追踪器](https://npmcn.com/package/%40dynatrace/oneagent-sdk/#readme-tracers) 详细情况请查阅.

除了常见的追踪器的API之外,这种追踪器还提供了额外的方法 `setVendorMessageId()` 财务报告和审定财务报表 `setCorrelationId()` 用于更详细地说明发送的信息。 两个API都收到 `string` 作为通过 `correlationId` 或者说 `vendorMessageId` 由短信系统提供.

**示例(见 [通讯Sample.js](https://npmcn.com/package/%40dynatrace/oneagent-sdk/samples/Messaging/MessagingSample.js) 详情如下:**

```js
function traceIncomingMessage(msg) {
  // create a tracer instance and start the trace, ensure dynatraceTag is set
  const startData = Object.assign({ dynatraceTag: msg.meta.dtTag }, systemInfo);
  const tracer = Api.traceIncomingMessage(startData);
  tracer.start(function processMessage(done) {
    // optional: set correlationId/vendorMessageId if present/relevant
    tracer.setCorrelationId(msg.meta.corrId).setVendorMessageId(`${msg.meta.msgId}`);

    // do whatever needed with the message, simulated via nextTick() here
    process.nextTick(done);
  }, function onDone(err) {
    if (err) {
      tracer.error();
    }
    tracer.end();
  });
}
```

### 追踪 SQL 数据库请求

SQL 数据库请求通过调用来追踪 `traceSQLDatabaseRequest()` 它需要一个数据库信息对象作为第一个参数和一个以请求特定数据为第二个参数的对象.

数据库信息是一个对象,在运行时通常不会改变. 它拥有下列财产:

-   `name` 强制 - 定义数据库名称的字符串
-   `vendor` 强制 - 持有数据库供应商名的字符串(例如Oracle, MySQL,.),可以是用户定义的名称. 如果可能,使用定义在 [数据库编辑器](https://npmcn.com/package/%40dynatrace/oneagent-sdk/#readme-database-vendors)

此外,它具有下列属性,说明与数据库的连接。 根据所使用的实际连接情况,应设定相应的财产/财产. 如果像主机/ socketPath/... 这样的特定信息不可用, 则应设置属性频道 Type .

-   `host` 在 TCP/ IP 连接时使用指定服务器侧主机名/ IP 的字符串( 注意 OneAgent 可以尝试解决主机名)
-   `port` TCP/IP 端口( 可选)
-   `socketPath` 指定 UNIX 域名套接字文件的字符串
-   `pipeName` 指定管道名称的字符串
-   `channelType` 指定用作通信信道的协议(如TCP/IP,IN PROCESS,.)。 有效值可通过 [频道类型](https://npmcn.com/package/%40dynatrace/oneagent-sdk/#readme-channel-type)。 。 。 .

第二种论点载有描述具体操作的数据,并具有以下属性:

-   `statement` 强制性 - 持有 SQL 语句的字符串, 要发送到数据库 .

结果是: `traceSQLDatabaseRequest()` 是一个用于与此跟踪相关的进一步操作的跟踪对象(参见 [追踪器](https://npmcn.com/package/%40dynatrace/oneagent-sdk/#readme-tracers) 详细情况请查阅.

除了外出追踪器常用的API之外,该追踪器还提供了额外的方法 `setResultData()` 用于确定数据库请求结果的细节. 它接收具有以下属性的对象:

-   `rowsReturned` 可选 - 此可追踪数据库请求返回的行数 。 只允许正值
-   `roundTripCount` 可选 - 已发生的圆通数. 只允许正值

请注意,SQL数据库跟踪只有在其他SDK跟踪(如被接入的远程呼叫)或OneAgent内置跟踪(如被接入的网络请求)中出现时才会被创建.

**示例(见 [数据库请求实例.js](https://npmcn.com/package/%40dynatrace/oneagent-sdk/samples/Database/DatabaseRequestSample.js) 详情如下:**

```js
// Static info describing the database
const dbInfo = {
  name: dbConfig.database,
  vendor: Sdk.DatabaseVendor.MARIADB,
  host: dbConfig.host,
  port: dbConfig.port
};

// Issue a traced SQL database request
function tracedSqlDatabaseRequest(sql, clientCb) {
  // create a SQL database tracer
  const tracer = Api.traceSQLDatabaseRequest(dbInfo, {
    statement: sql
  });

  // start tracer, calls connection.query(sql, cb) with connection set as this in query()
  tracer.startWithContext(connection.query, connection, sql, (err, results, fields) => {
    if (err) {
      // set the error on the tracer
      tracer.error(err);
    } else {
      // optionally set result data
      tracer.setResultData({
        rowsReturned: 15,
        roundTripCount: 32
      });
    }
    // end the tracer and call client callback forwarding results
    tracer.end(clientCb, err, results, fields);
  });
}
```

### 设置自定义请求属性

API( API ) `addCustomRequestAttribute()` 在目前追踪的服务呼叫中添加自定义请求属性 。 由于 OneAgent SDK 会选择当前打开的跟踪,所以没有提及需要的跟踪器. 这可能是SDK或 由OneAgent的传感器制造的痕迹 API可能多次被调用来添加更多的属性. 如果同一属性密钥被设置了好几次,那么所有值都会被记录下来.

`addCustomRequestAttribute()` 需要两个参数:

-   `key` 强制 - 指定属性名称的字符串
-   `value` 强制 - 指定属性值的字符串或数字

**示例(见 [自定义请求属性Sample.js](https://npmcn.com/package/%40dynatrace/oneagent-sdk/samples/CustomRequestAttributes/CustomRequestAttributesSample.js) 详情如下:**

```js
Api.addCustomRequestAttribute("fooAttribute", "bar");
Api.addCustomRequestAttribute("barAttribute", 15.34);
```

### 计量(过期)

> **说明**: 参数 API 属于 [Dynatrace 预览程序](https://www.dynatrace.com/support/help/whats-new/preview-and-early-adopter-releases/) 这已经是 **终止**. 与指标有关的所有API和类型 已经 **已贬值** 并在未来的释放中被移除. 这个 [摄取量](https://www.dynatrace.com/support/help/how-to-use-dynatrace/metrics/metric-ingestion/) 网页提供了如何替换这些API和如何报告的进一步资料 从现在起的测量数据.

SDK支持两个 **计量值类型**数字 : `Integer` 财务报告和审定财务报表 `Float` (双精度浮点. 你应该更倾向于整数度量,因为其效率更高,除非精度的丧失是不可接受的(但 考虑使用不同的单位,例如整数微秒而不是浮点秒.

这些不同 **各类衡量标准**数字 :

-   **计数器**: 对于所有正在计数诸如发送/接收字节到/从网络发送/接收的度量标准. 柜台只能用于跟踪流动中的东西,而不是状态. 它报告 `sum` 并且是最轻量级的.
-   **高盖**: 对于定期抽取当前状态的度量,例如温度,总数量 存储在磁盘上的字节。 高盖斯报告a `min`, (中文(简体) ), `max` 财务报告和审定财务报表 `average` 值( 但无) `sum`) (中文(简体) ).
-   **统计**: 对于事件驱动的度量衡,如网络接口的包大小. 最爱 重量度量衡。 报告 `min`, (中文(简体) ), `max`, (中文(简体) ), `average` 财务报告和审定财务报表 `count`。 。 。 .

每种组合的计量值类型和类型都有自己的创建功能,命名为 `create<ValueType><MetricKind>Metric`。 。 。 .

在创建以下计量信息时,需要提供:

-   `metricName` 强制 - 表示度量的字符串 。 最大大小为100字节. 尽管不推荐,但只要使用相同的创建函数(计量值类型和类型是相同的)和相同的选项,可以创建多个同名的度量实例. 否则,多次使用同一种公制名称就是一个错误. 所有同名的度量衡将合并在一起,仿佛您只使用一个度量衡实例.
    
-   `MetricOptions` 可选 - a `object` 具有下列属性:
    
    -   `unit` 可选 - 在 Dynatrace UI 中浏览公尺时显示的字符串 .
    -   `dimensionName` 可选 - a `string` 指定在度量衡中添加的尺寸的名称. 如果这里给出了一个名字,则需要在计分标准上定出一个尺寸值. 一个维度就像附加在值上的一个附加标签,例如"disk.write.bytes"的度量衡可以有一个"disk-id"的维度名称,当它加入值时,一个维度值将是"/dev/sda1".

### 跟踪上下文

实施工作遵循来自 [Dynatrace OneAgent SDK - 追踪上下文](https://github.com/Dynatrace/OneAgent-SDK#tracecontext)。 。 。 . 对于一种用法,例如: [W3CTrace Context ApiSample.js (英语)](https://npmcn.com/package/%40dynatrace/oneagent-sdk/samples/TraceContext/W3CTraceContextApiSample.js)。 。 。 .

### 行政辅助人员

#### 当前 SDK 状态

方法 `getCurrentState()` 返回 SDK 的当前状态。 通过常数对象提供有效值 `SDK.SDKState`数字 :

-   `ACTIVE` SDK连接到OneAgent并捕获数据.
-   `TEMPORARILY_INACTIVE` SDK与"OneAgent"相接,但捕获被禁用. 跳过创建 SDK 交易以保存资源是一种好的做法 。 应定期检查SDK状态,因为它在每一时间都可能发生变化.
-   `PERMANENTLY_INACTIVE` SDK没有连接到OneAgent,因此它永远不会捕捉到数据. 这种SDK状态在过程期间永远不会改变. 永远不要调用任何SDK API来节省资源是好的做法.

#### 设置记录的回调

方法 `setLoggingCallback(callbacks)` 可用于设置提醒和错误日志的回调。 日志调用收到字符串作为参数 。 当参数通过具有以下属性的对象时:

-   `warning` 可选 - 接受字符串作为参数的函数调用以传递警告消息
-   `error` 可选 - 接受字符串作为参数的函数调用以传递错误消息

输入回调属性将解开先前安装的回调 .

```js
Api.setLoggingCallbacks({
  warning: (msg) => console.error("DatabaseRequestSample SDK warning: " + msg),
  error: (msg) => console.error("DatabaseRequestSample SDK error: " + msg),
});
```

### 常数

#### 频道类型

常数值 `ChannelType` 指定所使用的运输通道的类型。 提供了以下数值:

-   `TCP_IP` 通过TCP/IP进行通信
-   `UNIX_DOMAIN_SOCKET` 通过 UNIX 域名套接字进行通信
-   `NAMED_PIPE` 通过命名管进行通信
-   `IN_PROCESS` 交流是当前进程(例如通过文件,......)中的某些机制
-   `OTHER` 用于其它频道类型

#### 数据库供应商

常数值 `DatabaseVendor` 可用作 `traceSQLDatabaseRequest()`提供以下数值:

-   `APACHE_HIVE`
-   `CLOUDSCAPE`
-   `HSQLDB`
-   `PROGRESS`
-   `MAXDB`
-   `HANADB`
-   `INGRES`
-   `FIRST_SQL`
-   `ENTERPRISE_DB`
-   `CACHE`
-   `ADABAS`
-   `FIREBIRD`
-   `DB2`
-   `DERBY_CLIENT`
-   `DERBY_EMBEDDED`
-   `FILEMAKER`
-   `INFORMIX`
-   `INSTANT_DB`
-   `INTERBASE`
-   `MYSQL`
-   `MARIADB`
-   `NETEZZA`
-   `ORACLE`
-   `PERVASIVE`
-   `POINTBASE`
-   `POSTGRESQL`
-   `SQLSERVER`
-   `SQLITE`
-   `SYBASE`
-   `TERADATA`
-   `VERTICA`
-   `CASSANDRA`
-   `H2`
-   `COLDFUSION_IMQ`
-   `REDSHIFT`
-   `COUCHBASE`

#### 信件目标类型

常数值 `MessageDestinationType` 指定所使用的信件目的类型。 提供了以下数值:

-   `QUEUE`
-   `TOPIC`

#### 信息系统供应商

常数值 `MessageSystemVendor` 可用作 `traceIncomingMessage()` 财务报告和审定财务报表 `traceOutgoingMessage()`. 使用这些常数可确保OneAgentSDK捕获的服务得到与通过内置传感器追踪相同的处理。 提供了以下数值:

-   `HORNETQ`
-   `ACTIVE_MQ`
-   `RABBIT_MQ`
-   `ARTEMIS`
-   `WEBSPHERE`
-   `MQSERIES_JMS`
-   `MQSERIES`
-   `TIBCO`
-   `KAFKA`

### 传出上下文

透明地包装 _支持_ 添加上下文信息的库。 对于所有尚未 _不支持_ 模块 `passContext()` 可用于为回调提供交易上下文.

**交易背景是什么?**

[Dynatrace 专利纯帕斯技术](https://www.dynatrace.com/en_us/application-performance-management/products/purepath-technology.html) 抓取时间和代码级别上下文 _全部_ 交易,端到端,从用户点击,跨出所有级别,到记录和回放数据库。 从技术上讲,这意味着Dynatrace在应用程序的任何入出函数调用中都增加了交易上下文.

**这对Node.js应用程序意味着什么?**

节点(Node.js)是单线形的-它的控制流基于事件和同步回调.

让我们看看一个与mongoDB找到文件的例子:

```js
function callback(err, document) {
  console.log(document.name);

  http.get('https://some-api.xyz/service', (res) => {});
    // ^^^                                 °°°°°°°°°°°
    // Asynchronous call                   Asynchronous callback
}

collection.findOne({_id: doc_id}, callback);
        // ^^^^^^^                °°°°°°°°
        // Asynchronous call      Asynchronous callback

```

之后 `collection.findOne()` 同步执行 `callback()` 将召入. `callback()` 再次包含一个同步调用 `http.get()` 执行输出的 HTTP 请求。 如果有当前交易上下文有持续跟踪,Dynatrace OneAgent将透明地在此出行请求中添加包含Dynatrace标记的HTTP头. 下一层----如果配有 " 一个代理人 " ----则将继续追踪。 如果没有进一步的干预,在同步援引和召回之间将失去任何交易上下文。 目前将上下文信息传递给回调的唯一可靠方法叫做"包装".

**示例: 常规召回** 假设 `some.asyncFunction()` 以下样本导致OneAgent中交易环境的损失。 确保 OneAgent 正确显示此函数召回内触发的活动 `passContext()` 用于创建关闭, 保留在调用时激活的交易上下文 `some.asyncFunction()`。 。 。 .

```js
const Api = require('@dynatrace/oneagent-sdk').createInstance();

some.asyncFunction(someParam, Api.passContext(function(err, result) {
  // Context is preserved
  http.get('https://some-api.xyz/service', Api.passContext((res) => {
    // other activity, e.g. outgoing web requests,...
  }));
}));
```

**重要: 通过 `passContext()` 需要相应的同步调用时间**

```js
// This will *NOT* work as transactional context at call time of some.asyncFunction() is not preserved
// instead the transactional context at definition of doSomething() is preserved which is not
// related to the relevant transaction triggered by calling some.asyncFunction().
const wrappedFunction = dta.passContext(someFunction);
function doSomething() {
  some.asyncFunction('someParam', wrappedFunction);
}

// This works, passContext() is called at invocation time of some.asyncFunction()
function doSomething() {
  some.asyncFunction('someParam', dta.passContext(someFunction));
}
```

## 进一步阅读

-   [独家特工SDK是什么?](https://www.dynatrace.com/support/help/extend-dynatrace/oneagent-sdk/what-is-oneagent-sdk/) 在 Dynatrace 文档中
-   [Dynatrace 群落中的反馈线索( M)](https://community.dynatrace.com/t5/Feedback-channel/Planned-features-for-OneAgent-SDK/m-p/147331)
-   [Dynatrace OneAgent SDK for Node.js: 将端到端的能见度扩展](https://www.dynatrace.com/news/blog/dynatrace-oneagent-sdk-for-node-js-extend-end-to-end-visibility/)

## 帮助支持( S)

**支助政策**

节点的Dynatrace OneAgent SDK具有GA状态. 特征得到Dynatrace的全力支持.

详细支助政策见 [Dynatrace One Agent SDK 帮助](https://github.com/Dynatrace/OneAgent-SDK#help)。 。 。 .

### 获得帮助

-   问个问题 [产品论坛](https://community.dynatrace.com/)
-   读取 [产品文档](https://www.dynatrace.com/support/help)

### 打开 a [GitHub 问题](https://github.com/Dynatrace/OneAgent-SDK-for-NodeJs/issues) 改为

-   报告小缺陷、小物品或打字
-   询问 SDK API 的改进或更改
-   询问与社区工作有关的任何问题

解放军不申请GitHub入场券

### 顾客可以开罚单 [Dynatrace 支持门户](https://dt-url.net/lb626l9) 改为

-   获得Dynatrace技术支持工程小组的支持
-   管理和解决与产品有关的技术问题

SLA根据客户的支持水平申请.

## 发布注释

另见 [释放](https://github.com/Dynatrace/OneAgent-SDK-for-NodeJs/releases)

| 版本 | 说明 |
| :-- | :-- |
| 1.5.0 (中文(简体) ) | 解析旧的 SDK 版本, 添加 TraceContextInfo 支持 |
| 1.4.1 国家 | 与指标有关的类型和API的折旧 |
| 1.4.0 (中文(简体) ) | 添加对指标的支持(仅审查) |
| 1.3.0 (单位:千美元) | 添加支持到跟踪消息 |
| 1.2.2 国家 | 别吞了例外 |
| 1.2.1 国家 | 改进类型定义 |
| 1.2.0 (中文(简体) ) | 添加自定义请求属性的支持 |
| 1.1.0 国家 | 为 SQL 数据库跟踪器添加设置ResultData () |
| 1.0.3 (中文(简体) ) | 早期访问β |
| 1.0.1 (中文(简体) ) | 初步释放 |

## 常见问题

### @dynatrace/oneagent-sdk 是什么？

Dynatrace One Agent 的节点\.js SDK

### 如何安装 @dynatrace/oneagent-sdk？

在项目目录运行 npm install @dynatrace/oneagent-sdk，或使用 pnpm add / yarn add / bun add。

### @dynatrace/oneagent-sdk 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @dynatrace/oneagent-sdk 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @dynatrace/oneagent-sdk 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>= 10\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @dynatrace/oneagent-sdk 可以商用吗？

@dynatrace/oneagent-sdk 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @dynatrace/oneagent-sdk 的下载量有多少？

根据 npm 官方下载统计，@dynatrace/oneagent-sdk 在 2026/10/13 – 2026/11/11 这 30 天内被下载 47,183 次，日均约 1,573 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @dynatrace/oneagent-sdk 还在维护吗？

最新版本 1\.5\.0 发布于 2023/02/23（3 年前）；至今共发布 11 个版本，其中过去 12 个月发布了 0 个；首次发布于 2018/02/02。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。