@forestadmin/agent-bff 1.32.0 → 1.33.0

package/README.md

@@ -36,6 +36,112 @@ dropped collection reachable.
 Two ways to run it: embedded in a Forest agent (`agent.addBff()`, see
 [Embedded in an agent](#embedded-in-an-agent)) or standalone, described here.
 
+### Docker (recommended)
+
+```bash
+cp .env.example .env   # then fill in the secrets
+docker compose up
+```
+
+The template targets a local, non-containerised run, so one value has to change for Docker:
+set `AGENT_URL=http://host.docker.internal:3351`. Left at `localhost`, it resolves to the BFF
+container itself and every agent call fails (see the note below).
+
+The `docker-compose.yml` at the root of this package starts a single BFF instance. See
+`.env.example` for the full list of environment variables and their descriptions.
+
+Or run the image directly:
+
+```bash
+docker run -d \
+  -p 3450:3450 \
+  --stop-timeout 15 \
+  --add-host host.docker.internal:host-gateway \
+  -e FOREST_AUTH_SECRET="..." \
+  -e FOREST_ENV_SECRET="..." \
+  -e FOREST_SERVER_URL="https://api.forestadmin.com" \
+  -e FOREST_APP_URL="https://app.forestadmin.com" \
+  -e AGENT_URL="http://host.docker.internal:3351" \
+  -e BFF_TOKEN_ENCRYPTION_KEY="$(openssl rand -base64 32)" \
+  ghcr.io/forestadmin/agent-bff:latest
+```
+
+> **Note:** When the BFF runs in Docker and your agent runs on the host machine, use
+> `host.docker.internal` instead of `localhost` in `AGENT_URL`. Docker Desktop resolves that
+> name natively; on Docker Engine for Linux it does not exist unless you map it, hence the
+> `--add-host` above (the Compose setup does the same through `extra_hosts`).
+
+The image's entry point is the CLI, so the subcommands below work the same way:
+
+```bash
+docker run --rm ghcr.io/forestadmin/agent-bff:latest openapi > openapi.json
+```
+
+Tags follow the npm package: `:latest`, `:1`, `:1.20` and the immutable `:1.20.2`.
+
+The package is public, so none of the commands above need a login. That visibility is set once,
+by hand, on the GHCR package: a package GHCR creates on its first push is private, and the
+workflow's `GITHUB_TOKEN` can push to it but not change what it is. Until someone flips it (the
+same step `workflow-executor` went through), pulls need
+`docker login ghcr.io -u <user> -p <token-with-read:packages>`.
+
+On `SIGTERM` or `SIGINT` the BFF stops accepting connections and gives the requests already in
+flight 10 seconds to finish before cutting their sockets, then exits 0. A second signal gives up on
+the wait and exits 1.
+
+Allow for that in your orchestrator's grace period. The whole budget is up to 11 seconds — the 10
+second deadline plus a 1 second fallback for the exit itself — and `docker stop` defaults to 10,
+so under load it would SIGKILL exactly when the shutdown is doing its job. Hence `--stop-timeout 15`
+above and `stop_grace_period: 15s` in the Compose file; on Kubernetes the default
+`terminationGracePeriodSeconds` of 30 already covers it.
+
+### Observability (OpenTelemetry)
+
+The Docker image ships with [OpenTelemetry](https://opentelemetry.io/) APM built in, and works with
+any OTLP-compatible backend (Datadog, Grafana Tempo, Jaeger, Honeycomb, etc.). It is **off by
+default** and turns on as soon as you point it at an OTLP receiver — no code changes or extra
+installs required. A setup that cannot start logs a warning and runs untraced rather than taking
+the process down with it. Tracing is set up before the app starts (auto-instrumentation for HTTP and the
+outbound calls to the agent and the Forest SaaS). The graceful shutdown described above waits for
+the buffered spans to be exported before it exits, but gives that its own 2 second deadline rather
+than the 10 seconds in-flight requests get: an unreachable collector costs you the last spans, never
+the ability to stop. Worst case it adds ~3 seconds to a shutdown.
+
+Configure it entirely through the standard OTel environment variables:
+
+| Variable | Description |
+| --- | --- |
+| `OTEL_EXPORTER_OTLP_ENDPOINT` | OTLP receiver URL (e.g. `http://collector:4318`). **Tracing stays off until this or `OTEL_TRACES_EXPORTER` is set.** |
+| `OTEL_SERVICE_NAME` | Service name reported in traces. Falls back to `service.name` in `OTEL_RESOURCE_ATTRIBUTES`, then to `forestadmin-agent-bff`. |
+| `OTEL_RESOURCE_ATTRIBUTES` | Extra resource attributes, e.g. `deployment.environment=production`. A `service.name` here is honoured when `OTEL_SERVICE_NAME` is unset. |
+| `OTEL_SDK_DISABLED` | Set to `true` (case-insensitive) to force-disable tracing whatever else is configured. |
+| `OTEL_TRACES_EXPORTER` | Which exporter the SDK builds: `otlp` (the default), `console`, `zipkin`, `none`, or a list. Setting it alone turns tracing on without an OTLP endpoint, which is what makes `console` usable for debugging. `none` keeps instrumentation running with nothing exported, so trace context still propagates to the agent and the Forest SaaS. |
+| `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` | Per-signal endpoint, taking precedence over the generic one above. Setting either turns tracing on. |
+| `OTEL_EXPORTER_OTLP_PROTOCOL` | `http/protobuf` (the default), `http/json` or `grpc`, with `OTEL_EXPORTER_OTLP_TRACES_PROTOCOL` for traces alone. |
+| `OTEL_METRICS_EXPORTER` / `OTEL_LOGS_EXPORTER` | Default to `none` here, against the SDK's own `otlp`: this image arms tracing, and leaving them unset would otherwise export metrics and logs to `http://localhost:4318` on the side. Set either one (`otlp`, `console`, …) to opt that signal back in. |
+
+```bash
+docker run -d \
+  -p 3450:3450 \
+  --stop-timeout 15 \
+  --add-host host.docker.internal:host-gateway \
+  -e FOREST_AUTH_SECRET="..." \
+  -e FOREST_ENV_SECRET="..." \
+  -e FOREST_SERVER_URL="https://api.forestadmin.com" \
+  -e FOREST_APP_URL="https://app.forestadmin.com" \
+  -e AGENT_URL="http://host.docker.internal:3351" \
+  -e BFF_TOKEN_ENCRYPTION_KEY="$(openssl rand -base64 32)" \
+  -e OTEL_EXPORTER_OTLP_ENDPOINT="http://collector:4318" \
+  ghcr.io/forestadmin/agent-bff:latest
+```
+
+> **Note:** These variables only do anything in the Docker image. The image's entry point loads
+> the tracing preload before the CLI; the npm `forest-bff` bin runs the CLI on its own, and the
+> OpenTelemetry packages are not npm dependencies — so outside Docker an `OTEL_*` variable is
+> read by nothing and the process starts untraced, silently.
+
+### Without Docker
+
 Packaged / production — run the bin:
 
 ```bash
@@ -99,7 +205,7 @@ yarn start:dev         # node --env-file=.env dist/cli.js
 | `FOREST_APP_URL`              | yes       | Forest front base URL, used to build the OAuth front-channel redirect (`src/oauth/oauth-routes.ts`).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
 | `AGENT_URL`                   | yes       | The customer agent base URL the BFF calls via agent-client.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
 | `BFF_TOKEN_ENCRYPTION_KEY`    | for OAuth | Base64-encoded 32-byte AES-256 key encrypting stored refresh tokens. Until it is set, the `/oauth/*` token-issuance routes are disabled and `/health` reports `configured.oauth: false` — but it stays `ok`, since the key gates OAuth and not boot; already-issued `bff_access` tokens still authenticate on `/agent/*` whenever `FOREST_AUTH_SECRET` is present.                                                                                                                                                                                                                                                                                                                                                                                             |
-| `HTTP_PORT`                   | no        | Server port, integer 0–65535. Defaults to `3450`. `0` binds an OS-assigned ephemeral port.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| `HTTP_PORT`                   | no        | Server port, integer 0–65535. Defaults to `3450`. `0` binds an OS-assigned ephemeral port — useful for a local run, unusable in the Docker image, where nothing outside the process learns which port it got: it can be neither published nor probed, and the image's healthcheck would report the container unhealthy forever.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
 | `BFF_ALLOWED_ORIGINS`         | no        | Comma-separated CORS allow-list of origins (scheme + host + port). An entry may carry a single `*` as the leading host label — `https://*.apps.zdusercontent.com` — which matches exactly one DNS label there, and nothing else: not two labels, not the apex, and never the scheme or the port. The host left after `*.` must be at least two non-empty labels, so `https://*.com` is refused; a two-label public suffix such as `https://*.co.uk` is not, and would allow every site under it. Any other `*` in the host is refused and warned about at boot; a `*` outside the host — in userinfo, a path or a query — is stripped along with the rest of the URL, so `https://*@example.com` is simply the exact origin `https://example.com`. Empty ⇒ no cross-origin browser access.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
 | `BFF_DEFAULT_TIMEZONE`        | no        | Fallback IANA timezone used when a request carries neither an `X-Forest-Timezone` header nor a body `timezone`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
 | `BFF_PUBLIC_URL`              | no        | The BFF's own external base URL, published as `servers[0].url` in the OpenAPI document so a generated client resolves endpoints without being configured by hand. Absent, `servers[0].url` stays `/`, which a consumer that fetched the document over HTTP resolves against that URL — but which leaves a client generated from an offline `forest-bff openapi` export with no base URL at all. Trailing slashes are stripped. A malformed value fails the boot, and so does one carrying credentials, a query string or a fragment: credentials would be published to every reader of the document, and anything behind a `?` or `#` swallows the path a generated client appends. |

package/dist/tracing-handle.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The one piece of state the preload and the CLI have to share.
+ *
+ * `--require` runs the preload in its own module, before `cli.js` is even loaded, so the SDK it
+ * builds has nowhere to go but a module both sides resolve to the same instance. Keeping it here —
+ * rather than having the preload arm a signal handler of its own — is what lets the shutdown path
+ * WAIT for the flush instead of racing it, and keeps the preload from consuming a signal the CLI
+ * has not armed a handler for yet.
+ *
+ * Nothing OpenTelemetry-specific is imported here, so the npm bin pays only for an empty variable.
+ */
+export interface TracingHandle {
+    shutdown(): Promise<void>;
+}
+export declare function setTracingHandle(sdk: TracingHandle | undefined): void;
+export declare function getTracingHandle(): TracingHandle | undefined;
+/**
+ * Flushes buffered spans, or resolves immediately when tracing was never armed — the shutdown path
+ * should not have to know which. A failing export is swallowed: a dead collector must not turn a
+ * clean shutdown into a failed one.
+ *
+ * No deadline here on purpose: `armShutdown` bounds whatever flush it is given, and it is the only
+ * caller. Bounding it twice would say the deadline lives in two places when it does not.
+ */
+export declare function flushTracing(): Promise<void>;
+//# sourceMappingURL=tracing-handle.d.ts.map

package/dist/tracing-handle.js

@@ -0,0 +1,40 @@
+"use strict";
+/**
+ * The one piece of state the preload and the CLI have to share.
+ *
+ * `--require` runs the preload in its own module, before `cli.js` is even loaded, so the SDK it
+ * builds has nowhere to go but a module both sides resolve to the same instance. Keeping it here —
+ * rather than having the preload arm a signal handler of its own — is what lets the shutdown path
+ * WAIT for the flush instead of racing it, and keeps the preload from consuming a signal the CLI
+ * has not armed a handler for yet.
+ *
+ * Nothing OpenTelemetry-specific is imported here, so the npm bin pays only for an empty variable.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setTracingHandle = setTracingHandle;
+exports.getTracingHandle = getTracingHandle;
+exports.flushTracing = flushTracing;
+let handle;
+function setTracingHandle(sdk) {
+    handle = sdk;
+}
+function getTracingHandle() {
+    return handle;
+}
+/**
+ * Flushes buffered spans, or resolves immediately when tracing was never armed — the shutdown path
+ * should not have to know which. A failing export is swallowed: a dead collector must not turn a
+ * clean shutdown into a failed one.
+ *
+ * No deadline here on purpose: `armShutdown` bounds whatever flush it is given, and it is the only
+ * caller. Bounding it twice would say the deadline lives in two places when it does not.
+ */
+async function flushTracing() {
+    try {
+        await handle?.shutdown();
+    }
+    catch {
+        /* istanbul ignore next — nothing to do about it, and it must not change the exit code. */
+    }
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoidHJhY2luZy1oYW5kbGUuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi9zcmMvdHJhY2luZy1oYW5kbGUudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IjtBQUFBOzs7Ozs7Ozs7O0dBVUc7O0FBUUgsNENBRUM7QUFFRCw0Q0FFQztBQVVELG9DQU1DO0FBeEJELElBQUksTUFBaUMsQ0FBQztBQUV0QyxTQUFnQixnQkFBZ0IsQ0FBQyxHQUE4QjtJQUM3RCxNQUFNLEdBQUcsR0FBRyxDQUFDO0FBQ2YsQ0FBQztBQUVELFNBQWdCLGdCQUFnQjtJQUM5QixPQUFPLE1BQU0sQ0FBQztBQUNoQixDQUFDO0FBRUQ7Ozs7Ozs7R0FPRztBQUNJLEtBQUssVUFBVSxZQUFZO0lBQ2hDLElBQUksQ0FBQztRQUNILE1BQU0sTUFBTSxFQUFFLFFBQVEsRUFBRSxDQUFDO0lBQzNCLENBQUM7SUFBQyxNQUFNLENBQUM7UUFDUCwwRkFBMEY7SUFDNUYsQ0FBQztBQUNILENBQUMifQ==

package/dist/tracing-preload.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=tracing-preload.d.ts.map

package/dist/tracing-preload.js

@@ -0,0 +1,27 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+// The `--require` entry point of the Docker image (see the Dockerfile's ENTRYPOINT). Separate from
+// `tracing.ts` on purpose: importing the setup must never arm an SDK, only calling it should.
+//
+// The SDK is handed to `tracing-handle` rather than wired to a signal here. The CLI arms the only
+// termination handler, and it flushes through that handle — so a signal arriving before the CLI is
+// up cannot be swallowed by a listener that does not terminate anything.
+const console_logger_1 = __importDefault(require("./adapters/console-logger"));
+const tracing_1 = __importDefault(require("./tracing"));
+const tracing_handle_1 = require("./tracing-handle");
+// Nothing here may throw. A `--require` runs before the entry point, so an exception aborts the
+// process before the BFF exists at all — a dead container in exchange for optional, best-effort
+// telemetry. `initTracing` degrades on its own for the cases it knows about; this catches the rest,
+// including whatever a future SDK version decides to throw from `start()`.
+try {
+    (0, tracing_handle_1.setTracingHandle)((0, tracing_1.default)());
+}
+catch (error) {
+    (0, console_logger_1.default)()('Warn', 'OpenTelemetry failed to initialise, starting untraced', {
+        reason: error instanceof Error ? error.message : String(error),
+    });
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoidHJhY2luZy1wcmVsb2FkLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vc3JjL3RyYWNpbmctcHJlbG9hZC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiOzs7OztBQUFBLG1HQUFtRztBQUNuRyw4RkFBOEY7QUFDOUYsRUFBRTtBQUNGLGtHQUFrRztBQUNsRyxtR0FBbUc7QUFDbkcseUVBQXlFO0FBQ3pFLCtFQUE0RDtBQUM1RCx3REFBb0M7QUFDcEMscURBQW9EO0FBRXBELGdHQUFnRztBQUNoRyxnR0FBZ0c7QUFDaEcsb0dBQW9HO0FBQ3BHLDJFQUEyRTtBQUMzRSxJQUFJLENBQUM7SUFDSCxJQUFBLGlDQUFnQixFQUFDLElBQUEsaUJBQVcsR0FBRSxDQUFDLENBQUM7QUFDbEMsQ0FBQztBQUFDLE9BQU8sS0FBSyxFQUFFLENBQUM7SUFDZixJQUFBLHdCQUFtQixHQUFFLENBQUMsTUFBTSxFQUFFLHVEQUF1RCxFQUFFO1FBQ3JGLE1BQU0sRUFBRSxLQUFLLFlBQVksS0FBSyxDQUFDLENBQUMsQ0FBQyxLQUFLLENBQUMsT0FBTyxDQUFDLENBQUMsQ0FBQyxNQUFNLENBQUMsS0FBSyxDQUFDO0tBQy9ELENBQUMsQ0FBQztBQUNMLENBQUMifQ==

package/dist/tracing.d.ts

@@ -0,0 +1,79 @@
+import type { Logger } from './ports/logger-port';
+/**
+ * The OpenTelemetry setup. `tracing-preload.ts` is what actually runs it, via `--require` before
+ * cli.js so the auto-instrumentation patches land before anything the app imports; keeping the two
+ * apart is what lets this module be imported by a test without arming an SDK.
+ *
+ * The SDK is initialised only when `OTEL_EXPORTER_OTLP_ENDPOINT` is set, so an install that never
+ * opted into APM pays nothing. Neither ending the process nor flushing on the way out is this
+ * module's business: it hands the SDK back, the preload parks it in `tracing-handle`, and the
+ * shutdown path flushes through that. Arming a signal handler here would consume a signal the CLI
+ * has not armed its own handler for yet, and nothing would then terminate the process.
+ * All configuration goes through the standard OTel environment variables:
+ *
+ *   OTEL_EXPORTER_OTLP_ENDPOINT   OTLP receiver (e.g. http://localhost:4318)
+ *   OTEL_SERVICE_NAME             default: forestadmin-agent-bff
+ *   OTEL_SDK_DISABLED             set to "true" to force-disable
+ *   OTEL_RESOURCE_ATTRIBUTES      e.g. deployment.environment=production
+ *   OTEL_METRICS_EXPORTER         default: none (the SDK's own default is otlp)
+ *   OTEL_LOGS_EXPORTER            default: none (the SDK's own default is otlp)
+ *
+ * The OTel packages are installed only into the Docker image's isolated deps (see
+ * `packages/agent-bff/docker/`), never shipped to npm consumers of the CLI — hence the dynamic
+ * require behind a seam, and the warning rather than a crash when they are absent.
+ */
+export declare const DEFAULT_SERVICE_NAME = "forestadmin-agent-bff";
+export interface OtelSdk {
+    start(): void;
+    shutdown(): Promise<void>;
+}
+export interface OtelModules {
+    NodeSDK: new (options: Record<string, unknown>) => OtelSdk;
+    getNodeAutoInstrumentations: () => unknown;
+}
+export interface TracingOptions {
+    /**
+     * The environment OUR decisions read: whether to arm at all, and what to name the service when
+     * nothing else does. It stops there — the SDK reads the real `process.env` for everything about
+     * the export itself, so a test injecting `env` cannot assert where spans go. Identical objects in
+     * production, so this is a limit on what the seam can test, not a behaviour.
+     */
+    env?: NodeJS.ProcessEnv;
+    logger?: Logger;
+    /** The dynamic require, as a seam: the packages exist only in the Docker image. */
+    load?: () => OtelModules | undefined;
+}
+/** The packages this image installs for APM, and the export it takes from each. */
+export declare const OTEL_MODULE_IDS: {
+    readonly sdk: "@opentelemetry/sdk-node";
+    readonly instrumentations: "@opentelemetry/auto-instrumentations-node";
+};
+/**
+ * The module resolution, as a seam. These packages are absent everywhere except the Docker image,
+ * so the real `require` can only ever take the failure branch here — passing a loader is what lets
+ * the success branch, and the package ids it asks for, be exercised at all. A typo in one of them
+ * would otherwise surface as an untraced image and nothing else.
+ */
+export type ModuleLoader = (id: string) => Record<string, unknown>;
+export declare function loadOtelModules(load?: ModuleLoader): OtelModules | undefined;
+/**
+ * The service name the environment already carries, by the spec's precedence: `OTEL_SERVICE_NAME`
+ * wins, then a `service.name` entry in the comma-separated `OTEL_RESOURCE_ATTRIBUTES` list.
+ * Undefined when neither names one, which is the only case where our own default should apply.
+ */
+export declare function serviceNameFromEnv(env: NodeJS.ProcessEnv): string | undefined;
+/**
+ * Strips the credentials out of the endpoint before it reaches the logs. `https://user:token@host`
+ * is a legitimate way to reach a collector behind basic auth, and container logs are the last place
+ * that token should end up — this package does not echo a secret anywhere else either.
+ *
+ * The query string goes with them, unread: collectors that take their key as `?api_key=` exist, and
+ * telling them apart from a harmless parameter means knowing every vendor's spelling. Nothing about
+ * the destination is lost — the host and path are what the line is for.
+ *
+ * An endpoint that does not parse is dropped from the log entirely rather than passed through: it
+ * cannot be redacted, so it cannot be shown. The SDK will fail on it soon enough on its own.
+ */
+export declare function redactEndpoint(endpoint: string): string | undefined;
+export default function initTracing(options?: TracingOptions): OtelSdk | undefined;
+//# sourceMappingURL=tracing.d.ts.map

package/dist/tracing.js

@@ -0,0 +1,168 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OTEL_MODULE_IDS = exports.DEFAULT_SERVICE_NAME = void 0;
+exports.loadOtelModules = loadOtelModules;
+exports.serviceNameFromEnv = serviceNameFromEnv;
+exports.redactEndpoint = redactEndpoint;
+exports.default = initTracing;
+const console_logger_1 = __importDefault(require("./adapters/console-logger"));
+/**
+ * The OpenTelemetry setup. `tracing-preload.ts` is what actually runs it, via `--require` before
+ * cli.js so the auto-instrumentation patches land before anything the app imports; keeping the two
+ * apart is what lets this module be imported by a test without arming an SDK.
+ *
+ * The SDK is initialised only when `OTEL_EXPORTER_OTLP_ENDPOINT` is set, so an install that never
+ * opted into APM pays nothing. Neither ending the process nor flushing on the way out is this
+ * module's business: it hands the SDK back, the preload parks it in `tracing-handle`, and the
+ * shutdown path flushes through that. Arming a signal handler here would consume a signal the CLI
+ * has not armed its own handler for yet, and nothing would then terminate the process.
+ * All configuration goes through the standard OTel environment variables:
+ *
+ *   OTEL_EXPORTER_OTLP_ENDPOINT   OTLP receiver (e.g. http://localhost:4318)
+ *   OTEL_SERVICE_NAME             default: forestadmin-agent-bff
+ *   OTEL_SDK_DISABLED             set to "true" to force-disable
+ *   OTEL_RESOURCE_ATTRIBUTES      e.g. deployment.environment=production
+ *   OTEL_METRICS_EXPORTER         default: none (the SDK's own default is otlp)
+ *   OTEL_LOGS_EXPORTER            default: none (the SDK's own default is otlp)
+ *
+ * The OTel packages are installed only into the Docker image's isolated deps (see
+ * `packages/agent-bff/docker/`), never shipped to npm consumers of the CLI — hence the dynamic
+ * require behind a seam, and the warning rather than a crash when they are absent.
+ */
+exports.DEFAULT_SERVICE_NAME = 'forestadmin-agent-bff';
+/** The packages this image installs for APM, and the export it takes from each. */
+exports.OTEL_MODULE_IDS = {
+    sdk: '@opentelemetry/sdk-node',
+    instrumentations: '@opentelemetry/auto-instrumentations-node',
+};
+function loadOtelModules(load = require) {
+    try {
+        const modules = {
+            NodeSDK: load(exports.OTEL_MODULE_IDS.sdk).NodeSDK,
+            getNodeAutoInstrumentations: load(exports.OTEL_MODULE_IDS.instrumentations)
+                .getNodeAutoInstrumentations,
+        };
+        // Resolving is not the same as finding what we came for. A package that loads but no longer
+        // exports the name we read — a rename on a version bump — would otherwise hand back a truthy
+        // object of undefined members, skip the "packages not available" branch, and throw a
+        // TypeError inside a `--require`, before the entry point runs at all. That is a dead container
+        // for an APM layer that is supposed to degrade to a warning.
+        if (Object.values(modules).some(exported => typeof exported !== 'function'))
+            return undefined;
+        return modules;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The OTel specification defines its boolean environment variables as case-insensitive, and this
+ * one is the kill switch: reading `TRUE` as "not disabled" would leave tracing running for someone
+ * who just asked for it to stop.
+ */
+function isDisabled(raw) {
+    return raw?.trim().toLowerCase() === 'true';
+}
+/**
+ * The service name the environment already carries, by the spec's precedence: `OTEL_SERVICE_NAME`
+ * wins, then a `service.name` entry in the comma-separated `OTEL_RESOURCE_ATTRIBUTES` list.
+ * Undefined when neither names one, which is the only case where our own default should apply.
+ */
+function serviceNameFromEnv(env) {
+    const explicit = env.OTEL_SERVICE_NAME?.trim();
+    if (explicit)
+        return explicit;
+    return env.OTEL_RESOURCE_ATTRIBUTES?.split(',')
+        .map(entry => entry.split('='))
+        .filter(([key, value]) => key?.trim() === 'service.name' && value?.trim())
+        .map(([, value]) => value.trim())
+        .pop();
+}
+/**
+ * Strips the credentials out of the endpoint before it reaches the logs. `https://user:token@host`
+ * is a legitimate way to reach a collector behind basic auth, and container logs are the last place
+ * that token should end up — this package does not echo a secret anywhere else either.
+ *
+ * The query string goes with them, unread: collectors that take their key as `?api_key=` exist, and
+ * telling them apart from a harmless parameter means knowing every vendor's spelling. Nothing about
+ * the destination is lost — the host and path are what the line is for.
+ *
+ * An endpoint that does not parse is dropped from the log entirely rather than passed through: it
+ * cannot be redacted, so it cannot be shown. The SDK will fail on it soon enough on its own.
+ */
+function redactEndpoint(endpoint) {
+    try {
+        const url = new URL(endpoint);
+        if (!url.username && !url.password && !url.search)
+            return endpoint;
+        url.username = '';
+        url.password = '';
+        url.search = '';
+        return url.toString();
+    }
+    catch {
+        return undefined;
+    }
+}
+function initTracing(options = {}) {
+    const { env = process.env, logger = (0, console_logger_1.default)(), load = loadOtelModules } = options;
+    // Any of the three standard ways to say "export traces somewhere" turns tracing on. The per-signal
+    // endpoint counts as much as the generic one, and OTEL_TRACES_EXPORTER counts on its own —
+    // requiring an OTLP collector before `console` does anything would be nonsense for an exporter
+    // that writes to stdout, and it is the obvious first thing to reach for when debugging.
+    //
+    // A blank value counts as unset throughout, not as "export to the OTel default": `env_file` hands
+    // an empty string through for a variable left blank in a `.env`, and arming the SDK against
+    // localhost:4318 is not what leaving the line empty asks for.
+    const endpoint = env.OTEL_EXPORTER_OTLP_TRACES_ENDPOINT?.trim() || env.OTEL_EXPORTER_OTLP_ENDPOINT?.trim();
+    const requestedExporter = env.OTEL_TRACES_EXPORTER?.trim().toLowerCase();
+    if ((!endpoint && !requestedExporter) || isDisabled(env.OTEL_SDK_DISABLED))
+        return undefined;
+    const modules = load();
+    if (!modules) {
+        logger('Warn', 'OpenTelemetry packages not available, skipping APM initialisation');
+        return undefined;
+    }
+    const { NodeSDK, getNodeAutoInstrumentations } = modules;
+    // Passing `serviceName` unconditionally would override OTEL_RESOURCE_ATTRIBUTES=service.name=...,
+    // which is a documented knob — someone setting only that would silently get our default. So we
+    // fill it in only when the environment names no service at all, and otherwise leave the SDK to
+    // apply the spec's own precedence (OTEL_SERVICE_NAME first, then the resource attribute).
+    const named = serviceNameFromEnv(env);
+    // NodeSDK reads OTEL_METRICS_EXPORTER and OTEL_LOGS_EXPORTER itself, and an unset one does not
+    // mean "off" — it means otlp. So arming traces alone also starts a metric reader and a log
+    // processor aimed at the OTLP default, http://localhost:4318. Under OTEL_TRACES_EXPORTER=console,
+    // which asks for no collector at all, that is a POST every minute to a port nobody named; where
+    // something else on the host does listen there, it is telemetry that install never opted into.
+    // This module arms tracing. The other two signals stay opt-in, through their own variable, which
+    // still works: we only fill in what the environment left blank.
+    env.OTEL_METRICS_EXPORTER = env.OTEL_METRICS_EXPORTER?.trim() || 'none';
+    env.OTEL_LOGS_EXPORTER = env.OTEL_LOGS_EXPORTER?.trim() || 'none';
+    // No `traceExporter`, deliberately. Passing one puts NodeSDK on its manual-configuration path,
+    // where it stops reading the environment — which is how OTEL_TRACES_EXPORTER, then
+    // OTEL_EXPORTER_OTLP_PROTOCOL, then the per-signal endpoint each turned out to be silently
+    // ignored, one review round after another. They were three symptoms of doing the SDK's job.
+    //
+    // sdk-node depends on every OTLP exporter and on the Zipkin one, so all of them are in the image
+    // already; leaving the choice to the SDK costs nothing and makes the whole standard surface work,
+    // protocol and per-signal overrides included. Our only decisions are whether to arm at all, and
+    // the service name when nothing else supplies one.
+    const sdk = new NodeSDK({
+        ...(named ? {} : { serviceName: exports.DEFAULT_SERVICE_NAME }),
+        instrumentations: [getNodeAutoInstrumentations()],
+    });
+    sdk.start();
+    // What was ASKED for, not what the SDK settled on — we no longer choose, so claiming a
+    // destination we did not pick would be inventing one. The endpoint is dropped when an exporter
+    // was named instead, since it would read as a promise this line cannot keep.
+    logger('Info', 'OpenTelemetry tracing enabled', {
+        serviceName: named ?? exports.DEFAULT_SERVICE_NAME,
+        ...(requestedExporter ? { exporter: requestedExporter } : {}),
+        ...(endpoint && !requestedExporter ? { endpoint: redactEndpoint(endpoint) } : {}),
+    });
+    return sdk;
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoidHJhY2luZy5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uL3NyYy90cmFjaW5nLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiI7Ozs7OztBQW1FQSwwQ0FtQkM7QUFnQkQsZ0RBVUM7QUFjRCx3Q0FjQztBQUVELDhCQXFFQztBQWpORCwrRUFBNEQ7QUFFNUQ7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7R0FzQkc7QUFFVSxRQUFBLG9CQUFvQixHQUFHLHVCQUF1QixDQUFDO0FBeUI1RCxtRkFBbUY7QUFDdEUsUUFBQSxlQUFlLEdBQUc7SUFDN0IsR0FBRyxFQUFFLHlCQUF5QjtJQUM5QixnQkFBZ0IsRUFBRSwyQ0FBMkM7Q0FDckQsQ0FBQztBQVVYLFNBQWdCLGVBQWUsQ0FBQyxPQUFxQixPQUFPO0lBQzFELElBQUksQ0FBQztRQUNILE1BQU0sT0FBTyxHQUFHO1lBQ2QsT0FBTyxFQUFFLElBQUksQ0FBQyx1QkFBZSxDQUFDLEdBQUcsQ0FBQyxDQUFDLE9BQU87WUFDMUMsMkJBQTJCLEVBQUUsSUFBSSxDQUFDLHVCQUFlLENBQUMsZ0JBQWdCLENBQUM7aUJBQ2hFLDJCQUEyQjtTQUMvQixDQUFDO1FBRUYsNEZBQTRGO1FBQzVGLDZGQUE2RjtRQUM3RixxRkFBcUY7UUFDckYsK0ZBQStGO1FBQy9GLDZEQUE2RDtRQUM3RCxJQUFJLE1BQU0sQ0FBQyxNQUFNLENBQUMsT0FBTyxDQUFDLENBQUMsSUFBSSxDQUFDLFFBQVEsQ0FBQyxFQUFFLENBQUMsT0FBTyxRQUFRLEtBQUssVUFBVSxDQUFDO1lBQUUsT0FBTyxTQUFTLENBQUM7UUFFOUYsT0FBTyxPQUFzQixDQUFDO0lBQ2hDLENBQUM7SUFBQyxNQUFNLENBQUM7UUFDUCxPQUFPLFNBQVMsQ0FBQztJQUNuQixDQUFDO0FBQ0gsQ0FBQztBQUVEOzs7O0dBSUc7QUFDSCxTQUFTLFVBQVUsQ0FBQyxHQUF1QjtJQUN6QyxPQUFPLEdBQUcsRUFBRSxJQUFJLEVBQUUsQ0FBQyxXQUFXLEVBQUUsS0FBSyxNQUFN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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forestadmin/agent-bff",
-  "version": "1.32.0",
+  "version": "1.33.0",
   "main": "dist/index.js",
   "bin": {
     "forest-bff": "dist/cli.js"