feat!: v8.0 — decision history API + telemetry simplification#187
Merged
saurabhjain1592 merged 2 commits intomainfrom May 8, 2026
Merged
feat!: v8.0 — decision history API + telemetry simplification#187saurabhjain1592 merged 2 commits intomainfrom
saurabhjain1592 merged 2 commits intomainfrom
Conversation
Major release. The headline customer-facing feature is the
list_decisions client API for paging recorded decisions; the v8 line
also tightens the telemetry contract.
Telemetry simplification:
- Drop the AxonFlowConfig.telemetry field and the corresponding
AxonFlow(..., telemetry=...) keyword argument. AXONFLOW_TELEMETRY=off
in the environment is now the SOLE opt-out lever.
- Drop the mode != "sandbox" default-suppression rule. Sandbox-mode
clients now fire telemetry on the same schedule as production-mode
clients; the payload is tagged stream="sandbox" so analytics can
distinguish dev/test pings from production heartbeat without
conflating them. The wire allowlist is enforced server-side by the
checkpoint-service IsValidIncomingStream gate (axonflow-enterprise
PR #2005).
- Simplify _is_telemetry_enabled() to a single env-var check. Drop
mode / telemetry_enabled / has_credentials parameters from the
internal helpers (_is_telemetry_enabled, send_telemetry_ping,
maybe_send_heartbeat).
- Add stream field to telemetry payload via _build_payload — set to
"sandbox" only when mode == "sandbox", omitted otherwise (server
defaults absent stream to "heartbeat", preserving wire-shape parity
with v7.x for the production case).
Tests:
- test_telemetry.py rewritten under v8 contract: drops the
config-override matrix, adds stream-tag assertions, uses
monkeypatch.setenv("AXONFLOW_TELEMETRY", "") to clear the
conftest-level autouse opt-out for tests that need to exercise the
firing path.
- test_heartbeat.py / test_heartbeat_e2e.py: drop telemetry_enabled=True
from maybe_send_heartbeat call sites — the parameter no longer exists.
Runtime-e2e:
- Adds runtime-e2e/sandbox_telemetry_stream_tag/{test.sh,README.md}
that builds a tiny Python program against the local SDK in sandbox
mode and asserts the CloudWatch event_stored row carries
sdk=python/8 AND stream=sandbox. NOT YET EXECUTED — gated on
axonflow-enterprise PR #2005 deploy. Without #2005 the server
hardcodes stream=heartbeat regardless of payload.
Mirrors axonflow-sdk-go PR #160. Linked: axonflow-sdk-typescript
PR #2006 (TS counterpart), axonflow-enterprise PR #2005 (server-side
wire allowlist).
Migration: see CHANGELOG.md "Migration guide (v7 → v8)" section.
Signed-off-by: Saurabh Jain <saurabhjain1592@gmail.com>
The v8 telemetry refactor removed several lines from client.py (telemetry_enabled propagation), shifting subsequent line numbers down by 2. The pre-existing falsey-clobber lint baseline is keyed on exact line numbers, so CI saw both '15 NEW findings' and '15 stale baseline entries' for the same code that was unchanged in semantics — pure positional drift. Re-running with --write-baseline rewrites the file to current line numbers; no actual lint violations were introduced. Signed-off-by: Saurabh Jain <saurabhjain1592@gmail.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Major release. Headline feature:
client.list_decisions(opts)for pagingrecorded decision history (already on
mainvia #186, graduates into thev8 line here). Bundled into a major because the v8 line also tightens
the telemetry contract: drop the
telemetryconfig override and thesandbox-mode silent-suppression rule;
AXONFLOW_TELEMETRY=offbecomesthe sole opt-out lever.
Mirrors axonflow-sdk-go #160 (Go counterpart, already merged).
Linked: axonflow-sdk-typescript #2006 (TS counterpart),
axonflow-enterprise #2005 (server-side wire allowlist for
stream).Why combined into a major
cross-SDK release train (Go has already landed; TS is in flight).
Splitting them would force two separate major bumps within days.
streamfield) is additive — production-modepayload remains byte-identical to v7.x because we omit the field
when it would be empty. Only sandbox-mode payloads change shape.
telemetrykwarg removalis a
TypeErrorat construction, not a silent behavior shift. Easyto migrate (drop the kwarg or set
AXONFLOW_TELEMETRY=off).Migration notes (v7.1.0 → v8.0.0)
AxonFlow(..., telemetry=...)keyword argument removed. Codeusing it raises
TypeError. Migration: drop the kwarg; setAXONFLOW_TELEMETRY=offin env if opt-out is desired.AxonFlowConfig.telemetryfield removed from the dataclass.stream="sandbox"tag.If your code path constructed
Mode.SANDBOXclients expecting zeropings, set
AXONFLOW_TELEMETRY=offfor that environment.Full migration table in CHANGELOG.md under "Migration guide (v7 → v8)".
Dependency on axonflow-enterprise#2005
The new payload
stream="sandbox"field is a no-op until #2005 deploysthe server-side
IsValidIncomingStreamallowlist to checkpoint Lambda.Pre-deploy, the Lambda hardcodes
stream=heartbeatregardless ofpayload. The Python SDK ships safely either way (additive field,
ignored by older Lambdas), but the runtime-e2e proof requires #2005
landed first.
Test plan
Unit tests — DONE
pytest tests/— 974 passed, 29 skipped, 0 failed locallyagainst Python 3.11. (Pre-existing flakiness in
test_telemetry_short_livedwhen~/Library/Caches/axonflow/has a stale stamp from a prior run; CI starts clean.)
ruff check axonflow/ tests/— cleantest_sandbox_mode_fires_with_stream_tag— sandbox-mode pingfires AND payload carries
stream="sandbox"test_sandbox_mode_emits_stream_tag/test_production_mode_omits_stream_tag—
_build_payloadshape contract_is_telemetry_enabledmatrix for the env-var-only contractRuntime-e2e — TEST EXISTS, NOT YET EXECUTED
runtime-e2e/sandbox_telemetry_stream_tag/test.shruns locallyagainst deployed checkpoint Lambda. Gated on axonflow-enterprise
#2005 deploy. Pre-#2005 the server hardcodes
stream=heartbeatregardless of payload, so the assertion wouldfail for a server-side reason rather than an SDK bug.
Self-review — DONE
5-question protocol per hunk run via
git diff feat/v8-telemetry-cleanup:telemetry_enabled=call-site removals checked across
axonflow/andtests/. Commentreferences to v7.x behavior are intentional (CHANGELOG-style
docstrings) and labeled as such.
_is_telemetry_enabledimports updated; no caller passes the old (mode, telemetry_enabled,
has_credentials) tuple anywhere.
_build_payloadonly adds
streamwhenmode == "sandbox". Production payload isbyte-identical to v7.x. Asserted by
test_production_mode_omits_stream_tag.test_disabled_sandbox_mode(expecting suppression) replaced withtest_sandbox_mode_fires_with_stream_tag(expecting fire + tag).Old
test_config_override_*tests removed (config field gone).("Decision history API + telemetry simplification"), not the
internal release-train shorthand.
Risk
opt-out unchanged, fire schedule unchanged.
now one ping per 7-day window per env, tagged
stream="sandbox".Mitigation: documented in README + CHANGELOG with migration path.
AxonFlow(..., telemetry=...)kwarg removed. Hardbreak is intentional (loud
TypeErroris better than silentno-op). Cross-SDK Go counterpart already shipped this way.
Linked PRs
IsValidIncomingStreamwire allowlist