Terminal
Terminal/Skill
Guides you through adding traces, metrics and logs to an Adobe App Builder runtime action (the telemetry library must already be set up).
By Adobe
Works with
npx skills add adobe/aio-lib-telemetry --skill aio-telemetry-instrumentInstrument one App Builder runtime action at a time. Start from the observability goal and add the minimum code needed.
Skip phases that are already answered. If the first message already identifies the action, goal, and requested code changes, implement directly.
For fixed-choice questions, use the runtime's selectable-question tool.
Work on one action per session. If the user asks for multiple actions or "the whole project," have them choose the first action and continue one at a time.
defineTelemetryConfig and branch on params or isDev inside it. Separate config files are rare (see references/implementation-patterns.md).Before instrumenting, confirm that @adobe/aio-lib-telemetry is installed and that the project already has a defineTelemetryConfig call. If either is missing, route to aio-telemetry-setup.
This skill can still add per-action setup such as instrumentEntrypoint and ENABLE_TELEMETRY: true for the target action.
For single-turn implementation tasks, prefer concrete code over advice.
Before anything else, identify which action to instrument.
app.config.yaml at the project root and any ext.config.yaml filesIf no actions are declared in config files, ask the user to point to the action file directly.
Once the action is identified, let the user describe the goal before filling any gaps with follow-up questions.
Read the action's source code systematically. Follow the checklist in references/code-analysis.md:
instrumentEntrypoint. If not present for this action, note it as something to add in Phase 4.For data-pipeline and event-ingestion actions, apply these defaults unless the request clearly asks for something else:
instrument() for I/O boundaries such as storage writes, downstream notifications, or SDK/network calls.defineMetrics() at module scope, not inside the handler.Present a brief summary to the user:
"I've read your action. Here's what I see: [2-3 sentence summary of what the action does, its external dependencies, and its complexity]."
Ask only for missing inputs:
commerceWebhooks() or commerceEvents().Based on the action analysis (Phase 1) and observability goals (Phase 2), create a proposal.
Present the plan as a table:
| # | What | Signal | API | Why |
|---|---|---|---|---|
| 1 | Wrap fetchProductData | Trace (child span) | instrument(fn) | See external call duration separately |
| 2 | Add product.count attribute | Span attribute | currentSpan.setAttributes() | Know how many products per invocation |
| 3 | Record cache hit/miss | Metric (counter) | defineMetrics() | Track cache effectiveness over time |
instrumentEntrypoint plus auto-instrumentation covers this well. You might just want to add 1-2 span attributes for context."Present the proposal and wait for approval:
"Here's my plan for instrumenting [action name]. Does this cover what you need, or would you like to adjust anything before I make the changes?"
Do not proceed to Phase 4 without user approval unless you are in direct implementation mode from the user's initial request.
After approval, implement each item. See references/implementation-patterns.md for code patterns.
defineMetrics() calls at module level or in a separate metrics fileinstrument() around target functionsgetLogger() or getInstrumentationHelpers().logger callscontextCarrier in outbound calls to other instrumented servicesMinimal pattern:
const fetchProductData = instrument(async function fetchProductData(productId) {
return commerceClient.getProduct(productId);
});
instrument() call uses a named function or provides spanConfig.spanName@adobe/aio-lib-telemetry, @adobe/aio-lib-telemetry/otel, and @adobe/aio-lib-telemetry/integrations are valid"To verify: run your action, then check [their backend] for a trace from [action name]. You should see [describe expected span tree based on what was implemented]."
aio-telemetry-setup skillaio-telemetry-troubleshooting skillFor library and OpenTelemetry documentation sources, see references/documentation-sources.md.
| File | When to read |
|---|---|
| references/documentation-sources.md | Raw GitHub doc paths and OpenTelemetry JS docs |
| references/signal-decision.md | Deciding which signal type to use, choosing instrumentation depth |
| references/implementation-patterns.md | Writing the actual instrumentation code (Phase 4) |
| references/action-patterns.md | Classifying the action and building default instrumentation profiles |
| references/code-analysis.md | Systematic code reading checklist (Phase 1) |