官方 Corlogix 反应原生插件

此软件包取代旧的 @coralogix/react-native-sdk 软件包.

链接

• 更改日志
• 实际用户监测

使用量

要使用 Corlogix SDK, 请打电话 CoralogixRum.init(options) 在应用程序加载后最快可用的时刻. 这将根据您提供的选项初始化 SDK . init 是一个 async 函数.

import { CoralogixRum } from '@coralogix/react-native-plugin'

await CoralogixRum.init({
  application: 'app-name',
  environment: 'production',
  public_key: 'abc-123-456',
  coralogixDomain: 'EU2',
  version: 'v1.0.3',
  labels: {
    payment: 'visa',
  },
  ignoreErrors: ['some error message to ignore'],
  ignoreUrls: [/.*\.svg/, /.*\.ico/], // will ignore all requests to .svg and .ico files 
  sessionSampleRate: 100, // Percentage of overall sessions being tracked, Default to 100%
});

本地 SDK 应用 sessionSampleRate 每届届会一次,包括每次新的届会 上届届会结束后的届会。 设定为全部百分比 0- 说吧100。 。 。 . 插件将分数值绕入整数, 绝不绕入非零速率 降为 0,因为原生桥读取值为整数.

一个抽取的会话仍然初始化了SDK,并且,当 traceParentInHeader 实值 启用,但仍添加 traceparent 发送请求的页眉, 所以后端跟踪 保持关联。 除此之外,它什么也没有报告,除非 excludeFromSampling 清单 至少一类:没有初始化事件,没有 session_replay_init 即使当 会话重放开始 。 列出一个类别,并报告该类别以及 SDK自己的内部事件.

提供背景资料或传送手动日志,利用导出功能 CoralogixRum。 。 。 . 记住这些功能在您使用之前 将一直没有活动 CoralogixRum.init()。 。 。 .

import { CoralogixRum } from '@coralogix/react-native-plugin';

// Update user context dynamically
CoralogixRum.setUserContext({
  user_id: '123',
  user_name: 'name',
  user_email: '[email protected]',
  account_id: 'acc-42', // optional, from 0.12.0
  account_name: 'Acme Corp', // optional, from 0.12.0
  user_metadata: {
    role: 'admin',
    // ...
  },
});

// Update custom labels dynamically
CoralogixRum.setLabels({
  ...CoralogixRum.getLabels(),
  paymentMethod: 'visa',
  userTheme: 'dark',
  // ...
});

// Update application context dynamically
CoralogixRum.setApplicationContext({
  application: 'app-name',
  version: '1.0.0',
});

CoralogixRum.log(CoralogixLogSeverity.Error, 'this is a log', { key: 'value' });
CoralogixRum.error('this is a log with error severity', { key: 'value' });

自定义日志

发送带有可选数据和标签的结构化日志.

CoralogixRum.log(CoralogixLogSeverity.Error, 'this is a log', { key: 'value' });

所有日志断块都存在短手签名 :

CoralogixRum.debug('this is a debug log', {key: 'value', pi: 3.14});
CoralogixRum.error('this is an error log', {error: 'yes', is_bad: 'no'});

[注] 由于React Natural的限制,并非所有的值类型都支持日志数据值. 我们的测试显示,反应土著不能将某些类型传递到珊瑚纪原生地层;我们确认的问题在于: Map, (中文(简体) ), Set, (中文(简体) ), Date 财务报告和审定财务报表 Function。 。 。 . 可能还有更多 例如:

// this would pass as an empty object to the coralogix native layer, same for Set and Date:
CoralogixRum.debug('this will be a problem', {key: new Map().set(1, 2)});

// this would pass as null to the coralogix native layer
CoralogixRum.debug('this will be a problem too', {key: () => {}});

如果你需要通过任何一种类型, 在你把它们交给 log 方法.

报告错误

报告用可选的结构化数据和标签处理错误. 每个错误事件选择下面的一个变体 ——每次调用都会生成单一出错报告.

参数:

• error (错误):报告错误对象.
• isCrash (布尔): 此错误是否代表崩溃( W)true)或经处理的例外情况(false) (中文(简体) ).
• data (可选):附在错误事件上的结构化数据对象. 空对象被省略 .
• labels (可选):用于对错误事件进行分类的密钥值对. 空对象被省略 .

