Terminal
Terminal/Skill
Walks you through fixing missing or broken telemetry in Adobe App Builder runtime actions, from config checks to log review.
By Adobe
Works with
npx skills add adobe/aio-lib-telemetry --skill aio-telemetry-troubleshooting@adobe/aio-lib-telemetry mostly forwards sdkConfig to OpenTelemetry's NodeSDKConfiguration. Validate config shape directly, especially in JavaScript projects without type checking.
Do not jump into the codebase. Start by understanding the user's problem through conversation. Only inspect code after gathering enough context for a targeted search.
For fixed-choice questions, use the runtime's selectable-question tool.
Ask the user to describe their problem. Understand:
aio app dev, or deployed to I/O Runtime)Before deep investigation, suggest these (many issues are one of these):
ENABLE_TELEMETRY: true set in app.config.yaml inputs? — #1 cause of "nothing works"export const main = instrumentEntrypoint(handler, { ...telemetryConfig })traceExporter, metricReaders, or logRecordProcessors in sdkConfigIf the user has an error message, look it up in references/error-messages.md for the exact cause and fix.
Get diagnostic information early and do what you can before asking for more input.
If not already enabled, ask the user to add this to their telemetry config and re-run:
diagnostics: {
logLevel: "debug",
}
See references/diagnostics-guide.md for complete details on log levels, where output appears, and how to interpret it.
Retrieve logs yourself when possible:
aio rt activation list.aio rt activation logs <activation_id> and analyze the output.aio app config get log-forwarding or fall back to code, config, error messages, and backend evidence.Add temporary log statements when they help verify execution flow or runtime config. Examples:
console.log at key points to verify execution orderparams (sanitized) to verify env vars reach the actiongetLogger() calls to trace data flowAfter adding temporary logs, have the user trigger the action and share the output. Remove the logs once the issue is resolved.
When you read the user's code, always validate the config against the known schema. Many issues come from invalid configs that silently fail — especially from plain JS users without type checking.
Use references/config-validation.md to check:
@adobe/aio-lib-telemetry, /otel, and /integrations existOTLPTraceExporterProto not OTLPTraceExporter)defineTelemetryConfig return { sdkConfig: { ... } }? Not flat properties?NodeSDKConfiguration properties? No invented keys?ENABLE_TELEMETRY, env var mapping with $VAR_NAMEIf the config is invalid, that's likely the root cause. Explain what's wrong, show the correct structure, and if it's a significant setup problem, mention the aio-telemetry-setup skill can help them start fresh.
Only after understanding the symptom, read:
defineTelemetryConfig call)app.config.yaml (env vars, ENABLE_TELEMETRY)instrumentEntrypoint wrapping)Match findings against known scenarios in references/common-scenarios.md:
If the user has a local observability stack (Docker LGTM, tunneling), check these:
docker ps | grep otel-lgtmcurl -s -o /dev/null -w "%{http_code}" http://localhost:4318/v1/traces (should return 200 or 405)docker logs cloudflared or docker logs ngrok)For tunnel-specific issues beyond basic connectivity (Cloudflare account issues, ngrok limits, etc.), refer the user to the respective tool's documentation or support channels.
Diagnostic output tells you exactly what happened:
error level messages have the root causedebug level, OTel logs HTTP requests — look for connection refused, 401, 429, timeoutsProvide the specific fix. If the problem is a setup issue (missing config, wrong structure), explain what's wrong and suggest the aio-telemetry-setup skill can help them set it up correctly from scratch.
If an OTel SDK option is unclear, consult references/documentation-sources.md.
Before escalating, rule out transient failures, local environment problems, and one-off breakage.
Only escalate after configuration, code, and local environment checks are exhausted:
For 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/config-validation.md | Validating user's config — import paths, schema, valid properties, common mistakes |
| references/error-messages.md | User reports a specific error message |
| references/diagnostics-guide.md | Need to enable/interpret diagnostic output, or need to ask user for logs |
| references/common-scenarios.md | Matching symptoms to known causes and fixes |