Add OTLP tracing endpoint flag and config key

New --tracing-endpoint flag (and tracingEndpoint config key) wires an
OTLP/HTTP traces exporter into a NodeTracerProvider so spans emitted by
@nilenso/megasthenes are shipped to Arize Phoenix (or any OTLP-compatible
collector). The URL is normalised to append /v1/traces when a bare base
URL is given. Spans are flushed via shutdownTracing() in the ask
command's finally block.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: kirang89

package.json

@@ -52,6 +52,12 @@
   },
   "dependencies": {
     "@nilenso/megasthenes": "file:../ask-forge",
+    "@opentelemetry/api": "^1.9.1",
+    "@opentelemetry/exporter-trace-otlp-http": "^0.215.0",
+    "@opentelemetry/resources": "^2.7.0",
+    "@opentelemetry/sdk-trace-base": "^2.7.0",
+    "@opentelemetry/sdk-trace-node": "^2.7.0",
+    "@opentelemetry/semantic-conventions": "^1.40.0",
     "marked": "^15.0.0",
     "marked-terminal": "^7.2.1"
   },

src/cli/ask-args.ts

@@ -30,6 +30,9 @@ export interface ParsedArgs {
 	sandboxTimeoutMs?: number;
 	sandboxSecret?: string;
 
+	// Tracing
+	tracingEndpoint?: string;
+
 	// Output
 	verbose: boolean;
 	json: boolean;
@@ -120,6 +123,10 @@ export function parseAskArgs(argv: readonly string[]): ParsedArgs {
 				out.sandboxSecret = consume();
 				break;
 
+			case "--tracing-endpoint":
+				out.tracingEndpoint = consume();
+				break;
+
 			case "--verbose":
 				out.verbose = true;
 				break;
@@ -171,6 +178,11 @@ Sandbox options:
   --sandbox-timeout-ms <ms>     Per-request timeout for sandbox calls.
   --sandbox-secret <s>          Shared secret for sandbox auth.
 
+Tracing options:
+  --tracing-endpoint <url>      OTLP/HTTP traces endpoint (e.g. Arize Phoenix at
+                                http://localhost:6006). The path "/v1/traces" is
+                                appended automatically if omitted.
+
 Output options:
   --verbose                     Stream tool calls, iteration starts, and errors to stderr.
   --json                        Emit the full TurnResult as JSON to stdout instead of markdown.

src/cli/ask-config.ts

@@ -29,6 +29,7 @@ export interface ResolvedConfig {
 	question: string;
 	verbose: boolean;
 	json: boolean;
+	tracingEndpoint?: string;
 }
 
 export type FileConfig = Partial<
@@ -48,6 +49,7 @@ export type FileConfig = Partial<
 		| "sandboxBaseUrl"
 		| "sandboxTimeoutMs"
 		| "sandboxSecret"
+		| "tracingEndpoint"
 	>
 >;
 
@@ -71,6 +73,7 @@ const ALLOWED_FILE_KEYS = [
 	"sandboxBaseUrl",
 	"sandboxTimeoutMs",
 	"sandboxSecret",
+	"tracingEndpoint",
 ] as const;
 
 export function defaultConfigPath(env: NodeJS.ProcessEnv): string | undefined {
@@ -148,6 +151,7 @@ export function parseFileConfig(raw: string, path: string): FileConfig {
 	setString("systemPromptFile");
 	setString("sandboxBaseUrl");
 	setString("sandboxSecret");
+	setString("tracingEndpoint");
 	setPosInt("maxIterations");
 	setPosInt("sandboxTimeoutMs");
 	setBool("verbose");
@@ -211,13 +215,16 @@ export function resolveConfig(
 		logger: nullLogger,
 	};
 
+	const tracingEndpoint = args.tracingEndpoint ?? file.tracingEndpoint;
+
 	return {
 		clientConfig,
 		sessionConfig,
 		askOptions: {},
 		question: args.question,
 		verbose: args.verbose || (file.verbose ?? false),
 		json: args.json || (file.json ?? false),
+		...(tracingEndpoint !== undefined ? { tracingEndpoint } : {}),
 	};
 }
 

src/cli/ask.ts

@@ -11,6 +11,7 @@ import { ASK_HELP, ArgParseError, parseAskArgs } from "./ask-args.ts";
 import { resolveConfig } from "./ask-config.ts";
 import { extractFinalAnswer, formatSummary, renderMarkdown } from "./ask-render.ts";
 import { findMissingTools, formatMissingToolsError } from "./check-tools.ts";
+import { setupTracing, shutdownTracing } from "./tracing.ts";
 
 const ERROR_EXIT_CODES: Record<ErrorType, number> = {
 	internal_error: 1,
@@ -50,7 +51,13 @@ export async function runAsk(argv: readonly string[]): Promise<number> {
 		throw e;
 	}
 
-	const { clientConfig, sessionConfig, askOptions, question, verbose, json } = resolved;
+	const { clientConfig, sessionConfig, askOptions, question, verbose, json, tracingEndpoint } =
+		resolved;
+
+	if (tracingEndpoint !== undefined) {
+		setupTracing(tracingEndpoint);
+		if (verbose) process.stderr.write(`[tracing] OTLP endpoint: ${tracingEndpoint}\n`);
+	}
 
 	// Preflight: in local mode the library shells out to git/rg/fd. Skip when
 	// running against a sandbox worker (those tools live in the worker, not here).
@@ -111,6 +118,8 @@ export async function runAsk(argv: readonly string[]): Promise<number> {
 		} catch {
 			// ignore close errors
 		}
+		// Flush pending spans before the process exits.
+		await shutdownTracing();
 	}
 }
 

src/cli/tracing.ts

@@ -0,0 +1,47 @@
+/**
+ * OTLP/HTTP tracing setup. When an endpoint is configured, register a global
+ * tracer provider so spans emitted by @nilenso/megasthenes (via
+ * @opentelemetry/api) are exported to a collector such as Arize Phoenix,
+ * Langfuse, Jaeger, or any OTLP-compatible receiver.
+ *
+ * The library uses trace.getTracer() lazily on each span creation, so
+ * registering the provider before client.connect() is sufficient.
+ */
+
+import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
+import { resourceFromAttributes } from "@opentelemetry/resources";
+import { BatchSpanProcessor } from "@opentelemetry/sdk-trace-base";
+import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
+import { ATTR_SERVICE_NAME } from "@opentelemetry/semantic-conventions";
+
+let provider: NodeTracerProvider | undefined;
+
+/**
+ * Resolve a user-provided endpoint to the full OTLP/HTTP traces URL. Accepts
+ * either a base URL (`http://localhost:6006`) — in which case `/v1/traces` is
+ * appended — or a fully-qualified traces URL.
+ */
+export function resolveTracesUrl(endpoint: string): string {
+	const trimmed = endpoint.replace(/\/$/, "");
+	return trimmed.endsWith("/v1/traces") ? trimmed : `${trimmed}/v1/traces`;
+}
+
+export function setupTracing(endpoint: string): void {
+	if (provider !== undefined) return;
+	const url = resolveTracesUrl(endpoint);
+	provider = new NodeTracerProvider({
+		resource: resourceFromAttributes({ [ATTR_SERVICE_NAME]: "megasthenes-cli" }),
+		spanProcessors: [new BatchSpanProcessor(new OTLPTraceExporter({ url }))],
+	});
+	provider.register();
+}
+
+export async function shutdownTracing(): Promise<void> {
+	if (provider === undefined) return;
+	try {
+		await provider.shutdown();
+	} catch {
+		// ignore shutdown errors — best-effort flush
+	}
+	provider = undefined;
+}