@adobe-commerce/aio-toolkit 1.2.5 → 1.2.7

package/files/cursor-context/rules/aio-toolkit-oop-best-practices.mdc

@@ -70,7 +70,7 @@ class OrderProcessor {
 **Keep implementation details private:**
 
 ```javascript
-// JavaScript (Node.js 12+)
+// JavaScript
 class UserManager {
   #apiKey; // Private field
   
@@ -197,7 +197,13 @@ class GetUserResolver {
   
   async execute() {
     return async (args) => {
-      const { logger } = this.ctx;
+      // args = GraphQL field arguments (e.g. { id } from getUser(id: ID!))
+      const { logger, headers, telemetry, params } = this.ctx;
+      // logger    - structured logger with auto-correlation
+      // headers   - incoming HTTP request headers
+      // telemetry - OpenTelemetry helper for custom spans
+      // params    - full OpenWhisk params (query, variables, operationName, action inputs)
+
       logger.info({ message: 'getUser-execution', args });
       
       try {
@@ -205,7 +211,7 @@ class GetUserResolver {
         return result;
       } catch (error) {
         logger.error({ message: 'getUser-error', error: error.message });
-        throw error;
+        throw error; // GraphQL returns this as a field error (HTTP 200 with errors[])
       }
     };
   }
@@ -308,7 +314,7 @@ class HelloWorld {
   
   async execute() {
     return async (args) => {
-      const { logger } = this.ctx;
+      const { logger, headers, telemetry, params } = this.ctx;
       // Implementation
     };
   }

package/files/cursor-context/rules/aio-toolkit-setup-new-relic-telemetry.mdc

@@ -8,7 +8,7 @@ alwaysApply: false
 
 ## Trigger Conditions
 
-This rule applies when the user requests to add New Relic telemetry to their actions using any of these phrases:
+This rule applies when the user requests to add New Relic telemetry, use structured logging, or add custom spans to their actions using any of these phrases:
 
 - "Add New Relic telemetry"
 - "Enable New Relic monitoring"
@@ -18,6 +18,16 @@ This rule applies when the user requests to add New Relic telemetry to their act
 - "Enable observability with New Relic"
 - "Setup New Relic OTLP"
 - "Add telemetry monitoring"
+- "How to use ctx.logger"
+- "Structured logging in my action"
+- "Log object fields as separate attributes"
+- "Add custom spans"
+- "Instrument a function with telemetry"
+- "Use ctx.telemetry"
+- "Add spans to my action"
+- "How to use formatError"
+- "Structured error logging"
+- "How does ctx.logger work"
 
 ### Supported Action Types
 
@@ -42,7 +52,150 @@ The `@adobe-commerce/aio-toolkit` library includes built-in New Relic telemetry
 5. **Tags data** - Adds environment, service name, and custom resource attributes
 6. **Detects success/failure** - Automatically detects action outcomes
 
-**No code changes required** - Telemetry is configured entirely through action inputs and environment variables.
+**No code changes required for New Relic setup** - Telemetry is configured entirely through action inputs and environment variables. However, `ctx.logger` and `ctx.telemetry` are available in every action handler and benefit from intentional usage patterns described below.
+
+---
+
+## Using `ctx.logger`
+
+`ctx.logger` is injected automatically into every action handler. It is available in all action types regardless of whether New Relic telemetry is enabled. All log methods accept a plain string or **an object with a `message` key**:
+
+```javascript
+const { logger } = ctx;
+
+logger.debug({ message: 'debug-message', key: 'value' });
+logger.info({ message: 'info-message', key: 'value' });
+logger.warn({ message: 'warn-message', key: 'value' });
+logger.error({ message: 'error-message', key: 'value' });
+```
+
+### Always log objects, not plain strings
+
+When telemetry is enabled, the toolkit's `JsonMessageProcessor` automatically **promotes each key in a logged object to a separate, queryable attribute in New Relic**. Plain string logs are stored as a single `message` attribute only:
+
+```javascript
+// Preferred — each field becomes a queryable attribute in New Relic
+logger.info({
+  message: 'order-created',
+  order_id: 'ORD-123',
+  customer_id: 'CUST-456',
+  total: 99.99,
+});
+// New Relic receives: message, order_id, customer_id, total as separate attributes
+
+// Avoid — entire message is a single string, not queryable by field
+logger.info('order created for CUST-456');
+```
+
+### Nested objects are flattened to dot-notation
+
+```javascript
+logger.debug({
+  message: 'ACTION_HEADERS',
+  headers: {
+    accept: 'application/json',
+    authorization: 'Bearer token',
+  },
+});
+// New Relic attributes: headers.accept, headers.authorization
+```
+
+### Automatic metadata injection
+
+The logger automatically merges contextual metadata into every object log call — you do not need to add these fields yourself:
+
+| Metadata key | Source | Description |
+|---|---|---|
+| `x-adobe-commerce-request-id` | `__ow_headers['x-adobe-commerce-request-id']` | Adobe Commerce request correlation ID |
+| `action.type` | `params.action_type` | Action category set by the framework (e.g. `runtime`, `webhook`, `event-consumer`) |
+
+When `ENABLE_TELEMETRY: true` and New Relic is configured, the `ENVIRONMENT` param is attached as a **resource attribute** on every log, trace, and metric automatically.
+
+### Log level
+
+Controlled by the `LOG_LEVEL` action input. Valid values: `trace`, `debug`, `info`, `warn`, `error`. Defaults to `info` if not set.
+
+---
+
+## Using `ctx.telemetry`
+
+`ctx.telemetry` is injected alongside `ctx.logger`. Its span methods are only functional when `ENABLE_TELEMETRY: true`; when disabled, `getCurrentSpan()` always returns `null`. It exposes three methods relevant to action developers.
+
+### `instrument(spanName, fn)` — create child spans
+
+Wraps any function (sync or async) to produce a **child span** within the current trace context. The instrumented function has the same signature as the original — it must be called to execute:
+
+```javascript
+const { logger, telemetry } = ctx;
+
+const fetchOrders = telemetry.instrument(
+  'runtime.action.my-action.fetchOrders',  // span name as it appears in New Relic
+  async (customerId) => {
+    const span = telemetry.getCurrentSpan();
+    if (span) {
+      span.setAttribute('customer.id', customerId);
+      span.addEvent('fetch-started');
+    }
+
+    const orders = await orderService.findByCustomer(customerId);
+
+    if (span) {
+      span.setAttribute('orders.count', orders.length);
+    }
+
+    return orders;
+  }
+);
+
+// instrument() wraps the function — call it to execute and produce the span
+const orders = await fetchOrders(params.customer_id);
+```
+
+> `instrument()` must be called **inside** an active trace context — i.e., inside the action handler. Calling it outside will produce no span.
+
+**Span naming convention**: use `[action-type].action.[action-name].[operation]` — e.g. `runtime.action.order-create.validatePayload`.
+
+### `getCurrentSpan()` — attach attributes and events
+
+Returns the currently active OpenTelemetry span, or `null` when telemetry is disabled or called outside an active context. **Always guard with `if (span)`**:
+
+```javascript
+const span = telemetry.getCurrentSpan();
+
+if (span) {
+  span.setAttribute('order.id', orderId);
+  span.setAttribute('order.status', 'processing');
+  span.addEvent('validation-passed');
+}
+```
+
+### `formatError(error)` — structured error logging
+
+Converts an `Error` object (or any thrown value) into a structured object safe for logging. Use it inside `catch` blocks to promote error fields to individual New Relic attributes:
+
+```javascript
+try {
+  await processOrder(orderId);
+} catch (error) {
+  logger.error({
+    message: 'order-processing-failed',
+    order_id: orderId,
+    ...telemetry.formatError(error),  // spreads error_name, error_message, error_stack
+  });
+}
+```
+
+**Returns:**
+
+| Key | Value |
+|---|---|
+| `error_name` | `error.name` |
+| `error_message` | `error.message` |
+| `error_stack` | `error.stack` |
+
+If the thrown value is not an `Error`, returns `{ error: String(error) }`.
+
+---
 
 ## Step 1: Verify Prerequisites and Existing Configuration
 
@@ -208,6 +361,8 @@ Locate the action under `application.runtimeManifest.packages.[package-name].act
     final: true
 ```
 
+> **Misconfiguration is fatal.** If `NEW_RELIC_TELEMETRY: true` is set but `NEW_RELIC_SERVICE_NAME` or `NEW_RELIC_LICENSE_KEY` is missing or blank, the action returns **HTTP 500 immediately** with a `Telemetry configuration error: ...` message. This is intentional — it prevents silently running without telemetry when you expect it to be active. Always ensure both variables are set in `.env` before deploying with `NEW_RELIC_TELEMETRY: true`.
+
 #### Packaged Actions (in `actions/[package]/actions.config.yaml`)
 
 For actions defined in separate config files:
@@ -296,6 +451,16 @@ NEW_RELIC_URL=[custom-endpoint]  # Optional: EU only
 
 **Alerting**: Set up alerts for high error rates, slow execution, failed invocations, or missing telemetry data.
 
+**PublishEvent Logger Integration**: When an action uses `PublishEvent` to publish CloudEvents, pass the action's `ctx.logger` to the constructor so publisher-level logs appear in the same New Relic trace:
+```javascript
+const publisher = new PublishEvent(
+  params.IMS_ORG_ID,
+  params.API_KEY,
+  accessToken,
+  logger   // ← pass ctx.logger here for correlated logs in New Relic
+);
+```
+
 **Multiple Environments**: Use different `ENVIRONMENT` values (dev/staging/prod) in separate `.env.{env}` files in project root. Filter New Relic data by environment tag.
 
 **CI/CD Integration**: Store `NEW_RELIC_LICENSE_KEY` in CI/CD secrets (GitHub Actions, etc.), set environment-specific values in deployment workflows.