@agentuity/telemetry 3.0.0-alpha.0

package/dist/tracestate.d.ts

@@ -0,0 +1,44 @@
+import { type Context } from '@opentelemetry/api';
+/**
+ * Entries to set on the W3C tracestate header. Each key-value pair is added
+ * to the parent context's existing traceState (if any). Values that are
+ * `undefined` or empty strings are skipped.
+ */
+export type TraceStateEntries = Record<string, string | undefined>;
+/**
+ * Build a context whose span context carries an enriched W3C traceState.
+ *
+ * The returned context is intended to be passed as the **parent context**
+ * to `tracer.startActiveSpan(name, opts, enrichedCtx, fn)` or
+ * `tracer.startSpan(name, opts, enrichedCtx)`.  Because the OTel SDK
+ * copies `traceState` from a *valid* parent span context into every new
+ * child span, the recording span that gets exported to OTLP will carry the
+ * enriched traceState — making it visible in backends like ClickHouse.
+ *
+ * ### How it works
+ *
+ * 1. If the supplied `parentContext` already contains a span with a valid
+ *    span context (e.g. from an incoming `traceparent` header), we enrich
+ *    that span context's traceState and wrap it in a `NonRecordingSpan`.
+ *
+ * 2. If there is **no** valid parent span (e.g. no incoming `traceparent`),
+ *    we synthesise a minimal remote span context with a freshly generated
+ *    traceId.  The OTel SDK will treat this as a valid remote parent,
+ *    inherit both the traceId **and** the traceState, and mark the new
+ *    span as a continuation of that trace.
+ *
+ * @param parentContext  The context to enrich (typically `context.active()`).
+ * @param entries        Key-value pairs to merge into the traceState.
+ * @returns A new `Context` ready to be used as a parent for span creation.
+ */
+export declare function enrichContextWithTraceState(parentContext: Context, entries: TraceStateEntries): Context;
+/**
+ * Generate a random 32-hex-char trace ID (16 bytes).
+ * Uses the Web Crypto API which is available in Bun and Node 20+.
+ */
+export declare function generateTraceId(): string;
+/**
+ * Generate a random 16-hex-char span ID (8 bytes).
+ */
+export declare function generateSpanId(): string;
+//# sourceMappingURL=tracestate.d.ts.map

package/dist/tracestate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracestate.d.ts","sourceRoot":"","sources":["../src/tracestate.ts"],"names":[],"mappings":"AAAA,OAAO,EAAqB,KAAK,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAGrE;;;;GAIG;AACH,MAAM,MAAM,iBAAiB,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;AAEnE;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,2BAA2B,CAC1C,aAAa,EAAE,OAAO,EACtB,OAAO,EAAE,iBAAiB,GACxB,OAAO,CAuCT;AAID;;;GAGG;AACH,wBAAgB,eAAe,IAAI,MAAM,CAIxC;AAED;;GAEG;AACH,wBAAgB,cAAc,IAAI,MAAM,CAIvC"}

package/dist/tracestate.js

