Telemetry · Getting Started

Introduction

@threadplane/telemetry is the shared telemetry package for the framework. It has separate surfaces for browser applications, Node adapters, and shared utilities.

The important boundary is simple:

  • browser telemetry is opt-in through Angular DI;
  • Node telemetry is opt-out and used by package lifecycle or server adapter code;
  • shared utilities expose event and environment helpers.

Don't treat the browser and Node entry points as interchangeable. They have different runtime assumptions and different privacy defaults.

#Entry points

// Shared utilities
import { isTelemetryDisabled, getDisableReason } from '@threadplane/telemetry';
 
// Browser Angular provider and service
import { provideThreadplaneTelemetry } from '@threadplane/telemetry/browser';
 
// Node/server helpers
import { disableTelemetry, capturePostinstall } from '@threadplane/telemetry/node';

The package also exports @threadplane/telemetry/node/postinstall for the package postinstall executable.

#Browser posture

The browser package does nothing unless the application explicitly provides telemetry config with enabled: true.

When enabled, delivery is chosen in this order:

  1. sink;
  2. endpoint;
  3. posthogKey.

For me, sink and endpoint are the paths to reach for. They keep delivery app-owned, so you decide where events go. posthogKey and posthogHost still exist for older integrations, but they're marked deprecated in source comments, so don't build anything new on them.

#Node posture

Node helpers check opt-out environment variables before sending. They use a per-process anonymous ID and deterministic sampling based on that ID.

Node capture failures return a failure result or are swallowed by adapter helpers. Telemetry should not break install, startup, or request handling.

#What this package does not promise

The source does not contain content capture for prompts, completions, tool inputs, or tool outputs. It also does not persist browser IDs to local storage or cookies.

It does collect runtime metadata when the corresponding Node or browser capture APIs are called. Keep event properties short, operational, and free of application data.

#Next steps

  • Browser Telemetry - wire provideThreadplaneTelemetry() and bridge the agent runtime into a sink.
  • Node Telemetry - capture helpers for package lifecycle and server adapters.
  • Privacy and opt-out - what's collected and how to turn it off.
  • Events - the event names and property shapes emitted by each surface.