# Catlx Telemetry

> CATLX — Telemetry & Observability

- Skill: `samraddhashrivastavatech/catlx-telemetry` (Agent Skill)
- Install (CLI): `npx skillmds@latest add samraddhashrivastavatech/catlx-telemetry`
- Raw SKILL.md: https://api.skillmd.com/api/skills/samraddhashrivastavatech/catlx-telemetry/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: SAMRADDHASHRIVASTAVATECH (https://skillmd.com/u/samraddhashrivastavatech)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/samraddhashrivastavatech/catlx-telemetry

---


# CATLX — Telemetry & Observability

This skill owns the **observability** of an autonomous system. Every action must be traceable to debug,
optimize, and audit it. All telemetry is stored **locally** and only sent externally with explicit opt-in.

> Canonical detail: `../knowledge/references/telemetry.md`. Load on demand.

---

## Purpose

Give CATLX full, local, queryable visibility into what it did and why — distributed tracing, structured
metrics, causal lineage, and profiling.

## When to activate

- User asks how to trace CATLX activity, view metrics, profile, or see the observability dashboard.
- Debugging "what did CATLX do in response to X" or "why did CATLX decide Y".
- Configuring sampling rate, storage, or the CLI report.

## What this skill handles

1. **Distributed tracing & correlation** — every voice command/workflow/background task gets a root
   **Trace ID (UUID v4)**; each sub-operation creates a **Span** with a parent Span ID. A Span records start
   time, end time, module name, operation type, input-parameters hash, output hash, and status
   (OK/ERROR/TIMEOUT). The **Correlation Engine** links traces across subsystems so the whole chain
   (Workflow → Memory Broker → Vector Store → AI Provider) shares one root Trace ID.
2. **Causal lineage** — for every AI-generated output, record which prompt was sent, which provider responded,
   which memory context was injected, and which user command initiated the chain; stored as a directed graph.
3. **Metrics** — at configurable sample rates (5% T0; 100% T2+): voice pipeline stage latencies, workflow step
   durations/retries, memory op latency, AI provider latency/tokens/cost, system resource usage (CPU/RAM/GPU)
   per module, error rates by module and workflow type.
4. **DuckDB storage** — columnar, zero-dependency, time-series-capable at `/data/telemetry/telemetry.duckdb`;
   writes in append batches of 100; partitioned by month.
5. **Profiling** — instrument hot paths with microsecond timing (Node.js Performance Hooks + V8 sampling
   profiler); auto-profile the slowest 1% of operations; store reports in `/data/telemetry/profiles/`.
6. **Observability dashboard** — Electron shell view (Ctrl+Shift+T or tray): trace waterfall (last 10 ops),
   metrics time-series, causal lineage graph viewer (Sigma.js), structured log viewer with full-text search.
   On T0, replaced by CLI: `catlx telemetry report`.

## Requirements / constraints

- **R13 (telemetry stays local):** never sent to a remote endpoint without explicit opt-in.
- Sampling rate and dashboard mode come from the CapabilityMap (`telemetry_sample_rate`, `gui_mode`).
- All tracing goes through correlation IDs shared across the PAL and Workflow Engine.

## Canonical knowledge it reads

`../knowledge/references/telemetry.md` · `../knowledge/references/data-registries.md` ·
`../knowledge/references/hardware-adaptation.md` · `../knowledge/rules/architectural-rules.md`.

## Delegation

- **Dashboard / GUI rendering** → delegate to `catlx-electron-shell`
  (`skill({ name: "catlx-electron-shell" })`).
- **Failover correlation** → delegate to `catlx-ai-provider`
  (`skill({ name: "catlx-ai-provider" })`).
- **Workflow run tracing** → delegate to `catlx-workflow-engine`
  (`skill({ name: "catlx-workflow-engine" })`).
- **Profiling/sampling tier** → delegate to `catlx-hardware-adaptation`
  (`skill({ name: "catlx-hardware-adaptation" })`).

## Edge cases & warnings

- **T0:** dashboard unavailable → use the `catlx telemetry report` CLI.
- **Write amplification:** batch telemetry writes (100 records) to minimize amplification.
- **Corruption:** DuckDB/vector stores must be recoverable (see recovery); never silently drop traces.
- **Privacy:** respect opt-in; a metric that could leak sensitive state should be flagged.

## Component lifecycle policy (reuse → install → adapt → create)

**NEVER create a new component as the default.** Before building/creating anything (a sub-skill, dependency,
reference, workflow, helper, adapter, or template), check, in order:
1. **Reuse** an existing local component (resolve aliases/equivalent capabilities first) — reuse, don't rebuild.
2. **Use** an already-registered component from the registry.
3. **Install** a suitable existing, trusted, supported component → validate → register → connect to the graph → use.
4. **Adapt** an existing compatible component via a small persistent adapter/wrapper instead of re-creating it.
5. **Create only as last resort** — then make it permanent immediately: stable id, canonical location, register,
   add to the capability index + dependency graph, add provenance, use, and allow future reuse.
6. Never reorganise/recreate already-generated components (no `Skill X 2` / `new` / `temp` variants); extend the
   existing one. Never create a second competing knowledge source; connect back to the canonical `knowledge/` layer.
   Promote any reusable artifact out of `/tmp`/scratch into the permanent ecosystem.

> Full policy: `../knowledge/rules/component-lifecycle.md`.

## Source / provenance

- **Source:** PART XI §11.1–11.7 (philosophy, tracing & correlation, causal lineage, metrics, DuckDB storage,
  profiling, observability dashboard).
- **Inferred:** none; endpooints/paths mapped to Windows-relative paths.