@@ -0,0 +1,84 @@
+import { trace, TraceFlags } from '@opentelemetry/api';
+import { TraceState } from '@opentelemetry/core';
+/**
+ * Build a context whose span context carries an enriched W3C traceState.
+ *
+ * The returned context is intended to be passed as the **parent context**
+ * to `tracer.startActiveSpan(name, opts, enrichedCtx, fn)` or
+ * `tracer.startSpan(name, opts, enrichedCtx)`.  Because the OTel SDK
+ * copies `traceState` from a *valid* parent span context into every new
+ * child span, the recording span that gets exported to OTLP will carry the
+ * enriched traceState — making it visible in backends like ClickHouse.
+ *
+ * ### How it works
+ *
+ * 1. If the supplied `parentContext` already contains a span with a valid
+ *    span context (e.g. from an incoming `traceparent` header), we enrich
+ *    that span context's traceState and wrap it in a `NonRecordingSpan`.
+ *
+ * 2. If there is **no** valid parent span (e.g. no incoming `traceparent`),
+ *    we synthesise a minimal remote span context with a freshly generated
+ *    traceId.  The OTel SDK will treat this as a valid remote parent,
+ *    inherit both the traceId **and** the traceState, and mark the new
+ *    span as a continuation of that trace.
+ *
+ * @param parentContext  The context to enrich (typically `context.active()`).
+ * @param entries        Key-value pairs to merge into the traceState.
+ * @returns A new `Context` ready to be used as a parent for span creation.
+ */
+export function enrichContextWithTraceState(parentContext, entries) {
+    const parentSpan = trace.getSpan(parentContext);
+    const parentSctx = parentSpan?.spanContext();
+    // Start from any existing traceState on the parent, or a fresh one.
+    let traceState = parentSctx?.traceState ?? new TraceState();
+    // Merge caller-supplied entries.
+    for (const [key, value] of Object.entries(entries)) {
+        if (value !== undefined && value !== '') {
+            traceState = traceState.set(key, value);
+        }
+    }
+    if (parentSctx && trace.isSpanContextValid(parentSctx)) {
+        // The parent already has a valid traceId/spanId (e.g. from an
+        // incoming request with `traceparent`).  We just need to update
+        // its traceState.
+        return trace.setSpan(parentContext, trace.wrapSpanContext({
+            ...parentSctx,
+            traceState,
+        }));
+    }
+    // No valid parent — synthesise a remote parent so the OTel SDK
+    // considers the span context valid and copies traceState to the child.
+    return trace.setSpan(parentContext, trace.wrapSpanContext({
+        traceId: generateTraceId(),
+        spanId: generateSpanId(),
+        traceFlags: TraceFlags.SAMPLED,
+        isRemote: true,
+        traceState,
+    }));
+}
+// ── ID generation helpers ────────────────────────────────────────────
+/**
+ * Generate a random 32-hex-char trace ID (16 bytes).
+ * Uses the Web Crypto API which is available in Bun and Node 20+.
+ */
+export function generateTraceId() {
+    const bytes = new Uint8Array(16);
+    crypto.getRandomValues(bytes);
+    return hexFromBytes(bytes);
+}
+/**
+ * Generate a random 16-hex-char span ID (8 bytes).
+ */
+export function generateSpanId() {
+    const bytes = new Uint8Array(8);
+    crypto.getRandomValues(bytes);
+    return hexFromBytes(bytes);
+}
+function hexFromBytes(bytes) {
+    let hex = '';
+    for (let i = 0; i < bytes.length; i++) {
+        hex += bytes[i].toString(16).padStart(2, '0');
+    }
+    return hex;
+}
+//# sourceMappingURL=tracestate.js.map

package/dist/tracestate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracestate.js","sourceRoot":"","sources":["../src/tracestate.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,UAAU,EAAgB,MAAM,oBAAoB,CAAC;AACrE,OAAO,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AASjD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,UAAU,2BAA2B,CAC1C,aAAsB,EACtB,OAA0B;IAE1B,MAAM,UAAU,GAAG,KAAK,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC;IAChD,MAAM,UAAU,GAAG,UAAU,EAAE,WAAW,EAAE,CAAC;IAE7C,oEAAoE;IACpE,IAAI,UAAU,GAAG,UAAU,EAAE,UAAU,IAAI,IAAI,UAAU,EAAE,CAAC;IAE5D,iCAAiC;IACjC,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;QACpD,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,EAAE,EAAE,CAAC;YACzC,UAAU,GAAG,UAAU,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QACzC,CAAC;IACF,CAAC;IAED,IAAI,UAAU,IAAI,KAAK,CAAC,kBAAkB,CAAC,UAAU,CAAC,EAAE,CAAC;QACxD,8DAA8D;QAC9D,gEAAgE;QAChE,kBAAkB;QAClB,OAAO,KAAK,CAAC,OAAO,CACnB,aAAa,EACb,KAAK,CAAC,eAAe,CAAC;YACrB,GAAG,UAAU;YACb,UAAU;SACV,CAAC,CACF,CAAC;IACH,CAAC;IAED,+DAA+D;IAC/D,uEAAuE;IACvE,OAAO,KAAK,CAAC,OAAO,CACnB,aAAa,EACb,KAAK,CAAC,eAAe,CAAC;QACrB,OAAO,EAAE,eAAe,EAAE;QAC1B,MAAM,EAAE,cAAc,EAAE;QACxB,UAAU,EAAE,UAAU,CAAC,OAAO;QAC9B,QAAQ,EAAE,IAAI;QACd,UAAU;KACV,CAAC,CACF,CAAC;AACH,CAAC;AAED,wEAAwE;AAExE;;;GAGG;AACH,MAAM,UAAU,eAAe;IAC9B,MAAM,KAAK,GAAG,IAAI,UAAU,CAAC,EAAE,CAAC,CAAC;IACjC,MAAM,CAAC,eAAe,CAAC,KAAK,CAAC,CAAC;IAC9B,OAAO,YAAY,CAAC,KAAK,CAAC,CAAC;AAC5B,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,cAAc;IAC7B,MAAM,KAAK,GAAG,IAAI,UAAU,CAAC,CAAC,CAAC,CAAC;IAChC,MAAM,CAAC,eAAe,CAAC,KAAK,CAAC,CAAC;IAC9B,OAAO,YAAY,CAAC,KAAK,CAAC,CAAC;AAC5B,CAAC;AAED,SAAS,YAAY,CAAC,KAAiB;IACtC,IAAI,GAAG,GAAG,EAAE,CAAC;IACb,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACvC,GAAG,IAAK,KAAK,CAAC,CAAC,CAAY,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IAC3D,CAAC;IACD,OAAO,GAAG,CAAC;AACZ,CAAC"}

