@adobe-commerce/aio-toolkit 1.2.6 → 1.2.7

package/CHANGELOG.md

@@ -5,6 +5,122 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.2.7] - 2026-06-18
+
+### ✨ Features
+
+- **feat(telemetry): add Grafana LGTM telemetry provider**
+
+  New `GrafanaTelemetry` class in `src/framework/telemetry/grafana/` forwards OpenTelemetry
+  signals (traces, metrics, logs) to a Grafana LGTM collector via OTLP/HTTP. Three operating
+  modes:
+
+  - **Dev** (`GRAFANA_DEV=true`) — targets `http://localhost:4318`, the default OTLP port of the
+    [Grafana LGTM Docker image](https://github.com/grafana/docker-otel-lgtm); no credentials
+    required. Start the stack with:
+    ```bash
+    docker run --rm -p 3000:3000 -p 4317:4317 -p 4318:4318 --name otel-lgtm grafana/otel-lgtm:latest
+    ```
+  - **Tunnel / deployed** — targets `GRAFANA_ENDPOINT` without authentication; use a Cloudflare
+    tunnel to expose a local stack to deployed Runtime actions:
+    ```bash
+    npx cloudflared tunnel --url http://localhost:4318
+    ```
+  - **Grafana Cloud** (`GRAFANA_CLOUD=true`) — targets `GRAFANA_ENDPOINT` with HTTP Basic auth
+    derived from `GRAFANA_INSTANCE_ID` and `GRAFANA_API_KEY`.
+
+  Added to the provider fallback chain after New Relic:
+  1. New Relic — `NEW_RELIC_TELEMETRY=true`
+  2. Grafana LGTM — `GRAFANA_TELEMETRY=true`
+  3. No telemetry — original action runs uninstrumented
+
+  **Configuration reference:**
+
+  | Variable | Required | Default | Description |
+  |---|---|---|---|
+  | `ENABLE_TELEMETRY` | ✅ | — | Must be `true` to enable any telemetry |
+  | `GRAFANA_TELEMETRY` | ✅ | — | Must be `true` to select this provider |
+  | `GRAFANA_DEV` | — | `false` | `true` for localhost dev mode |
+  | `GRAFANA_ENDPOINT` | ✅ tunnel & Cloud / — dev | — | Collector base URL |
+  | `GRAFANA_SERVICE_NAME` | — | `app-builder-app` | Service name tag |
+  | `GRAFANA_CLOUD` | — | `false` | `true` for Grafana Cloud Basic auth |
+  | `GRAFANA_INSTANCE_ID` | ✅ when `GRAFANA_CLOUD=true` | — | Grafana Cloud stack instance ID |
+  | `GRAFANA_API_KEY` | ✅ when `GRAFANA_CLOUD=true` | — | Grafana Cloud API key / token |
+
+- **feat(log-sanitizer): add `LogSanitizer` class and `SENSITIVE_KEYS` param support**
+
+  New `LogSanitizer` class in `src/framework/telemetry/helpers/log-sanitizer/` deep-clones a
+  value and replaces sensitive field values with `"[REDACTED]"` before they reach the log stream.
+
+  **Built-in sensitive key detection (case-insensitive):**
+  - Exact matches: `authorization`, `x-api-key`, `cookie`, `set-cookie`
+  - Suffix patterns: `*_api_key`, `*_secret`, `*_token`, `*_password`, `*_key`, `*-token`, `*-secret`, `*-key`
+
+  All action classes (`RuntimeAction`, `EventConsumerAction`, `OpenwhiskAction`) automatically
+  sanitize headers, parameters, and results in their debug log calls. `Telemetry.createLogger()`
+  also sanitizes all object-type arguments passed to the returned logger. `LogSanitizer` is
+  exported from the main package index for direct use.
+
+  **Project-specific keys via `SENSITIVE_KEYS` param:**
+
+  New `static parseSensitiveKeys(raw: unknown): ReadonlySet<string>` parses the optional
+  `SENSITIVE_KEYS` action param into additional keys to redact. All action classes and
+  `Telemetry.createLogger()` call it automatically. Accepts:
+
+  | Input type | Example | Result |
+  |---|---|---|
+  | Comma-separated string | `"x-merchant-token,internal_id"` | `Set { "x-merchant-token", "internal_id" }` |
+  | Array | `["x-merchant-token", "INTERNAL_ID"]` | `Set { "x-merchant-token", "internal_id" }` |
+  | Single string | `"x-merchant-token"` | `Set { "x-merchant-token" }` |
+  | Anything else (incl. `undefined`) | — | `Set {}` (no additional keys) |
+
+  Add project-specific keys in `app.config.yaml`:
+  ```yaml
+  inputs:
+    SENSITIVE_KEYS: "x-merchant-token,internal_order_id"
+  ```
+
+### 🛠️ Internal
+
+- **chore(telemetry): replace `@ts-expect-error` directives with ambient OTel type declaration**
+
+  Three stale `@ts-expect-error` directives in the telemetry source are replaced by a new
+  ambient module declaration in `src/global-types/adobe-aio-lib-telemetry-otel.d.ts` that
+  correctly types the `@adobe/aio-lib-telemetry/otel` sub-path export.
+
+- **refactor(log-sanitizer): extract constants to `types.ts`**
+
+  `EXACT_SENSITIVE_KEYS` and `SENSITIVE_KEY_SUFFIXES` moved from inline module-level constants
+  to exported constants in a dedicated `types.ts`, making them importable and independently
+  testable.
+
+- **feat(telemetry): add `GrafanaTelemetryValidator`**
+
+  New `GrafanaTelemetryValidator` implementing `BaseTelemetryValidator`:
+  - `isConfigured()` — `true` when both `ENABLE_TELEMETRY=true` and `GRAFANA_TELEMETRY=true`
+  - `validateConfiguration()` — no-op in dev mode; throws `TelemetryInputError` when
+    `GRAFANA_ENDPOINT` or `GRAFANA_SERVICE_NAME` is missing/empty in tunnel or Cloud mode
+
+- **chore(test): add `test/tsconfig.json`**
+
+  Gives VS Code's TypeScript language server the correct context for test files (jest/node
+  types, relaxed `noUncheckedIndexedAccess` and `exactOptionalPropertyTypes`).
+
+- **chore(test): fix missing platform mock in Linux `isCursorIde()` test**
+
+  The Linux `execPath` test case was not mocking `os.platform()` to return `'linux'`,
+  causing it to fall through to the macOS branch on macOS developer machines.
+
+### 📚 Documentation
+
+- **README** — new Grafana LGTM section covering all three operating modes, `app.config.yaml`
+  snippets, `.env` variables, usage example, and full env-var reference table.
+- **README** — `LogSanitizer` section documenting the class API, `parseSensitiveKeys()`,
+  `SENSITIVE_KEYS` param usage, sensitive key detection table, constructor options, and
+  behavioural notes.
+
+---
+
 ## [1.2.6] - 2026-05-10
 
 ### ✨ Features

