拥抱 Web SDK

关于

Embrace Web SDK 建立在顶端之上 打开几何 为网络获取性能数据 应用程序,通过无缝连接网络和后端遥测,使您的系统具有完整的存储可观察性 就是这样.

通过这个SDK录制的遥测可以被 Embrace 平台所消耗,用于 Embrace 客户,但它也可以是 非客户直接向任何OTel收集器出口所收集的数据,或 它们主办或由其他供应商主办。 实际上,这种SDK是一种替代使用 OpenTeleometry JS SDK 互联网档案馆的存檔,存档日期2013-12-02 直接用于想要杠杆的网络应用程序 openTeleometer 生态系统的可观察性, 但也想要所有高级的遥测捕捉器, Embrace 已知 为.

目前,仅支持斯潘斯和日志,但未来会增加其他信号.

更多文件和实例可见于我们 网络文档

快速启动

安装软件包

无 :

npm install @embrace-io/web-sdk

线条 :

yarn add @embrace-io/web-sdk

[TIP] 关于CDN安装,见 包含 SDK 作为代码片段来自 CDN。 。 。 .

初始化 SDK

首先注册一个Embrace账户,方法是: https://dash.embrace.io/ signup (英语) (见 在不拥抱的情况下使用 如果你想跳过这一步的话.

一旦您创建了 Embrace 网络应用程序, 您可以使用您的应用程序初始化 SDK 应用程序的应用程序版本。 在应用的生命周期中,应该尽早开始以下工作 捕获遥测 :

import { initSDK } from '@embrace-io/web-sdk';

const result = initSDK({
  appID: 'YOUR_EMBRACE_APP_ID',
  appVersion: 'YOUR_APP_VERSION',
});

if (!!result) {
  console.log('Successfully initialized the Embrace SDK');
} else {
  console.log('Failed to initialize the Embrace SDK');
}

此时你应该能够重建你的应用 让Embrace开始收集遥测数据 数据应该开始到 一旦SDK报告至少1个已完成会话,就会出现在 Embrace Dashboard 中. 这可以通过发射触发 您的应用程序,然后通过关闭标签/窗口或简单地将其放入背景来结束会话.

[注] 可能要几分钟后 头几会才会出现在你的"拥抱"仪表板上.

添加痕迹

除了我们的自动仪器提供的东西之外 你还可以为您想要追踪的操作 创造自己的周期. 对于最基本的用法,只要开始一个周期,并在完成一些操作后结束:

import { trace } from '@embrace-io/web-sdk';

const span = trace.startSpan('span-name');

someAsyncOperation()
  .then(() => span.end())
  .catch(() => span.fail());

只能输出明确结束的跨度 。 属性和活动也可以添加到时间段 生前或后期。 我们的API 包了 OpenTeleometry 软件 Tracer 这样你就可以跟随 这些实例 更详尽的用例.

[注] 导出到 Embrace 时, 属性值必须是字符串, 即使 OTel 接口允许更宽 类型范围

添加日志

您可以向会话中添加基本上下文, 并释放出在会话时间表中可以看到的面包屑:

import { session } from '@embrace-io/web-sdk';

session.addBreadcrumb('something happened');

完整的日志信息也可以被发布 。 请注意,与出出出面包屑不同的是,木头更重并可能 触发网络请求以导出数据:

import { log } from '@embrace-io/web-sdk';

log.message('Loading not finished in time.', 'error', {
  attributes: {
    propertyA: 'valueA',
    propertyB: 'valueB',
  },
});

添加例外情况

SDK自动捕获未处理的例外.

如果需要登录一个已处理的例外,可以使用人工方式调用logException方法:

import { log } from '@embrace-io/web-sdk';

try {
  // some operation...
} catch (e) {
  log.logException(e as Error, {
    handled: true,
    attributes: {
      propertyA: 'valueA',
      propertyB: 'valueB',
    },
  });
}

反应仪器

与反应有关的仪器记录如下: 反应.md。 。 。 .

丰富元数据

您可以添加自定义属性, 作为当前会话的一部分 :

import { session } from '@embrace-io/web-sdk';

session.addProperty('my-custom-property', 'some value');

这些属性默认只包含在本会话中. 如果您想要添加在所有会话中发送的永久属性, 您可以配置寿命选项 :