package/package.json

@@ -0,0 +1,58 @@
+{
+	"name": "@agentuity/telemetry",
+	"version": "3.0.0-alpha.0",
+	"license": "Apache-2.0",
+	"author": "Agentuity employees and contributors",
+	"type": "module",
+	"main": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"exports": {
+		".": {
+			"import": "./dist/index.js",
+			"types": "./dist/index.d.ts"
+		}
+	},
+	"files": [
+		"src",
+		"dist"
+	],
+	"scripts": {
+		"clean": "rm -rf dist tsconfig.tsbuildinfo",
+		"build": "bunx tsc --build",
+		"typecheck": "bunx tsc --noEmit",
+		"prepublishOnly": "bun run clean && bun run build"
+	},
+	"dependencies": {
+		"@agentuity/core": "3.0.0-alpha.0",
+		"@agentuity/server": "3.0.0-alpha.0",
+		"@opentelemetry/api": "^1.9.0",
+		"@opentelemetry/api-logs": "^0.207.0",
+		"@opentelemetry/auto-instrumentations-node": "^0.66.0",
+		"@opentelemetry/core": "^2.2.0",
+		"@opentelemetry/exporter-logs-otlp-http": "^0.207.0",
+		"@opentelemetry/exporter-metrics-otlp-http": "^0.207.0",
+		"@opentelemetry/exporter-trace-otlp-http": "^0.207.0",
+		"@opentelemetry/host-metrics": "^0.36.2",
+		"@opentelemetry/otlp-exporter-base": "^0.207.0",
+		"@opentelemetry/resources": "^2.2.0",
+		"@opentelemetry/sdk-logs": "^0.207.0",
+		"@opentelemetry/sdk-metrics": "^2.2.0",
+		"@opentelemetry/sdk-node": "^0.207.0",
+		"@opentelemetry/sdk-trace-base": "^2.2.0",
+		"@opentelemetry/semantic-conventions": "^1.37.0"
+	},
+	"devDependencies": {
+		"@types/bun": "latest",
+		"bun-types": "latest",
+		"typescript": "^5.9.0"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"sideEffects": true,
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/agentuity/sdk.git",
+		"directory": "packages/telemetry"
+	}
+}

package/src/console.ts

