brass-runtime 1.16.1 → 1.17.0

package/docs/frameworks/vanilla.md

@@ -0,0 +1,224 @@
+# Vanilla integration
+
+Use this when an app does not have a framework-level DI or lifecycle system.
+The same shape works for plain browser TypeScript, Node HTTP handlers, CLIs,
+and small services.
+
+## Browser
+
+Browser apps should send telemetry to a same-origin proxy. Do not ship Grafana
+Cloud or collector credentials to the client.
+
+```ts
+// brass.browser.ts
+import { Runtime } from "brass-runtime/core";
+import {
+  defineHttpPolicyPresets,
+  makeDefaultHttpClient,
+} from "brass-runtime/http";
+import {
+  makeObservability,
+  makeOtlpOptions,
+  withHttpObservability,
+} from "brass-runtime/observability";
+
+const policyPresets = defineHttpPolicyPresets({
+  readModel: {
+    lane: "read-model",
+    priority: 3,
+    retry: { maxRetries: 2, baseDelayMs: 100, maxDelayMs: 1_000 },
+  },
+  command: {
+    lane: "command",
+    priority: 1,
+    retry: false,
+  },
+});
+
+export const brass = (() => {
+  const observability = makeObservability({
+    serviceName: "shop-web",
+    resource: { "deployment.environment": "browser" },
+    logs: false,
+    sampling: { ratio: 0.1, respectRemoteSampled: true, forceSampleOnError: true },
+    redaction: {},
+    cardinality: { maxValuesPerLabel: 100 },
+    otlp: makeOtlpOptions({
+      endpoint: "/api/otel",
+      timeoutMs: 10_000,
+      retry: { attempts: 2, initialDelayMs: 100, maxDelayMs: 1_000 },
+      pipeline: { maxQueueSize: 2_000, batchSize: 128, dropPolicy: "drop-oldest" },
+    }),
+    flushIntervalMs: 15_000,
+    autoStart: true,
+  });
+
+  const runtime = new Runtime({
+    env: observability.env,
+    hooks: observability.hooks,
+  });
+
+  const http = makeDefaultHttpClient({
+    baseUrl: "/api",
+    preset: "balanced",
+    timeoutMs: 5_000,
+    policyPresets,
+    middleware: [withHttpObservability(observability)],
+  });
+
+  return {
+    observability,
+    runtime,
+    http,
+    shutdown: async () => {
+      await http.shutdown();
+      await observability.shutdown();
+    },
+  };
+})();
+```
+
+Use it from ordinary browser code:
+
+```ts
+type User = {
+  readonly id: string;
+  readonly name: string;
+};
+
+export async function loadCurrentUser(): Promise<User> {
+  const response = await brass.runtime.toPromise(
+    brass.http.getJson<User>("/users/me", {
+      policy: "readModel",
+      timeoutMs: 2_000,
+    }),
+  );
+
+  return response.body;
+}
+
+window.addEventListener("pagehide", () => {
+  void brass.shutdown();
+});
+```
+
+## Node
+
+On the server, Brass can send directly to a collector because credentials stay
+inside the trusted process.
+
+```ts
+// brass.node.ts
+import { Runtime } from "brass-runtime/core";
+import {
+  defineHttpPolicyPresets,
+  makeDefaultHttpClient,
+} from "brass-runtime/http";
+import {
+  makeObservability,
+  makeOtlpOptions,
+  withHttpObservability,
+} from "brass-runtime/observability";
+
+const policyPresets = defineHttpPolicyPresets({
+  readModel: {
+    lane: "read-model",
+    priority: 3,
+    retry: { maxRetries: 2, baseDelayMs: 100, maxDelayMs: 1_000 },
+  },
+  command: {
+    lane: "command",
+    priority: 1,
+    retry: false,
+  },
+});
+
+export const brass = (() => {
+  const observability = makeObservability({
+    serviceName: process.env.OTEL_SERVICE_NAME ?? "vanilla-node",
+    serviceVersion: process.env.OTEL_SERVICE_VERSION,
+    resource: {
+      "deployment.environment": process.env.NODE_ENV ?? "development",
+    },
+    logs: { minLevel: "info" },
+    sampling: { ratio: 0.25, respectRemoteSampled: true, forceSampleOnError: true },
+    redaction: {},
+    cardinality: { maxValuesPerLabel: 100 },
+    otlp: makeOtlpOptions({
+      endpoint: process.env.GRAFANA_OTLP_ENDPOINT ?? "http://grafana-alloy:4318",
+      headers: process.env.GRAFANA_OTLP_AUTHORIZATION
+        ? { Authorization: process.env.GRAFANA_OTLP_AUTHORIZATION }
+        : undefined,
+      timeoutMs: 10_000,
+      retry: { attempts: 3, initialDelayMs: 100, maxDelayMs: 2_000 },
+      pipeline: {
+        maxQueueSize: 10_000,
+        batchSize: 512,
+        dropPolicy: "drop-oldest",
+        shutdownTimeoutMs: 10_000,
+      },
+    }),
+    flushIntervalMs: 10_000,
+    autoStart: true,
+  });
+
+  const runtime = new Runtime({
+    env: observability.env,
+    hooks: observability.hooks,
+  });
+
+  const http = makeDefaultHttpClient({
+    baseUrl: process.env.API_BASE_URL ?? "https://api.internal",
+    preset: "production",
+    timeoutMs: 5_000,
+    policyPresets,
+    middleware: [withHttpObservability(observability)],
+  });
+
+  return {
+    observability,
+    runtime,
+    http,
+    shutdown: async () => {
+      await http.shutdown();
+      await observability.shutdown();
+    },
+  };
+})();
+```
+
+Use the Node request adapter when you receive `IncomingMessage`-like requests:
+
+```ts
+import { createServer } from "node:http";
+import {
+  makeNodeRequestObservabilityContext,
+} from "brass-runtime/observability";
+import { brass } from "./brass.node";
+
+const server = createServer(async (req, res) => {
+  const ctx = makeNodeRequestObservabilityContext(brass.observability, req, {
+    route: req.url?.startsWith("/users/") ? "/users/:id" : req.url,
+  });
+
+  const response = await ctx.run(
+    ctx.withRequestSpan(
+      brass.http.getJson("/users/42", {
+        policy: "readModel",
+        timeoutMs: 2_000,
+      }),
+    ),
+  );
+
+  res.setHeader("content-type", "application/json");
+  res.end(JSON.stringify(response.body));
+});
+
+process.once("SIGTERM", async () => {
+  await new Promise<void>((resolve) => server.close(() => resolve()));
+  await brass.shutdown();
+});
+
+server.listen(process.env.PORT ?? 3000);
+```
+

