Same agent Smaller bill. The tools and infrastructure to get more work from your AI. Fewer tokens. Less compute. Lower cost.
TypeScript agent-harnessagent-harness-engineeringai-engineeringai-observabilityamd-gpuclaude-codeclickhousecodexcoding-agentcoding-agentscursorgenaigpu-monitoringllm-observabilityllmopsnvidia-smiobservabilityopen-sourceopenaiopentelemetry
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.tsnew file mode 100644index 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.tsindex 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.tsnew file mode 100644index 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);+}