Terminal
Terminal/Skill
Walks you through adding OpenTelemetry tracing, metrics and logs to Adobe App Builder runtime actions, including Grafana and New Relic backends.
By Adobe
Works with
npx skills add adobe/aio-lib-telemetry --skill aio-telemetry-setup@adobe/aio-lib-telemetry SetupInteractive setup guide. Gather user requirements through conversation, then generate the right configuration.
Ask only for missing inputs: project state, backend, desired signals, any commerceEvents() or commerceWebhooks() integration, whether traces must continue downstream, and whether local development needs Docker or tunneling. If the user already gives these, generate the implementation in one pass.
For fixed-choice questions, use the runtime's selectable-question tool.
Generate incrementally unless the user asks for concrete files.
npm install @adobe/aio-lib-telemetry
In app.config.yaml, add ENABLE_TELEMETRY: true as input to each action (or at package level for all actions).
runtimeManifest:
packages:
my-package:
actions:
my-action:
function: actions/my-action/index.js
inputs:
ENABLE_TELEMETRY: true
CRITICAL: Without this env var set to true, telemetry silently does nothing. This is the #1 setup mistake.
Create a telemetry.{ts,js} file.
Minimal config (no backend yet):
import {
defineTelemetryConfig,
getPresetInstrumentations,
getAioRuntimeResource,
} from "@adobe/aio-lib-telemetry";
export const telemetryConfig = defineTelemetryConfig((params, isDev) => {
return {
sdkConfig: {
serviceName: "my-app-builder-app",
instrumentations: getPresetInstrumentations("simple"),
resource: getAioRuntimeResource(),
},
};
});
For backend-specific exporter configuration, read the appropriate reference:
Use params or isDev inside one shared defineTelemetryConfig for environment-specific behavior. Separate config files are rare.
Wrap the action's main function:
import { instrumentEntrypoint } from "@adobe/aio-lib-telemetry";
import { telemetryConfig } from "./telemetry";
function main(params) {
// existing implementation
}
const instrumentedMain = instrumentEntrypoint(main, telemetryConfig);
export { instrumentedMain as main };
If using integrations, merge them into the config:
import { commerceEvents } from "@adobe/aio-lib-telemetry/integrations";
const instrumentedMain = instrumentEntrypoint(main, {
...telemetryConfig,
integrations: [commerceEvents()],
});
See references/integrations.md for details.
Use one placement only: shared telemetry config or a specific instrumentEntrypoint.
For Commerce handlers that invoke another action, use commerceEvents() on the handler and forward contextCarrier on the downstream OpenWhisk call. Do not introduce x-telemetry-context or __telemetryContext in new code.
With the entrypoint wrapped, your action produces a root span. For deeper instrumentation, use aio-telemetry-instrument.
At this point, setup is complete. The steps below are optional and depend on the user's architecture.
Needed when the runtime action calls other instrumented services — whether other App Builder actions, external APIs, microservices, or any system that supports W3C Trace Context.
Sending side — serialize context into outbound requests:
import { getInstrumentationHelpers } from "@adobe/aio-lib-telemetry";
function callExternalService() {
const { contextCarrier } = getInstrumentationHelpers();
fetch(serviceUrl, { headers: { ...contextCarrier } });
}
For OpenWhisk action-to-action calls, pass the carrier in the params body rather than HTTP headers:
function invokeFulfillment(openwhisk, payload) {
const { contextCarrier } = getInstrumentationHelpers();
return openwhisk.actions.invoke({
name: "fulfill-order",
params: { ...payload, ...contextCarrier },
});
}
Receiving side — depends on the target:
instrumentEntrypoint and you send contextCarrier in normal params or headers. Use propagation.getContextCarrier only for custom carrier shapes.traceparent/tracestate from headersFor manual propagation, non-HTTP scenarios, or disabling propagation, see references/propagation.md.
If the user wants to see telemetry data during local development, guide them through setting up a local observability stack. See references/local-dev-setup.md for:
isDev conditional configuration patternsgetInstrumentationHelpers() returns:
currentSpan - active span (set attributes, add events)contextCarrier - pre-serialized W3C headers for propagationtracer - global tracer for creating custom spansmeter - global meter for creating custom metricslogger - auto-configured logger correlated to current traceThrows if called outside an instrumented function.
| Symptom | Likely cause |
|---|---|
| No telemetry at all | ENABLE_TELEMETRY not set to true |
| No spans for inner functions | Used instrument but function never called within an instrumentEntrypoint context. See the aio-telemetry-instrument skill. |
| Traces not linking across services | Context carrier not sent in outbound headers |
| Signals missing occasionally | Container shut down before flush completed (known limitation) |
Enable diagnostics for debugging:
defineTelemetryConfig((params, isDev) => ({
sdkConfig: {
/* ... */
},
diagnostics: { logLevel: "debug" },
}));
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/grafana-backend.md | Configuring Grafana (Docker LGTM or Grafana Cloud) as backend |
| references/new-relic-backend.md | Configuring New Relic as backend |
| references/local-dev-setup.md | Setting up local observability stack, Docker Compose, tunneling |
| references/integrations.md | Adobe Commerce Events and Webhooks integrations |
| references/propagation.md | Context propagation between services, manual propagation |
| references/api-surface.md | Full API reference — functions, types, imports |