备选案文1:基本错误报告

import { CoralogixRum } from '@coralogix/react-native-plugin';

try {
  await processPayment(order);
} catch (error) {
  CoralogixRum.reportError(error, false);
}

备选案文2:结构化数据

try {
  await processPayment(order);
} catch (error) {
  CoralogixRum.reportError(error, false, {
    orderId: '12345',
    paymentMethod: 'visa',
    amount: 99.99,
  });
}

备选案文3:有数据和标签

try {
  await processPayment(order);
} catch (error) {
  CoralogixRum.reportError(
    error,
    false,
    { orderId: '12345', amount: 99.99 },
    { team: 'payments', severity: 'high' }
  );
}

报告相撞事故:

try {
  await criticalOperation();
} catch (error) {
  CoralogixRum.reportError(
    error,
    true, // isCrash = true
    { operation: 'criticalTask', stage: 'initialization' },
    { environment: 'production' }
  );
}

查看跟踪

要跟踪视图,请在视图发生变化时设置视图上下文.

CoralogixRum.setViewContext({
  view: 'Home',
});

您可以使用 反应导航。 。 。 . 使用 StateChange 上的导航控制器回调跟踪路由变化并手动更新视图上下文,如下所示:

<NavigationContainer
  ref={navigationRef}
  onStateChange={() => {
    const currentRouteName = navigationRef.current.getCurrentRoute().name;

    CoralogixRum.setViewContext({ view: currentRouteName });
  }}
>
  {/* ... */}
</NavigationContainer>

重新创建会话

根据需要重新创建 RUM 会话——例如用户登录——以便 随后的活动属于新会话,新会话代号.

CoralogixRum.createNewSession();

仪器

打开/关闭特定仪器;默认为所有人真实. 每个仪器都负责SDK为您追踪和收集的数据.

await CoralogixRum.init({
  // ...
  instrumentations: {
    errors: true,
    custom: true,
    mobile_vitals: true,
    anr: true,
    lifecycle: true,
    user_interaction: true,
    network: true
  },
});

[注] 网络仪器也注入了W3C traceparent 头曰. 设置 network 改为 false 也停止跟踪上下文的传播,即使 traceParentInHeader 已启用.

移动生命探测器

禁用特定的移动生命值检测和收集

await CoralogixRum.init({
  // ...
  mobileVitals: {
    warm: true,
    cold: true,
    cpu: true,
    memory: true,
    rendering: true,
    slowFrozenFrames: true,
  }
});

冷的开始

报告每个用户可见的发射有两个冷启动值:

• cold ——由原生SDK测得:过程从第一个原生帧入手.
• cold_hybrid ——由插件测量:进程开始到第一个带有反应内容的框架 在屏幕上。 这是您的用户实际看到的发射时间,所以它至少总是 cold。 。 。 .

