skuba 13.0.0-subpath-imports-20250730060533 → 13.0.0-subpath-imports-20251003052152

package/template/express-rest-api/.gantry/prod.yml

@@ -1,4 +1,8 @@
-environment: prod
+deployment: prod
+env: production
 
 maxInstanceCount: 10
 minInstanceCount: 3
+
+openTelemetry:
+  enabled: true

package/template/express-rest-api/Dockerfile

@@ -8,7 +8,7 @@ COPY . .
 
 RUN pnpm install --offline
 RUN pnpm build
-RUN pnpm install --offline --prod
+RUN CI=true pnpm install --offline --prod
 
 ###
 
@@ -28,4 +28,4 @@ ARG PORT=8001
 ENV PORT=${PORT}
 EXPOSE ${PORT}
 
-CMD ["lib/listen.js"]
+CMD ["--require", "./lib/tracing.js", "./lib/listen.js"]

package/template/express-rest-api/Dockerfile.dev-deps

@@ -1,5 +1,3 @@
-# syntax=docker/dockerfile:1.17
-
 FROM public.ecr.aws/docker/library/node:22-alpine AS dev-deps
 
 RUN --mount=type=bind,source=package.json,target=package.json \

package/template/express-rest-api/README.md

@@ -70,19 +70,19 @@ pnpm start:debug
 
 This project is deployed through a [Buildkite pipeline](.buildkite/pipeline.yml).
 
-- Commits to a feature branch can be deployed to the dev environment by unblocking a step in the Buildkite UI
-- Commits to the default branch are automatically deployed to the dev and prod environments in sequence
+- Commits to a feature branch can be deployed to the development environment by unblocking a step in the Buildkite UI
+- Commits to the default branch are automatically deployed to the development and production environments in sequence
 
 To rapidly roll back a change,
 retry an individual deployment step from the previous build in Buildkite.
-Note that this will introduce drift between the head of the default Git branch and the live environment;
+Note that this will introduce drift between the head of the default Git branch and the live deployments;
 use with caution and always follow up with a proper revert or fix in Git history.
 
 ## Support
 
 ### Dev
 
-TODO: add support links for the dev environment.
+TODO: add support links for the dev deployment.
 
 <!--
 - CloudWatch dashboard
@@ -92,7 +92,7 @@ TODO: add support links for the dev environment.
 
 ### Prod
 
-TODO: add support links for the prod environment.
+TODO: add support links for the prod deployment.
 
 <!--
 - CloudWatch dashboard

package/template/express-rest-api/gantry.apply.yml

@@ -9,9 +9,14 @@ owner: '{{values "owner"}}'
 image: '{{values "image"}}'
 
 env:
-  ENVIRONMENT: '{{values "environment"}}'
+  DEPLOYMENT: '{{values "deployment"}}'
   SERVICE: '{{values "service"}}'
 
+  DD_ENV: '{{values "env"}}'
+  DD_SERVICE: '{{values "service"}}'
+
+  OPENTELEMETRY_ENABLED: '{{values "openTelemetry.enabled"}}'
+
 {{if .Values.cloudwatchDashboardDisabled}}
 cloudwatchDashboardDisabled: {{values "cloudwatchDashboardDisabled"}}
 {{end}}
@@ -20,6 +25,17 @@ cloudwatchDashboardDisabled: {{values "cloudwatchDashboardDisabled"}}
 datadogSecretId: '{{values "datadogSecretId"}}'
 {{end}}
 
+# Uncomment if the `tin` tier is acceptable for your SEEK Auth Sidecar logs
+# The eeeoh log forwarder bypasses Amazon CloudWatch for cost savings
+# logSink:
+#   forwarder: eeeoh
+#   splunkIndex: '{{values "logSink.splunkIndex"}}'
+
+openTelemetry:
+  datadogEnvironmentName: '{{values "env"}}'
+  enabled: {{values "openTelemetry.enabled"}}
+  useGantryServiceName: true
+
 {{if .Values.pagerDutyEndpoint}}
 pagerDutyEndpoint: '{{values "pagerDutyEndpoint"}}'
 {{end}}

package/template/express-rest-api/package.json