package/README.md

@@ -312,7 +312,7 @@ OpenTelemetry integration for enterprise-grade observability with distributed tr
 - Access to current OpenTelemetry span via `ctx.telemetry` for custom instrumentation
 - `telemetry.instrument()` method for wrapping functions with automatic span creation
 - Conditional span access based on `ENABLE_TELEMETRY` flag
-- Multi-provider support (New Relic implemented, Grafana ready)
+- Multi-provider support (New Relic and Grafana LGTM implemented)
 - Graceful fallback when telemetry is not configured
 - Zero performance impact when disabled (opt-in via feature flags)
 
@@ -420,6 +420,195 @@ SELECT * FROM Log WHERE `x-adobe-commerce-request-id` = 'request-123' AND level
 SELECT count(*) FROM Log FACET `action.type` SINCE 1 hour ago
 ```
 
+---
+
+#### Grafana LGTM Telemetry
+
+The Grafana provider forwards traces, metrics, and logs to an OTLP/HTTP collector backed by the [Grafana LGTM](https://github.com/grafana/docker-otel-lgtm) all-in-one stack (**L**oki · **G**rafana · **T**empo · **M**imir). It works in two modes:
+
+| Mode | When | Collector URL |
+|---|---|---|
+| **Dev** | `GRAFANA_DEV=true` | `http://localhost:4318` (Docker image) |
+| **Deployed** | `GRAFANA_DEV` not set | `GRAFANA_ENDPOINT` (e.g. Cloudflare tunnel) |
+
+##### Dev mode — local Docker stack
+
+Start the LGTM stack with a single command:
+
+```bash
+docker run --rm -p 3000:3000 -p 4317:4317 -p 4318:4318 \
+  --name otel-lgtm \
+  grafana/otel-lgtm:latest
+```
+
+This exposes:
+
+| Port | Service |
+|---|---|
+| `3000` | Grafana UI — open `http://localhost:3000` (default credentials: `admin` / `admin`) |
+| `4317` | OTLP gRPC endpoint |
+| `4318` | OTLP HTTP endpoint (used by the toolkit) |
+
+Configure `app.config.yaml`:
+
+```yaml
+runtime-action:
+  function: actions/runtime-action/index.js
+  web: 'yes'
+  runtime: nodejs:22
+  inputs:
+    LOG_LEVEL: debug
+    ENABLE_TELEMETRY: true
+    GRAFANA_TELEMETRY: true
+    GRAFANA_DEV: true
+    GRAFANA_SERVICE_NAME: $GRAFANA_SERVICE_NAME
+  annotations:
+    require-adobe-auth: true
+    final: true
+```
+
+`.env`:
+
+```bash
+GRAFANA_SERVICE_NAME=my-app-builder-app
+```
+
+##### Deployed mode — Cloudflare tunnel
+
+Adobe I/O Runtime actions run in the cloud and cannot reach `localhost`. Expose your local LGTM stack via a [Cloudflare Tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/do-more-with-tunnels/trycloudflare/):
+
+```bash
+npx cloudflared tunnel --url http://localhost:4318
+# Outputs a URL like: https://abc123-def456.trycloudflare.com
+```
+
+Configure `app.config.yaml`:
+
+```yaml
+runtime-action:
+  function: actions/runtime-action/index.js
+  web: 'yes'
+  runtime: nodejs:22
+  inputs:
+    LOG_LEVEL: debug
+    ENABLE_TELEMETRY: true
+    GRAFANA_TELEMETRY: true
+    GRAFANA_ENDPOINT: $GRAFANA_ENDPOINT
+    GRAFANA_SERVICE_NAME: $GRAFANA_SERVICE_NAME
+  annotations:
+    require-adobe-auth: true
+    final: true
+```
+
+`.env`:
+
+```bash
+GRAFANA_ENDPOINT=https://abc123-def456.trycloudflare.com
+GRAFANA_SERVICE_NAME=my-app-builder-app
+```
+
+##### Usage example
+
+Telemetry is automatically initialized when you use framework action classes:
+
+```javascript
+/*
+ * <license header>
+ */
+
+const { RuntimeAction, RuntimeActionResponse, HttpMethod } = require('@adobe-commerce/aio-toolkit');
+const name = 'runtime-action';
+
+exports.main = RuntimeAction.execute(
+  name,
+  [HttpMethod.POST],
+  [],
+  ['Authorization'],
+  async (params, ctx) => {
+    const { logger, telemetry } = ctx;
+
+    logger.info({
+      message: `${name}-log`,
+      params: JSON.stringify(params),
+    });
+
+    const sampleInstrumental = telemetry.instrument(
+      `runtime.action.${name}.sampleInstrumental`,
+      async () => {
+        const span = telemetry.getCurrentSpan();
+
+        if (span) {
+          span.setAttribute('test', 'ABC');
+        }
+
+        logger.info({
+          message: `${name}-sampleInstrumental`,
+          test: 'ABC',
+        });
+
+        return 'Hello World';
+      }
+    );
+
+    const result = await sampleInstrumental();
+
+    return RuntimeActionResponse.success(result);
+  }
+);
+```
+
+##### Grafana Cloud
+
+Grafana Cloud provides a managed LGTM backend. It uses the same OTLP/HTTP protocol but requires
+HTTP Basic authentication with your stack's **Instance ID** and an **API key**.
+
+Find your OTLP endpoint and instance ID in **Grafana Cloud → Stack → OpenTelemetry**.
+
+Configure `app.config.yaml`:
+
+```yaml
+runtime-action:
+  inputs:
+    ENABLE_TELEMETRY: true
+    GRAFANA_TELEMETRY: true
+    GRAFANA_CLOUD: true
+    GRAFANA_ENDPOINT: $GRAFANA_ENDPOINT
+    GRAFANA_SERVICE_NAME: $GRAFANA_SERVICE_NAME
+    GRAFANA_INSTANCE_ID: $GRAFANA_INSTANCE_ID
+    GRAFANA_API_KEY: $GRAFANA_API_KEY
+```
+
+`.env`:
+
+```bash
+GRAFANA_ENDPOINT=https://otlp-gateway-prod-us-east-0.grafana.net/otlp
+GRAFANA_SERVICE_NAME=my-app-builder-app
+GRAFANA_INSTANCE_ID=123456
+GRAFANA_API_KEY=glc_xxx
+```
+
+##### Environment variable reference
+
+| Variable | Mode | Required | Default | Description |
+|---|---|---|---|---|
+| `ENABLE_TELEMETRY` | all | ✅ | — | Must be `true` to enable any telemetry |
+| `GRAFANA_TELEMETRY` | all | ✅ | — | Must be `true` to select the Grafana provider |
+| `GRAFANA_DEV` | dev | — | `false` | Set `true` to use `http://localhost:4318` |
+| `GRAFANA_CLOUD` | cloud | — | `false` | Set `true` to enable Grafana Cloud Basic auth |
+| `GRAFANA_ENDPOINT` | tunnel / cloud | ✅ | — | Collector base URL (not needed in dev mode) |
+| `GRAFANA_SERVICE_NAME` | tunnel / cloud | ✅ | `app-builder-app` | Service name tag (not needed in dev mode) |
+| `GRAFANA_INSTANCE_ID` | cloud | ✅ | — | Grafana Cloud stack instance ID |
+| `GRAFANA_API_KEY` | cloud | ✅ | — | Grafana Cloud API key / token |
+
+**Multi-provider fallback chain:**
+
+The toolkit tries providers in this order:
+1. **New Relic** — when `NEW_RELIC_TELEMETRY=true`
+2. **Grafana LGTM** — when `GRAFANA_TELEMETRY=true`
+3. **No telemetry** — original action runs uninstrumented
+
+---
+
 **Supported Action Classes:**
 
 Telemetry is automatically integrated with all framework action classes:
