Add AgentPond tracing to development examples

.gitignore

@@ -11,6 +11,7 @@ lib/
 .env
 .env.local
 .env.*.local
+.agentpond/
 
 # Logs
 logs
@@ -40,4 +41,4 @@ temp/
 /dev-output/
 
 # Keep the .gitmodules file that defines the submodule
-!/.gitmodules 
+!/.gitmodules

README.md

@@ -680,6 +680,33 @@ Our URL validation system provides several key benefits:
 
 This approach ensures reliable URL extraction while maintaining the full power of Zod's schema validation.
 
+## AgentPond tracing
+
+The executable extraction example supports opt-in
+[AgentPond](https://github.com/marcusschiesser/agentpond) tracing. The
+instrumentation runs only when a Files SDK environment is loaded; importing
+`@lightfeed/extractor` as a library remains unchanged.
+
+```bash
+npx agentpond init
+npx agentpond env init local \
+  --provider fs \
+  --root "$PWD/.agentpond/envs/local/objects"
+npx agentpond env use local
+
+eval "$(npx agentpond env get local)"
+npm run test:usage
+
+npx agentpond sync
+npx agentpond traces list --limit 10
+```
+
+The local `fs` provider is for development only. For deployed trusted Node.js
+services, configure a persistent provider from the
+[Files SDK provider catalog](https://files-sdk.dev/docs/providers). OpenInference
+captures model inputs and outputs, so review the data policy before enabling
+tracing with production traffic.
+
 ## Development
 
 ### Setup

agentpond-instrumentation.cjs

@@ -0,0 +1,52 @@
+"use strict";
+
+require("dotenv/config");
+
+const {
+  LangChainInstrumentation,
+} = require("@arizeai/openinference-instrumentation-langchain");
+const { resourceFromAttributes } = require("@opentelemetry/resources");
+const { BatchSpanProcessor } = require("@opentelemetry/sdk-trace-base");
+const { NodeTracerProvider } = require("@opentelemetry/sdk-trace-node");
+const CallbackManagerModule = require("@langchain/core/callbacks/manager");
+
+let tracerProvider;
+let startupPromise;
+let shutdownPromise;
+
+function startAgentPondTracing() {
+  if (!process.env.FILES_SDK_PROVIDER || tracerProvider) {
+    return Promise.resolve();
+  }
+  startupPromise ??= initializeAgentPondTracing();
+  return startupPromise;
+}
+
+async function initializeAgentPondTracing() {
+  const { createFilesSpanExporterFromRuntimeEnv } =
+    await import("@agentpond/files-sdk/otel");
+
+  tracerProvider = new NodeTracerProvider({
+    resource: resourceFromAttributes({
+      "service.name": "lightfeed-extractor-example",
+    }),
+    spanProcessors: [
+      new BatchSpanProcessor(createFilesSpanExporterFromRuntimeEnv()),
+    ],
+  });
+  tracerProvider.register();
+
+  const instrumentation = new LangChainInstrumentation({ tracerProvider });
+  instrumentation.manuallyInstrument(CallbackManagerModule);
+}
+
+function shutdownAgentPondTracing() {
+  if (!tracerProvider) return Promise.resolve();
+  shutdownPromise ??= tracerProvider.shutdown();
+  return shutdownPromise;
+}
+
+module.exports = {
+  shutdownAgentPondTracing,
+  startAgentPondTracing,
+};