@crvouga/mockingbird-service-otel 3.3.0 → 3.4.0

package/CHANGELOG.md

@@ -1,6 +1,16 @@
 # Changelog — @crvouga/mockingbird-service-otel
 
-## 3.3.0 (2026-10-11)
+## 3.4.0 (2026-10-12)
+
+### Features
+
+- unify the emulator control plane ([2068547](https://github.com/crvouga/mockingbird/commit/2068547bedde4e2e2331c1657c1a78120e84428b))
+
+### Dependencies
+
+- `@crvouga/mockingbird-service-sqlite`
+
+## 3.3.0 (2026-10-10)
 
 ### Features
 

package/DISCOVERY.md

@@ -35,6 +35,7 @@ repository; live parity is an additional oracle check, not a substitute for the
 
 - `GET /__admin/health`
 - `GET /__admin`
+- `GET /__admin/controls`
 - `GET /__admin/state`
 - `GET /__admin/requests`
 - `GET /__admin/metrics`
@@ -45,6 +46,28 @@ For HTTP services, use `x-mockingbird-namespace` (or the documented credential/p
 parallel tests do not share state. Admin state, journal, metrics and fault-preset endpoints are
 designed for assertions and diagnosis by consuming test suites.
 
+## Admin controls
+
+Every HTTP emulator takes the same controls, and each means the same thing at boot
+(`createRuntime({ adminControls })`, `serve --admin-controls`), over `/__admin`, and in a request header:
+
+| Control | Admin API | Request header | Interface |
+| --- | --- | --- | --- |
+| Isolate state by key | `GET /__admin/namespaces` | `x-mockingbird-namespace: <key>` | [Namespaces](https://mockingbird.chrisvouga.dev/docs/admin-controls/namespaces) |
+| Reset to boot | `POST /__admin/reset` | `x-mockingbird-reset: true` | [Reset](https://mockingbird.chrisvouga.dev/docs/admin-controls/reset) |
+| Snapshot and restore | `POST /__admin/snapshots`, `POST /__admin/snapshots/<id>/restore` | `x-mockingbird-snapshot: <name>`, `x-mockingbird-restore: <name>` | [Snapshot and restore](https://mockingbird.chrisvouga.dev/docs/admin-controls/snapshot-and-restore) |
+| Move the clock | `POST /__admin/clock` | `x-mockingbird-time: <instant>`, `x-mockingbird-advance: <duration>` | [Clock](https://mockingbird.chrisvouga.dev/docs/admin-controls/clock) |
+| Read or branch from old state | `GET /__admin/timeline` | `x-mockingbird-at: <checkpoint>`, `x-mockingbird-branch: <name>` | [Checkpoints and branches](https://mockingbird.chrisvouga.dev/docs/admin-controls/checkpoints-and-branches) |
+| Inject a fault | `POST /__admin/faults` | `x-mockingbird-fault: <fault>` | [Faults](https://mockingbird.chrisvouga.dev/docs/admin-controls/faults) |
+| Latency and timeouts | `PUT /__admin/latency` | `x-mockingbird-delay: <duration>`, `x-mockingbird-timeout: <duration>` | [Latency and timeouts](https://mockingbird.chrisvouga.dev/docs/admin-controls/latency-and-timeouts) |
+| Replay from a seed | `PUT /__admin/controls` | `x-mockingbird-seed: <seed>` | [Seed and determinism](https://mockingbird.chrisvouga.dev/docs/admin-controls/seed-and-determinism) |
+| See what happened | `GET /__admin/requests`, `GET /__admin/state` | | [Journal, metrics and state](https://mockingbird.chrisvouga.dev/docs/admin-controls/journal-and-state) |
+
+`GET /__admin` lists every route and header with a one-line summary, and `GET /__admin/controls`
+is the namespace's current control document. The same seed and the same requests give the same
+bytes. Setting controls as an emulator starts is [Boot](https://mockingbird.chrisvouga.dev/docs/admin-controls/boot); every route and header is in
+the [Reference](https://mockingbird.chrisvouga.dev/docs/admin-controls/reference). The full guide: <https://mockingbird.chrisvouga.dev/docs/admin-controls>.
+
 ## Report a mismatch or missing capability
 
 Follow the [agent reporting contract](https://github.com/crvouga/mockingbird/blob/main/docs/REPORTING_ISSUES.md). Include package version,

package/README.md

@@ -37,44 +37,51 @@ npx mockingbird-otel serve --ingest-basic-auth "$OTLP_INSTANCE_ID:$OTLP_TOKEN"
 ```
 
 ```ts
-import { createRuntime } from "@crvouga/mockingbird-service-otel"
-
-const otel = createRuntime()
-const call = (path: string, init: RequestInit) => otel.fetch(new Request(`http://otel.test${path}`, init))
-
-// What @opentelemetry/exporter-logs-otlp-http sends for one winston/pino event log.
-await call("/v1/logs", {
-  method: "POST",
-  headers: { "content-type": "application/json", authorization: "Bearer ingest-token" },
-  body: JSON.stringify({
-    resourceLogs: [{
-      resource: { attributes: [{ key: "service.name", value: { stringValue: "backend" } }] },
-      scopeLogs: [{ logRecords: [{
-        severityText: "info",
-        body: { stringValue: "reconcile done" }, // dropped: bodies are never stored
-        attributes: [
-          { key: "event", value: { stringValue: "initial_credit_reconcile_completed" } },
-          { key: "granted", value: { intValue: "1" } },
-        ],
-      }] }],
-    }],
-  }),
+import { SeverityNumber } from "@opentelemetry/api-logs"
+import { OTLPLogExporter } from "@opentelemetry/exporter-logs-otlp-http"
+import { resourceFromAttributes } from "@opentelemetry/resources"
+import { LoggerProvider, SimpleLogRecordProcessor } from "@opentelemetry/sdk-logs"
+import { createServer } from "@crvouga/mockingbird-service-otel/server"
+
+const server = await createServer()
+
+// The OpenTelemetry SDK your application already uses. Only the exporter's URL changes.
+const exporter = new OTLPLogExporter({
+  url: `${server.url}/v1/logs`,
+  headers: { authorization: "Bearer ingest-token" },
+})
+const loggerProvider = new LoggerProvider({
+  resource: resourceFromAttributes({ "service.name": "backend" }),
+  processors: [new SimpleLogRecordProcessor(exporter)],
+})
+loggerProvider.getLogger("backend").emit({
+  severityNumber: SeverityNumber.INFO,
+  severityText: "info",
+  body: "reconcile done", // dropped: bodies are never stored
+  attributes: { event: "initial_credit_reconcile_completed", granted: 1 },
 })
+await loggerProvider.forceFlush()
 
-// Long-poll until it lands, then query it the way our O2 clients do.
-await call("/__admin/wait", {
+// Test control: long-poll until the event lands.
+await fetch(`${server.url}/__admin/wait`, {
   method: "POST",
   headers: { "content-type": "application/json" },
   body: JSON.stringify({ kind: "log", where: { event: "initial_credit_reconcile_completed" } }),
 })
-const search = await call("/api/30rBqcDevOrg7Hn2KmQ4xW9sLtY/_search", {
+
+// Then query it the way our O2 clients do (OpenObserve's search API is plain HTTP).
+const search = await fetch(`${server.url}/api/30rBqcDevOrg7Hn2KmQ4xW9sLtY/_search`, {
   method: "POST",
   headers: { "content-type": "application/json", authorization: `Basic ${btoa("agent:pw")}` },
   body: JSON.stringify({
     query: { sql: `SELECT * FROM "default" WHERE event = 'initial_credit_reconcile_completed'` },
   }),
 })
+console.log(await search.json())
 // { hits: [{ service_name: "backend", event: "…", granted: 1, severity_text: "info", _timestamp }], … }
+
+await loggerProvider.shutdown()
+await server.close()
 ```
 
 ### Receiver