session.addProperty('my-custom-property', 'some value', {
  lifespan: 'permanent',
});

不断更新您的应用程序版本

拥抱使用 appVersion 您可以提供收集到的片段遥测,并允许您查看差异 释放,因此,当您发布新版本的应用程序时,您应当确保更新此值。 若为 用你的电话 package.json 来跟踪你的应用软件的版本 然后不断更新的方法 就是读一下 初始化 SDK 时值( 假设您的捆绑器提供了导入 json 文件的方法) :

import * as packageInfo from '../<some-path>/package.json';

initSDK({
  appID: 'YOUR_EMBRACE_APP_ID',
  appVersion: packageInfo.version,
});

或者,如果您的应用程序版本是作为您的 CI/CD 进程的一部分生成的, 您可以使用我们的 CLI 工具来注入您的 应用程序版本在构建时输入您的捆绑 。 这个过程是 上传源代码图 说明 见下文.

上传源代码图

要在 Embrace 中查看象征性的堆栈痕迹, 您必须首先上传您的捆绑和源图 文档。 您可以使用我们的 CLI 工具这样做, 如果您还没有安装的话, 您可以使用:

无 :

npm install --save-dev @embrace-io/web-cli

线条 :

yarn add -D @embrace-io/web-cli

您还需要一个 Symbol Upload API标志. 这个可以在你的拥抱仪表板上找到 改为 设置 - > API 密码。 。 。 .

然后把CLI连接到你的构建过程中 并把它指向你所构建的JS文件所居住的路径 执行上传 :

npx embrace-web-cli upload -a "YOUR_EMBRACE_APP_ID" -t "YOUR_EMBRACE_UPLOAD_API_TOKEN" -p "JS_BUILD_PATH"

[尖叫声] 在文件被包装之前(例如,在创建多克图像或部署存档之前)必须运行 CLI . CLI 向捆绑文件的结尾插入一个注释和一个简短的函数以允许符号化,所以它需要 在包装之前发生.

此外, 如果您的应用版本只在构建时才为人所知, 您可以将它包含在相同的命令中, 以便它注入 进入捆绑。 如果您遵循这种方法, 调用时不包含应用软件 initSDK 由于该值需要 优先级 :

npx embrace-web-cli upload --app-version "APP_VERSION" -a "YOUR_EMBRACE_APP_ID" -t "YOUR_EMBRACE_UPLOAD_API_TOKEN" -p "JS_BUILD_PATH"

[注] 目前我们只支持用函数关键字定义函数名的符号化 . 对于指定给常数或变量的函数,您仍然可以看到未同步的符号 . 行号和列号,连同文件名,将永远被符号化为原始来源.

配置自动仪器

SDK提供数个自动仪器出箱,以改变这些设备的行为(或禁用某些设备) 完全的) 你可以通过一个 defaultInstrumentationConfig 初始化 SDK 时的对象 :

import { initSDK } from '@embrace-io/web-sdk';

initSDK({
  appID: 'YOUR_EMBRACE_APP_ID',
  appVersion: 'YOUR_APP_VERSION',
  defaultInstrumentationConfig: {
    omit: new Set(['@opentelemetry/instrumentation-fetch']),
  },
});

查看类型定义 defaultInstrumentationConfig 以查看整套配置选项.

对于更先进的定制,您也可以包括额外的仪器,只要它们符合 Instrumentation 接口 :

import { initSDK } from '@embrace-io/web-sdk';

initSDK({
  appID: 'YOUR_EMBRACE_APP_ID',
  appVersion: 'YOUR_APP_VERSION',
  instrumentations: [myCustomInstrumentation],
});

自定义出口商

您可以设置自定义日志并追踪出口商, 并在初始化 SDK 时通过 。 出口商应: 配置以指向一个相容的 OTLP 端点,并包含该端点所需的任何信头,例如 授权。 由于这些导出请求将由浏览器提出, 也要求端点返回 相关CORS标题:

import { OTLPLogExporter } from '@opentelemetry/exporter-logs-otlp-http';
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';

