# @embrace-io/react-native-otlp 中文文档

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

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

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

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

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

- 包体积（解压后）：62.4 kB，31 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：react-native \>=0\.56\.0
- 首次发布：2025-01-06T17:29:00.136Z
- 最新版本发布：2026-10-08T17:08:47.420Z
- 近 30 天下载量：10936（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：17（近 12 个月 9 个）

## 中文简介

用于 Embrace SDK 的回放原生包装, 允许连接到 OTLP 端点

## 安装

```sh
npm install @embrace-io/react-native-otlp
```

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

## README

# 反应原生拥抱 - OTLP

> \[尖叫声\] 此套件被贬值,将在下个主要发行中被移除. 相反, [在本地代码中启动拥抱](https://embrace.io/docs/react-native/integration/session-reporting/#start-embrace-sdk-in-the-native-side) 财务报告和审定财务报表 [配置本地 SDK 中的 OTLP 导出](https://embrace.io/docs/react-native/features/otlp/#initializing-in-the-native-layer)。 。 。 .

这个 [打开遥测协议](https://opentelemetry.io/docs/specs/otel/protocol/) (OTLP)是一种开放的标准,它能够将可观察性数据——例如痕迹和日志——从应用转移到各种监测和分析后端。 通过采用OTLP,开发者可以以一致的格式发送遥测数据,使多个后端的集成直截了当.

这一组件为通过HTTP向任何OTLP兼容后端输出跟踪和日志数据提供了一种简单的方式. 该组件还不断向Embrace发送遥测数据,确保Embrace平台的持续可观察性,同时允许用户将数据导出至其他可观察后端.

# 所需资源

使用此软件包必须事先安装 `@embrace-io/react-native` 和综合。 要了解更多情况 请访问我们 [文档](https://embrace.io/docs/react-native/integration/)。 。 。 .

# 一体化

## 添加 JavaScript 库

无 :

```sh
npm install @embrace-io/react-native-otlp
```

线条 :

```sh
yarn add @embrace-io/react-native-otlp
```

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

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

## 初始化

举例来说,我们将使用Grafana Cloud, 用OTLP的端点, 将遥测数据重新定位。 详情请上网查询 [文档](https://grafana.com/docs/grafana-cloud/send-data/otlp/send-data-otlp/)。 。 。 .

```javascript
import React, {useEffect, useMemo, useState} from "react";
import {useEmbrace} from "@embrace-io/react-native";
import {View, Text} from "react-native";
import {Stack} from "expo-router";

// for this particular case where we use Grafana Cloud this token should be passed with the format `instance:token` converted into a base64 string.
const GRAFANA_TOKEN = "base64(instance:token)";
const EXPORT_CONFIG = {
  logExporter: {
    endpoint: "https://otlp-gateway-prod-us-central-0.grafana.net/otlp/v1/logs",
    headers: [
      {
        key: "Authorization",
        token: `Basic ${GRAFANA_TOKEN}`,
      },
    ],
  },
  traceExporter: {
    endpoint:
      "https://otlp-gateway-prod-us-central-0.grafana.net/otlp/v1/traces",
    headers: [
      {
        key: "Authorization",
        token: `Basic ${GRAFANA_TOKEN}`,
      },
    ],
  },
};

// this is the minimum of configuration needed at this point,
// for more information please refer to docs under [`@embrace-io/react-native`](../core).
// iOS is configurable through code, Android configuration happens at build time
const SDK_CONFIG = {appId: "abcde"};

function RootLayout() {
  const {isPending, isStarted} = useEmbrace({
    ios: SDK_CONFIG,
    exporters: EXPORT_CONFIG
  });

  if (isPending) {
    return (
      <View>
        <Text>Loading Embrace</Text>
      </View>
    );
  } else {
    if (!isStarted) {
      console.log('An error occurred during Embrace initialization');
    }
  }

  // regular content of the application
  return (
    <Stack>
      <Stack.Screen name="(tabs)" options={{headerShown: false}} />
    </Stack>
  );
}

export default RootLayout;
```

## 在土著地层初始化

如果您已经将 Embrace React 原生 SDK 初始化, 或者您正在计划运行我们文件节中提到的安装脚本, 您仍然可以从 OTLP 自定义导出功能中获益 。 记住安装脚本正在添加初始化 Embrace 在原住民一侧所需的最小代码, 但并没有将导出遥测数据的配置整合到您选择的后端 。 为此,你需要手动调整Android/iOS两侧.

### iOS系统

如果您已经运行了上面提到的安装脚本, 您就可以找到 `EmbraceInitializer.swift` 带有您可以更新的初始代码的文件 :

```swift
import Foundation
import EmbraceIO
import RNEmbraceOTLP // Do not forget to import `RNEmbraceOTLP` module which will make the proper classes available

let GRAFANA_AUTH_TOKEN = "Basic __YOUR TOKEN__"
let GRAFANA_TRACES_ENDPOINT = "https://otlp-gateway-prod-us-central-0.grafana.net/otlp/v1/traces"
let GRAFANA_LOGS_ENDPOINT = "https://otlp-gateway-prod-us-central-0.grafana.net/otlp/v1/logs"

@objcMembers class EmbraceInitializer: NSObject {
    static func start() -> Void {
        do {
          // Preparing Span Exporter config with the minimum required
          let traceExporter = OtlpHttpTraceExporter(endpoint: URL(string: GRAFANA_TRACES_ENDPOINT)!,
            config: OtlpConfiguration(
                headers: [("Authorization", GRAFANA_AUTH_TOKEN)]
            )
          )
          
          // Preparing Log Exporter config with the minimum required
          let logExporter = OtlpHttpLogExporter(endpoint: URL(string: GRAFANA_LOGS_ENDPOINT)!,
             config: OtlpConfiguration(
                headers: [("Authorization", GRAFANA_AUTH_TOKEN)]
             )
          )
          
          try Embrace
              .setup(
                  options: Embrace.Options(
                      appId: "__YOUR APP ID__",
                      platform: .reactNative,
                      export: OpenTelemetryExport(spanExporter: traceExporter, logExporter: logExporter) // passing the configuration into `export`
                  )
              )
              .start()
        } catch let e {
            print("Error starting Embrace \(e.localizedDescription)")
        }
    }
}
```

### 机器人

与 iOS 类似, 如果您已经运行了安装脚本, 您将会看到您已设置的以下行 `MainApplication` 文件 :

```
Embrace.start(this)
```

扭动 `onCreate` 使用以下片段以初始化出口商的方法,并采用所需的最低配置.

拥抱暴露出两种注册自定义出口商的方法,这取决于您出口商的OpenTeleometry API的构建方式:

-   `Embrace.addSpanExporter` 编号 : `Embrace.addLogRecordExporter` 接受 OpenTeleometry Kotlin 出口商.
-   `Embrace.addJavaSpanExporter` 编号 : `Embrace.addJavaLogRecordExporter` 接受 OpenTeleomet Java 导出 .

下面的例子使用OpenTeleomet Java导出.

增加下列进口:

```kotlin
import io.opentelemetry.exporter.otlp.http.trace.OtlpHttpSpanExporter
import io.opentelemetry.exporter.otlp.http.logs.OtlpHttpLogRecordExporter
```

然后在"OnCreate"方法中列出以下内容:

```kotlin
// Preparing Span Exporter config with the minimum required
val spanExporter = OtlpHttpSpanExporter.builder()
                                .setEndpoint("https://otlp-gateway-prod-us-central-0.grafana.net/otlp/v1/traces")
                                .addHeader("Authorization", "Basic __YOUR TOKEN__")

// Preparing Log Exporter config with the minimum required
val logExporter = OtlpHttpLogRecordExporter.builder()
                                .setEndpoint("https://otlp-gateway-prod-us-central-0.grafana.net/otlp/v1/logs")
                                .addHeader("Authorization", "Basic __YOUR TOKEN__")

Embrace.addJavaSpanExporter(spanExporter.build())
Embrace.addJavaLogRecordExporter(logExporter.build())

// This is the line already added by the install script
Embrace.start(this)
```

## 禁用对 OTLP 导出网络请求的跟踪

拥抱会自动为网络请求创建跨度, 但因为 OTLP 导出本身会提出网络请求 这样可以产生一个循环,使导出网络请求产生一个跨度,然后导出,然后创建另一个跨度 间距等.

为避免这种情况, 您可以配置您正在导出到的端点, 以忽略 Android 和 iOS .

### 机器人

编辑 `android/app/src/main/embrace-config.json` 在应用程序中添加 `disabled_url_patterns` 键。 在上述例子中 如果你出口到格拉法纳 你的配置看起来像:

```json
{
  "app_id": "xxxxx",
  "api_token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "sdk_config": {
    "app_framework": "react_native",
    "networking": {
      "enable_network_span_forwarding": true,
      "disabled_url_patterns": [
        "grafana.net"
      ]
    }
  }
}
```

### iOS系统

在联署材料中初始化时,您只需包括 `disabledUrlPatterns` 键,在上述示例中,如果您是 导出到 Grafana 您将在 `SDK_CONFIG`数字 :

```json
"disabledUrlPatterns": [
    "grafana.net"
]
```

在斯威夫特初始化时,在设置 Embrace 时需要更多的配置. 首先将以下导入添加到 `EmbraceInitializer.swift`数字 :

```swift
import EmbraceCrash
```

然后设置自定义 `URLSessionCaptureService` 忽略格拉法纳导出:

```swift
let servicesBuilder = CaptureServiceBuilder()
let urlSessionServiceOptions = URLSessionCaptureService.Options(
  injectTracingHeader: true,
  requestsDataSource: nil,
  ignoredURLs: ["grafana.net"]
)
// manually adding the URLSessionCaptureService
servicesBuilder.add(.urlSession(options: urlSessionServiceOptions))
// adding defaults
servicesBuilder.addDefaults()
```

启动 SDK 时最后通过附加配置 :

```swift
try Embrace
    .setup(
        options: Embrace.Options(
          appId: "__YOUR APP ID__",
          platform: .reactNative,
          captureServices: servicesBuilder.build(),
          crashReporter: EmbraceCrashReporter(),
          export: OpenTelemetryExport(spanExporter: traceExporter, logExporter: logExporter) // passing the configuration into `export`
        )
    )
    .start()
```

## 解决问题

请参看我们 [完整整合指南](https://embrace.io/docs/react-native/integration/)继续 遇到问题,请 [直接联系我们](mailto:support@embrace.io) 或伸出我们 [社区黑](https://community.embrace.io/)

## 常见问题

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

用于 Embrace SDK 的回放原生包装, 允许连接到 OTLP 端点

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

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

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

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

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

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

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

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

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

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

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

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