@@ -430,6 +619,97 @@ Telemetry is automatically integrated with all framework action classes:
 
 All action classes provide structured logging with automatic request ID and action type tracking.
 
+#### `LogSanitizer`
+
+Utility class that deep-clones a value and replaces sensitive field values with `"[REDACTED]"` before writing to logs. Used internally by all action classes and available for direct use.
+
+**Sensitive key detection (case-insensitive):**
+
+| Match type | Keys / patterns |
+|---|---|
+| Exact | `authorization`, `x-api-key`, `cookie`, `set-cookie` |
+| Suffix | `*_api_key`, `*_secret`, `*_token`, `*_password`, `*_key`, `*-token`, `*-secret`, `*-key` |
+
+**Constructor:**
+
+```typescript
+new LogSanitizer(
+  additionalSensitiveKeys?: ReadonlySet<string>, // extra keys to redact (lowercase)
+  maxDepth?: number                              // recursion limit, default 10
+)
+```
+
+**`LogSanitizer.parseSensitiveKeys(raw: unknown): ReadonlySet<string>`**
+
+Static helper that parses the `SENSITIVE_KEYS` runtime param into a `ReadonlySet<string>` suitable for the constructor. Accepts three input forms:
+
+| Input type | Example value | Result |
+|---|---|---|
+| Comma-separated string | `"x-merchant-token,internal_id"` | `Set { "x-merchant-token", "internal_id" }` |
+| Array | `["x-merchant-token", "INTERNAL_ID"]` | `Set { "x-merchant-token", "internal_id" }` |
+| Single string | `"x-merchant-token"` | `Set { "x-merchant-token" }` |
+| Anything else (incl. `undefined`) | — | `Set {}` (no-op) |
+
+All keys are lowercased; whitespace around commas and in array elements is trimmed; non-string array elements are silently dropped.
+
+**Automatic `SENSITIVE_KEYS` param support:**
+
+All action classes (`RuntimeAction`, `EventConsumerAction`, `OpenwhiskAction`) and `Telemetry.createLogger()` automatically call `parseSensitiveKeys(params.SENSITIVE_KEYS)` when initializing `LogSanitizer`. To extend sanitization with project-specific keys, add them to `app.config.yaml`:
+
+```yaml
+application:
+  actions:
+    my-action:
+      function: actions/my-action/index.js
+      inputs:
+        SENSITIVE_KEYS: "x-merchant-token,internal_order_id"
+```
+
+Or pass an array when testing:
+
+```typescript
+await myAction({ ...params, SENSITIVE_KEYS: ['x-merchant-token', 'internal_order_id'] });
+```
+
+**Usage:**
+
+```typescript
+const { LogSanitizer } = require('@adobe-commerce/aio-toolkit');
+
+const sanitizer = new LogSanitizer();
+
+// Sanitize HTTP headers before logging
+logger.debug({
+  message: 'Headers received',
+  headers: sanitizer.execute(params.__ow_headers || {}),
+});
+// authorization, x-api-key, cookie → "[REDACTED]"
+
+// Sanitize full action parameters (includes env-bound secrets)
+logger.debug({
+  message: 'Parameters received',
+  parameters: sanitizer.execute(params),
+});
+// MY_API_KEY, NEW_RELIC_LICENSE_KEY, GRAFANA_API_KEY → "[REDACTED]"
+
+// Extend with project-specific keys using parseSensitiveKeys
+const customSanitizer = new LogSanitizer(
+  LogSanitizer.parseSensitiveKeys(params.SENSITIVE_KEYS)
+);
+customSanitizer.execute(data);
+
+// Or construct a Set directly
+const fixedSanitizer = new LogSanitizer(new Set(['x-merchant-token', 'my_internal_secret']));
+fixedSanitizer.execute(data);
+```
+
+**Behaviour:**
+- Returns a deep copy — never mutates the input
+- Handles nested objects and arrays recursively (configurable depth limit)
+- Primitives (`string`, `number`, `boolean`, `null`, `undefined`) are returned as-is
+
+---
+
 #### `RuntimeApiGatewayService`
 Flexible Adobe I/O Runtime API Gateway client that accepts bearer tokens for authenticated requests.
 

package/dist/aio-toolkit-cli-workflow/bin/cli.js

@@ -216,7 +216,7 @@ var require_package = __commonJS({
   "package.json"(exports2, module2) {
     module2.exports = {
       name: "@adobe-commerce/aio-toolkit",
-      version: "1.2.6",
+      version: "1.2.7",
       description: "A comprehensive TypeScript toolkit for Adobe App Builder applications providing standardized Adobe Commerce integrations, I/O Events orchestration, file storage utilities, authentication helpers, and robust backend development tools with 100% test coverage.",
       main: "./dist/index.js",
       module: "./dist/index.mjs",