@@ -19,22 +19,28 @@
     "test:watch": "skuba test --watch"
   },
   "dependencies": {
-    "@seek/logger": "^10.0.0",
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/core": "^2.0.0",
+    "@opentelemetry/exporter-trace-otlp-grpc": "^0.205.0",
+    "@opentelemetry/instrumentation-aws-sdk": "^0.60.0",
+    "@opentelemetry/instrumentation-http": "^0.205.0",
+    "@opentelemetry/propagator-b3": "^2.0.0",
+    "@opentelemetry/sdk-node": "^0.205.0",
+    "@seek/logger": "^11.1.0",
     "express": "^5.0.0",
-    "hot-shots": "^10.0.0",
-    "seek-datadog-custom-metrics": "^4.6.3",
+    "hot-shots": "^11.0.0",
+    "seek-datadog-custom-metrics": "^6.0.0",
     "skuba-dive": "^2.0.0"
   },
   "devDependencies": {
     "@types/express": "^5.0.0",
     "@types/node": "^22.13.10",
     "@types/supertest": "^6.0.0",
-    "mime": "^4.0.1",
     "pino-pretty": "^13.0.0",
     "skuba": "*",
     "supertest": "^7.0.0"
   },
-  "packageManager": "pnpm@10.12.4",
+  "packageManager": "pnpm@10.17.1",
   "engines": {
     "node": ">=22"
   }

package/template/express-rest-api/src/api/healthCheck.ts