package/docs/nestjs.md

@@ -0,0 +1,6 @@
+# NestJS integration
+
+The NestJS recipe now lives at [`docs/frameworks/nestjs.md`](./frameworks/nestjs.md).
+
+This file is kept as a compatibility pointer for older links.
+

package/docs/observability-framework-examples.md

@@ -7,6 +7,10 @@ flush OTLP metrics/traces.
 They use optional framework dependencies so the runtime package does not force
 Express, Fastify, or Nest into normal installs.
 
+For production-style integration recipes across React, Next.js, Angular,
+Express, Fastify, and Nest, see
+[`docs/framework-integrations.md`](./framework-integrations.md).
+
 ## Express
 
 ```bash
@@ -61,9 +65,17 @@ curl http://localhost:3002/metrics
 
 Source: `src/examples/observabilityNest.ts`.
 
+For a production-style Nest module with DI tokens, Grafana/OTLP configuration,
+an observed Brass HTTP client, and shutdown wiring, see
+[`docs/frameworks/nestjs.md`](./frameworks/nestjs.md).
+
 ## What the examples demonstrate
 
 - `makeObservabilityFromEnv(process.env)` for deployment-style setup.
+- `makeOtlpOptions(...)` for collector endpoint configuration without adding
+  vendor-specific code to Brass.
+- `withHttpObservability(...)` around the Brass HTTP client for outbound
+  metrics, spans, logs, policy context, and trace propagation.
 - Framework-specific request adapters:
   - `makeExpressRequestObservabilityContext`
   - `makeFastifyRequestObservabilityContext`

package/docs/observability.md

@@ -327,6 +327,109 @@ collector does not create overlapping exports.
 Finished spans are pruned after successful export and can also be bounded with
 `traces.maxFinishedSpans` / `traces.maxSpanAgeMs`.
 
+### Vendor-neutral collector recipes
+
+Brass intentionally does not know about Grafana Cloud, AppDynamics, or any
+OpenTelemetry SDK implementation. The runtime only needs OTLP HTTP endpoint
+URLs, headers, and optional export tuning. Keep vendor naming in application
+code by writing small helpers that call the backend-neutral `makeOtlpOptions`.
+
+```ts
+import {
+  makeObservability,
+  makeOtlpOptions,
+  type ObservabilityOtlpOptions,
+} from "brass-runtime/observability";
+
+function productionOtlp(input: {
+  readonly endpoint: string;
+  readonly headers?: Record<string, string>;
+}): ObservabilityOtlpOptions {
+  return makeOtlpOptions({
+    endpoint: input.endpoint,
+    headers: input.headers,
+    timeoutMs: 10_000,
+    retry: { attempts: 3, initialDelayMs: 100, maxDelayMs: 2_000 },
+    pipeline: {
+      maxQueueSize: 10_000,
+      batchSize: 512,
+      dropPolicy: "drop-oldest",
+      shutdownTimeoutMs: 10_000,
+    },
+  });
+}
+```
+
+Grafana Cloud can be configured as a direct OTLP endpoint or through
+Grafana Alloy/OpenTelemetry Collector. The helper stays in your app and only
+returns Brass OTLP config:
+
+```ts
+function grafanaCloudCollector(input: {
+  readonly endpoint: string;
+  readonly authorization?: string;
+}): ObservabilityOtlpOptions {
+  return productionOtlp({
+    endpoint: input.endpoint,
+    headers: input.authorization
+      ? { Authorization: input.authorization }
+      : undefined,
+  });
+}
+
+const observability = makeObservability({
+  serviceName: "shopping-ms",
+  serviceVersion: "1.2.3",
+  resource: {
+    "service.namespace": "shopping",
+    "deployment.environment": "production",
+  },
+  otlp: grafanaCloudCollector({
+    endpoint: process.env.GRAFANA_OTLP_ENDPOINT!,
+    authorization: process.env.GRAFANA_OTLP_AUTHORIZATION,
+  }),
+});
+```
+
+For AppDynamics, prefer sending Brass telemetry to the AppDynamics/OpenTelemetry
+Collector deployed next to the service. Authentication and vendor-specific
+exporters stay in the collector config:
+
+```ts
+function appDynamicsCollector(input: {
+  readonly endpoint: string;
+}): ObservabilityOtlpOptions {
+  return productionOtlp({
+    endpoint: input.endpoint,
+  });
+}
+
+const observability = makeObservability({
+  serviceName: "car-rental-ms",
+  serviceVersion: "1.2.3",
+  resource: {
+    "service.namespace": "car-rental",
+    "deployment.environment": "production",
+  },
+  otlp: appDynamicsCollector({
+    endpoint: process.env.APPD_OTEL_COLLECTOR_ENDPOINT ?? "http://appd-otel-collector:4318",
+  }),
+});
+```
+
+Then attach the same observability instance to HTTP without changing the
+collector helpers:
+
+```ts
+import { makeDefaultHttpClient } from "brass-runtime/http";
+import { withHttpObservability } from "brass-runtime/observability";
+
+const http = makeDefaultHttpClient({
+  baseUrl: "https://api.example.com",
+  middleware: [withHttpObservability(observability)],
+});
+```
+
 Sampling can be configured globally, by ratio, or with rules:
 
 ```ts
@@ -423,6 +526,10 @@ const router = makeHttpRouter([
 
 Runnable framework examples live in
 [`docs/observability-framework-examples.md`](./observability-framework-examples.md).
+Production-style framework integration recipes live in
+[`docs/framework-integrations.md`](./framework-integrations.md).
+For a NestJS module recipe with Grafana/OTLP, DI tokens, HTTP client
+observability, and shutdown wiring, see [`docs/frameworks/nestjs.md`](./frameworks/nestjs.md).
 
 Collector smoke and performance budget helpers:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brass-runtime",
-  "version": "1.16.1",
+  "version": "1.17.0",
   "description": "Effect runtime utilities for TypeScript",
   "license": "MIT",
   "author": "Augusto Vivaldelli",