Skill Tracer
Skills › HyperFrames › media-use › telemetry-dashboard.md

telemetry-dashboard.md

49 lines · skills/media-use/references/telemetry-dashboard.md at a595755

Open on GitHub

Most marks come from matching words in the file, so treat them as pointers.

1# media-use usage dashboard
2
3Reproducible definition of the media-use usage dashboard. The dashboard answers
4"how much is media-use used, for what, is reuse working, and what can't it
5satisfy" from the telemetry `scripts/lib/telemetry.mjs` already emits. Build it
6in an authorized HyperFrames analytics project; this doc is the source of truth
7so it can be recreated. Local complement: `resolve --stats` (same questions,
8from `.media/` + `~/.media`, no dashboard access needed).
9

media-use usage dashboard

Reproducible definition of the media-use usage dashboard. The dashboard answers "how much is media-use used, for what, is reuse working, and what can't it satisfy" from the telemetry scripts/lib/telemetry.mjs already emits. Build it in an authorized HyperFrames analytics project; this doc is the source of truth so it can be recreated. Local complement: resolve --stats (same questions, from .media/ + ~/.media, no dashboard access needed).

Raw lines 1 to 9
Runs code scripts/lib/telemetry.mjs :5
10## Identity (see `scripts/lib/telemetry.mjs`)
12Events attribute to the **same person as the hyperframes CLI and studio**
13— the shared install id in `~/.hyperframes/config.json` (`anonymousId`), stitched
14to the HeyGen account (`$identify`, `distinct_id` = email/username) on sign-in.
15Not fully anonymous by design; pseudonymous before sign-in, account-linked after.
16`$ip:null`. Opt-out: `HYPERFRAMES_NO_TELEMETRY=1` / `DO_NOT_TRACK=1` (also CI, dev).

Identity (see scripts/lib/telemetry.mjs)

Events attribute to the same person as the hyperframes CLI and studio — the shared install id in ~/.hyperframes/config.json (anonymousId), stitched to the HeyGen account ($identify, distinct_id = email/username) on sign-in. Not fully anonymous by design; pseudonymous before sign-in, account-linked after. $ip:null. Opt-out: HYPERFRAMES_NO_TELEMETRY=1 / DO_NOT_TRACK=1 (also CI, dev).

Raw lines 10 to 17
Runs code scripts/lib/telemetry.mjs :10
18## Event catalog (verified present in-project)
20Every event carries `surface: "media-use"`. Event **properties are coarse** —
21never intent text, file names, or paths.
23| Event | Fires on | Key properties |
24| ---------------------------------------------------------------------- | ----------------------------------------- | ---------------------------------------------------------------------- |
25| `media_use_resolve` | a resolve that produced/returned an asset | `type`, `source`, `provider`, `via`, `local_only`, `provider_override` |
26| `media_use_resolve_miss` | a resolve that found nothing | `type`, `local_only`, `provider_override` (no intent) |
27| `media_use_candidates` | `--candidates` / `--dry-run` listing | `type`, counts |
28| `media_use_doctor_run` | `--doctor` | `ok`, `checks_failed`, `failed[]` |
29| `media_use_compare` | `grade-compare` / `compare` | `command`, `cells`, `truncated`, `total`, `render_ready_timed_out` |
30| `media_use_transcribe` · `media_use_duck` · `media_use_transcript_cut` | audio-engine ops | op-specific |

Event catalog (verified present in-project)

Every event carries surface: "media-use". Event properties are coarse — never intent text, file names, or paths.

EventFires onKey properties
media_use_resolvea resolve that produced/returned an assettype, source, provider, via, local_only, provider_override
media_use_resolve_missa resolve that found nothingtype, local_only, provider_override (no intent)
media_use_candidates--candidates / --dry-run listingtype, counts
media_use_doctor_run--doctorok, checks_failed, failed[]
media_use_comparegrade-compare / comparecommand, cells, truncated, total, render_ready_timed_out
media_use_transcribe · media_use_duck · media_use_transcript_cutaudio-engine opsop-specific
Raw lines 18 to 31
32## Dashboard tiles
341. **Invocation volume** — `query-trends`, count of `media_use_resolve` over time (daily). "How much."
352. **By media type** — `media_use_resolve` broken down by `type` (bgm/sfx/image/icon/logo/voice/grade/lut). "For what."
363. **Resolve hit-rate** — trends formula: `A / (A + B)` where A = `media_use_resolve`, B = `media_use_resolve_miss`. "Is the catalog covering needs."
374. **Provider mix** — `media_use_resolve` broken down by `provider`; a second tile by `via` (`url` / `params-fallback` / `params`) to catch CDN→params LUT downgrades.
385. **Top misses** — `media_use_resolve_miss` broken down by `type` (the tuning signal — pair with local `resolve --stats`, which also shows the missed _intents_ that telemetry deliberately omits).
396. **Doctor health** — `media_use_doctor_run` broken down by `failed[]` (which dependency check fails most) + `checks_failed` distribution.
407. **Compare cost** — `media_use_compare` by `command`, plus `truncated` / `render_ready_timed_out` rates (observe before lifting the 16-cell cap).
418. **Adoption (optional)** — if the `first_run` property ships (plan U5), segment `media_use_resolve` first-run vs repeat.

Dashboard tiles

  1. Invocation volume — query-trends, count of media_use_resolve over time (daily). "How much."
  2. By media type — media_use_resolve broken down by type (bgm/sfx/image/icon/logo/voice/grade/lut). "For what."
  3. Resolve hit-rate — trends formula: A / (A + B) where A = media_use_resolve, B = media_use_resolve_miss. "Is the catalog covering needs."
  4. Provider mix — media_use_resolve broken down by provider; a second tile by via (url / params-fallback / params) to catch CDN→params LUT downgrades.
  5. Top misses — media_use_resolve_miss broken down by type (the tuning signal — pair with local resolve --stats, which also shows the missed intents that telemetry deliberately omits).
  6. Doctor health — media_use_doctor_run broken down by failed[] (which dependency check fails most) + checks_failed distribution.
  7. Compare cost — media_use_compare by command, plus truncated / render_ready_timed_out rates (observe before lifting the 16-cell cap).
  8. Adoption (optional) — if the first_run property ships (plan U5), segment media_use_resolve first-run vs repeat.
Raw lines 32 to 42
43## Recreate in an analytics dashboard
45For each tile, confirm the event/property schema, build its trend or breakdown,
46then add it to a dashboard. Keep names prefixed `media-use:` so the dashboard is
47greppable. Cross-surface note: because identity is shared with CLI/studio, you
48can also break these down by the same person across `cli_command*` and `studio:*`
49events.

Recreate in an analytics dashboard

For each tile, confirm the event/property schema, build its trend or breakdown, then add it to a dashboard. Keep names prefixed media-use: so the dashboard is greppable. Cross-surface note: because identity is shared with CLI/studio, you can also break these down by the same person across cli_command* and studio:* events.

Raw lines 43 to 49