@@ -0,0 +1,91 @@
+import { SeverityNumber } from '@opentelemetry/api-logs';
+import { type ExportResult, ExportResultCode } from '@opentelemetry/core';
+import type { LogRecordExporter, ReadableLogRecord } from '@opentelemetry/sdk-logs';
+import type { SpanExporter, ReadableSpan } from '@opentelemetry/sdk-trace-base';
+import { __originalConsole } from './logger';
+
+/**
+ * Console implementation of the LogRecordExporter interface
+ * Uses __originalConsole to avoid infinite loop when console is patched
+ */
+export class ConsoleLogRecordExporter implements LogRecordExporter {
+	private dumpRecords = false;
+
+	constructor(dumpRecords: boolean) {
+		this.dumpRecords = dumpRecords;
+	}
+	/**
+	 * Exports log records to the console
+	 *
+	 * @param logs - The log records to export
+	 * @param resultCallback - Callback function to report the export result
+	 */
+	export(logs: ReadableLogRecord[], resultCallback: (result: ExportResult) => void): void {
+		for (const log of logs) {
+			if (this.dumpRecords) {
+				__originalConsole.log('[LOG]', {
+					body: log.body,
+					severityNumber: log.severityNumber,
+					severityText: log.severityText,
+					timestamp: log.hrTime,
+					attributes: log.attributes,
+					resource: log.resource.attributes,
+				});
+			} else {
+				const severity = log.severityNumber ? SeverityNumber[log.severityNumber] : 'INFO';
+				const msg = `[${severity}] ${log.body}`;
+				switch (log.severityNumber) {
+					case SeverityNumber.DEBUG:
+						__originalConsole.debug(msg);
+						break;
+					case SeverityNumber.INFO:
+						__originalConsole.info(msg);
+						break;
+					case SeverityNumber.WARN:
+						__originalConsole.warn(msg);
+						break;
+					case SeverityNumber.ERROR:
+						__originalConsole.error(msg);
+						break;
+					default:
+						__originalConsole.log(msg);
+						break;
+				}
+			}
+		}
+		resultCallback({ code: ExportResultCode.SUCCESS });
+	}
+
+	/**
+	 * Shuts down the exporter
+	 *
+	 * @returns A promise that resolves when shutdown is complete
+	 */
+	shutdown(): Promise<void> {
+		return Promise.resolve();
+	}
+}
+
+/**
+ * Console implementation of the SpanExporter interface
+ * Uses __originalConsole to avoid infinite loop when console is patched
+ */
+export class DebugSpanExporter implements SpanExporter {
+	export(spans: ReadableSpan[], resultCallback: (result: ExportResult) => void): void {
+		for (const span of spans) {
+			__originalConsole.log('[SPAN]', {
+				name: span.name,
+				traceId: span.spanContext().traceId,
+				spanId: span.spanContext().spanId,
+				duration: span.duration,
+				status: span.status,
+				attributes: span.attributes,
+			});
+		}
+		resultCallback({ code: ExportResultCode.SUCCESS });
+	}
+
+	shutdown(): Promise<void> {
+		return Promise.resolve();
+	}
+}

package/src/exporters/README.md

