Product Spec Harness
GuidesHướng dẫn
HomeTrang chủ › GuidesHướng dẫn › telemetrytelemetry
Read-only · honest by designChỉ-đọc · trung thực theo thiết kế

telemetry

v1.1.0

After you've used the harness a while, telemetry tells you — in plain Vietnamese — how your own tooling is doing. A script gathers deterministic counts; the skill narrates them. It reports whether the machinery runs (usage & health), never whether the product wins the market.Sau khi dùng harness một thời gian, telemetry cho bạn biết — bằng tiếng Việt thuần — bộ đồ nghề của bạn đang chạy thế nào. Script gom số liệu tất định; skill diễn giải. Nó báo máy móc có chạy không (mức dùng & sức khỏe), không bao giờ báo sản phẩm có thắng thị trường không.

✓ Reach for it when✓ Dùng khi

  • you want to know which skills actually get usedbạn muốn biết skill nào thực sự được dùng
  • a script is erroring or slow and you want proofmột script lỗi hay chậm và bạn cần bằng chứng
  • checking subagent success / validate-pass healthkiểm tra subagent đạt/hỏng · sức khỏe validate-pass

✗ Can't tell you✗ Không thể nói

  • market or user outcome — usage ≠ effectivenesskết quả thị trường/người dùng — mức dùng ≠ hiệu quả
  • exact tokens/ms — those are labelled "ước lượng"token/ms chính xác — gắn nhãn "ước lượng"
  • what to prune — it suggests, never editscắt cái gì — chỉ gợi ý, không sửa
Worked exampleVí dụ thật

One lens, four formatsMột lăng kính, bốn định dạng

The usage lens over the same data, rendered four ways: ascii to glance, md to paste, mermaid to chart, json to pipe. sample data Lăng kính usage trên cùng dữ liệu, render bốn kiểu: ascii để liếc, md để dán, mermaid để vẽ, json để nối ống. dữ liệu mẫu

analyze_telemetry.py --lens usage --format ascii --lang vi
== TELEMETRY: MỨC DÙNG & SỨC KHỎE ==

[OK] MỨC DÙNG — 35 lượt gọi, 4 đã dùng, 0 sở hữu chưa dùng

## Mức dùng kỹ năng (30 ngày gần đây)

Tổng lượt gọi: **35** trên **4** kỹ năng; catalog 0.

| # | Kỹ năng                          | Lượt |
| --- | -------------------------------- | ---- |
| 1 | cleanmatic-product-spec          | 16   |
| 2 | cleanmatic-product-spec-critique | 9    |
| 3 | cleanmatic-telemetry             | 6    |
| 4 | cleanmatic-release               | 4    |

**Chưa dùng lần nào (sở hữu):** 0

```mermaid
pie showData
    title Mức dùng kỹ năng
    "cleanmatic-product-spec" : 16
    "cleanmatic-product-spec-critique" : 9
    "cleanmatic-telemetry" : 6
    "cleanmatic-release" : 4
```

{
  "lens": "usage_tokens",
  "days": 30,
  "total_invocations": 35,
  "skills_used": 4,
  "catalog_size": 0,
  "owned_size": 0,
  "never_used": [],
  "never_used_external_count": 0,
  "by_day": {
    "2026-06-01": 2,
    "2026-06-02": 5,
    "2026-06-03": 2,
    "2026-06-04": 2,
    "2026-06-05": 5,
    "2026-06-06": 1,
    "2026-06-07": 2,
    "2026-06-08": 5,
    "2026-06-09": 1,
    "2026-06-10": 3,
    "2026-06-11": 5,
    "2026-06-12": 2
  },
  "with_tokens": false,
  "rows": [
    {
      "skill": "cleanmatic-product-spec",
      "count": 16,
      "tokens": 0,
      "owned": false
    },
    {
      "skill": "cleanmatic-product-spec-critique",
      "count": 9,
      "tokens": 0,
      "owned": false
    },
    {
      "skill": "cleanmatic-telemetry",
      "count": 6,
      "tokens": 0,
      "owned": false
    },
    {
      "skill": "cleanmatic-release",
      "count": 4,
      "tokens": 0,
      "owned": false
    }
  ],
  "gated": false
}

Mermaid is shown as source — the page vendors no chart library, staying dependency-free. Numbers are clearly-labelled sample data.Mermaid hiện ở dạng nguồn — trang không nhúng thư viện vẽ nào, giữ không-phụ-thuộc. Số liệu là dữ liệu mẫu có gắn nhãn rõ.

10 lenses, 4 formats (ascii · md · mermaid · json)10 lăng kính, 4 định dạng (ascii · md · mermaid · json)

usage
counts · tokens · never-usedđếm · token · chưa dùng
session
duration · files · co-occurrencethời lượng · file · đồng hiện
health
script errors · avg mslỗi script · ms TB
reliability
subagent success/failsubagent đạt/hỏng
workflow
actual vs declared chainschuỗi thực vs khai báo
validate
validate-pass proxyproxy validate-pass
memory
orphans · dead linksmồ côi · link chết
product_memory
spec-store healthsức khỏe spec-store
forensics
one session rebuiltdựng lại một phiên
all
the dashboard-litebảng tổng quan gọn
⚖️ "Cái này KHÔNG đo được""Cái này KHÔNG đo được"

Every report ends with what it does not measure:Mỗi báo cáo kết bằng những gì nó không đo:

  • market / user outcome — usage ≠ effectivenesskết quả thị trường / người dùng — mức dùng ≠ hiệu quả
  • any thin lens → "chưa đủ dữ liệu", never spunlăng kính mỏng → "chưa đủ dữ liệu", không thổi phồng
  • suggestions only — no authority to prune or editchỉ gợi ý — không có quyền cắt hay sửa
🪝
5 telemetry sink hooks + 2 enforcement hooks share one runtime and one on/off file. The 5 sinks auto-register at install, are fail-open, make no network calls, and write only to gitignored .claude/telemetry/*.jsonl. The 2 enforcement hooks (memory-gap, critique-nudge) default off — a blocking hook is never fallback-enabled. Global kill-switch: CK_TELEMETRY_DISABLED=1.5 sink hook telemetry + 2 hook cưỡng chế dùng chung một runtime và một file bật/tắt. 5 sink tự đăng ký khi cài, fail-open, không gọi mạng, chỉ ghi vào .claude/telemetry/*.jsonl đã gitignore. 2 hook cưỡng chế (memory-gap, critique-nudge) mặc định tắt — hook chặn không bao giờ được bật theo fallback. Công tắc tổng: CK_TELEMETRY_DISABLED=1.
← PrevTrướcreleasereleaseNextSau →Spec hierarchyCây spec