ref: Replace diagnostic channels with proprietary global hooks

.changeset/global-hooks-cutover.md

@@ -0,0 +1,5 @@
+---
+"braintrust": patch
+---
+
+wip ref: Replace diagnostic channels with proprietary global hooks

e2e/scenarios/nextjs-auto-instrumentation/template/app/api/test/route.ts

@@ -1,12 +1,20 @@
-import "braintrust"; // Triggers configureNode(), which applies patchTracingChannel
+import "braintrust"; // Registers Braintrust's global instrumentation hooks.
 import OpenAI from "openai";
-import { tracingChannel } from "node:diagnostics_channel";
 import { createServer } from "node:http";
 import type { AddressInfo } from "node:net";
 
 // Must be dynamic — this route starts an in-process HTTP server per request.
 export const dynamic = "force-dynamic";
 
+type InstrumentationHook = {
+  subscribe(handlers: InstrumentationHookHandlers): void;
+  unsubscribe(handlers: InstrumentationHookHandlers): boolean;
+};
+
+type InstrumentationHookHandlers = {
+  start(): void;
+};
+
 export async function GET() {
   // Spin up a minimal mock OpenAI server so no real API calls are made.
   const mockServer = createServer((_req, res) => {
@@ -33,19 +41,20 @@ export async function GET() {
   );
   const { port } = mockServer.address() as AddressInfo;
 
-  const channel = tracingChannel("orchestrion:openai:chat.completions.create");
-  let channelFired = false;
+  const hooks = (
+    globalThis as typeof globalThis & {
+      __braintrust_instrumentation_hooks?: Map<string, InstrumentationHook>;
+    }
+  ).__braintrust_instrumentation_hooks;
+  const hook = hooks?.get("orchestrion:openai:chat.completions.create");
+  let hookFired = false;
   const subscriber = {
     start: () => {
-      channelFired = true;
+      hookFired = true;
     },
-    end: () => {},
-    asyncStart: () => {},
-    asyncEnd: () => {},
-    error: () => {},
   };
 
-  channel.subscribe(subscriber);
+  hook?.subscribe(subscriber);
 
   try {
     const client = new OpenAI({
@@ -58,9 +67,9 @@ export async function GET() {
       messages: [{ role: "user", content: "hi" }],
     });
   } finally {
-    channel.unsubscribe(subscriber);
+    hook?.unsubscribe(subscriber);
     mockServer.close();
   }
 
-  return Response.json({ instrumented: channelFired });
+  return Response.json({ instrumented: hookFired });
 }

e2e/scenarios/nextjs-auto-instrumentation/template/scenario.ts

@@ -98,12 +98,12 @@ async function main() {
 
     if (!data.instrumented) {
       throw new Error(
-        `OpenAI tracing channel did not fire; Next.js ${bundler} instrumentation is not working`,
+        `OpenAI global hook did not fire; Next.js ${bundler} instrumentation is not working`,
       );
     }
 
     console.log(
-      `OpenAI tracing channel fired at runtime; Next.js ${bundler} instrumentation is active`,
+      `OpenAI global hook fired at runtime; Next.js ${bundler} instrumentation is active`,
     );
 
     const edgeResponse = await httpGet(`http://localhost:${PORT}/api/edge`);

e2e/scenarios/openai-agents-instrumentation/scenario.impl.mjs

@@ -37,7 +37,7 @@ export async function runOpenAIAgentsAutoInstrumentationScenario() {
 
   // Remove the built-in OpenAI trace exporter so it doesn't POST to
   // api.openai.com/v1/traces/ingest with the cassette placeholder key.
-  // Braintrust captures trace events via diagnostics_channel independently.
+  // Braintrust captures trace events via global instrumentation hooks independently.
   setTraceProcessors([]);
 
   await runTracedScenario({

js/NOTICE

@@ -18,3 +18,9 @@ licenses/import-in-the-middle/NOTICE.
 This package also includes a modified fork of require-in-the-middle 8.0.1.
 require-in-the-middle is licensed under the MIT License.
 See licenses/require-in-the-middle/LICENSE.
+
+The global instrumentation hook runtime is adapted from the Node.js
+diagnostics_channel TracingChannel implementation.
+Copyright Node.js contributors. All rights reserved.
+It is licensed under the MIT License.
+See licenses/node-diagnostics-channel/LICENSE.

js/licenses/node-diagnostics-channel/LICENSE

@@ -0,0 +1,19 @@
+Copyright Node.js contributors. All rights reserved.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to
+deal in the Software without restriction, including without limitation the
+rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+sell copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+IN THE SOFTWARE.

js/package.json

@@ -224,7 +224,6 @@
     "cli-progress": "^3.12.0",
     "cli-table3": "^0.6.5",
     "cors": "^2.8.5",
-    "dc-browser": "^1.0.4",
     "dotenv": "^16.4.5",
     "esbuild": "0.28.1",
     "esquery": "^1.7.0",