Skip to content

feat(telemetry): adopt v1 schema (telemetry_type, profile, classifiers)#60

Merged
saurabhjain1592 merged 1 commit into
mainfrom
feat/v1-telemetry-schema
May 8, 2026
Merged

feat(telemetry): adopt v1 schema (telemetry_type, profile, classifiers)#60
saurabhjain1592 merged 1 commit into
mainfrom
feat/v1-telemetry-schema

Conversation

@saurabhjain1592
Copy link
Copy Markdown
Member

Summary

Adopts the v1 telemetry schema (locked at axonflow-enterprise#2004) on the codex plugin's anonymous 7-day heartbeat. Closes the codex line-item under axonflow-enterprise#2008 (4-plugin umbrella).

Bundled with the V1.1 list-recent-decisions skill that was already sitting in the [Unreleased] section since 2026-05-07 — both ship together so users see one minor version transition.

What changes on the wire

The 1.4.0 heartbeat now emits four fields the receiver routes on:

Field Source Allowlist
telemetry_type hardcoded "plugin" discriminator
endpoint_type classify_endpoint_type() localhost | private_network | remote | unknown
profile AXONFLOW_PROFILE env or "unknown" free-form
deployment_mode classify_deployment_mode() self_hosted | community_saas | unknown

Detection logic in scripts/telemetry-ping.sh matches the claude-code plugin (#72) for cross-plugin parity.

Definition of Done

1. Tested

  • bash -n scripts/telemetry-ping.sh → clean.
  • New v1 telemetry-schema fields exercised end-to-end via the heartbeat real-stack harness — see Runtime-proven below.

2. Deep self-reviewed

Hunk-by-hunk review with the 5-question protocol:

  1. scripts/telemetry-ping.sh — replaced AXONFLOW_MODE/AXONFLOW_AUTH deployment_mode logic with the v1 endpoint-driven classifier + AXONFLOW_TRY=1 override. Two pure-bash classifier functions (classify_deployment_mode, classify_endpoint_type). Same shape as the openclaw + claude-code plugins so cross-plugin analytics dimensions stay consistent.
  2. tests/heartbeat-real-stack/run_real_stack.sh — assertion 5 expanded from one line to four (telemetry_type, endpoint_type, profile, deployment_mode). The harness binds to 127.0.0.1, so the v1 classifier returns endpoint_type=localhost and deployment_mode=self_hosted — that's the v1-correct answer.
  3. .codex-plugin/plugin.json — version 1.3.0 → 1.4.0.
  4. CHANGELOG.md — promoted unreleased V1.1 work into 1.4.0 release entry, added the v1 telemetry-schema additive section + the deployment_mode normalization callout.
  5. runtime-e2e/v1_telemetry_schema/ — wraps the heartbeat-real-stack harness for the definition-of-done mechanical gate. Lint-clean per scripts/lint-no-mocks-in-runtime-e2e.sh.

3. Runtime-proven

bash tests/heartbeat-real-stack/run_real_stack.sh against a real local Python checkpoint server:

--- Cold start: bootstrap + first heartbeat ---
  PASS: cold-start exit 0
  PASS: canary line on stderr matches fake endpoint + community-saas
  PASS: registration file written / mode 0600 / cs_<uuid>
  PASS: telemetry heartbeat fired exactly once (counter=1)
  PASS: ping telemetry_type=plugin
  PASS: ping endpoint_type=localhost (harness binds to 127.0.0.1)
  PASS: ping profile=unknown (AXONFLOW_PROFILE unset)
  PASS: ping deployment_mode=self_hosted (harness endpoint is 127.0.0.1)
  PASS: telemetry stamp file written / mode 0600

--- Warm cache: stamp gate + cached registration ---
  PASS: warm-cache exit 0
  PASS: no new registration POST (cached path)
  PASS: telemetry suppressed by stamp gate (delta=0)

Passed: 15
Failed: 0

The same harness runs in CI cross-platform (Ubuntu / macOS) via .github/workflows/heartbeat-real-stack.yml.

SoX governance

No direct CRUD against prod-checkpoint-telemetry-events. Plugin POSTs only to public /v1/ping. Per feedback_telemetry_table_is_sox.md.

Release-class actions

Tag + Release require explicit per-version authorization per feedback_releases_require_approval.md and feedback_distinguish_tag_from_release.md. This PR is for merge only.

Linked

  • axonflow-enterprise#2008 — plugin telemetry_type adoption umbrella
  • axonflow-openclaw-plugin#119 — sibling openclaw plugin (MERGED)
  • axonflow-claude-plugin#72 — sibling claude-code plugin (in flight)

@saurabhjain1592 saurabhjain1592 force-pushed the feat/v1-telemetry-schema branch from 7448329 to 8e5802d Compare May 8, 2026 10:48
Aligns the anonymous 7-day heartbeat with the v1 telemetry schema
locked at axonflow-enterprise#2004 (#2008 plugin umbrella). Bundled
into the same minor as the V1.1 list-recent-decisions skill from the
prior unreleased section so users only see one minor transition.

New emitted fields on the heartbeat:
  - telemetry_type: "plugin"        — discriminator the receiver uses to
                                       route plugin pings vs SDK / platform
                                       / synthetic on the v1 schema
  - endpoint_type                   — localhost | private_network | remote
                                       | unknown; mirrors SDK ClassifyEndpoint
  - profile                         — sourced from AXONFLOW_PROFILE; reports
                                       "unknown" when unset

deployment_mode enum normalised to v1 (`self_hosted | community_saas |
unknown`). Detection moves off AXONFLOW_MODE / AXONFLOW_AUTH onto
endpoint host + AXONFLOW_TRY=1 (community-saas behind custom
hostname). The prior `production`/`development`/`community-saas`
values are removed — analytics queries that match those must update.

Heartbeat real-stack harness updated to assert all four v1 payload
fields against a real network round-trip;
runtime-e2e/v1_telemetry_schema/ delegates to it for the
definition-of-done mechanical gate.

Bumps 1.3.0 → 1.4.0 in .codex-plugin/plugin.json + CHANGELOG.

Signed-off-by: Saurabh Jain <saurabhjain1592@gmail.com>
@saurabhjain1592 saurabhjain1592 force-pushed the feat/v1-telemetry-schema branch from 8e5802d to 1721bf1 Compare May 8, 2026 10:51
@saurabhjain1592 saurabhjain1592 merged commit efe191b into main May 8, 2026
12 checks passed
@saurabhjain1592 saurabhjain1592 deleted the feat/v1-telemetry-schema branch May 12, 2026 13:39
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant