docs: agent tracing guides for 20 frameworks + per-framework skills - #1115
Confidence 2/5 · 4 issues to address
🔴 Confidence 2/5 · risky as written
Docs and skills only, but the inline-key guidance now contradicts the env-var export guard left in the Spring AI skill.
quality 58/100 · 4 warnings · 1 note · tests not needed · risk low
Flips the agent-tracing guides and the framework skills from an env-var ingest key to an inline key with MAPLE_TEST as the placeholder, and rewrites the per-skill key bullets. Safe for the product, but one skill now disables its own export on the path it recommends.
- Every guide/skill inlines the ingest key;
MAPLE_TESTreplaces the env-var fallback maple-onboardand themaple-*-styleskills drop the missing-key bootstrap guards- Spring AI keeps an env-var-based export guard while now allowing an inline key
- Claude Agent SDK skills let the agent inline the key instead of throwing when it is unset
Findings
🟠 Warning · F10 · Inlining the key in application.properties makes the main guard disable export
correctness · skills/maple-agent-tracing-spring-ai/SKILL.md:27-28
Line 27 now permits inlining the ingest key in application.properties when the repo has no env convention, but the guard this file prescribes (line 68) decides with System.getenv("MAPLE_INGEST_KEY"); the version this change replaced read Boot's environment, which includes application.properties. With the key inlined and no env var set, main turns export off (and ${MAPLE_INGEST_KEY:} expands to an empty Bearer ), so the instrumented app sends nothing and the guide's own verification fails.
Decide the guard on Boot's environment again (the `ApplicationEnvironmentPreparedEvent` listener this change dropped) so a key that lives in `application.properties` or an imported profile is seen, or state that the inline path skips the guard.
🔵 Note · F11 · Step 2a tells the agent to replace a throw that the snippet does not have
correctness · skills/maple-agent-tracing-claude-agent-sdk/SKILL.md:41
The parenthetical this change added tells the agent to "replace the key lookup and the throw", but neither prescribed snippet contains a throw: the TypeScript mapleEnv() (SKILL.md:50-56) and the Python maple_env() (SKILL.md:99-105) both warn once and return early. An agent following the instruction literally has nothing to replace but the lookup.
Drop "and the throw" from the parenthetical, or point at the warning branch it is describing.
Still open from earlier reviews
- 🟠 Warning · F6 · Page says a project
.claude/settings.jsonoverridesoptions.envand also that it cannot set these variables ·apps/landing/src/content/docs/agent-tracing/claude-agent-sdk.mdx:142 - 🟠 Warning · F8 ·
telemetry = StrandsTelemetry().setup_otlp_exporter()assigns the setup call's result, then flush uses it ·skills/maple-agent-tracing-strands/SKILL.md:63 - 🟠 Warning · F9 ·
management.tracing.export.enabledis not a Boot property, so traces are never disabled when the key is unset ·skills/maple-agent-tracing-spring-ai/SKILL.md:70
Fixed since the last review
- ✅
F7 · Step 1 says throw whenMAPLE_INGEST_KEYis unset; themapleEnv()code it prescribes warns instead
What was checked
MAPLE_TESTis the gateway sentinel and returns 200 without storing (apps/ingest/src/main.rs:105), so the placeholder claim holdsmaple_pk_keys resolve for OTLP paths (resolve_ingest_key,apps/ingest/src/main.rs:5479-5481), so "the public key also works on servers" holds- Read the diffs of all 63 changed files at ade4adc; none add production code, spans or queries
ade4adc · Updated on every push. Reply "won't fix" to dismiss a finding, or mention @maple-review-bot to ask about one.
Annotations
Check warning on line 28 in skills/maple-agent-tracing-spring-ai/SKILL.md
maple-review-bot / Maple / review
correctness: Inlining the key in `application.properties` makes the `main` guard disable export
Line 27 now permits inlining the ingest key in `application.properties` when the repo has no env convention, but the guard this file prescribes (line 68) decides with `System.getenv("MAPLE_INGEST_KEY")`; the version this change replaced read Boot's environment, which includes `application.properties`. With the key inlined and no env var set, `main` turns export off (and `${MAPLE_INGEST_KEY:}` expands to an empty `Bearer `), so the instrumented app sends nothing and the guide's own verification fails.
Check notice on line 41 in skills/maple-agent-tracing-claude-agent-sdk/SKILL.md
maple-review-bot / Maple / review
correctness: Step 2a tells the agent to replace a throw that the snippet does not have
The parenthetical this change added tells the agent to "replace the key lookup and the throw", but neither prescribed snippet contains a throw: the TypeScript `mapleEnv()` (`SKILL.md:50-56`) and the Python `maple_env()` (`SKILL.md:99-105`) both warn once and return early. An agent following the instruction literally has nothing to replace but the lookup.