initSDK({
  appID: 'YOUR_EMBRACE_APP_ID',
  appVersion: 'YOUR_APP_VERSION',
  spanExporters: [
    new OTLPTraceExporter({
      url: 'https://example.com/endpoint/for/traces',
      headers: {
        Authorization: 'Basic TOKEN',
      },
    }),
  ],
  logExporters: [
    new OTLPLogExporter({
      url: 'https://example.com/endpoint/for/logs',
      headers: {
        Authorization: 'Basic TOKEN',
      },
    }),
  ],
  defaultInstrumentationConfig: {
    network: {
      ignoreUrls: [
        'https://example.com/endpoint/for/traces',
        'https://example.com/endpoint/for/logs',
      ],
    },
  },
});

[尖叫声] 拥抱会自动为网络请求创建跨度, 但因为 OTLP 导出本身会使网络 请求此选项可生成一个周期, 即导出网络请求所创建的周期, 然后导出该周期 创建另一个跨等.

为避免这种情况,您可以配置网络仪器,以忽略您要导出到的 URL , 如 上面的片断.

包含 SDK 作为代码片段来自 CDN

我们建议你把我们的SDK列为普通npm依赖(参见: 快速启动) (中文(简体) ). 如果你喜欢包含 sDK作为CDN的代码片段,您可以通过在您生成的 HTML 文件上添加以下脚本标记来做到这一点:

<script src="https://cdn.jsdelivr.net/npm/@embrace-io/web-sdk" crossorigin="anonymous"></script>

注意:我们推荐您给特定版本打针,以避免打破更改. 喜欢:

<script src="https://cdn.jsdelivr.net/npm/@embrace-io/[email protected]" crossorigin="anonymous"></script>

替换 X.X.X 包含您想要包含的 SDK 版本 。 检查可用的版本 打开 无。 。 。 .

我们建议你把这个脚本标记添加到 <head> 中的HTML文件,使其在应用程序代码之前加载。 这个会 将 SDK 暴露为全球变量 EmbraceWebSdk 编辑 window 对象。 脚本前需要添加此内容 使用sdk.

其余部分假设使用国家预防机制装置中的SDK, 此处需要作一些修改,以铭记 参考这些文件:

1. 从节点模块导入 sdk 已不再有效 。 相反,从全球范围参考 window 对象 :

   - import { initSDK, log, page, session, trace, user } from '@embrace-io/web-sdk';
   + const { initSDK, log, page, session, trace, user } = window.EmbraceWebSdk;
   

2. 我们的CLI工具在从CDN装入时不支持插入应用程序版本,因为在这种情况下,我们的SDK不是 与代码相捆绑,相反,您在初始化 sdk 时需要确保通过您的应用版本 实例如下:

   initSDK({
     appVersion: '0.0.1',
     /*...*/
   });
   

同步装入

如果您喜欢同步加载SDK以避免屏蔽页面的渲染,您需要添加 跟随片断到您的 HTML 文件。 记得替换 X.X.X 您想要包含的 SDK 版本 :

<script>
   !function(){window.EmbraceWebSdkOnReady=window.EmbraceWebSdkOnReady||{q:[],onReady:function(e){window.EmbraceWebSdkOnReady.q.push(e)}};let e=document.createElement("script");e.async=!0,e.crossOrigin="anonymous",e.src="https://cdn.jsdelivr.net/npm/@embrace-io/[email protected]",e.onload=function(){window.EmbraceWebSdkOnReady.q.forEach(e=>e()),window.EmbraceWebSdkOnReady.q=[],window.EmbraceWebSdkOnReady.onReady=function(e){e()}};let n=document.getElementsByTagName("script")[0];n.parentNode.insertBefore(e,n)}();
</script>

通过推迟SDK的装入,任何早期对SDK的呼叫都需要被包裹在 onReady 方法 :

window.EmbraceWebSdkOnReady.onReady(() => {
  window.EmbraceWebSdk.initSDK({
    appVersion: '0.0.1',
    /*...*/
  });
});

这对于确保SDK在开始使用前被满载是必要的.

[尖叫声] SDK可能会错过一些在SDK初始化前发射的早期遥测事件,如果使用这种方法的话.

运行 SDK 的多例

如果您在同一页上有多个应用程序并想要运行 SDK 的多个实例,您可以通过 为每个应用程序创建 SDK 实例。 确保旗帜 registerGlobally 设置为 false 何时 启动SDK.