@@ -0,0 +1,217 @@
+# JSONL Exporters
+
+Custom OpenTelemetry exporters that write telemetry data (logs, traces, metrics) to JSONL (JSON Lines) files instead of sending directly to an OTLP endpoint.
+
+## Overview
+
+These exporters write telemetry data to local files in JSONL format. Each line in the file represents a single telemetry item in JSON format. This allows for:
+
+1. **Decoupled Processing**: Telemetry data is buffered locally and processed separately
+2. **Reliability**: Data persists even if the OTLP endpoint is temporarily unavailable
+3. **Batch Processing**: A separate cron job can read and send data in batches
+4. **Easy Debugging**: JSONL files can be inspected directly
+
+## How It Works
+
+### 1. Writing Telemetry Data
+
+The exporters write telemetry data to timestamped JSONL files:
+
+- **Logs**: `./otel-data/logs-<timestamp>.jsonl`
+- **Traces**: `./otel-data/traces-<timestamp>.jsonl`
+- **Metrics**: `./otel-data/metrics-<timestamp>.jsonl`
+
+Files are named with an ISO timestamp (with colons and periods replaced by hyphens) to ensure uniqueness. The exporters will continue writing to the same file as long as it exists.
+
+### 2. Reading and Forwarding Data (External Process)
+
+A separate cron job (recommended: every 30 seconds) should:
+
+1. Read the JSONL files
+2. Parse each line as a JSON object
+3. Send the telemetry data to your OTLP endpoint
+4. Delete the file after successful transmission
+
+This decouples the application from the OTLP endpoint and provides resilience.
+
+## Configuration
+
+### Enabling JSONL Exporters
+
+By default, JSONL exporters are enabled. You can configure them via the `OtelConfig`:
+
+```typescript
+import { registerOtel } from '@agentuity/runtime/otel';
+
+registerOtel({
+	name: 'my-app',
+	version: '1.0.0',
+	url: 'https://otel.example.com',
+	useJsonlExporter: true, // Enable JSONL exporters (default: true)
+	jsonlBasePath: './.agentuity/otel-data', // Directory for JSONL files
+});
+```
+
+### Disabling JSONL Exporters
+
+To use the original OTLP exporters (direct network calls):
+
+```typescript
+registerOtel({
+	name: 'my-app',
+	version: '1.0.0',
+	url: 'https://otel.example.com',
+	useJsonlExporter: false, // Disable JSONL, use OTLP directly
+});
+```
+
+## File Format
+
+### Logs
+
+Each log entry contains:
+
+```json
+{
+	"timestamp": [seconds, nanoseconds],
+	"observedTimestamp": [seconds, nanoseconds],
+	"severityNumber": 9,
+	"severityText": "INFO",
+	"body": "Log message",
+	"attributes": { "key": "value" },
+	"resource": { "@agentuity/orgId": "...", ... },
+	"instrumentationScope": { "name": "...", "version": "..." },
+	"spanContext": { "traceId": "...", "spanId": "...", ... }
+}
+```
+
+### Traces
+
+Each span contains:
+
+```json
+{
+	"traceId": "...",
+	"spanId": "...",
+	"traceState": "...",
+	"name": "operation-name",
+	"kind": 1,
+	"startTime": [seconds, nanoseconds],
+	"endTime": [seconds, nanoseconds],
+	"attributes": { "key": "value" },
+	"status": { "code": 0 },
+	"events": [],
+	"links": [],
+	"resource": { "@agentuity/orgId": "...", ... },
+	"droppedAttributesCount": 0,
+	"droppedEventsCount": 0,
+	"droppedLinksCount": 0,
+	"duration": [seconds, nanoseconds],
+	"ended": true
+}
+```
+
+### Metrics
+
+Each metric batch contains:
+
+```json
+{
+	"resource": { "@agentuity/orgId": "...", ... },
+	"scopeMetrics": [
+		{
+			"scope": { "name": "...", "version": "..." },
+			"metrics": [
+				{
+					"descriptor": { "name": "...", "description": "...", ... },
+					"dataPointType": 0,
+					"dataPoints": [...],
+					"aggregationTemporality": 1
+				}
+			]
+		}
+	]
+}
+```
+
+## Example Cron Job
+
+Here's an example script that reads JSONL files and forwards them to OTLP:
+
+```typescript
+#!/usr/bin/env bun
+
+import { readdir, readFile, unlink } from 'node:fs/promises';
+import { join } from 'node:path';
+
+const OTEL_ENDPOINT = process.env.OTEL_ENDPOINT || 'https://otel.agentuity.cloud';
+const OTEL_TOKEN = process.env.OTEL_TOKEN;
+const DATA_DIR = process.env.DATA_DIR || './.agentuity/otel-data';
+
+async function processFiles() {
+	const files = await readdir(DATA_DIR);
+
+	for (const file of files) {
+		if (file.endsWith('.jsonl')) {
+			const filePath = join(DATA_DIR, file);
+			const content = await readFile(filePath, 'utf-8');
+			const lines = content.trim().split('\n');
+
+			const type = file.startsWith('logs-')
+				? 'logs'
+				: file.startsWith('traces-')
+					? 'traces'
+					: 'metrics';
+
+			try {
+				// Send to OTLP endpoint
+				await fetch(`${OTEL_ENDPOINT}/v1/${type}`, {
+					method: 'POST',
+					headers: {
+						'Content-Type': 'application/json',
+						Authorization: `Bearer ${OTEL_TOKEN}`,
+					},
+					body: JSON.stringify({ [type]: lines.map((line) => JSON.parse(line)) }),
+				});
+
+				// Delete file after successful transmission
+				await unlink(filePath);
+				console.log(`Processed and deleted ${file}`);
+			} catch (error) {
+				console.error(`Failed to process ${file}:`, error);
+				// Don't delete the file on error, will retry next time
+			}
+		}
+	}
+}
+
+processFiles().catch(console.error);
+```
+
+Add this to your crontab to run every 30 seconds:
+
+```bash
+* * * * * /path/to/process-otel-data.ts
+* * * * * sleep 30 && /path/to/process-otel-data.ts
+```
+
+## Exporters
+
+### JSONLLogExporter
+
+Implements `LogRecordExporter` interface.
+
+### JSONLTraceExporter
+
+Implements `SpanExporter` interface.
+
+### JSONLMetricExporter
+
+Implements `PushMetricExporter` interface.
+
+## Notes
+
+- Files are written synchronously using `appendFileSync` for simplicity and reliability
+- File existence is checked before each write, creating a new file if necessary
+- Timestamps in filenames use ISO format with special characters replaced by hyphens
+- The exporters handle errors gracefully and report them via the callback mechanism

