# @embrace-io/react-native-tracer-provider 中文文档

规范地址：https://npmcn.com/package/%40embrace-io/react-native-tracer-provider/

版本：7\.2\.0
npm 元数据更新时间：2026-10-08T17:08:48.742Z
中文译文更新时间：2026-11-13T15:00:33.742Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40embrace-io/react-native-tracer-provider
原文对照：https://npmcn.com/package/%40embrace-io/react-native-tracer-provider/?lang=original
项目主页：https://github.com/embrace-io/embrace-react-native-sdk
源码仓库：https://github.com/embrace-io/embrace-react-native-sdk

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

- 包体积（解压后）：99.8 kB，40 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- peer 依赖：react-native \>=0\.56\.0
- 首次发布：2024-10-22T18:45:15.316Z
- 最新版本发布：2026-10-08T17:08:48.173Z
- 近 30 天下载量：32656（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：20（近 12 个月 9 个）

## 中文简介

符合 OpenTeleometry Tracer 接口的嵌入式 SDK 反应原生

## 安装

```sh
npm install @embrace-io/react-native-tracer-provider
```

也可以使用：`pnpm add @embrace-io/react-native-tracer-provider`、`yarn add @embrace-io/react-native-tracer-provider`、`bun add @embrace-io/react-native-tracer-provider`

## README

# 反应土著拥抱 - 土著追踪提供者

> \[大
> 
> 本单元要求 [反应原生拥抱 SDK](https://www.npmjs.com/package/@embrace-io/react-native)。 。 。 .

此软件包将 Embrace 的本地 SDK 包裹在 OpenTeleometry 上 [追踪提供者](https://opentelemetry.io/docs/concepts/signals/traces/#tracer-provider)。 。 。 . 允许根据 OpenTeleometry 的 JS API 创建自定义仪器,并从中收集痕迹 任何包含在您的应用程序中的 JS Openterometry 仪器库或本地仪器.

### 安装

无 :

```sh
npm install @embrace-io/react-native-tracer-provider
```

线条 :

```sh
yarn add @embrace-io/react-native-tracer-provider
```

对于iOS,您还需要安装或更新应用程序的吊舱:

```sh
cd ios && pod install --repo-update
```

### 在代码中设置

在您的应用程序周期开始附近初始化 Tracer 提供者 。 拥抱SDK需要先开始 可以使用跟踪提供者。 要做到这一点, 您可以在安装提供者的组件之前启动 SDK ,或者你可以使用 `enabled` 参数 `useEmbraceNativeTracerProvider` 来防止它 启动到 SDK 准备好, 如此例子:

```javascript
const {isStarted} = useEmbrace({
  ios: SDK_CONFIG,
});

const optionalConfig = {...}; // See EmbraceNativeTracerProviderConfig in ./src/types/ for possible options
const {tracerProvider: embraceTracerProvider, tracer: embraceTracer} = useEmbraceNativeTracerProvider(optionalConfig, isStarted);
```

然后可以使用提供的追踪器在您的应用程序中添加自定义仪器:

```javascript

const MyScreen = () => {
  useEffect(() => {
    span = embraceTracer.startSpan("my-span");

    someAsyncOperation().then(() => span.end());
  }, []);
  return <View />;
};
```

如果你不想绕来绕去的话 `tracer` 对象,您可以从 `@opentelemetry/api` 图书馆。 首先将 Embrace 追踪器提供商注册为全局:

```javascript
import { trace } from "@opentelemetry/api";
trace.setGlobalTracerProvider(embraceTracerProvider);
```

然后,你可以在苍蝇上创建新的追踪器 需要的地方和 `getTracer` 来自OTel API 的方法将知道 使用 Embrace 作为跟踪提供者 :

```javascript
import { trace } from "@opentelemetry/api";

const MyScreen = () => {
  useEffect(() => {
    const tracer = trace.getTracer("my-application");
    
    span = tracer.startSpan("my-span");

    someAsyncOperation().then(() => span.end());
  }, []);

  return <View />;
};
```

这种在全球注册跟踪器提供者的方法也意味着您应用程序中的任何OTel仪器库 现在可以自动找到Embrace的提供商,并将其用于追踪.

### 限制

-   目前不支持将链接添加到跨度中, `span.addLink(...)` 财务报告和审定财务报表 `span.addLinks(...)` 举起手来.
-   目前只支持字符串跨度属性, 其他类型将转换为字符串表达式
-   `parentSpanId` 如果父母的跨度在孩子的跨度开始的上一个会话中已经结束,则将不会设定
-   由于OTEL Swift API中的限制 `schemaUrl` 呼吁 `getTracer` 在 iOS 上被忽略
-   由于与本地模块的通信是同步的 `span.spanContext()` 如果 呼叫后立即执行 `startSpan` 例如:

```javascript
  const mySpan = tracer.startSpan("my-span");
  const spanContext = mySpan.spanContext(); // can be configured to throw an error instead through EmbraceNativeTracerProviderConfig

  console.log(spanContext.traceId) // prints ""
  console.log(spanContext.spanId) // prints ""
```

为避免这个问题,您可以使用同步版本:

```javascript
  const mySpan = tracer.startSpan("my-span");
  const spanContext = await (mySpan as EmbraceNativeSpan).spanContextAsync();

  console.log(spanContext.traceId) // prints "51e60a6917dfe46871d7f1d39f66d02c"
  console.log(spanContext.spanId) // prints "b2248eb58720064e"
```

## 常见问题

### @embrace-io/react-native-tracer-provider 是什么？

符合 OpenTeleometry Tracer 接口的嵌入式 SDK 反应原生

### 如何安装 @embrace-io/react-native-tracer-provider？

在项目目录运行 npm install @embrace-io/react-native-tracer-provider，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react-native（\>=0\.56\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @embrace-io/react-native-tracer-provider 支持 TypeScript 吗？

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

### @embrace-io/react-native-tracer-provider 支持 ESM 还是 CommonJS？

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

### @embrace-io/react-native-tracer-provider 可以商用吗？

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

### @embrace-io/react-native-tracer-provider 的下载量有多少？

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

### @embrace-io/react-native-tracer-provider 还在维护吗？

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