@@ -3,8 +3,8 @@ import type { Handler } from 'express';
 /**
  * Signifies that the API is available to serve requests.
  *
- * The deployment environment calls this endpoint to see if the container is
- * unhealthy and needs to be recycled.
+ * The workload hosting environment calls this endpoint to see if the container
+ * is unhealthy and needs to be recycled.
  */
 export const healthCheckHandler: Handler = (_req, res) => {
   res.send('');

package/template/express-rest-api/src/config.ts

@@ -1,7 +1,7 @@
 import { Env } from 'skuba-dive';
 
 interface Config {
-  environment: Environment;
+  deployment: Deployment;
 
   logLevel: string;
   name: string;
@@ -11,17 +11,17 @@ interface Config {
   port: number | null;
 }
 
-type Environment = (typeof environments)[number];
+type Deployment = (typeof deployments)[number];
 
 const dev = '<%- devGantryEnvironmentName %>';
 const prod = '<%- prodGantryEnvironmentName %>';
 
-const environments = ['local', 'test', dev, prod] as const;
+const deployments = ['local', 'test', dev, prod] as const;
 
-const environment = Env.oneOf(environments)('ENVIRONMENT');
+const deployment = Env.oneOf(deployments)('DEPLOYMENT');
 
 /* istanbul ignore next: config verification makes more sense in a smoke test */
-const configs: Record<Environment, () => Omit<Config, 'environment'>> = {
+const configs: Record<Deployment, () => Omit<Config, 'deployment'>> = {
   local: () => ({
     logLevel: 'debug',
     name: '<%- serviceName %>',
@@ -60,6 +60,6 @@ const configs: Record<Environment, () => Omit<Config, 'environment'>> = {
 };
 
 export const config: Config = {
-  ...configs[environment](),
-  environment,
+  ...configs[deployment](),
+  deployment,
 };

package/template/express-rest-api/src/framework/logging.ts

@@ -1,17 +1,21 @@
-import createLogger from '@seek/logger';
+import { createLogger } from '@seek/logger';
 
 import { config } from '#src/config.js';
 
 export const logger = createLogger({
-  base: {
-    environment: config.environment,
-    version: config.version,
+  eeeoh: {
+    /**
+     * TODO: choose an appropriate Datadog log tier.
+     *
+     * https://github.com/seek-oss/logger/blob/master/docs/eeeoh.md#datadog-log-tiers
+     */
+    datadog: 'tin',
+    team: '<%- teamName %>',
+    use: 'environment',
   },
 
   level: config.logLevel,
 
-  name: config.name,
-
   transport:
-    config.environment === 'local' ? { target: 'pino-pretty' } : undefined,
+    config.deployment === 'local' ? { target: 'pino-pretty' } : undefined,
 });

package/template/express-rest-api/src/framework/metrics.ts

@@ -7,5 +7,5 @@ import { config } from '#src/config.js';
 
 /* istanbul ignore next: StatsD client is not our responsibility */
 export const metricsClient = createStatsDClient(StatsD, config, (err) =>
-  logger.error({ err }, 'StatsD error'),
+  logger.error(err, 'StatsD error'),
 );

package/template/express-rest-api/src/listen.ts

@@ -19,3 +19,9 @@ const listener = app.listen(config.port, () => {
 // https://docs.aws.amazon.com/elasticloadbalancing/latest/application/application-load-balancers.html#connection-idle-timeout
 // AWS recommends setting an application timeout larger than the load balancer
 listener.keepAliveTimeout = 31000;
+
+// Report unhandled rejections instead of crashing the process
+// Make sure to monitor these reports and alert as appropriate
+process.on('unhandledRejection', (err) =>
+  logger.error(err, 'Unhandled promise rejection'),
+);

package/template/express-rest-api/src/tracing.ts

@@ -0,0 +1,56 @@
+/**
+ * OpenTelemetry tracing initialisation. This is a standalone TS/JS module that is not
+ * referenced by application source code directly. It is required at runtime using the
+ * node command's `--require` argument, see Dockerfile for details.
+ */
+
+import { propagation } from '@opentelemetry/api';
+import { CompositePropagator } from '@opentelemetry/core';
+import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-grpc';
+import { AwsInstrumentation } from '@opentelemetry/instrumentation-aws-sdk';
+import { HttpInstrumentation } from '@opentelemetry/instrumentation-http';
+import { B3InjectEncoding, B3Propagator } from '@opentelemetry/propagator-b3';
+import { NodeSDK } from '@opentelemetry/sdk-node';
+
+const app = 'opentelemetry';
+const log = (level: string, msg: string, extra = {}) => {
+  const toLog = { msg, level, app, time: new Date().toISOString(), ...extra };
+  console.log(JSON.stringify(toLog)); // eslint-disable-line no-console
+};
+
+const main = () => {
+  // Use B3 propagation to ensure proper propagation between systems that use
+  // OpenTelemetry and native Datadog APM, such as Istio/Envoy.
+  propagation.setGlobalPropagator(
+    new CompositePropagator({
+      propagators: [
+        new B3Propagator(),
+        new B3Propagator({ injectEncoding: B3InjectEncoding.MULTI_HEADER }),
+      ],
+    }),
+  );
+
+  const sdk = new NodeSDK({
+    traceExporter: new OTLPTraceExporter(),
+    autoDetectResources: false,
+    instrumentations: [new HttpInstrumentation(), new AwsInstrumentation()],
+  });
+
+  sdk.start();
+
+  process.on('SIGTERM', () => {
+    sdk
+      .shutdown()
+      .then(() => log('info', 'OpenTelemetry successfully terminated'))
+      .catch((err: Error) =>
+        log('error', 'OpenTelemetry failed to terminate', { err }),
+      )
+      .finally(() => process.exit(0)); // eslint-disable-line no-process-exit
+  });
+};
+
+if (process.env.OPENTELEMETRY_ENABLED === 'true') {
+  main();
+} else {
+  log('info', 'OpenTelemetry not enabled');
+}

package/template/greeter/Dockerfile

@@ -1,5 +1,3 @@
-# syntax=docker/dockerfile:1.17
-
 FROM public.ecr.aws/docker/library/node:22-alpine AS dev-deps
 
 RUN --mount=type=bind,source=package.json,target=package.json \

package/template/greeter/README.md

@@ -75,7 +75,7 @@ For inspiration in this space, check out:
 
 ### Dev
 
-TODO: add support links for the dev environment.
+TODO: add support links for the dev deployment.
 
 <!--
 - CloudWatch dashboard
@@ -85,7 +85,7 @@ TODO: add support links for the dev environment.
 
 ### Prod
 
-TODO: add support links for the prod environment.
+TODO: add support links for the prod deployment.
 
 <!--
 - CloudWatch dashboard

package/template/greeter/package.json

@@ -23,9 +23,9 @@
   },
   "devDependencies": {
     "@types/node": "^22.13.10",
-    "skuba": "13.0.0-subpath-imports-20250730060533"
+    "skuba": "13.0.0-subpath-imports-20251003052152"
   },
-  "packageManager": "pnpm@10.12.4",
+  "packageManager": "pnpm@10.17.1",
   "engines": {
     "node": ">=22"
   }

package/template/koa-rest-api/.buildkite/pipeline.yml

@@ -77,6 +77,9 @@ steps:
       queue: <%- devBuildkiteQueueName %>
     label: 🤞 Deploy Dev
     concurrency_group: <%- teamName %>/deploy/gantry/<%- devGantryEnvironmentName %>
+    env:
+      DD_DEPLOYMENT_ENVIRONMENT: development
+      DD_DEPLOYMENT_SERVICE: <%- serviceName %>
     key: deploy-dev
     plugins:
       - seek-jobs/gantry#v4.0.0:
@@ -93,6 +96,9 @@ steps:
     branches: ${BUILDKITE_PIPELINE_DEFAULT_BRANCH}
     concurrency_group: <%- teamName %>/deploy/gantry/<%- prodGantryEnvironmentName %>
     depends_on: deploy-dev
+    env:
+      DD_DEPLOYMENT_ENVIRONMENT: production
+      DD_DEPLOYMENT_SERVICE: <%- serviceName %>
     plugins:
       - seek-jobs/gantry#v4.0.0:
           command: apply

package/template/koa-rest-api/.env

@@ -1 +1 @@
-ENVIRONMENT=local
+DEPLOYMENT=local

package/template/koa-rest-api/.gantry/dev.yml

@@ -1,4 +1,5 @@
-environment: dev
+deployment: dev
+env: development
 
 maxInstanceCount: 1
 minInstanceCount: 1
@@ -7,5 +8,4 @@ minInstanceCount: 1
 cloudwatchDashboardDisabled: true
 
 openTelemetry:
-  datadogEnvironmentName: development
-  enabled: false
+  enabled: true

package/template/koa-rest-api/.gantry/prod.yml

@@ -1,8 +1,8 @@
-environment: prod
+deployment: prod
+env: production
 
 maxInstanceCount: 10
 minInstanceCount: 3
 
 openTelemetry:
-  datadogEnvironmentName: production
-  enabled: false
+  enabled: true

package/template/koa-rest-api/Dockerfile

@@ -8,7 +8,7 @@ COPY . .
 
 RUN pnpm install --offline
 RUN pnpm build
-RUN pnpm install --offline --prod
+RUN CI=true pnpm install --offline --prod
 
 ###
 

package/template/koa-rest-api/Dockerfile.dev-deps

@@ -1,5 +1,3 @@
-# syntax=docker/dockerfile:1.17
-
 FROM public.ecr.aws/docker/library/node:22-alpine AS dev-deps
 
 RUN --mount=type=bind,source=package.json,target=package.json \

package/template/koa-rest-api/README.md

@@ -29,7 +29,7 @@ It uses the [Koa] middleware framework and common SEEK packages.
 Resource APIs enable synchronous interactions and serve as the backbone of SEEK's general service architecture.
 
 The `koa-rest-api` template is modelled after a hypothetical service for posting and retrieving job advertisements.
-It's stubbed out with in-memory [storage](src/storage) which can observed by standing up an environment with multiple instances.
+It's stubbed out with in-memory [storage](src/storage) which can observed by standing up a deployment with multiple instances.
 Storage is local to each instance, so load balancing across the instances may render a read inconsistent with a previous write.
 This would be replaced with an external data store in production.
 
@@ -75,19 +75,19 @@ pnpm start:debug
 
 This project is deployed through a [Buildkite pipeline](.buildkite/pipeline.yml).
 
-- Commits to a feature branch can be deployed to the dev environment by unblocking a step in the Buildkite UI
-- Commits to the default branch are automatically deployed to the dev and prod environments in sequence
+- Commits to a feature branch can be deployed to the development environment by unblocking a step in the Buildkite UI
+- Commits to the default branch are automatically deployed to the development and production environments in sequence
 
 To rapidly roll back a change,
 retry an individual deployment step from the previous build in Buildkite.
-Note that this will introduce drift between the head of the default Git branch and the live environment;
+Note that this will introduce drift between the head of the default Git branch and the live deployment;
 use with caution and always follow up with a proper revert or fix in Git history.
 
 ## Support
 
 ### Dev
 
-TODO: add support links for the dev environment.
+TODO: add support links for the dev deployment.
 
 <!--
 - CloudWatch dashboard
@@ -97,7 +97,7 @@ TODO: add support links for the dev environment.
 
 ### Prod
 
-TODO: add support links for the prod environment.
+TODO: add support links for the prod deployment.
 
 <!--
 - CloudWatch dashboard

package/template/koa-rest-api/gantry.apply.yml

@@ -9,10 +9,14 @@ owner: '{{values "owner"}}'
 image: '{{values "image"}}'
 
 env:
-  ENVIRONMENT: '{{values "environment"}}'
-  OPENTELEMETRY_ENABLED: '{{.Values.openTelemetry.enabled | default false}}'
+  DEPLOYMENT: '{{values "deployment"}}'
   SERVICE: '{{values "service"}}'
 
+  DD_ENV: '{{values "env"}}'
+  DD_SERVICE: '{{values "service"}}'
+
+  OPENTELEMETRY_ENABLED: '{{values "openTelemetry.enabled"}}'
+
 {{if .Values.cloudwatchDashboardDisabled}}
 cloudwatchDashboardDisabled: {{values "cloudwatchDashboardDisabled"}}
 {{end}}
@@ -21,9 +25,17 @@ cloudwatchDashboardDisabled: {{values "cloudwatchDashboardDisabled"}}
 datadogSecretId: '{{values "datadogSecretId"}}'
 {{end}}
 
+# Uncomment if the `tin` tier is acceptable for your SEEK Auth Sidecar logs
+# The eeeoh log forwarder bypasses Amazon CloudWatch for cost savings
+# logSink:
+#   forwarder: eeeoh
+#   splunkIndex: '{{values "logSink.splunkIndex"}}'
+
 openTelemetry:
-  datadogEnvironmentName: '{{values "openTelemetry.datadogEnvironmentName"}}'
+  datadogEnvironmentName: '{{values "env"}}'
   enabled: {{values "openTelemetry.enabled"}}
+  useGantryServiceName: true
+
 {{if .Values.pagerDutyEndpoint}}
 pagerDutyEndpoint: '{{values "pagerDutyEndpoint"}}'
 {{end}}

package/template/koa-rest-api/package.json

@@ -20,22 +20,22 @@
   },
   "dependencies": {
     "@koa/bodyparser": "^6.0.0",
-    "@koa/router": "^13.0.0",
+    "@koa/router": "^14.0.0",
     "@opentelemetry/api": "^1.9.0",
     "@opentelemetry/core": "^2.0.0",
-    "@opentelemetry/exporter-trace-otlp-grpc": "^0.203.0",
-    "@opentelemetry/instrumentation-aws-sdk": "^0.56.0",
-    "@opentelemetry/instrumentation-http": "^0.203.0",
+    "@opentelemetry/exporter-trace-otlp-grpc": "^0.205.0",
+    "@opentelemetry/instrumentation-aws-sdk": "^0.60.0",
+    "@opentelemetry/instrumentation-http": "^0.205.0",
     "@opentelemetry/propagator-b3": "^2.0.0",
-    "@opentelemetry/sdk-node": "^0.203.0",
-    "@seek/logger": "^10.0.0",
-    "hot-shots": "^10.0.0",
+    "@opentelemetry/sdk-node": "^0.205.0",
+    "@seek/logger": "^11.1.0",
+    "hot-shots": "^11.0.0",
     "koa": "^3.0.1",
     "koa-compose": "^4.1.0",
-    "seek-datadog-custom-metrics": "^4.6.3",
+    "seek-datadog-custom-metrics": "^6.0.0",
     "seek-koala": "^7.1.0",
     "skuba-dive": "^2.0.0",
-    "zod": "^3.25.67"
+    "zod": "^4.0.0"
   },
   "devDependencies": {
     "@types/chance": "^1.1.3",
@@ -45,12 +45,11 @@
     "@types/node": "^22.13.10",
     "@types/supertest": "^6.0.0",
     "chance": "^1.1.8",
-    "mime": "^4.0.1",
     "pino-pretty": "^13.0.0",
     "skuba": "*",
     "supertest": "^7.0.0"
   },
-  "packageManager": "pnpm@10.12.4",
+  "packageManager": "pnpm@10.17.1",
   "engines": {
     "node": ">=22"
   }

package/template/koa-rest-api/src/api/healthCheck.ts

@@ -3,8 +3,8 @@ import type { Middleware } from '#src/types/koa.js';
 /**
  * Signifies that the API is available to serve requests.
  *
- * The deployment environment calls this endpoint to see if the container is
- * unhealthy and needs to be recycled.
+ * The workload hosting environment calls this endpoint to see if the container
+ * is unhealthy and needs to be recycled.
  */
 export const healthCheckHandler: Middleware = (ctx) => {
   ctx.state.skipRequestLogging = true;

package/template/koa-rest-api/src/config.ts

@@ -1,7 +1,7 @@
 import { Env } from 'skuba-dive';
 
 interface Config {
-  environment: Environment;
+  deployment: Deployment;
 
   logLevel: string;
   name: string;
@@ -11,17 +11,17 @@ interface Config {
   port: number | null;
 }
 
-type Environment = (typeof environments)[number];
+type Deployment = (typeof deployments)[number];
 
 const dev = '<%- devGantryEnvironmentName %>';
 const prod = '<%- prodGantryEnvironmentName %>';
 
-const environments = ['local', 'test', dev, prod] as const;
+const deployments = ['local', 'test', dev, prod] as const;
 
-const environment = Env.oneOf(environments)('ENVIRONMENT');
+const deployment = Env.oneOf(deployments)('DEPLOYMENT');
 
 /* istanbul ignore next: config verification makes more sense in a smoke test */
-const configs: Record<Environment, () => Omit<Config, 'environment'>> = {
+const configs: Record<Deployment, () => Omit<Config, 'deployment'>> = {
   local: () => ({
     logLevel: 'debug',
     name: '<%- serviceName %>',
@@ -62,6 +62,6 @@ const configs: Record<Environment, () => Omit<Config, 'environment'>> = {
 };
 
 export const config: Config = {
-  ...configs[environment](),
-  environment,
+  ...configs[deployment](),
+  deployment,
 };

package/template/koa-rest-api/src/framework/logging.ts

@@ -1,4 +1,4 @@
-import createLogger, { createDestination } from '@seek/logger';
+import { createDestination, createLogger } from '@seek/logger';
 import { RequestLogging } from 'seek-koala';
 
 import { config } from '#src/config.js';
@@ -9,26 +9,30 @@ const { createContextMiddleware, mixin } =
 export const contextMiddleware = createContextMiddleware();
 
 const { destination, stdoutMock } = createDestination({
-  mock: config.environment === 'test',
+  mock: config.deployment === 'test',
 });
 
 export { stdoutMock };
 
 export const logger = createLogger(
   {
-    base: {
-      environment: config.environment,
-      version: config.version,
+    eeeoh: {
+      /**
+       * TODO: choose an appropriate Datadog log tier.
+       *
+       * https://github.com/seek-oss/logger/blob/master/docs/eeeoh.md#datadog-log-tiers
+       */
+      datadog: 'tin',
+      team: '<%- teamName %>',
+      use: 'environment',
     },
 
     mixin,
 
     level: config.logLevel,
 
-    name: config.name,
-
     transport:
-      config.environment === 'local' ? { target: 'pino-pretty' } : undefined,
+      config.deployment === 'local' ? { target: 'pino-pretty' } : undefined,
   },
   destination,
 );

package/template/koa-rest-api/src/framework/metrics.ts

@@ -7,5 +7,5 @@ import { config } from '#src/config.js';
 
 /* istanbul ignore next: StatsD client is not our responsibility */
 export const metricsClient = createStatsDClient(StatsD, config, (err) =>
-  logger.error({ err }, 'StatsD error'),
+  logger.error(err, 'StatsD error'),
 );