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

Install @mosaicstack/telemetry-client in API #369

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

Summary

Add the @mosaicstack/telemetry-client npm package to apps/api and create a NestJS module that provides a singleton telemetry client for the entire API.

Requirements

Package Installation

  • Install @mosaicstack/telemetry-client from Gitea npm registry (https://git.mosaicstack.dev/api/packages/mosaic/npm/)
  • Add .npmrc scoped registry config if not already present

NestJS Module: MosaicTelemetryModule

  • Global module (@Global()) so all services can inject
  • TelemetryClient singleton initialized from environment variables
  • Lifecycle hooks: onModuleInit() → client.start(), onModuleDestroy() → client.stop()
  • Graceful shutdown flushes remaining events

Configuration (env vars)

MOSAIC_TELEMETRY_ENABLED=true
MOSAIC_TELEMETRY_SERVER_URL=https://tel-api.mosaicstack.dev
MOSAIC_TELEMETRY_API_KEY=<64-char hex>
MOSAIC_TELEMETRY_INSTANCE_ID=<uuid>
MOSAIC_TELEMETRY_DRY_RUN=false

Injectable Service: MosaicTelemetryService

  • Wraps TelemetryClient with convenience methods
  • trackTaskCompletion(event: TaskCompletionEvent) — queue event
  • getPrediction(query) — read cached prediction
  • refreshPredictions(queries) — fetch from server
  • Exposes EventBuilder for constructing events
  • Returns no-op when MOSAIC_TELEMETRY_ENABLED=false

Key SDK Details

  • Zero runtime dependencies (native fetch + crypto)
  • Background batch submission every 5 minutes (configurable)
  • Bounded FIFO queue (max 1000 events)
  • Never throws — errors routed to onError callback (log via NestJS Logger)
  • Exponential backoff on failed submissions

Acceptance Criteria

  • Package installed and importable
  • Module registered globally in AppModule
  • Client starts on app bootstrap, stops on shutdown
  • Disabled mode works (no HTTP calls when MOSAIC_TELEMETRY_ENABLED=false)
  • Dry-run mode logs events to console instead of sending
  • Unit tests for module initialization and service wrapper
## Summary Add the `@mosaicstack/telemetry-client` npm package to `apps/api` and create a NestJS module that provides a singleton telemetry client for the entire API. ## Requirements ### Package Installation - Install `@mosaicstack/telemetry-client` from Gitea npm registry (`https://git.mosaicstack.dev/api/packages/mosaic/npm/`) - Add `.npmrc` scoped registry config if not already present ### NestJS Module: `MosaicTelemetryModule` - Global module (`@Global()`) so all services can inject - `TelemetryClient` singleton initialized from environment variables - Lifecycle hooks: `onModuleInit()` → `client.start()`, `onModuleDestroy()` → `client.stop()` - Graceful shutdown flushes remaining events ### Configuration (env vars) ``` MOSAIC_TELEMETRY_ENABLED=true MOSAIC_TELEMETRY_SERVER_URL=https://tel-api.mosaicstack.dev MOSAIC_TELEMETRY_API_KEY=<64-char hex> MOSAIC_TELEMETRY_INSTANCE_ID=<uuid> MOSAIC_TELEMETRY_DRY_RUN=false ``` ### Injectable Service: `MosaicTelemetryService` - Wraps `TelemetryClient` with convenience methods - `trackTaskCompletion(event: TaskCompletionEvent)` — queue event - `getPrediction(query)` — read cached prediction - `refreshPredictions(queries)` — fetch from server - Exposes `EventBuilder` for constructing events - Returns no-op when `MOSAIC_TELEMETRY_ENABLED=false` ### Key SDK Details - Zero runtime dependencies (native fetch + crypto) - Background batch submission every 5 minutes (configurable) - Bounded FIFO queue (max 1000 events) - Never throws — errors routed to `onError` callback (log via NestJS Logger) - Exponential backoff on failed submissions ## Acceptance Criteria - [ ] Package installed and importable - [ ] Module registered globally in AppModule - [ ] Client starts on app bootstrap, stops on shutdown - [ ] Disabled mode works (no HTTP calls when MOSAIC_TELEMETRY_ENABLED=false) - [ ] Dry-run mode logs events to console instead of sending - [ ] Unit tests for module initialization and service wrapper
jason.woltje added the apiapi labels 2026-02-15 05:27:53 +00:00
jason.woltje added this to the M10-Telemetry (0.0.10) milestone 2026-02-15 05:31:19 +00:00
jason.woltje commented 2026-02-15 08:05:00 +00:00
Author
Owner
Copy Link

Completed in commit 0c4ad7c on feature/m10-telemetry. Installed @mosaicstack/telemetry-client, created MosaicTelemetryModule (global NestJS module), MosaicTelemetryService wrapper, config from env vars. 32 unit tests.

Completed in commit 0c4ad7c on feature/m10-telemetry. Installed @mosaicstack/telemetry-client, created MosaicTelemetryModule (global NestJS module), MosaicTelemetryService wrapper, config from env vars. 32 unit tests.
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 api api
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#369
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?