mosaic/stack
1
0
Fork 0
Code Issues 10 Pull Requests Actions Packages Projects Releases 2 Wiki Activity

Documentation: Telemetry integration guide #376

New Issue
Closed
opened 2026-02-15 05:29:42 +00:00 by jason.woltje · 1 comment
jason.woltje commented 2026-02-15 05:29:42 +00:00
Owner
Copy Link

Summary

Create comprehensive documentation explaining how Mosaic Telemetry is integrated into the Stack, how to configure it, what events are tracked, and how predictions work.

Requirements

Documentation Structure

1. Overview

  • What Mosaic Telemetry is (task completion tracking for AI operations)
  • How it differs from OpenTelemetry (OTEL handles request tracing; Mosaic Telemetry handles AI task metrics)
  • Architecture diagram: Stack → Telemetry Client SDK → Telemetry API → PostgreSQL → Predictions

2. Configuration Guide

  • All environment variables with descriptions and defaults
  • How to enable/disable telemetry
  • Dry-run mode for development
  • How to obtain API key and instance ID
  • Self-hosted vs hosted telemetry API

3. What Gets Tracked

  • TaskCompletionEvent schema with all fields explained
  • Which Stack components emit events (API LLM service, Coordinator)
  • Event lifecycle: creation → queue → batch submission → API ingestion

4. Prediction System

  • How predictions work (historical data → statistical distributions)
  • How to query predictions
  • Confidence levels and fallback behavior
  • How predictions improve over time with more data

5. SDK Reference

  • JS SDK: @mosaicstack/telemetry-client
    • Package location (Gitea npm registry)
    • Dev version format: 0.1.0-dev.YYYYMMDDHHmmss
  • Python SDK: mosaicstack-telemetry
    • Package location (Gitea PyPI registry)
    • Dev version format: 0.1.0.devYYYYMMDDHHmmss

6. Development Guide

  • How to test telemetry locally (dry-run mode)
  • How to add new event tracking points
  • How to verify events are being sent
  • Troubleshooting: common issues and solutions

Location

  • docs/telemetry.md in the mosaic-stack repo
  • Link from main README.md

Acceptance Criteria

  • Overview with architecture diagram
  • Complete configuration reference
  • Event schema documentation with field descriptions
  • Prediction system explained
  • Both SDK references with install instructions
  • Development/testing guide
  • Linked from README.md
## Summary Create comprehensive documentation explaining how Mosaic Telemetry is integrated into the Stack, how to configure it, what events are tracked, and how predictions work. ## Requirements ### Documentation Structure #### 1. Overview - What Mosaic Telemetry is (task completion tracking for AI operations) - How it differs from OpenTelemetry (OTEL handles request tracing; Mosaic Telemetry handles AI task metrics) - Architecture diagram: Stack → Telemetry Client SDK → Telemetry API → PostgreSQL → Predictions #### 2. Configuration Guide - All environment variables with descriptions and defaults - How to enable/disable telemetry - Dry-run mode for development - How to obtain API key and instance ID - Self-hosted vs hosted telemetry API #### 3. What Gets Tracked - TaskCompletionEvent schema with all fields explained - Which Stack components emit events (API LLM service, Coordinator) - Event lifecycle: creation → queue → batch submission → API ingestion #### 4. Prediction System - How predictions work (historical data → statistical distributions) - How to query predictions - Confidence levels and fallback behavior - How predictions improve over time with more data #### 5. SDK Reference - JS SDK: @mosaicstack/telemetry-client - Package location (Gitea npm registry) - Dev version format: `0.1.0-dev.YYYYMMDDHHmmss` - Python SDK: mosaicstack-telemetry - Package location (Gitea PyPI registry) - Dev version format: `0.1.0.devYYYYMMDDHHmmss` #### 6. Development Guide - How to test telemetry locally (dry-run mode) - How to add new event tracking points - How to verify events are being sent - Troubleshooting: common issues and solutions ### Location - `docs/telemetry.md` in the mosaic-stack repo - Link from main README.md ## Acceptance Criteria - [ ] Overview with architecture diagram - [ ] Complete configuration reference - [ ] Event schema documentation with field descriptions - [ ] Prediction system explained - [ ] Both SDK references with install instructions - [ ] Development/testing guide - [ ] Linked from README.md
jason.woltje added the docs label 2026-02-15 05:29:42 +00:00
jason.woltje added this to the M10-Telemetry (0.0.10) milestone 2026-02-15 05:31:20 +00:00
jason.woltje commented 2026-02-15 08:05:02 +00:00
Author
Owner
Copy Link

Completed in commit 74a5044 on feature/m10-telemetry. Comprehensive docs/telemetry.md (737 lines): architecture, configuration, event schema, predictions, SDK reference (JS+Python), dev guide. Linked from README.

Completed in commit 74a5044 on feature/m10-telemetry. Comprehensive docs/telemetry.md (737 lines): architecture, configuration, event schema, predictions, SDK reference (JS+Python), dev guide. Linked from README.
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
ai
AI/LLM integration
 api
Backend/API work
 api
auth
Authentication
 database
database
Database/schema work
 devops
Docker/deployment
 docs
Documentation
 frontend
graph
knowledge-module
migration
Data migration
 orchestrator
Orchestrator service (apps/orchestrator/)
 p0
Critical priority
 p1
High priority
 p2
Medium priority
 p3
Low priority
 performance
Performance work
 phase-1
phase-2
phase-3
phase-4
phase-5
plugin
MoltBot plugin work
 search
security
Security-related
 setup
Initial setup
 testing
Testing/QA
 web
Frontend work
No Label docs
Milestone
No items
No Milestone M10-Telemetry (0.0.10)
Projects
Clear projects
No project
Assignees
Clear assignees
jason.woltje
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: mosaic/stack#376
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?