docs: correct interceptor execution order in CLAUDE.md - #575
Merged
Conversation
The documented interceptor order was the reverse of the runtime nesting.
_buildInterceptors pushes [telemetry, timeout, retry, cache] and
_executeWithInterceptors folds the array so each later entry becomes the
inner wrapper, netting outermost-to-innermost: Cache -> Retry -> Timeout
-> Telemetry -> fn().
Also fix the config example: it must be wrapped in { default: ... }
(PluginExecutionSettings), retry uses 'attempts' not 'maxRetries', cache
'ttl' is in seconds, cache/retry need 'enabled' to activate, and the
per-call telemetry key is 'telemetryInterceptor' (not 'telemetry: { traces }').
Add the layered-observability nuance (cache layer + connectors carry their
own spans; timeout/retry only log).
Co-authored-by: Isaac <no-reply@databricks.com>
Signed-off-by: Atila Fassina <atila@fassina.eu>
Contributor
🤖 AppKit PR bot🔬 Run evalsStart an eval for this PR from the evals-monitor app: Go to Evals Monitor → 📦 Try this PR's app templateScaffolds a new app from this PR's SDK build. Run it in any folder (requires the GitHub CLI — gh run download 33861774533 -R databricks/appkit -n appkit-template-0.71.0-pr.f444d6a-fix-interceptor-order-discrepancy-575 -D appkit-pr-575 \
&& unzip -o "appkit-pr-575/appkit-template-0.71.0-pr.f444d6a-fix-interceptor-order-discrepancy-575.zip" -d "appkit-pr-575" \
&& databricks apps init --template "appkit-pr-575"The template pins |
MarioCadenas
approved these changes
Sep 4, 2026
atilafassina
marked this pull request as ready for review
September 7, 2026 06:31
atilafassina
requested review from
calvarjorge
and
a lite review from Copilot
September 7, 2026 06:31
Contributor
There was a problem hiding this comment.
🟡 Changes recommended
The updated docs contain a couple of factual inaccuracies (the wrapper-fold description and a non-existent file path) that should be corrected before merging.
Once you've addressed the issues Copilot identified, you can request another Copilot review.
Pull request overview
This PR updates the root CLAUDE.md documentation to accurately describe AppKit’s interceptor nesting order at runtime and corrects the per-call execute() configuration example to match the actual PluginExecutionSettings/PluginExecuteConfig shape used by the SDK.
Changes:
- Correct interceptor nesting order to match runtime behavior (Cache outermost → Telemetry innermost).
- Add an “observability is layered” note describing which layers emit spans vs. logs/metrics.
- Fix the
execute()config example keys/structure (e.g.,{ default: ... },retry.attempts,cache.ttlunits,telemetryInterceptor).
File summaries
| File | Description |
|---|---|
| CLAUDE.md | Fixes interceptor-order and execution-config documentation to match the actual runtime composition and config types. |
Review details
- Files reviewed: 1/1 changed files
- Comments generated: 2
- Review effort level: Lite
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
| 3. **TimeoutInterceptor** - AbortSignal timeout | ||
| 4. **TelemetryInterceptor** (innermost) - Traces the execution span, then `fn()` runs | ||
|
|
||
| `_buildInterceptors` pushes them in the array order `[telemetry, timeout, retry, cache]`, then `_executeWithInterceptors` folds that array so each *later* entry becomes the *inner* wrapper — netting the cache-outermost order above. |
|
|
||
| **Observability is layered — it's not just the one `plugin.execute` span:** | ||
| - The innermost `TelemetryInterceptor` opens `plugin.execute`, but because it sits *below* cache/retry/timeout: a cache hit never reaches it, retry attempts do not share a single parent span, and a timeout surfaces only as a generic "Operation cancelled by client" (indistinguishable from a user cancel). | ||
| - The **cache layer** (`src/cache/index.ts`) opens its own `cache.getOrExecute` span with a `cache.hit` attribute plus hit/miss metrics and structured logs — so cache hits *are* observable, via that layer. |
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
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.
What
Corrects the Execution Interceptor Pattern section of the root
CLAUDE.md, which documented the interceptor nesting in the exact reverse of the runtime behavior, plus several wrong keys in the config example.Why
The doc claimed the order was
Telemetry (outermost) → Timeout → Retry → Cache (innermost). The actual runtime nesting is the reverse:_buildInterceptors(packages/appkit/src/plugin/plugin.ts) pushes the array as[telemetry, timeout, retry, cache]._executeWithInterceptorsfolds that array so each later entry becomes the inner wrapper.fn().The in-code comment at
plugin.ts:700(telemetry → timeout → retry → cache (innermost to outermost)) was already correct — onlyCLAUDE.mdwas stale.Changes
plugin.executespan doesn't wrap cache hits/retries/timeouts, but the cache layer emits its owncache.getOrExecutespan + hit/miss metrics, and connectors carry their own spans;timeout/retryonly log.{ default: ... }(PluginExecutionSettings) — the realexecute()signature.retry: { maxRetries: 3 }→retry: { enabled: true, attempts: 3 }(RetryConfig.attempts).cache.ttlis in seconds, and cache needsenabled+cacheKeyto activate.telemetry: { traces: true }→telemetryInterceptor: { enabled: true }(the per-call key;tracesis plugin-level config).Docs-only change — no code touched.
Note / follow-up
There's a separate, deliberate design question left for a follow-up: whether the code should make
TelemetryInterceptoroutermost (so the span covers retries/timeout/cache-hit). Not done here — it changes the interceptor composition and trades away the pure-work-latency signal, so it wants its own PR + owner sign-off. Recommended alternative if pursued: an outer operation span plus the existing inner per-attempt span.This pull request and its description were written by Isaac.