package/src/exporters/index.ts

@@ -0,0 +1,3 @@
+export { JSONLLogExporter } from './jsonl-log-exporter';
+export { JSONLTraceExporter } from './jsonl-trace-exporter';
+export { JSONLMetricExporter } from './jsonl-metric-exporter';

package/src/exporters/jsonl-log-exporter.ts

@@ -0,0 +1,113 @@
+import { type ExportResult, ExportResultCode } from '@opentelemetry/core';
+import type { LogRecordExporter, ReadableLogRecord } from '@opentelemetry/sdk-logs';
+import { existsSync, appendFileSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+
+/**
+ * JSONL implementation of the LogRecordExporter interface
+ * Writes logs to a timestamped JSONL file
+ */
+export class JSONLLogExporter implements LogRecordExporter {
+	private currentFile: string | null = null;
+	private readonly basePath: string;
+	private readonly filePrefix: string;
+
+	/**
+	 * Creates a new JSONL log record exporter
+	 * @param basePath - Directory to store the JSONL files
+	 */
+	constructor(basePath: string) {
+		this.basePath = basePath;
+		this.filePrefix = 'otel-log';
+		this.ensureDirectory();
+	}
+
+	private ensureDirectory(): void {
+		if (!existsSync(this.basePath)) {
+			mkdirSync(this.basePath, { recursive: true });
+		}
+	}
+
+	private getOrCreateFile(): string {
+		// If current file exists, use it
+		if (this.currentFile && existsSync(this.currentFile)) {
+			return this.currentFile;
+		}
+
+		this.currentFile = join(
+			this.basePath,
+			`${this.filePrefix}-${Date.now()}.${randomUUID()}.jsonl`
+		);
+		return this.currentFile;
+	}
+
+	/**
+	 * Exports log records to a JSONL file
+	 *
+	 * @param logs - The log records to export
+	 * @param resultCallback - Callback function to report the export result
+	 */
+	export(logs: ReadableLogRecord[], resultCallback: (result: ExportResult) => void): void {
+		try {
+			if (logs.length === 0) {
+				resultCallback({ code: ExportResultCode.SUCCESS });
+				return;
+			}
+			const file = this.getOrCreateFile();
+			const lines: string[] = [];
+			for (const log of logs) {
+				const record = {
+					timestamp: log.hrTime,
+					observedTimestamp: log.hrTimeObserved,
+					severityNumber: log.severityNumber,
+					severityText: log.severityText,
+					body: log.body,
+					attributes: log.attributes,
+					resource: log.resource.attributes,
+					instrumentationScope: log.instrumentationScope,
+					spanContext: log.spanContext,
+				};
+
+				lines.push(JSON.stringify(record));
+			}
+			const payload = `${lines.join('\n')}\n`;
+			try {
+				appendFileSync(file, payload, 'utf-8');
+			} catch (err) {
+				// File may have been deleted, reset and retry once
+				const code = (err as NodeJS.ErrnoException).code;
+				if (code === 'ENOENT') {
+					this.currentFile = null;
+					const newFile = this.getOrCreateFile();
+					appendFileSync(newFile, payload, 'utf-8');
+				} else {
+					throw err;
+				}
+			}
+
+			resultCallback({ code: ExportResultCode.SUCCESS });
+		} catch (error) {
+			resultCallback({
+				code: ExportResultCode.FAILED,
+				error: error instanceof Error ? error : new Error(String(error)),
+			});
+		}
+	}
+
+	/**
+	 * Shuts down the exporter
+	 *
+	 * @returns A promise that resolves when shutdown is complete
+	 */
+	async shutdown(): Promise<void> {
+		this.currentFile = null;
+	}
+
+	/**
+	 * Forces a flush of any pending data
+	 */
+	async forceFlush(): Promise<void> {
+		// No-op for file-based exporter as writes are synchronous
+	}
+}