import { initSDK } from '@embrace-io/web-sdk';

const embraceSDK = initSDK({
  appID: 'YOUR_EMBRACE_APP_ID',
  appVersion: 'YOUR_APP_VERSION',
  registerGlobally: false, // Prevents the SDK from registering itself globally
});

由于SDK没有在全球注册,您需要使用 embraceSDK 实例访问 SDK 方法 以及财产.

import { initSDK } from '@embrace-io/web-sdk';

const embraceSDK = initSDK({
  appID: 'YOUR_EMBRACE_APP_ID',
  appVersion: 'YOUR_APP_VERSION',
  registerGlobally: false, // Prevents the SDK from registering itself globally
});

// Use this
embraceSDK.log.message('This is a log message', 'info');

// Instead of
import { log } from '@embrace-io/web-sdk';

log.message('This is a log message', 'info');

一些仪器仍在全球注册,我们正积极地努力使每个设备都适合本地:

• 获取和 XHR 仪器补丁全局功能(globalThis.fetch 财务报告和审定财务报表 XMLHttpRequest.prototype) (中文(简体) ). 何时 在同一页上运行的多个 SDK 实例,每个实例都安装了自己的包装并生成跨度 每一个网络请求.
• 全局错误处理器会听到所有未处理的错误和拒绝, 所有 SDK 都会报告所有错误 没有被抓住.

网络跨度转发

SDK可以被配置为在向外发送的网络请求中注入一个痕量母头. 此标题包括 客户端追踪ID与该特定网络跨度相关。 在Enbrace后端,这些网络跨度就可以了 被传送到您选择的其他遥测提供者。 这样你就能一边看客户端 服务器侧式的,构成同一总体跟踪的一部分,以提供端到端的表示. 更多细节可以 发现于 网络扩展转发文档页面。 。 。 .

这个功能的赋能和配置是通过我们的Enbrace仪表板完成的,所以不需要在其中设置 SDK可以打开它,但是有一些SDK侧面的配置使得特性无法意识到:

启用特定CORS请求

默认情况下 traceparent 发出CORS请求时不包含标题 。 这是因为服务器是 命中可能无法配置允许为 CORS 请求添加信头(参见 访问控制- Allow 标题) (中文(简体) ). 您可以指定您想要转发 CORS 请求和允许您接受的特定 URL 将获取或 XHR 仪器配置为允许的字符串和正则列表后的额外标题 :

import { initSDK } from '@embrace-io/web-sdk';

initSDK({
  appID: 'YOUR_EMBRACE_APP_ID',
  appVersion: 'YOUR_APP_VERSION',
  defaultInstrumentationConfig: {
    '@opentelemetry/instrumentation-fetch': {
      propagateTraceHeaderCorsUrls: [
        /example\.com/, // propagates for any CORS requests with URLs that match the regex
        'https://www.example.com/foo', // propagates for CORS requests to URLs that exactly match the string
      ],
    },
    '@opentelemetry/instrumentation-xml-http-request': {
      propagateTraceHeaderCorsUrls: [
        /example\.com/, // propagates for any CORS requests with URLs that match the regex
        'https://www.example.com/foo', // propagates for CORS requests to URLs that exactly match the string
      ],
    },
  },
});

冲突配置

SDK的特定配置与Network Span Transforming不相容,并将导致特性成为 设定时关闭 :

import { initSDK } from '@embrace-io/web-sdk';

initSDK({
  appID: 'YOUR_EMBRACE_APP_ID',
  appVersion: 'YOUR_APP_VERSION',

  // The following are not supported alongside Network Span Forwarding and will cause that feature to turn off:
  // 1. Setting registerGlobally to false
  registerGlobally: false,
  // 2. Providing a custom propagator
  propagator: myCustomPropagator,
  // 3. Omitting both network instrumentations
  defaultInstrumentationConfig: {
    omit: new Set([
      '@opentelemetry/instrumentation-fetch',
      '@opentelemetry/instrumentation-xml-http-request',
    ]),
  },
});

屏蔽客户端

A 类 blockNetworkSpanForwarding 可用配置旗来屏蔽网络分页转发特性, 不论 已配置的服务器侧:

import { initSDK } from '@embrace-io/web-sdk';

