Recommend batched span export for Firebase instrumentation (#40)

Author: marcusschiesser

.changeset/batched-firebase-span-export.md

@@ -0,0 +1,5 @@
+---
+"agentpond": patch
+---
+
+Recommend batched OpenTelemetry span export for Firebase instrumentation so each stored object can contain multiple spans.

docs/direct-object-store-export.md

@@ -57,6 +57,8 @@ sdk.start();
 await sdk.shutdown();
 ```
 
+NodeSDK wraps `traceExporter` in a `BatchSpanProcessor`. AgentPond preserves each exporter invocation as one immutable object-store object, so a batch of spans is written as one object. If you configure span processors directly, prefer `BatchSpanProcessor` for production and force-flush at the application's real lifecycle boundary.
+
 ## Object Stores
 
 Use the matching adapter for the deployment:

packages/otel/tests/otel.test.ts

@@ -17,6 +17,7 @@ import { resourceFromAttributes } from "@opentelemetry/resources";
 import { NodeSDK } from "@opentelemetry/sdk-node";
 import {
 	BasicTracerProvider,
+	BatchSpanProcessor,
 	InMemorySpanExporter,
 	type ReadableSpan,
 	SimpleSpanProcessor,
@@ -144,6 +145,40 @@ test("empty exports succeed without writing an object", async () => {
 	await exporter.shutdown();
 });
 
+test("a batched exporter invocation writes multiple spans in one object", async () => {
+	const store = new MemoryObjectStore();
+	const exporter = new AgentPondSpanExporter({
+		store,
+		projectId: "project-a",
+	});
+	const provider = new BasicTracerProvider({
+		resource: resourceFromAttributes({ "service.name": "batched-export-test" }),
+		spanProcessors: [new BatchSpanProcessor(exporter)],
+	});
+	const tracer = provider.getTracer("batched-export-test");
+
+	tracer.startSpan("first span").end();
+	tracer.startSpan("second span").end();
+	await provider.forceFlush();
+
+	const keys = await store.listKeys("otel/project-a/");
+	assert.equal(keys.length, 1);
+	const resourceSpans = await store.getJson<
+		Array<{ scopeSpans?: Array<{ spans?: unknown[] }> }>
+	>(keys[0]);
+	const storedSpanCount = resourceSpans.reduce(
+		(resourceCount, resourceSpan) =>
+			resourceCount +
+			(resourceSpan.scopeSpans ?? []).reduce(
+				(scopeCount, scopeSpan) => scopeCount + (scopeSpan.spans?.length ?? 0),
+				0,
+			),
+		0,
+	);
+	assert.equal(storedSpanCount, 2);
+	await provider.shutdown();
+});
+
 test("storage failures are returned through the exporter callback", async () => {
 	class FailingStore extends MemoryObjectStore {
 		override async putJson(): Promise<void> {

skills/agentpond-instrumentation/SKILL.md

@@ -63,7 +63,7 @@ Stop after presenting the proposal and ask for explicit confirmation before inst
 3. Create or update one centralized server instrumentation module.
 4. Reuse an existing default Firebase Admin app. Add default initialization only when it is absent; follow [references/firebase.md](references/firebase.md).
 5. Create `createFirebaseSpanExporter()` after the default app exists.
-6. Add the exporter to the existing provider. When no provider exists, create one using APIs supported by the installed OpenTelemetry version and a processor appropriate for direct export.
+6. Add the exporter to the existing provider. When no provider exists, create one using APIs supported by the installed OpenTelemetry version and prefer NodeSDK's batched `traceExporter` configuration or an explicit `BatchSpanProcessor`.
 7. Register the selected OpenInference instrumentation before AI clients are created.
 8. Add manual CHAIN and TOOL spans only where auto-instrumentation leaves important application behavior invisible.
 9. Preserve one `session.id` across all turns in the same conversation.

skills/agentpond-instrumentation/references/firebase.md

@@ -41,12 +41,9 @@ When no provider exists, a typical Node SDK shape is:
 ```ts
 import { createFirebaseSpanExporter } from "@agentpond/firebase";
 import { NodeSDK } from "@opentelemetry/sdk-node";
-import { SimpleSpanProcessor } from "@opentelemetry/sdk-trace-base";
 
 const sdk = new NodeSDK({
-  spanProcessors: [
-    new SimpleSpanProcessor(createFirebaseSpanExporter()),
-  ],
+  traceExporter: createFirebaseSpanExporter(),
   instrumentations: [
     // Add the integration selected for the detected AI SDK or framework.
   ],
@@ -55,7 +52,9 @@ const sdk = new NodeSDK({
 sdk.start();
 ```
 
-Adapt the construction to the installed SDK API and project lifecycle. Initialize the module before instrumented clients. Force-flush at a real lifecycle boundary when required; do not shut down a reusable Functions instance after every request.
+NodeSDK wraps `traceExporter` in a `BatchSpanProcessor`, so each exporter invocation can contain multiple spans and AgentPond writes one object per exported batch. When constructing a provider manually or tuning queue and batch settings, create a `BatchSpanProcessor` explicitly instead. Do not use `SimpleSpanProcessor` for normal production export because it invokes the exporter separately for every ended span.
+
+Adapt the construction to the installed SDK API and project lifecycle. Initialize the module before instrumented clients. Force-flush at a real lifecycle boundary when required so queued batches finish exporting; do not shut down a reusable Functions instance after every request.
 
 ## Storage Rules review
 

tests/skills.test.ts

@@ -51,6 +51,8 @@ test("Firebase instrumentation skill preserves the setup and verification workfl
 		/Storage Rules/i,
 		/nested block/i,
 		/framework-native/i,
+		/traceExporter/,
+		/BatchSpanProcessor/,
 		/CHAIN/,
 		/TOOL/,
 		/session\.id/,
@@ -60,4 +62,5 @@ test("Firebase instrumentation skill preserves the setup and verification workfl
 	]) {
 		assert.match(content, required);
 	}
+	assert.doesNotMatch(content, /new SimpleSpanProcessor/);
 });