diff --git a/.syncpackrc.js b/.syncpackrc.js index 7208c290..93f8f4b0 100644 --- a/.syncpackrc.js +++ b/.syncpackrc.js @@ -54,6 +54,7 @@ export default { // Ignore this expected mismatch. "packages": ["@all-platforms/*"], "dependencies": ["@workleap/telemetry", "@workleap/common-room"], + "dependencyTypes": ["prod"], "isIgnored": true }, { @@ -61,6 +62,7 @@ export default { // Ignore this expected mismatch. "packages": ["@honeycomb-api-key/*", "@honeycomb-proxy/*"], "dependencies": ["@workleap/honeycomb"], + "dependencyTypes": ["prod"], "isIgnored": true }, { diff --git a/agent-skills/workleap-telemetry/SKILL.md b/agent-skills/workleap-telemetry/SKILL.md index 328acad0..8f943416 100644 --- a/agent-skills/workleap-telemetry/SKILL.md +++ b/agent-skills/workleap-telemetry/SKILL.md @@ -1,38 +1,59 @@ --- name: workleap-telemetry description: | - Guide for @workleap/telemetry, Workleap's unified telemetry connecting Honeycomb, LogRocket, and Mixpanel with automatic correlation IDs. - - Use this skill when: - (1) Initializing wl-telemetry in a frontend application - (2) Correlation values (Telemetry Id, Device Id) and cross-tool data correlation - (3) Honeycomb tracing, OpenTelemetry spans, and performance monitoring - (4) LogRocket session replay, user identification, and privacy controls - (5) Mixpanel analytics, event tracking, and cross-product tracking - (6) Configuring wl-telemetry diagnostic loggers (LogRocketLogger) - (7) Storybook/test setup with Noop telemetry clients - (8) Reviewing or troubleshooting telemetry instrumentation + Guide for @workleap/telemetry — Workleap's unified telemetry package connecting Honeycomb (tracing), LogRocket (session replay), and Mixpanel (analytics) with automatic correlation IDs. + + Use when initializing @workleap/telemetry, instrumenting Honeycomb traces/spans, configuring LogRocket replay or privacy, tracking Mixpanel events, setting up Noop clients for Storybook/tests, or troubleshooting telemetry correlation. Also activate when someone mentions observability, session replay, or analytics in a Workleap frontend context. metadata: - version: 3.2 + version: 3.3 --- # Workleap Telemetry (wl-telemetry) `@workleap/telemetry` is an umbrella package that integrates Honeycomb, LogRocket, and Mixpanel with consistent correlation IDs for unified debugging and analysis. +## Platform Roles + +- **Honeycomb**: Distributed tracing and performance monitoring (LCP, CLS, INP) +- **LogRocket**: Session replay and frontend debugging +- **Mixpanel**: Product analytics and event tracking + +## Quick Start + +```typescript +import { initializeTelemetry, TelemetryProvider } from "@workleap/telemetry/react"; + +const telemetryClient = initializeTelemetry("wlp", { + logRocket: { appId: "your-app-id" }, + honeycomb: { + namespace: "your-namespace", + serviceName: "your-service", + apiServiceUrls: [/.+/g], + options: { proxy: "https://your-otel-proxy" } + }, + mixpanel: { + envOrTrackingApiBaseUrl: "production" + } +}); + + + + +``` + ## Critical Rules -1. **Use umbrella package** — Always use `@workleap/telemetry`, not standalone packages -2. **Do not invent APIs** — Only use documented APIs from references -3. **Correlation is automatic** — Never manually set Telemetry Id or Device Id; never create your own `TelemetryContext` instances -4. **Noop for non-production** — Use `NoopTelemetryClient` in Storybook/tests -5. **Privacy matters** — Never log PII to LogRocket; use `data-public`/`data-private` attributes -6. **productFamily is required** — `initializeTelemetry` requires `"wlp"` or `"sg"` as the first argument +1. **Use the umbrella package** — Import from `@workleap/telemetry`, not standalone packages like `@workleap/honeycomb` directly. Standalone packages bypass the automatic correlation ID propagation that ties all three platforms together. +2. **Do not invent APIs** — Only use APIs documented in the references. The model may hallucinate plausible-looking methods that don't exist. +3. **Let correlation happen automatically** — Never manually set Telemetry Id or Device Id, and never create your own `TelemetryContext` instances. The SDK manages the lifecycle and cross-tool propagation; manual overrides break the correlation chain. +4. **Use Noop clients outside production** — Use `NoopTelemetryClient` in Storybook and tests to avoid sending real telemetry data and to prevent initialization errors in non-browser environments. +5. **Protect user privacy** — Never log PII to LogRocket. Session replays are shared across teams and may be reviewed broadly; use `data-public`/`data-private` HTML attributes to control what gets recorded. +6. **productFamily is required** — `initializeTelemetry` requires `"wlp"` (Workleap Platform) or `"sg"` (ShareGate) as the first argument. This determines platform-specific defaults and routing. ## Reference Guide -For detailed documentation beyond the rules above, consult: +Consult these references based on what you need: -- **`references/api.md`** — Initialization options, TelemetryClient properties, Honeycomb/LogRocket/Mixpanel client APIs, React hooks, Noop clients, LogRocketLogger -- **`references/integrations.md`** — Platform-specific configuration, Honeycomb tracing patterns, LogRocket privacy and user identification, Mixpanel event tracking, cross-platform correlation workflows -- **`references/examples.md`** — Full application setup, Storybook/test configuration, user identification, custom Honeycomb traces, Mixpanel tracking patterns, logging configuration, troubleshooting +- **`references/api.md`** — Function signatures, type definitions, and complete API surface for all clients and hooks. Start here when you need to know exactly what parameters a method accepts. +- **`references/integrations.md`** — Platform-specific configuration patterns, custom Honeycomb traces, LogRocket privacy controls, Mixpanel event tracking, and cross-platform correlation workflows. Start here for "how do I configure X" questions. +- **`references/examples.md`** — Copy-paste starter code for common scenarios: full app setup, Storybook decorators, test utilities, user identification, and troubleshooting. Start here for "show me how to do X" questions. diff --git a/agent-skills/workleap-telemetry/references/api.md b/agent-skills/workleap-telemetry/references/api.md index ba870821..965e30f7 100644 --- a/agent-skills/workleap-telemetry/references/api.md +++ b/agent-skills/workleap-telemetry/references/api.md @@ -42,8 +42,8 @@ const telemetryClient = initializeTelemetry(productFamily, { spanProcessors?: SpanProcessor[]; fetchInstrumentation?: false | ((defaults) => FetchInstrumentationOptions); documentLoadInstrumentation?: false | ((defaults) => DocumentLoadInstrumentationOptions); - xmlHttpRequestInstrumentation?: true | ((defaults) => XHRInstrumentationOptions); // Disabled by default - userInteractionInstrumentation?: true | ((defaults) => UserInteractionOptions); // Disabled by default + xmlHttpRequestInstrumentation?: false | ((defaults) => XHRInstrumentationOptions); // Disabled by default; provide a function to enable and customize + userInteractionInstrumentation?: false | ((defaults) => UserInteractionOptions); // Disabled by default; provide a function to enable and customize transformers?: HoneycombSdkOptionsTransformer[]; } }, diff --git a/agent-skills/workleap-telemetry/references/integrations.md b/agent-skills/workleap-telemetry/references/integrations.md index 07203e3f..5de9ad77 100644 --- a/agent-skills/workleap-telemetry/references/integrations.md +++ b/agent-skills/workleap-telemetry/references/integrations.md @@ -46,8 +46,8 @@ honeycomb: { fetchInstrumentation: (config) => config, // Customize fetch instrumentation documentLoadInstrumentation: (config) => config, // Customize document load instrumentation - // Disabled by default. Use `true` to enable with defaults, or a function to enable and customize. - xmlHttpRequestInstrumentation: true, // Enable XHR instrumentation + // Disabled by default. Provide a function to enable and customize. + xmlHttpRequestInstrumentation: (config) => config, // Enable and customize XHR instrumentation userInteractionInstrumentation: (config) => config, // Enable and customize user interactions transformers: [] // SDK-level configuration transformers