Skip to content

Same agent Smaller bill. The tools and infrastructure to get more work from your AI. Fewer tokens. Less compute. Lower cost.

feat(ts): add startTrace() and trace() manual span helpers (#1292)

citizen204841af3df4e84
diff --git a/sdk/typescript/src/__tests__/manual-trace.test.ts b/sdk/typescript/src/__tests__/manual-trace.test.ts
new file mode 100644
index 00000000..53df4a22
--- /dev/null
+++ b/sdk/typescript/src/__tests__/manual-trace.test.ts
@@ -0,0 +1,139 @@
+import { trace as otelTrace, SpanStatusCode } from '@opentelemetry/api';
+import {
+ InMemorySpanExporter,
+ SimpleSpanProcessor,
+} from '@opentelemetry/sdk-trace-base';
+import { NodeTracerProvider } from '@opentelemetry/sdk-trace-node';
+import { ATTR_SERVICE_NAME } from '@opentelemetry/semantic-conventions';
+import OpenlitConfig from '../config';
+import SemanticConvention from '../semantic-convention';
+import { startTrace, trace } from '../manual-trace';
+
+describe('manual-trace', () => {
+ let exporter: InMemorySpanExporter;
+ let provider: NodeTracerProvider;
+
+ beforeAll(() => {
+ exporter = new InMemorySpanExporter();
+ provider = new NodeTracerProvider({
+ spanProcessors: [new SimpleSpanProcessor(exporter)],
+ });
+ provider.register();
+ OpenlitConfig.updateConfig({
+ tracer: provider as any,
+ applicationName: 'TestApp',
+ environment: 'TestEnv',
+ });
+ });
+
+ beforeEach(() => {
+ exporter.reset();
+ });
+
+ afterAll(async () => {
+ await provider.shutdown();
+ });
+
+ it('startTrace nests child spans under the manual span', async () => {
+ await startTrace('parent-operation', async () => {
+ await otelTrace.getTracer('openlit').startActiveSpan('child-llm', (child) => {
+ child.setAttribute('gen_ai.system', 'openai');
+ child.end();
+ });
+ });
+
+ const spans = exporter.getFinishedSpans();
+ expect(spans).toHaveLength(2);
+ const parentSpan = spans.find((s) => s.name === 'parent-operation');
+ const childSpan = spans.find((s) => s.name === 'child-llm');
+ expect(parentSpan).toBeDefined();
+ expect(childSpan).toBeDefined();
+ expect(childSpan!.parentSpanContext?.spanId).toBe(parentSpan!.spanContext().spanId);
+ expect(parentSpan!.attributes[ATTR_SERVICE_NAME]).toBe('TestApp');
+ expect(parentSpan!.attributes[SemanticConvention.ATTR_DEPLOYMENT_ENVIRONMENT]).toBe(
+ 'TestEnv'
+ );
+ expect(parentSpan!.status.code).toBe(SpanStatusCode.OK);
+ });
+
+ it('startTrace nests child spans across await boundaries', async () => {
+ await startTrace('async-parent', async () => {
+ await Promise.resolve();
+ otelTrace.getTracer('openlit').startActiveSpan('async-child', (child) => {
+ child.end();
+ });
+ });
+
+ const spans = exporter.getFinishedSpans();
+ const parentSpan = spans.find((s) => s.name === 'async-parent');
+ const childSpan = spans.find((s) => s.name === 'async-child');
+ expect(childSpan!.parentSpanContext?.spanId).toBe(parentSpan!.spanContext().spanId);
+ });
+
+ it('startTrace setResult and setMetadata stamp attributes', async () => {
+ await startTrace('metadata-test', async (span) => {
+ span.setResult('hello');
+ span.setMetadata({ 'custom.key': 'value', count: 3 });
+ });
+
+ const finished = exporter.getFinishedSpans()[0];
+ expect(finished.attributes[SemanticConvention.GEN_AI_OUTPUT_MESSAGES]).toBe('hello');
+ expect(finished.attributes['custom.key']).toBe('value');
+ expect(finished.attributes.count).toBe(3);
+ });
+
+ it('trace() ends span on sync success and nests children', () => {
+ const result = trace('sync-chain', (span) => {
+ otelTrace.getTracer('openlit').startActiveSpan('sync-child', (child) => {
+ child.end();
+ });
+ span.setResult('done');
+ return 42;
+ });
+
+ expect(result).toBe(42);
+ const spans = exporter.getFinishedSpans();
+ const parentSpan = spans.find((s) => s.name === 'sync-chain');
+ const childSpan = spans.find((s) => s.name === 'sync-child');
+ expect(childSpan!.parentSpanContext?.spanId).toBe(parentSpan!.spanContext().spanId);
+ expect(parentSpan!.attributes[SemanticConvention.GEN_AI_OUTPUT_MESSAGES]).toBe('done');
+ expect(parentSpan!.status.code).toBe(SpanStatusCode.OK);
+ });
+
+ it('trace() ends span on async success', async () => {
+ const result = await trace('async-chain', async (span) => {
+ await Promise.resolve();
+ span.setResult('async-done');
+ return 'ok';
+ });
+
+ expect(result).toBe('ok');
+ const parentSpan = exporter.getFinishedSpans().find((s) => s.name === 'async-chain');
+ expect(parentSpan!.attributes[SemanticConvention.GEN_AI_OUTPUT_MESSAGES]).toBe('async-done');
+ expect(parentSpan!.status.code).toBe(SpanStatusCode.OK);
+ });
+
+ it('trace() records errors and sets ERROR status', () => {
+ expect(() =>
+ trace('failing-sync', () => {
+ throw new Error('boom');
+ })
+ ).toThrow('boom');
+
+ const parentSpan = exporter.getFinishedSpans().find((s) => s.name === 'failing-sync');
+ expect(parentSpan!.status.code).toBe(SpanStatusCode.ERROR);
+ expect(parentSpan!.events.some((e) => e.name === 'exception')).toBe(true);
+ });
+
+ it('trace() records async rejection', async () => {
+ await expect(
+ trace('failing-async', async () => {
+ await Promise.resolve();
+ throw new Error('async-boom');
+ })
+ ).rejects.toThrow('async-boom');
+
+ const parentSpan = exporter.getFinishedSpans().find((s) => s.name === 'failing-async');
+ expect(parentSpan!.status.code).toBe(SpanStatusCode.ERROR);
+ });
+});
diff --git a/sdk/typescript/src/index.ts b/sdk/typescript/src/index.ts
index 0e30e22f..a4cbd070 100644
--- a/sdk/typescript/src/index.ts
+++ b/sdk/typescript/src/index.ts
@@ -18,6 +18,7 @@ import {
} from './helpers';
import { runEval, runEvalBatch, fetchEvalTypes } from './evals';
import { logScore } from './score';
+import { TracedSpan, startTrace, trace as traceManual } from './manual-trace';
import Metrics from './otel/metrics';
import SemanticConvention from './semantic-convention';
import { parseBoolEnv } from './otel/utils';
@@ -167,6 +168,9 @@ class Openlit extends BaseOpenlit {
static withAgentVersion = runWithAgentVersion;
static getAgentVersion = getCurrentAgentVersion;
+ static startTrace = startTrace;
+ static trace = traceManual;
+
static init(options?: OpenlitOptions) {
try {
diag.setLogger(new DiagConsoleLogger(), DiagLogLevel.WARN);
@@ -228,6 +232,7 @@ const openlit = Openlit as typeof Openlit & {
export default openlit;
export { Openlit, usingAttributes, injectAdditionalAttributes, logScore };
+export { TracedSpan, startTrace, traceManual as trace };
export type { OpenlitOptions } from './types';
export type { LogScoreOptions } from './score';
diff --git a/sdk/typescript/src/manual-trace.ts b/sdk/typescript/src/manual-trace.ts
new file mode 100644
index 00000000..fabf097f
--- /dev/null
+++ b/sdk/typescript/src/manual-trace.ts
@@ -0,0 +1,124 @@
+import { Span, SpanKind, SpanStatusCode, trace as otelTrace } from '@opentelemetry/api';
+import { ATTR_SERVICE_NAME } from '@opentelemetry/semantic-conventions';
+import OpenlitConfig from './config';
+import SemanticConvention from './semantic-convention';
+
+function getTracer() {
+ const provider = OpenlitConfig.tracer as any;
+ return provider?.getTracer?.('openlit') ?? otelTrace.getTracer('openlit');
+}
+
+function attachAppAttrs(span: Span): void {
+ span.setAttribute(ATTR_SERVICE_NAME, OpenlitConfig.applicationName ?? 'default');
+ span.setAttribute(
+ SemanticConvention.ATTR_DEPLOYMENT_ENVIRONMENT,
+ OpenlitConfig.environment ?? 'default'
+ );
+}
+
+/**
+ * Wrapper for an OpenTelemetry span with helpers to set result and metadata.
+ * Mirrors Python's TracedSpan — the span lifecycle is managed by startTrace() /
+ * trace(), so you do not call end() yourself (like Python's `with` block).
+ */
+export class TracedSpan {
+ private readonly _span: Span;
+
+ constructor(span: Span) {
+ this._span = span;
+ }
+
+ /** Record the AI output or function return value on the span. */
+ setResult(result: string): void {
+ this._span.setAttribute(SemanticConvention.GEN_AI_OUTPUT_MESSAGES, result);
+ }
+
+ /** Stamp arbitrary key/value attributes onto the span. */
+ setMetadata(metadata: Record<string, string | number | boolean>): void {
+ this._span.setAttributes(metadata);
+ }
+}
+
+function runInActiveSpan<T>(
+ name: string,
+ fn: (span: TracedSpan) => T | Promise<T>
+): T | Promise<T> {
+ return getTracer().startActiveSpan(
+ name,
+ { kind: SpanKind.CLIENT },
+ (rawSpan: Span) => {
+ attachAppAttrs(rawSpan);
+ const handle = new TracedSpan(rawSpan);
+
+ const endOk = () => {
+ rawSpan.setStatus({ code: SpanStatusCode.OK });
+ rawSpan.end();
+ };
+
+ const endError = (err: unknown): never => {
+ rawSpan.recordException(err as Error);
+ rawSpan.setStatus({
+ code: SpanStatusCode.ERROR,
+ message: String(err),
+ });
+ rawSpan.end();
+ throw err;
+ };
+
+ try {
+ const result = fn(handle);
+ if (result !== null && typeof (result as any)?.then === 'function') {
+ return (result as Promise<T>).then(
+ (val) => {
+ endOk();
+ return val;
+ },
+ (err) => endError(err)
+ );
+ }
+ endOk();
+ return result;
+ } catch (err) {
+ return endError(err);
+ }
+ }
+ );
+}
+
+/**
+ * Start a named CLIENT span scoped to a callback — the TypeScript equivalent of
+ * Python's `with start_trace(name) as span:`.
+ *
+ * The span is active for the duration of `fn`, so child LLM spans nest correctly.
+ *
+ * @example
+ * const answer = await openlit.startTrace('my-operation', async (span) => {
+ * const result = await doWork();
+ * span.setResult(String(result));
+ * return result;
+ * });
+ */
+export function startTrace<T>(
+ name: string,
+ fn: (span: TracedSpan) => T | Promise<T>
+): T | Promise<T> {
+ return runInActiveSpan(name, fn);
+}
+
+/**
+ * Wrap a function call in a CLIENT span — the TypeScript equivalent of
+ * Python's `@openlit.trace` decorator.
+ *
+ * @example
+ * const answer = await openlit.trace('my-chain', async (span) => {
+ * const result = await chain.invoke({ question });
+ * span.setResult(result.content);
+ * return result;
+ * });
+ */
+export function trace<T>(
+ name: string,
+ fn: (span: TracedSpan) => T | Promise<T>
+): T | Promise<T> {
+ return runInActiveSpan(name, fn);
+}