initSDK({
  appID: 'YOUR_EMBRACE_APP_ID',
  appVersion: 'YOUR_APP_VERSION',

  blockNetworkSpanForwarding: true,
});

在不拥抱的情况下使用

如果你不想把数据寄给Embrace 你只要在呼叫时省略了拥抱应用程序的ID initSDK。请注意 此例至少需要按照步骤配置一个自定义导出者 从 自定义出口商 或者SDK认为配置无效.

浏览器支持

SDK是作为模块被导入,由捆绑机转接. 我们提供一个ES2022模块版本,供使用 在现代建筑管道。 OpenTeleometry设定了当前ES2022的最小语言特性支持. 我们的默认无害环境管理 SDK也以此为目标,以确保兼容性. 详见 页:1 打开几何文件。 。 。 .

我们还提供CDN版本,可转录到ES6/ES2015,与更古老的浏览器实现最大兼容.

解决问题

主要版本之间的升级

请看我们的 升级指南 具体步骤.

与 OTel 包的兼容性

SDK建于OpenTeleometry上方,因此可以与其他OTel库并用. 重要:新项目应使用OpenTeleomet 2.x. OpenTeleomet 1.x支持仅限于SDK的1.x版本,这些版本被贬值.

如果您希望通过配置自定义资源、出口商、处理器或仪器来定制 SDK 行为, 您必须确保您使用与我们的 SDK 兼容的 OTel 软件包的版本 :

关于SDK使用的依赖性完整清单,请参见: 软件包.json。 。 。 .

打开SDK的动词记录

默认情况下,SDK只会向控制台发送出错级别日志. 当 初始化情况如下:

import { initSDK, DiagLogLevel } from '@embrace-io/web-sdk';

initSDK({
  appID: 'YOUR_EMBRACE_APP_ID',
  appVersion: 'YOUR_APP_VERSION',
  logLevel: DiagLogLevel.ALL,
});

此外,将SDK初始化为 ConsoleLogRecordExporter 财务报告和审定财务报表 ConsoleSpanExporter 出口商允许您接受 更详细地查看SDK出口的跨度和日志。 可以设立海关出口商, 在这种情况下,其输出将进行分批处理,或用自定义处理器包裹,以看到遥测输出时的输出 发射 :

import { initSDK, DiagLogLevel } from '@embrace-io/web-sdk';
import {
  ConsoleLogRecordExporter,
  SimpleLogRecordProcessor,
} from '@opentelemetry/sdk-logs';
import {
  ConsoleSpanExporter,
  SimpleSpanProcessor,
} from '@opentelemetry/sdk-trace';

initSDK({
  appID: 'YOUR_EMBRACE_APP_ID',
  appVersion: 'YOUR_APP_VERSION',
  logLevel: DiagLogLevel.INFO,

  // setup as exporters to output with the same batching as when exporting to a collector endpoint
  spanExporters: [new ConsoleSpanExporter()],
  logExporters: [new ConsoleLogRecordExporter()],

  // OR, wrap exporters with simple processors to output as soon as telemetry is emitted
  spanProcessors: [new SimpleSpanProcessor(new ConsoleSpanExporter())],
  logProcessors: [new SimpleLogRecordProcessor(new ConsoleLogRecordExporter())],
});

仅客户端使用

Embrace SDK是为浏览器环境而设计的. 导入到服务器侧码( 如 Next.js 服务器组件, API 路由, 边缘中端软件) 不会产生运行时间错误, 因为 initSDK 检测非浏览环境和返回 false. SDK API 喜欢 session 财务报告和审定财务报表 trace 需要浏览器上下文,并且不会在服务器上运行.

为了取得最佳效果,导入并初始化SDK只使用客户端代码. Next.js 设置,包括 App 路由器和页面 路由器示例和构建配置,参见 下一届。 。 。 .

财务问题

SDK 的数据如何导出

参见 数据出口.md 关于数据如何从SDK输出的细节.

如何保护敏感数据

SDK提供了几个帮助保护敏感数据的选项,参见: 改为 本准则 更多信息.

支助

如果你有特别建议或者发现一些不正确的东西 请打开 a 一个 问题 由拥抱团队进行分解或接触 我们 社区黑 直接,更快的援助.

捐款

请参看我们 捐款指南 要开始.