设置 mobileVitals.cold (或 instrumentations.mobile_vitals改为: false 两者都禁用. 从背景开始的启动(无头JS,背景取取取,推取)和预发iOS 发射不报告 cold_hybrid。 。 。 .

[注] 关于Android, cold_hybrid 未以无桥模式报告( 新架构默认) 由于 React Industrial 0.74 : React Industrial 只发布它依赖的内容出现的标记 当应用程序运行与桥梁.

不包括抽样

默认情况下,当一个会话被采样出来时(通过 sessionSampleRate),没有 报道了RUM事件. 使用 excludeFromSampling 继续报告具体 事件分类,即使会议被抽取.

import { CoralogixRum } from '@coralogix/react-native-plugin';

await CoralogixRum.init({
  // ...
  sessionSampleRate: 10,
  excludeFromSampling: ['errors', 'logs'], // always emitted, even for sampled-out sessions
});

允许的值 : 'errors', (中文(简体) ), 'logs', (中文(简体) ), 'network', (中文(简体) ), 'userInteractions', (中文(简体) ), 'mobileVitals', (中文(简体) ), 'customSpan', (中文(简体) ), 'customMeasurement', (中文(简体) ), 'navigation',以及 'lifecycle'。 。 。 . 'navigation' 财务报告和审定财务报表 'lifecycle' 可在0.15.0版本查阅. 这些与本地iOS和Android SDKs所接受的价值观相同. 插件忽略 一个未识别的值并记录一个给它命名的警告.

excludeFromSampling 仅影响抽取的会议;抽取的会议 报告所有启用的内容。 它永远无法重现 工具你 关入 instrumentations: 与 instrumentations: { network: false }, (中文(简体) ), 列名 'network' 这里没有效果.

这里列出任何东西 也带回了SDK自己的内部事件—— 启动事件,以及 session_replay_init 当会话重放开始时——用于此 抽样会议。 列表为空,会话完全不报告 .

内部a beforeSend 召回电话, session_context.isSessionSampledIn 告诉你一个事件是来自抽样的会话,还是只通过 excludeFromSampling因此,可以进一步过滤被排除在外的类别.

忽略错误

忽略错误选项允许您排除符合特定标准的错误 . 此选项接受一组字符串和正则表达式来匹配事件的错误消息 . 使用正则表达式进行精确匹配, 因为字符串会删除部分匹配 .

import { CoralogixRum } from '@coralogix/react-native-plugin';

await CoralogixRum.init({
  // ...
  ignoreErrors: [/Exact Match Error Message/, 'partial/match'],
});

TracePurent 信头

在信头中添加可跨服务界限的微量上下文传播

await CoralogixRum.init({
  // ...
  traceParentInHeader: {
    enabled: true
  },
});

[注] 这个 traceparent 信头由网络仪表所添加,因此这个特性取决于它. 若为 您设置 instrumentations.network 改为 false,即使与 enabled: true。 。 。 .

从0.15.0版本开始,末端的微量旗 traceparent 遵循会议 iOS和Android的取样决定:

• 01 (抽样)会议取样时,或取样时 excludeFromSampling 包含 'network'。 。 。 .
• 00 (未抽样)会议抽出和 'network' 除外.

请求开始于 CoralogixRum.init 完成带无 traceparent 头曰.

如果你的Android应用软件没有应用 Corlogix Gradle 插件,插件会添加标题 从 Java 脚本。 每个 fetch 这得到一个 traceparent {\fn黑体\fs22\bord1\shad0\3ahbe\4ah00\fscx67\fscy66\2chffffff\3ch808080}然后等500多毫秒 {\fn黑体\fs22\bord1\shad0\3ahbe\4ah00\fscx67\fscy66\2chffffff\3ch808080}再等500多毫秒 原生SDK的采样决定, 如果决定不做, 则不用头条就出去 及时赶到 为了保持等待 请求你不需要追踪,只列出你自己 服务 traceParentInHeader.options.allowedTracingUrls。 。 。 .

自定义纸

创建手动 RUM 跨度用于您的应用程序中的自定义工具流程 。 要求数 traceParentInHeader.enabled: true。 。 。 .

先决条件:

await CoralogixRum.init({
  // ...
  traceParentInHeader: { enabled: true },
});

基本用途——全球范围的儿童:

import { CoralogixRum } from '@coralogix/react-native-plugin';

const tracer = CoralogixRum.getCustomTracer();

const globalSpan = await tracer.startGlobalSpan('checkout', { step: 'start' });
if (!globalSpan) return; // another global span is already active

const childSpan = await globalSpan.startCustomSpan('validate-cart');
await childSpan?.endSpan();

await globalSpan.endSpan();

连接网络请求 withContext数字 :

当你打电话 fetch 内部 withContext,网络请求会自动链接到当前全球范围的跟踪.

const globalSpan = await tracer.startGlobalSpan('checkout');

await globalSpan.withContext(async () => {
  await fetch('https://api.example.com/cart'); // linked to globalSpan's traceId
});

await globalSpan.endSpan();

ignoredInstruments - 将自动仪器排除在跟踪之外:

传出仪器名称,防止网络请求、错误或在此追踪器期间所发射的相互作用与您的自定义跟踪链接.

const tracer = CoralogixRum.getCustomTracer(['networkRequests', 'userInteractions', 'errors']);

[注] 一次可能只有一个全球范围. startGlobalSpan 返回时 null 如果全球范围已经打开.

时间测量

测量任意流动的持续时间,一对 startTimeMeasure(name, labels?) 编号 : endTimeMeasure(name) 打电话 本地SDK记录起/终时间戳,并将三角洲报告为自定义测量跨度(毫秒).

import { CoralogixRum } from '@coralogix/react-native-plugin';

CoralogixRum.startTimeMeasure('checkout', { flow: 'checkout' });

await validateCart();
await charge();
await confirm();

CoralogixRum.endTimeMeasure('checkout');

行为 :

• 两通电话都是火和遗忘的——他们直接从桥上穿过,进入本土,立即返回.
• JS方面没有州;当地SDK拥有飞行登记簿.
• 你负责配对每个 startTimeMeasure(name, labels?) 和一个 endTimeMeasure(name)。 。 。 . 漏掉的开始持续到记忆 CoralogixRum.shutdown()。 。 。 .
• 无比 endTimeMeasure 电话被本地SDK悄悄地打倒了.
• 通话 startTimeMeasure 再次打开 name 覆盖上一个开始.

Tracks 导出器

在您的 JavaScript 代码中接收来自本地 SDK 的 OTLP 格式跟踪批次 。 使用此来将相容的OTLP后端(如Jaeger,自定义收藏家)与Corlogix并列.

await CoralogixRum.init({
  // ...
  tracesExporter: (data) => {
    // data.resource_spans contains OTLP JSON-format span data
    sendToMyOtlpBackend(JSON.stringify(data));
  },
});

回调收到一个 TraceExporterData 对象 :

{
  resource_spans: [
    {
      resource: { attributes: [{ key: string, value: { string_value: string } }] },
      scope_spans: [
        {
          scope: { name: string, version?: string },
          spans: [
            {
              trace_id: string,
              span_id: string,
              parent_span_id?: string,
              name: string,
              start_time_unix_nano: string,
              end_time_unix_nano: string,
              attributes: [{ key: string, value: {...} }],
              status: { code: string },
            }
          ]
        }
      ]
    }
  ]
}

[注] 每批原产地出口一次召回火灾,通常包含若干个跨度,而不是每个跨度一个.

在发送前

在发送到 Corlogix 之前启用事件访问和修改, 支持内容修改, 以及事件丢弃 .

await CoralogixRum.init({
  // ...
  beforeSend: (event) => {
    // Discard events from @company.com users.
    if (event.session_context.user_email?.endsWith('@company.com')) {
      return null;
    }

    // Redact sensitive information.
    event.session_context.user_email = '***@***';

    return event;
  },
});

将排除的事件分开 beforeSend

每件事都带 session_context.isSessionSampledIn。 。 。 . false 表示事件 从一个被抽取的会话中给你的 这发生在事件的类别 列在 excludeFromSampling为了SDK自己 内部事件,包括任何非空出事件,不包括清单。 用它来应用自己的 在排除列表上过滤, 例如只保留错误- 严重事件 抽样会议:

await CoralogixRum.init({
  // ...
  sessionSampleRate: 10,
  excludeFromSampling: ['errors', 'logs'],
  beforeSend: (event) => {
    // Default to `true`: a native SDK older than the one this plugin pins does not
    // stamp the flag, and `!undefined` would drop everything but errors.
    const sampledIn = event.session_context.isSessionSampledIn ?? true;

    // Session sampled out: forward only error-severity events, drop the rest.
    if (
      !sampledIn &&
      event.event_context?.severity !== CoralogixLogSeverity.Error
    ) {
      return null;
    }

    return event;
  },
});

[注] 总是读成 isSessionSampledIn ?? true。该字段不在 早于它的原生SDK,而SDK从未发明它没有给出的值.

isSessionSampledIn 它只报告SDK的取样决定 因此,分配对所发事件没有任何影响。 决定是 当事件创建时记录, 因此事件缓冲到会话旋转 保留所属会议的决定.

只读字段

有些字段用于召回 读取,不改变。 SDK还原它 自定义值 : beforeSend 返回,从而分配其中任何一种或注射 一个输入返回对象——对发送的事件没有影响.

内部 session_context, (中文(简体) ), 仅限 可编辑用户字段 :

任何其它键入 session_context 包括你的回电发明 已丢弃, 因此会话身份无法伪造 .

删除一个可编辑字段是荣耀的,因为逐一删除编辑是有效的用途. 这意味着返回a 手建部分设备 session_context 放弃用户字段 您已退出;如果想要更改,请编辑您获得的事件(或展开) 一块地,其余的留着.

这些顶级字段也是只读的,因为重写会腐朽 痕量关联、事件解析或产品分析,而不是编辑任何内容:

spanId, (中文(简体) ), traceId, (中文(简体) ), fingerPrint, (中文(简体) ), timestamp, (中文(简体) ), platform, (中文(简体) ), mobile_sdk, (中文(简体) ), snapshot_context, (中文(简体) ), isSnapshotEvent, (中文(简体) ), prev_session, (中文(简体) ), view_number, (中文(简体) ), isNavigationEvent

view_number 财务报告和审定财务报表 isNavigationEvent 记录SDK建造时观察到的情况 活动。 他们故意不从 event_context.type因此,如果 重新标出事件 isNavigationEvent 当你 需要"其实是导航".

其它的都一样.. event_context (包括 severity, (中文(简体) ), labels, (中文(简体) ), error_context, (中文(简体) ), log_context, (中文(简体) ), network_request_context, (中文(简体) ), view_context, (中文(简体) ), environment, (中文(简体) ), device_context, (中文(简体) ), device_state, (中文(简体) ), version_metadata 可编辑, 返回时 null 仍然完全放弃事件.

代理 URL 服务器

路由请求的代理配置 .
通过指定代理 URL,所有 RUM 数据将通过 POST 方法被引导到此 URL. 然而,有必要将这些数据随后从代理中转发到Corlogix. 发送到代理服务器的每个请求的 Corlogix 路由在请求的 cxforward 参数中可用 (例如, https://www.your-proxy.com/endpoint?cxforward=https%3A%2F%2Fingress.eu1.rum-ingress-coralogix.com%2Frowser%2Fv1beta%2Flogs) (中文(简体) ).

await CoralogixRum.init({
  // ...
  coralogixDomain: 'EU1',
  proxyUrl: 'https://www.your-proxy.com/endpoint',
});

会话重放

会话重放允许您记录并重放用户会话,以了解用户行为和调试问题.

初始化会话重放

要初始化会话重放, 调用 SessionReplay.init(options) 带有所需的配置选项.

import { SessionReplay } from '@coralogix/react-native-plugin';

await SessionReplay.init({
  captureScale: 0.5,                    // Scale factor for screenshots (0.0 to 1.0)
  captureCompressQuality: 0.8,         // Compression quality for screenshots (0.0 to 1.0)
  sessionRecordingSampleRate: 100,      // Percentage of sessions to record (0 to 100)
  autoStartSessionRecording: true,      // Automatically start recording when initialized
  maskAllTexts: true,                   // Mask all text content by default (optional, default: true)
  textsToMask: ['password', '^card.*'], // Array of strings/regex patterns for specific text masking (optional)
  maskAllImages: false,                 // Mask all images (optional, default: false)
});

选项 :

• captureScale (需要):截图的缩放因子. 一定在0.0到1.0之间 较低的值会缩小文件大小,但可能降低质量.
• captureCompressQuality (需要):截图的压缩质量. 一定在0.0到1.0之间 更高的值会提高质量但会增加文件大小.
• sessionRecordingSampleRate (需要):会议记录的百分比。 一定在0到100之间 使用100来记录所有会话.
• autoStartSessionRecording (要求):如果 true,在初始化后自动开始记录。 若为 false您必须手动拨打 startSessionRecording()。 。 。 .
• maskAllTexts (可选):如果 true,默认情况下,所有文本内容都被掩盖。 默认为 true。 。 。 .
• textsToMask (可选) : 组合字符串或regex模式来掩盖特定的文本内容. 仅在 maskAllTexts 实值 false。 。 。 .
• maskAllImages (可选):如果 true,所有图像都蒙上面具。 默认为 false。 。 。 .

检查初始化状态

检查会话重播是否已初始化 :

const isInited = await SessionReplay.isInited();
console.log('Session Replay initialized:', isInited);

检查记录状态

检查会话重播是否正在录制 :

const isRecording = await SessionReplay.isRecording();
console.log('Session Replay recording:', isRecording);

开始录制

手动启动会话记录 :

SessionReplay.startSessionRecording();

说明: 若为 autoStartSessionRecording 设置为 true 在输入选项中,自动开始录制,不需要使用这种方法.

停止记录

手动停止会话记录 :

SessionReplay.stopSessionRecording();

抓取截图

在会话中手动抓取截图 :

SessionReplay.captureScreenshot();

这对捕捉您想要强调的用户行程中的特定时刻很有用.

关闭会话重放

关闭会话重放以清理资源 :

await SessionReplay.shutdown();

遮盖敏感内容

重放会话时, 遮罩不设门 。 它会编辑用户交互事件所产生的敏感内容,无论你是否录制回放,当会话重放被启用时,同样的口罩也会将内容隐藏在录制中.

伪装有两种方式 Masked 建议. 遮盖整个逻辑元素——球场,行,按钮——而不是其内分.

Masked (建议)

Masked 从插件本身导出,不需要会话重放设置。 包起任何敏感的东西——它使 View 并接受 View 道具,所以它可以包裹一个完整的控制器,或者只是其中的敏感部分:

import { Text } from 'react-native';
import { Masked } from '@coralogix/react-native-plugin';

<Masked>
  <Text>Card: {cardNumber}</Text>
</Masked>

别放 Masked 内置 a <Text> - 包裹最外侧 <Text> 换句话说.

SessionReplay.maskView

或者,通过 SessionReplay.maskView 页:1 onLayout 任何观点。 它接受一个 LayoutChangeEvent 并致力于遗产和新建筑(Fabric):

import { Text, View } from 'react-native';
import { SessionReplay } from '@coralogix/react-native-plugin';

<View onLayout={SessionReplay.maskView}>
  <Text>{cardNumber}</Text>
</View>

附加到主机组件上——一个接受的自定义组件 onLayout 但从不向真实的视线前进 却默默不作声 使用 Masked (单位:千美元) Switch· ; maskView 无法标出它的相互作用.

蒙面互动

仍报告有窃听口罩内容 interaction_context.target_element_inner_text 已编辑为 *** 财务报告和审定财务报表 interaction_context.is_masked_element: true. 身份字段和水龙头坐标按原样报告,重播记录显示没有水龙头标记. is_masked_element 是只读的,所以在 beforeSend 以降低或进一步修改被遮住的相互作用.

请注意: target_element 倒计时 accessibilityLabel,它没有被编辑——给被遮盖的键盘密钥一个共享标签(accessibilityLabel="pin-key"而不是他们输入的数字.

可选 - Corlogix Gradle 插件( Android)

Corlogix Gradle 插件在构建时自动将所有 OkHttp 客户端安装在您的应用(包括第三方 SDKs)中 . 这确保所有网络流量自动被追踪并报告给Corlogix,不需要手动设置或代码修改. 这个插件对于在内部创建自己的 OkHttpClient 实例, 否则无法监视的网络库的仪器化特别有用 .

应用插件

1. 将插件添加到您的工程类路径
   在您的项目级别 build.gradle 文件 :

   buildscript {
       dependencies {
           classpath "com.coralogix.gradle.plugin:gradle-plugin:0.0.2"
       }
   }
   

2. 在您的应用模块中应用插件
   在你的应用级建筑顶端。 gradle 文件 :

   apply plugin: "com.coralogix.gradle.plugin"
   

配置插件

插件会曝光一个简单的 Gradle 扩展名, 您可以在您的应用模块中使用 :

coralogix {
  // Enable or disable instrumentation (default: true)
  enabled = true

  // Print debug logs during the build process (default: false)
  log = false
}

如果默认配置适合您的需要,则可以安全地省略此块——默认将自动适用.

说明

此插件是可选的 . 常规 Java 脚本 fetch 没有电话和标准网络请求仍将是仪器.

然而,插件是唯一从第三方库或使用自己的SDK获取网络活动的方法 OkHttpClient 内部实例.

解决问题

URL. 来源未执行

1. npm install react-native-url-polyfill
2. 在您输入点文件(index.js)上方添加: import "react-native-url-polyfill/auto"