workleap-telemetry-v2

用途

@workleap/telemetry 是一个伞包（umbrella package），用于将 Honeycomb、LogRocket 和 Mixpanel 三个遥测平台整合到统一的解决方案中，通过一致的关联 ID 实现跨平台的统一调试与分析。

核心概念

关联值（Correlation Values）

两个自动生成的关联 ID 用于统一所有遥测平台：

ID	用途	Honeycomb	LogRocket/Mixpanel
Telemetry Id	单次应用加载	app.telemetry_id	Telemetry Id
Device Id	跨会话的设备标识	app.device_id	Device Id

如果启用了 LogRocket，Honeycomb 和 Mixpanel 会自动接收 app.logrocket_session_url / LogRocket Session URL。

平台角色

Honeycomb：分布式追踪、性能监控、RUM 指标（LCP、CLS、INP）
LogRocket：会话回放、前端调试、用户体验调查
Mixpanel：产品分析、事件追踪、用户行为洞察

使用方式

快速开始

import { initializeTelemetry, TelemetryProvider } from "@workleap/telemetry/react";

const telemetryClient = initializeTelemetry({
  logRocket: { appId: "your-app-id" },
  honeycomb: {
    namespace: "your-namespace",
    serviceName: "your-service",
    apiServiceUrls: [/.+/g],
    options: { proxy: "https://your-otel-proxy" }
  },
  mixpanel: {
    productId: "wlp",
    envOrTrackingApiBaseUrl: "production"
  }
});

// Wrap application
<TelemetryProvider client={telemetryClient}>
  <App />
</TelemetryProvider>

使用平台客户端

通过 hooks 访问各平台客户端：

const telemetryClient = useTelemetryClient();
const honeycombClient = useHoneycombInstrumentationClient();
const logRocketClient = useLogRocketInstrumentationClient();
const mixpanelClient = useMixpanelClient();
const track = useMixpanelTrackingFunction();

Storybook/测试（Noop 客户端）

import { NoopTelemetryClient, TelemetryProvider } from "@workleap/telemetry/react";

const telemetryClient = new NoopTelemetryClient();

<TelemetryProvider client={telemetryClient}>
  <Story />
</TelemetryProvider>

详细参考

完整 API 参考：参见 references/api.md
集成模式：参见 references/integrations.md 了解平台特定模式
使用示例：参见 references/examples.md 了解常见模式

关键规则

使用伞包——始终使用 @workleap/telemetry，而非独立包
不要虚构 API——仅使用参考文档中记录的 API
关联是自动的——切勿手动设置 Telemetry Id 或 Device Id
非生产环境使用 Noop——在 Storybook/测试中使用 NoopTelemetryClient
隐私很重要——切勿将 PII 记录到 LogRocket；使用 data-public/data-private 属性

适用场景

适用于需要统一前端遥测的 React 应用，尤其是同时使用 Honeycomb、LogRocket 和 Mixpanel 进行性能监控、会话回放和产品分析的团队。

限制

资料中未提供关于收费、价格、平台支持范围、具体性能效果等更多信息。