Jason Woltje
177720e523
Standalone npm package (@mosaicstack/telemetry-client) for reporting task-completion telemetry and querying predictions from the Mosaic Stack Telemetry server. - TelemetryClient with setInterval-based background flush - EventQueue (bounded FIFO array) - BatchSubmitter with native fetch, exponential backoff, Retry-After - PredictionCache (Map + TTL) - EventBuilder with auto-generated event_id/timestamp - Zero runtime dependencies (Node 18+ native APIs) - 43 tests, 86% branch coverage Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
114 lines
3.2 KiB
Markdown
114 lines
3.2 KiB
Markdown
# @mosaicstack/telemetry-client
|
|
|
|
TypeScript client SDK for [Mosaic Stack Telemetry](https://tel.mosaicstack.dev). Reports task-completion metrics from AI coding harnesses and queries crowd-sourced predictions.
|
|
|
|
**Zero runtime dependencies** — uses native `fetch`, `crypto.randomUUID()`, and `setInterval`.
|
|
|
|
## Installation
|
|
|
|
```bash
|
|
npm install @mosaicstack/telemetry-client
|
|
```
|
|
|
|
## Quick Start
|
|
|
|
```typescript
|
|
import { TelemetryClient, TaskType, Complexity, Harness, Provider, Outcome } from '@mosaicstack/telemetry-client';
|
|
|
|
const client = new TelemetryClient({
|
|
serverUrl: 'https://tel.mosaicstack.dev',
|
|
apiKey: 'your-64-char-hex-api-key',
|
|
instanceId: 'your-instance-uuid',
|
|
});
|
|
|
|
client.start();
|
|
|
|
// Build and track an event
|
|
const event = client.eventBuilder.build({
|
|
task_duration_ms: 45000,
|
|
task_type: TaskType.IMPLEMENTATION,
|
|
complexity: Complexity.MEDIUM,
|
|
harness: Harness.CLAUDE_CODE,
|
|
model: 'claude-sonnet-4-5-20250929',
|
|
provider: Provider.ANTHROPIC,
|
|
estimated_input_tokens: 5000,
|
|
estimated_output_tokens: 2000,
|
|
actual_input_tokens: 5500,
|
|
actual_output_tokens: 2200,
|
|
estimated_cost_usd_micros: 30000,
|
|
actual_cost_usd_micros: 33000,
|
|
quality_gate_passed: true,
|
|
quality_gates_run: [],
|
|
quality_gates_failed: [],
|
|
context_compactions: 0,
|
|
context_rotations: 0,
|
|
context_utilization_final: 0.4,
|
|
outcome: Outcome.SUCCESS,
|
|
retry_count: 0,
|
|
});
|
|
|
|
client.track(event);
|
|
|
|
// When shutting down
|
|
await client.stop();
|
|
```
|
|
|
|
## Querying Predictions
|
|
|
|
```typescript
|
|
const query = {
|
|
task_type: TaskType.IMPLEMENTATION,
|
|
model: 'claude-sonnet-4-5-20250929',
|
|
provider: Provider.ANTHROPIC,
|
|
complexity: Complexity.MEDIUM,
|
|
};
|
|
|
|
// Fetch from server and cache locally
|
|
await client.refreshPredictions([query]);
|
|
|
|
// Get cached prediction (returns null if not cached)
|
|
const prediction = client.getPrediction(query);
|
|
if (prediction?.prediction) {
|
|
console.log('Median input tokens:', prediction.prediction.input_tokens.median);
|
|
console.log('Median cost (microdollars):', prediction.prediction.cost_usd_micros.median);
|
|
}
|
|
```
|
|
|
|
## Configuration
|
|
|
|
```typescript
|
|
const client = new TelemetryClient({
|
|
serverUrl: 'https://tel.mosaicstack.dev', // Required
|
|
apiKey: 'your-api-key', // Required (64-char hex)
|
|
instanceId: 'your-uuid', // Required
|
|
|
|
// Optional
|
|
enabled: true, // Set false to disable (track() becomes no-op)
|
|
submitIntervalMs: 300_000, // Background flush interval (default: 5 min)
|
|
maxQueueSize: 1000, // Max queued events (default: 1000, FIFO eviction)
|
|
batchSize: 100, // Events per batch (default/max: 100)
|
|
requestTimeoutMs: 10_000, // HTTP timeout (default: 10s)
|
|
predictionCacheTtlMs: 21_600_000, // Prediction cache TTL (default: 6 hours)
|
|
dryRun: false, // Log events instead of sending
|
|
maxRetries: 3, // Retry attempts on failure
|
|
onError: (err) => console.error(err), // Error callback
|
|
});
|
|
```
|
|
|
|
## Dry-Run Mode
|
|
|
|
For testing without sending data:
|
|
|
|
```typescript
|
|
const client = new TelemetryClient({
|
|
serverUrl: 'https://tel.mosaicstack.dev',
|
|
apiKey: 'test-key',
|
|
instanceId: 'test-uuid',
|
|
dryRun: true,
|
|
});
|
|
```
|
|
|
|
## License
|
|
|
|
MPL-2.0
|