Maple Audit

Maple instrumentation audit

Review an existing OpenTelemetry setup against what Maple actually consumes, produce a findings report, then fix the gaps. This is the counterpart to maple-onboard: that skill installs telemetry from scratch; this one assumes instrumentation exists and asks whether it's right.

Before auditing, read checks.md in this skill's directory — it is the full check registry (check ids, severities, what each gap breaks in Maple). Every finding you report must cite a check id from there; never invent attribute keys or conventions that aren't in checks.md or the upstream OTel semconv.

For how to fix what you find, use the companion skills — don't improvise recipes:

• maple-onboarding-style for general OTel taste, VCS attributes, log bridges, metrics, LLM conventions.
• maple-nextjs-style, maple-nodejs-style, maple-python-style, maple-effect-style, maple-go-style, maple-rust-style, maple-java-style, maple-csharp-style, maple-kotlin-style for stack-specific bootstrap shapes.

Severity

Step 1 — Enumerate services and classify

Map every app/service in the repo exactly as maple-onboard Step 1 does (workspace manifests, apps/*, services/*, mobile, edge/serverless functions — skip pure type/config packages). For each, find its OTel bootstrap and classify:

• instrumented — has an SDK bootstrap; gets the full audit below.
• partial — some signals wired (e.g. traces but no log bridge); audit what exists, flag what's absent.
• not instrumented — no OTel at all. That is a single critical finding pointing the user at maple-onboard; don't run per-check audits against nothing.

Show the user the service list with classifications before auditing, so they can correct it.

Step 2 — Static code audit

Per instrumented service, work through the categories in checks.md:

1. *Bootstrap & resource (RES-\) — read the SDK init: is `service.name` explicit, are `service.version`, `deployment.environment.name`, `vcs.repository.url.full`, `vcs.ref.head.revision` on the resource? Any invented keys? 2. Status & kind (STAT-\) — grep for status handling: SDK status enum vs hand-stamped strings; failure paths recording exceptions; outbound calls created as `Client`/`Producer` spans. 3. Trace coverage (SPAN-\)* — what should be traced but isn't. Compare the dependency manifest against the instrumentation registered in the bootstrap (a DB driver or queue client with no instrumentation package means that whole category emits nothing). Then read the code for critical business operations, background jobs, and queue consumers with no span in their call path — when this service misbehaves, what would an operator need to see that currently emits nothing? 4. Service-map attribution (MAP-\) — for every outbound dependency in the code (HTTP clients to internal services, DB drivers, queues), check the corresponding spans set `peer.service` (and `db.system` for DBs) consistently. 5. Attribute keys (REN-\, NAME-\) — grep attribute call sites (`setAttribute`, `set_attribute`, `setAttributes`, attribute map literals) for the deprecated/camelCase keys in the REN table and for double-emission of old+new keys. 6. Logs (LOG-\) — is an OTLP log bridge wired under the logger the app actually uses? Do in-span logs carry trace context? Structured fields? 7. Metrics (MET-\) — instruments at module scope, low-cardinality labels, business coverage. 8. PII (PII-01) — scan attribute values for emails, tokens, auth headers, full bodies. 9. LLM (LLM-\)* — only if the project calls LLM providers.

Collect findings as you go: service, check id, severity, evidence (file:line), and which Maple feature it affects (from checks.md).

Step 3 — Live cross-check (only when the Maple MCP is connected)

If mcp__maple__* tools are available, verify the static findings against what's actually arriving. If they're not available, say so in one line of the report and move on — the static audit stands alone. Don't ask the user to install the MCP mid-audit.

• `get_instrumentation_recommendations` — the authoritative list of deprecated/double-emitted/non-conforming attribute keys, reconciled against the org's live span data, plus resource-attribute coverage gaps. Where it disagrees with your static REN/NAME findings, the live data wins (the code you read may not be deployed, or other emitters exist).
• `list_services` — confirm every service you enumerated actually reports. A service that's instrumented in code but absent here is a critical export problem (bootstrap not loaded, key wrong, exporter blocked).
• `explore_attributes` (resource scope) — confirm environment/VCS/version resource attrs arrive in practice.
• `service_map` — a service whose code makes outbound calls but shows no outgoing edges confirms MAP-01/02/03 findings from the data side.
• `get_service_top_operations` (or search_traces per service) — confirm trace-coverage findings: a critical operation you flagged under SPAN-02/03 that never appears as a span name in live data is confirmed untraced; a DB-heavy service whose traces contain no DB client spans confirms SPAN-01.

Annotate existing findings with live evidence rather than duplicating them.

Step 4 — Findings report

Present the report before making any edit. Format:

## Instrumentation audit — <repo>

### <service-name>  (instrumented | partial | not instrumented)
| Severity | Check  | Finding                                   | Evidence            | Affects                  |
| critical | MAP-01 | Client spans to billing lack peer.service | src/billing.ts:88   | service map edge missing |
| warn     | REN-02 | emits http.status_code                    | live: 12.4k spans/24h | rename to http.response.status_code |
...

### Summary
N critical · N warn · N info across M services. Recommended fix order: …

Every row carries a check id and concrete evidence (file:line for static, counts/tool output for live). If the MCP wasn't connected, note "live cross-check skipped — Maple MCP not connected" here.

Step 5 — Apply fixes

After the report, fix in severity order (critical → warn → info), following the relevant style skill for each edit. Rules:

• Pure key renames (REN rows of kind rename) have two valid routes: rename at the SDK (preferred — fixes it at the source), or accept the matching Recommendation Issue in Maple Settings → Ingestion, which creates an ingest attribute mapping. Tell the user both; default to the SDK rename when you're already editing that file.
• Double-emission and naming issues can only be fixed at the SDK — an ingest mapping can't merge keys.
• Idempotent edits; preserve the project's package manager, logger, and formatting.
• Never remove an existing observability vendor (Sentry, Datadog, …) — coexistence is the default.
• Never put PII in attributes; when fixing PII-01, replace the value with an ID or drop the attribute, don't hash-and-keep.
• Never commit, push, or open PRs.

If the user only wants the review, stop after Step 4 — the report is a complete deliverable.

Step 6 — Re-verify

For every service you touched, run the same smoke as maple-onboard Step 4: the service's own dev/build command starts cleanly, and OTLP POSTs from the running process return 2xx. A fix that breaks startup is a regression — fix or revert it, don't paper over it.

Then close out: summarize what changed per service, and tell the user that after deploying, re-running get_instrumentation_recommendations (or checking Settings → Ingestion in Maple) will show issues auto-resolving as the offending keys stop arriving — reconciliation is automatic.

Hard rules

• No edits before the findings report has been shown (Step 4).
• Every finding cites a check id from checks.md; no invented attribute keys or conventions.
• The static audit must work standalone — the Maple MCP is an enhancer, never a requirement.
• Never modify files outside the project root; never commit or push.
• Fix recipes come from the maple-*-style skills, not from memory.

Maple instrumentation audit checklist

The full check registry for the maple-audit skill. Each check has a stable id, what to look for in the code, a severity, the Maple feature affected, and where to find the fix recipe.

Severities:

• critical — breaks a Maple feature outright or is a data risk. Fix first.
• warn — the feature works degraded or the data is harder to query than it should be.
• info — nice-to-have; improves signal quality but nothing is broken.

Fix pointers reference the companion skills: maple-onboarding-style (general), maple-nodejs-style, maple-nextjs-style, maple-python-style, maple-go-style, maple-rust-style, maple-java-style, maple-csharp-style, maple-kotlin-style, maple-effect-style.

RES — Resource attributes

Set once per process on the SDK resource, in the OTel bootstrap. Look for the resource construction (resourceFromAttributes(...) / Resource.create(...) in TS, Resource(attributes={...}) in Python, resource.NewWithAttributes(...) in Go, Resource::builder() in Rust, registerOTel({ attributes }) for @vercel/otel).

Fix: maple-onboarding-style → "VCS resource attributes" + the per-language style skill's bootstrap section.

STAT — Span status & kind

These are span fields, not attributes, and both spellings are load-bearing on the Maple side: stored values must be Title Case (Ok / Error / Unset, Server / Client / Producer / Consumer / Internal).

Fix: maple-onboarding-style + per-language style skill ("record exceptions" pattern; in TS/JS withSpan from @maple/otel-helpers handles status + exception recording).

SPAN — Trace coverage

Not just "are the spans right" but "is everything that should be traced actually traced". Read the code the way an on-call operator would: when this service misbehaves, which operations would they need to see? Auto-instrumentation covers HTTP in/out, DB queries, and framework lifecycle — that's the floor; anything with real latency or a failure mode above that floor needs its own span (the same bar maple-onboard Step 3 applies when installing).

Static heuristics for SPAN-01/02: compare the dependency manifest (HTTP frameworks, DB drivers, queue clients, LLM SDKs) against the instrumentation registered in the bootstrap; grep entry points for job/consumer handlers with no startActiveSpan/withSpan/decorator in their call path.

Fix: maple-onboard Step 3 + maple-onboarding-style (span naming, attributes, withSpan); per-language style skill for the auto-instrumentation package list.

MAP — Service-map attribution

Fix: maple-onboarding-style; the public reference is the "Service map" section of Maple's attributes docs (https://maple.dev/docs/concepts/otel-conventions).

REN — Deprecated / non-conforming attribute keys

<!-- This table mirrors ATTRIBUTE_RENAMES in packages/domain/src/recommendations.ts (the engine behind Maple's in-product Recommendation Issues). When the Maple MCP is connected, the get_instrumentation_recommendations tool is AUTHORITATIVE — it reconciles against live span data. This static table only powers the code-side audit. -->

Maple keeps fallback chains for the common legacy HTTP keys (legacy and current names feed the same fast columns), so these are renames for forward-compatibility and clean querying — warn, not breakage. Search the codebase for the deprecated key in setAttribute/set_attribute/attribute-map literals.

All REN checks are warn. Two extra rules:

• REN-DUAL (warn): if a service emits both the deprecated and the canonical key on the same spans (double-emission), standardize on the canonical key at the SDK. An ingest mapping cannot merge them — the canonical key already exists, so the mapping would silently no-op.
• Fix routes: pure renames can be fixed either at the SDK (preferred) or by accepting the corresponding Recommendation Issue in Maple Settings → Ingestion (creates an ingest attribute mapping). Double-emission and naming issues can only be fixed at the SDK.

LOG — Logs

Fix: maple-onboarding-style "Signals" + per-language style skill's log-bridge section.

MET — Metrics

Fix: maple-onboarding-style "Signals" / "Metrics" sections.

NAME — Naming conventions

PII — Sensitive data

LLM — gen_ai conventions

Only applies when the project calls an LLM provider (OpenAI, Anthropic, Google, …).

Fix: maple-onboarding-style "LLM metrics".