@dash0/serverless-dash0 1.0.0

package/README.md

@@ -0,0 +1,84 @@
+# serverless-dash0
+
+Serverless Framework plugin that automatically adds the [Dash0](https://www.dash0.com) Lambda extension layer and environment variables to your functions.
+
+Compatible with Serverless Framework v3 and v4.
+
+## Installation
+
+```bash
+npm install --save-dev serverless-dash0
+```
+
+## Usage
+
+Add the plugin to your `serverless.yml` and configure the `custom.dash0` section:
+
+```yaml
+plugins:
+  - serverless-dash0
+
+custom:
+  dash0:
+    endpoint: https://ingress.eu-west-1.aws.dash0.com:4318
+    token: ${env:DASH0_TOKEN}
+    layerVersion: latest
+
+functions:
+  myFunction:
+    handler: handler.hello
+    runtime: nodejs20.x
+    dash0-traced: true
+
+  untracedFunction:
+    handler: handler.other
+    runtime: nodejs20.x
+```
+
+Only functions with `dash0-traced: true` will have the Dash0 layer and environment variables added. All other functions are left untouched.
+
+### Supported runtimes
+
+| Runtime         | Layer                    |
+| --------------- | ------------------------ |
+| `nodejs*`       | `dash0-extension-node`   |
+| `python*`       | `dash0-extension-python` |
+| `java*`         | `dash0-extension-java`   |
+
+Container image functions (`image` instead of `handler`) are not supported. Use the [Dash0 Docker images](https://github.com/dash0hq/dash0-lambda-extension#docker) instead.
+
+## Configuration reference
+
+All options are set under `custom.dash0` in your `serverless.yml`.
+
+### Required
+
+| Option | Type | Description |
+| --- | --- | --- |
+| `endpoint` | `string` | Dash0 OTLP ingestion endpoint. |
+| `layerVersion` | `number` or `"latest"` | Layer version to use. A specific version number, or `"latest"` to use the version bundled with the plugin. |
+| `token` | `string` | Dash0 API token. Required unless `tokenSecretArn` is provided. |
+| `tokenSecretArn` | `string` | ARN of an AWS Secrets Manager secret containing the Dash0 API token. Required unless `token` is provided. If both are set, both environment variables will be added. |
+
+### Optional
+
+| Option | Type | Default | Env var set | Description |
+| --- | --- | --- | --- | --- |
+| `tokenSecretKey` | `string` | - | `DASH0_TOKEN_SECRET_KEY` | JSON key to extract the token from the secret (when the secret value is a JSON object). |
+| `dataset` | `string` | - | `DASH0_DATASET` | Route telemetry to a specific Dash0 dataset. |
+| `extensionLogLevel` | `string` | `warn` | `DASH0_EXTENSION_LOG_LEVEL` | Log level for the extension. One of: `trace`, `debug`, `info`, `warn`, `error`. |
+| `disableAutoInstrumentation` | `boolean` | `false` | `DASH0_DISABLE_AUTO_INSTRUMENTATION` | Disable auto-instrumentation. The extension will still create synthetic spans. |
+| `sendOnInvocationEnd` | `boolean` | `true` | `DASH0_SEND_ON_INVOCATION_END` | Send telemetry at the end of the current invocation instead of the beginning of the next. |
+| `disableTelemetryLogCollection` | `boolean` | `false` | `DASH0_DISABLE_TELEMETRY_LOG_COLLECTION` | Disable Lambda Telemetry API log collection. |
+| `createPayloadLogRecords` | `boolean` | `true` | `DASH0_CREATE_PAYLOAD_LOG_RECORDS` | Create log records for request/response payloads. |
+| `requestTimeout` | `number` | `2000` | `DASH0_REQUEST_TIMEOUT` | HTTP request timeout in milliseconds. |
+| `xrayTracesEnabled` | `boolean` | `false` | `DASH0_XRAY_TRACES_ENABLED` | Preserve X-Ray trace context. |
+| `maskRules` | `string` | - | `DASH0_MASK_RULES` | JSON array of regex patterns for masking sensitive data. |
+| `maskEnvVars` | `string` | - | `DASH0_MASK_ENV_VARS` | JSON array of regex patterns for masking environment variable values. |
+
+### Behavior
+
+- The plugin runs at the `before:package:initialize` lifecycle hook.
+- Existing function layers are preserved; the Dash0 layer is appended.
+- Existing function environment variables are never overwritten. If you set `DASH0_EXTENSION_LOG_LEVEL` on a specific function, the plugin will not replace it with the global value.
+- Functions with unsupported runtimes or container images are skipped with a warning.

package/dist/config-validator.d.ts

@@ -0,0 +1,20 @@
+export interface Dash0Config {
+    endpoint: string;
+    layerVersion: number | 'latest';
+    layerAccountId?: string;
+    layerNamePrefix?: string;
+    token?: string;
+    tokenSecretArn?: string;
+    tokenSecretKey?: string;
+    dataset?: string;
+    extensionLogLevel?: string;
+    disableAutoInstrumentation?: boolean | string;
+    sendOnInvocationEnd?: boolean | string;
+    disableTelemetryLogCollection?: boolean | string;
+    createPayloadLogRecords?: boolean | string;
+    requestTimeout?: number;
+    xrayTracesEnabled?: boolean | string;
+    maskRules?: string;
+    maskEnvVars?: string;
+}
+export declare function validateConfig(config: unknown): Dash0Config;

package/dist/config-validator.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateConfig = validateConfig;
+const VALID_LOG_LEVELS = ['trace', 'debug', 'info', 'warn', 'error'];
+function validateConfig(config) {
+    if (!config || typeof config !== 'object') {
+        throw new Error('[serverless-dash0] Missing "custom.dash0" configuration block');
+    }
+    const c = config;
+    if (!c.endpoint || typeof c.endpoint !== 'string') {
+        throw new Error('[serverless-dash0] "custom.dash0.endpoint" is required and must be a string');
+    }
+    if (c.layerVersion === undefined || c.layerVersion === null) {
+        throw new Error('[serverless-dash0] "custom.dash0.layerVersion" is required (positive integer or "latest")');
+    }
+    if (c.layerVersion !== 'latest') {
+        const parsed = Number(c.layerVersion);
+        if (!Number.isInteger(parsed) || parsed < 1) {
+            throw new Error('[serverless-dash0] "custom.dash0.layerVersion" must be a positive integer or "latest"');
+        }
+        c.layerVersion = parsed;
+    }
+    if (c.layerAccountId !== undefined) {
+        c.layerAccountId = String(c.layerAccountId);
+    }
+    if (!c.token && !c.tokenSecretArn) {
+        throw new Error('[serverless-dash0] Either "custom.dash0.token" or "custom.dash0.tokenSecretArn" must be provided');
+    }
+    if (c.extensionLogLevel !== undefined) {
+        if (!VALID_LOG_LEVELS.includes(c.extensionLogLevel)) {
+            throw new Error(`[serverless-dash0] "custom.dash0.extensionLogLevel" must be one of: ${VALID_LOG_LEVELS.join(', ')}`);
+        }
+    }
+    return c;
+}

package/dist/env-injector.d.ts

@@ -0,0 +1,2 @@
+import { Dash0Config } from './config-validator';
+export declare function buildEnvironment(config: Dash0Config): Record<string, string>;

package/dist/env-injector.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildEnvironment = buildEnvironment;
+const OPTIONAL_MAPPINGS = {
+    dataset: 'DASH0_DATASET',
+    extensionLogLevel: 'DASH0_EXTENSION_LOG_LEVEL',
+    disableAutoInstrumentation: 'DASH0_DISABLE_AUTO_INSTRUMENTATION',
+    sendOnInvocationEnd: 'DASH0_SEND_ON_INVOCATION_END',
+    disableTelemetryLogCollection: 'DASH0_DISABLE_TELEMETRY_LOG_COLLECTION',
+    createPayloadLogRecords: 'DASH0_CREATE_PAYLOAD_LOG_RECORDS',
+    requestTimeout: 'DASH0_REQUEST_TIMEOUT',
+    xrayTracesEnabled: 'DASH0_XRAY_TRACES_ENABLED',
+    maskRules: 'DASH0_MASK_RULES',
+    maskEnvVars: 'DASH0_MASK_ENV_VARS',
+};
+function buildEnvironment(config) {
+    const env = {};
+    env.AWS_LAMBDA_EXEC_WRAPPER = '/opt/wrapper';
+    env.DASH0_ENDPOINT = config.endpoint;
+    if (config.token) {
+        env.DASH0_TOKEN = config.token;
+    }
+    if (config.tokenSecretArn) {
+        env.DASH0_TOKEN_SECRET_ARN = config.tokenSecretArn;
+    }
+    if (config.tokenSecretKey) {
+        env.DASH0_TOKEN_SECRET_KEY = config.tokenSecretKey;
+    }
+    for (const [configKey, envVar] of Object.entries(OPTIONAL_MAPPINGS)) {
+        const value = config[configKey];
+        if (value !== undefined && value !== null) {
+            env[envVar] = String(value);
+        }
+    }
+    return env;
+}

package/dist/index.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/index.js

@@ -0,0 +1,107 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+const config_validator_1 = require("./config-validator");
+const runtime_mapping_1 = require("./runtime-mapping");
+const layer_arn_builder_1 = require("./layer-arn-builder");
+const env_injector_1 = require("./env-injector");
+const bundledVersions = __importStar(require("./versions.json"));
+class ServerlessDash0Plugin {
+    constructor(serverless, options, utils) {
+        this.serverless = serverless;
+        this.options = options;
+        this.log = utils?.log
+            ? (msg) => utils.log.notice(msg)
+            : (msg) => serverless.cli.log(msg);
+        this.warn = utils?.log
+            ? (msg) => utils.log.warning(msg)
+            : (msg) => serverless.cli.log(`WARNING: ${msg}`);
+        this.hooks = {
+            'before:package:initialize': () => this.addDash0Tracing(),
+        };
+    }
+    getBundledVersion(layerName) {
+        const version = bundledVersions[layerName];
+        if (!version) {
+            throw new Error(`[serverless-dash0] No bundled version found for layer "${layerName}". Please specify an explicit layerVersion.`);
+        }
+        return version;
+    }
+    addDash0Tracing() {
+        const dash0Config = (0, config_validator_1.validateConfig)(this.serverless.service.custom?.dash0);
+        const region = this.options.region ||
+            this.serverless.service.provider.region ||
+            process.env.AWS_REGION ||
+            process.env.AWS_DEFAULT_REGION ||
+            'us-east-1';
+        const dash0Env = (0, env_injector_1.buildEnvironment)(dash0Config);
+        const functions = this.serverless.service.functions;
+        const useLatest = dash0Config.layerVersion === 'latest';
+        for (const [funcName, funcDef] of Object.entries(functions)) {
+            const traced = funcDef['dash0-traced'];
+            if (traced !== true && traced !== 'true') {
+                continue;
+            }
+            if (funcDef.image) {
+                this.warn(`[serverless-dash0] Skipping function "${funcName}": container image functions cannot use Lambda layers. Use the Dash0 Docker image instead.`);
+                continue;
+            }
+            const runtime = funcDef.runtime || this.serverless.service.provider.runtime;
+            const layerName = (0, runtime_mapping_1.resolveLayerName)(runtime);
+            if (!layerName) {
+                this.warn(`[serverless-dash0] Skipping function "${funcName}": unsupported runtime "${runtime ?? 'undefined'}". Supported: nodejs*, python*, java*.`);
+                continue;
+            }
+            const layerVersion = useLatest
+                ? this.getBundledVersion(layerName)
+                : dash0Config.layerVersion;
+            const layerArn = (0, layer_arn_builder_1.buildLayerArn)(region, layerName, layerVersion, dash0Config.layerAccountId, dash0Config.layerNamePrefix);
+            // Append layer (no duplicates)
+            funcDef.layers = funcDef.layers || [];
+            if (!funcDef.layers.includes(layerArn)) {
+                funcDef.layers.push(layerArn);
+            }
+            // Merge env vars (never overwrite existing)
+            funcDef.environment = funcDef.environment || {};
+            for (const [key, value] of Object.entries(dash0Env)) {
+                if (funcDef.environment[key] === undefined) {
+                    funcDef.environment[key] = value;
+                }
+            }
+            this.log(`[serverless-dash0] Configured tracing for function "${funcName}" (${runtime}, layer v${layerVersion})`);
+        }
+    }
+}
+module.exports = ServerlessDash0Plugin;

package/dist/layer-arn-builder.d.ts

@@ -0,0 +1,2 @@
+export declare const DEFAULT_LAYER_ACCOUNT_ID = "115813213817";
+export declare function buildLayerArn(region: string, layerName: string, layerVersion: number, accountId?: string, layerNamePrefix?: string): string;

package/dist/layer-arn-builder.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_LAYER_ACCOUNT_ID = void 0;
+exports.buildLayerArn = buildLayerArn;
+exports.DEFAULT_LAYER_ACCOUNT_ID = '115813213817';
+function buildLayerArn(region, layerName, layerVersion, accountId, layerNamePrefix) {
+    const account = accountId || exports.DEFAULT_LAYER_ACCOUNT_ID;
+    const prefixedName = layerNamePrefix ? `${layerNamePrefix}${layerName}` : layerName;
+    return `arn:aws:lambda:${region}:${account}:layer:${prefixedName}:${layerVersion}`;
+}

package/dist/runtime-mapping.d.ts

@@ -0,0 +1 @@
+export declare function resolveLayerName(runtime: string | undefined): string | null;

package/dist/runtime-mapping.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveLayerName = resolveLayerName;
+const RUNTIME_MAP = {
+    node: 'dash0-extension-node',
+    python: 'dash0-extension-python',
+    java: 'dash0-extension-java',
+};
+function resolveLayerName(runtime) {
+    if (!runtime || typeof runtime !== 'string') {
+        return null;
+    }
+    const normalized = runtime.toLowerCase();
+    for (const [prefix, layerName] of Object.entries(RUNTIME_MAP)) {
+        if (normalized.startsWith(prefix)) {
+            return layerName;
+        }
+    }
+    return null;
+}

package/dist/versions.json

@@ -0,0 +1,5 @@
+{
+    "dash0-extension-node": 5,
+    "dash0-extension-python": 5,
+    "dash0-extension-java": 5
+}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@dash0/serverless-dash0",
+  "version": "1.0.0",
+  "description": "Serverless Framework plugin to automatically add Dash0 Lambda tracing layers and configuration",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "test": "jest",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "serverless",
+    "serverless-plugin",
+    "dash0",
+    "lambda",
+    "tracing",
+    "opentelemetry",
+    "observability"
+  ],
+  "author": "Dash0",
+  "license": "Apache-2.0",
+  "devDependencies": {
+    "@types/jest": "^29.5.14",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.3.2",
+    "typescript": "^5.8.3"
+  },
+  "peerDependencies": {
+    "serverless": ">=3.0.0"
+  },
+  "peerDependenciesMeta": {
+    "serverless": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=16.0.0"
+  },
+  "files": ["dist/", "README.md"]
+}