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(typescript): add DigitalOcean Gradient auto-instrumentation (#1270)

Manan Bansal049f56d41fa3
diff --git a/sdk/typescript/package-lock.json b/sdk/typescript/package-lock.json
index f4ee9000..522130e5 100644
--- a/sdk/typescript/package-lock.json
+++ b/sdk/typescript/package-lock.json
@@ -24,6 +24,7 @@
"js-tiktoken": "^1.0.12"
},
"devDependencies": {
+ "@digitalocean/gradient": "^0.1.0-alpha.2",
"@eslint/js": "^9.2.0",
"@types/jest": "^29.0.0",
"ai21": "^1.3.0",
@@ -591,6 +592,13 @@
"@jridgewell/sourcemap-codec": "^1.4.10"
}
},
+ "node_modules/@digitalocean/gradient": {
+ "version": "0.1.0-alpha.2",
+ "resolved": "https://registry.npmjs.org/@digitalocean/gradient/-/gradient-0.1.0-alpha.2.tgz",
+ "integrity": "sha512-UuQBxuvSiHUGm1x69kwTrB2gEJg5mpXPZIZ0erCzkuPo/tVkK+AcOzV39NbhZAuqU+b2mE7rxSCtSMTyS6tNgw==",
+ "dev": true,
+ "license": "Apache-2.0"
+ },
"node_modules/@eslint-community/eslint-utils": {
"version": "4.9.1",
"resolved": "https://registry.npmjs.org/@eslint-community/eslint-utils/-/eslint-utils-4.9.1.tgz",
diff --git a/sdk/typescript/package.json b/sdk/typescript/package.json
index fea098a2..d595d317 100644
--- a/sdk/typescript/package.json
+++ b/sdk/typescript/package.json
@@ -44,6 +44,7 @@
"author": "Aman Agarwal <[email protected]>",
"license": "ISC",
"devDependencies": {
+ "@digitalocean/gradient": "^0.1.0-alpha.2",
"@eslint/js": "^9.2.0",
"@types/jest": "^29.0.0",
"ai21": "^1.3.0",
diff --git a/sdk/typescript/src/helpers.ts b/sdk/typescript/src/helpers.ts
index cbbc6c7a..0c4d8d4d 100644
--- a/sdk/typescript/src/helpers.ts
+++ b/sdk/typescript/src/helpers.ts
@@ -205,6 +205,7 @@ const PROVIDER_DEFAULT_ENDPOINTS: Record<string, [string, number]> = {
mistral_ai: ['api.mistral.ai', 443],
groq: ['api.groq.com', 443],
ai21: ['api.ai21.com', 443],
+ digitalocean: ['inference.do-ai.run', 443],
together: ['api.together.xyz', 443],
fireworks: ['api.fireworks.ai', 443],
perplexity: ['api.perplexity.ai', 443],
diff --git a/sdk/typescript/src/instrumentation/__tests__/gradient-trace-comparison.test.ts b/sdk/typescript/src/instrumentation/__tests__/gradient-trace-comparison.test.ts
new file mode 100644
index 00000000..e409c8f2
--- /dev/null
+++ b/sdk/typescript/src/instrumentation/__tests__/gradient-trace-comparison.test.ts
@@ -0,0 +1,464 @@
+/**
+ * Cross-Language Trace Comparison Tests for the DigitalOcean Gradient Integration
+ *
+ * These verify that the TypeScript Gradient instrumentation emits the same span
+ * attributes / events as the Python SDK reference
+ * (sdk/python/src/openlit/instrumentation/gradient). Gradient is OpenAI-shaped:
+ * responses carry a `model` field, requests support seed / frequency_penalty /
+ * presence_penalty, and streaming usage arrives on the final chunk as `usage`.
+ * The provider name is `digitalocean` and chat is served from inference.do-ai.run.
+ */
+
+import GradientWrapper from '../gradient/wrapper';
+import OpenlitConfig from '../../config';
+import OpenLitHelper from '../../helpers';
+import BaseWrapper from '../base-wrapper';
+import SemanticConvention from '../../semantic-convention';
+
+jest.mock('../../config');
+jest.mock('../../helpers', () => ({
+ __esModule: true,
+ default: {},
+ isFrameworkLlmActive: jest.fn(() => false),
+ getFrameworkParentContext: jest.fn(() => undefined),
+ getCurrentAgentVersion: jest.fn(() => undefined),
+}));
+jest.mock('../base-wrapper');
+
+const SERVER = { serverAddress: 'inference.do-ai.run', serverPort: 443 };
+const AGENT_SERVER = { serverAddress: 'abc123.agents.do-ai.run', serverPort: 443 };
+
+describe('Gradient Cross-Language Trace Comparison', () => {
+ let mockSpan: any;
+
+ beforeEach(() => {
+ mockSpan = {
+ setAttribute: jest.fn(),
+ addEvent: jest.fn(),
+ end: jest.fn(),
+ setStatus: jest.fn(),
+ };
+
+ (OpenlitConfig as any).environment = 'openlit-testing';
+ (OpenlitConfig as any).applicationName = 'openlit-test';
+ (OpenlitConfig as any).captureMessageContent = true;
+ (OpenlitConfig as any).pricingInfo = {};
+ (OpenlitConfig as any).disableEvents = false;
+
+ (OpenLitHelper as any).getChatModelCost = jest.fn().mockReturnValue(0.001);
+ (OpenLitHelper as any).getImageModelCost = jest.fn().mockReturnValue(0.05);
+ (OpenLitHelper as any).openaiTokens = jest.fn().mockReturnValue(5);
+ (OpenLitHelper as any).handleException = jest.fn();
+ (OpenLitHelper as any).createStreamProxy = jest
+ .fn()
+ .mockImplementation((stream, _generator) => stream);
+ (OpenLitHelper as any).buildInputMessages = jest
+ .fn()
+ .mockReturnValue('[{"role":"user","parts":[{"type":"text","content":"Test"}]}]');
+ (OpenLitHelper as any).buildOutputMessages = jest
+ .fn()
+ .mockReturnValue(
+ '[{"role":"assistant","parts":[{"type":"text","content":"Response"}],"finish_reason":"stop"}]'
+ );
+ (OpenLitHelper as any).buildSystemInstructionsFromMessages = jest
+ .fn()
+ .mockImplementation((messages: any[]) => {
+ const sys = (messages || []).find((m: any) => m?.role === 'system');
+ return sys ? JSON.stringify([{ type: 'text', content: String(sys.content) }]) : undefined;
+ });
+ (OpenLitHelper as any).buildToolDefinitions = jest.fn().mockReturnValue(undefined);
+ (OpenLitHelper as any).emitInferenceEvent = jest.fn();
+ (OpenLitHelper as any).computeAgentVersionHash = jest
+ .fn()
+ .mockReturnValue('ts-test-version-hash');
+
+ (BaseWrapper as any).recordMetrics = jest.fn();
+ (BaseWrapper as any).setBaseSpanAttributes = jest
+ .fn()
+ .mockImplementation((span, attrs) => {
+ span.setAttribute(SemanticConvention.GEN_AI_PROVIDER_NAME_OTEL, attrs.aiSystem);
+ span.setAttribute(SemanticConvention.GEN_AI_REQUEST_MODEL, attrs.model);
+ if (attrs.cost !== undefined) {
+ span.setAttribute(SemanticConvention.GEN_AI_USAGE_COST, attrs.cost);
+ }
+ if (attrs.serverAddress) {
+ span.setAttribute(SemanticConvention.SERVER_ADDRESS, attrs.serverAddress);
+ }
+ if (attrs.serverPort !== undefined) {
+ span.setAttribute(SemanticConvention.SERVER_PORT, attrs.serverPort);
+ }
+ span.setAttribute(SemanticConvention.GEN_AI_SDK_VERSION, '1.9.0');
+ });
+ });
+
+ afterEach(() => {
+ jest.clearAllMocks();
+ });
+
+ const mockResponse = () => ({
+ id: 'gradient-test-id',
+ model: 'llama3.3-70b-instruct',
+ choices: [
+ {
+ index: 0,
+ finish_reason: 'stop',
+ message: { role: 'assistant', content: 'DO says hi', reasoning_content: 'thinking...' },
+ },
+ ],
+ usage: { prompt_tokens: 10, completion_tokens: 20, total_tokens: 30 },
+ });
+
+ describe('Chat Completion Trace Consistency', () => {
+ it('should set the same core attributes as the Python SDK', async () => {
+ const mockArgs = [
+ {
+ messages: [{ role: 'user', content: 'What is LLM Observability?' }],
+ model: 'llama3.3-70b-instruct',
+ max_tokens: 100,
+ temperature: 0.7,
+ stream: false,
+ },
+ ];
+
+ await GradientWrapper._chatCompletion({
+ args: mockArgs,
+ genAIEndpoint: 'digitalocean.chat.completions',
+ response: mockResponse(),
+ span: mockSpan,
+ ...SERVER,
+ operationName: SemanticConvention.GEN_AI_OPERATION_TYPE_CHAT,
+ apiType: 'chat',
+ });
+
+ expect(mockSpan.setAttribute).toHaveBeenCalledWith(
+ SemanticConvention.GEN_AI_PROVIDER_NAME_OTEL,
+ 'digitalocean'
+ );
+ expect(mockSpan.setAttribute).toHaveBeenCalledWith(
+ SemanticConvention.GEN_AI_REQUEST_MODEL,
+ 'llama3.3-70b-instruct'
+ );
+ expect(mockSpan.setAttribute).toHaveBeenCalledWith(
+ SemanticConvention.GEN_AI_RESPONSE_MODEL,
+ 'llama3.3-70b-instruct'
+ );
+ expect(mockSpan.setAttribute).toHaveBeenCalledWith(
+ SemanticConvention.GEN_AI_RESPONSE_ID,
+ 'gradient-test-id'
+ );
+ expect(mockSpan.setAttribute).toHaveBeenCalledWith(SemanticConvention.GEN_AI_USAGE_INPUT_TOKENS, 10);
+ expect(mockSpan.setAttribute).toHaveBeenCalledWith(SemanticConvention.GEN_AI_USAGE_OUTPUT_TOKENS, 20);
+ expect(mockSpan.setAttribute).toHaveBeenCalledWith(SemanticConvention.GEN_AI_CLIENT_TOKEN_USAGE, 30);
+ expect(mockSpan.setAttribute).toHaveBeenCalledWith(SemanticConvention.GEN_AI_REQUEST_TEMPERATURE, 0.7);
+ expect(mockSpan.setAttribute).toHaveBeenCalledWith(SemanticConvention.GEN_AI_REQUEST_MAX_TOKENS, 100);
+ expect(mockSpan.setAttribute).toHaveBeenCalledWith(SemanticConvention.GEN_AI_REQUEST_IS_STREAM, false);
+ expect(mockSpan.setAttribute).toHaveBeenCalledWith(SemanticConvention.GEN_AI_RESPONSE_FINISH_REASON, ['stop']);
+ expect(mockSpan.setAttribute).toHaveBeenCalledWith(SemanticConvention.GEN_AI_OUTPUT_TYPE, 'text');
+ expect(mockSpan.setAttribute).toHaveBeenCalledWith(SemanticConvention.OPENAI_API_TYPE, 'chat');
+ expect(mockSpan.setAttribute).toHaveBeenCalledWith(SemanticConvention.SERVER_ADDRESS, 'inference.do-ai.run');
+ expect(mockSpan.setAttribute).toHaveBeenCalledWith(SemanticConvention.SERVER_PORT, 443);
+ });
+
+ it('prefers max_completion_tokens over max_tokens (Python parity)', async () => {
+ const mockArgs = [
+ {
+ messages: [{ role: 'user', content: 'Test' }],
+ model: 'llama3.3-70b-instruct',
+ max_tokens: 50,
+ max_completion_tokens: 128,
+ stream: false,
+ },
+ ];
+
+ await GradientWrapper._chatCompletion({
+ args: mockArgs,
+ genAIEndpoint: 'digitalocean.chat.completions',
+ response: mockResponse(),
+ span: mockSpan,
+ ...SERVER,
+ operationName: SemanticConvention.GEN_AI_OPERATION_TYPE_CHAT,
+ apiType: 'chat',
+ });
+
+ expect(mockSpan.setAttribute).toHaveBeenCalledWith(SemanticConvention.GEN_AI_REQUEST_MAX_TOKENS, 128);
+ });
+
+ it('falls back to the "unknown" request model when none is supplied (matches Python)', async () => {
+ const mockArgs = [{ messages: [{ role: 'user', content: 'Test' }], stream: false }];
+ const responseNoModel = { ...mockResponse(), model: '' };
+
+ await GradientWrapper._chatCompletion({
+ args: mockArgs,
+ genAIEndpoint: 'digitalocean.chat.completions',
+ response: responseNoModel,
+ span: mockSpan,
+ ...SERVER,
+ operationName: SemanticConvention.GEN_AI_OPERATION_TYPE_CHAT,
+ apiType: 'chat',
+ });
+
+ expect(mockSpan.setAttribute).toHaveBeenCalledWith(SemanticConvention.GEN_AI_REQUEST_MODEL, 'unknown');
+ expect(mockSpan.setAttribute).toHaveBeenCalledWith(SemanticConvention.GEN_AI_RESPONSE_MODEL, 'unknown');
+ });
+
+ it('stamps openlit.agent.version_hash on the chat span', async () => {
+ const mockArgs = [
+ { messages: [{ role: 'user', content: 'Hash me' }], model: 'llama3.3-70b-instruct', stream: false },
+ ];
+
+ await GradientWrapper._chatCompletion({
+ args: mockArgs,
+ genAIEndpoint: 'digitalocean.chat.completions',
+ response: mockResponse(),
+ span: mockSpan,
+ ...SERVER,
+ operationName: SemanticConvention.GEN_AI_OPERATION_TYPE_CHAT,
+ apiType: 'chat',
+ });
+
+ expect((OpenLitHelper as any).computeAgentVersionHash).toHaveBeenCalled();
+ expect(mockSpan.setAttribute).toHaveBeenCalledWith(
+ SemanticConvention.OPENLIT_AGENT_VERSION_HASH,
+ 'ts-test-version-hash'
+ );
+ });
+
+ it('should NOT set total_tokens on the span', async () => {
+ const mockArgs = [
+ { messages: [{ role: 'user', content: 'Test' }], model: 'llama3.3-70b-instruct', stream: false },
+ ];
+
+ await GradientWrapper._chatCompletion({
+ args: mockArgs,
+ genAIEndpoint: 'digitalocean.chat.completions',
+ response: mockResponse(),
+ span: mockSpan,
+ ...SERVER,
+ operationName: SemanticConvention.GEN_AI_OPERATION_TYPE_CHAT,
+ apiType: 'chat',
+ });
+
+ const attributeKeys = (mockSpan.setAttribute as jest.Mock).mock.calls.map(([key]: [string]) => key);
+ expect(attributeKeys).not.toContain(SemanticConvention.GEN_AI_USAGE_TOTAL_TOKENS);
+ });
+
+ it('omits seed / penalties / optionals when not provided (no sentinel values)', async () => {
+ const mockArgs = [
+ { messages: [{ role: 'user', content: 'Test' }], model: 'llama3.3-70b-instruct', stream: false },
+ ];
+
+ await GradientWrapper._chatCompletion({
+ args: mockArgs,
+ genAIEndpoint: 'digitalocean.chat.completions',
+ response: mockResponse(),
+ span: mockSpan,
+ ...SERVER,
+ operationName: SemanticConvention.GEN_AI_OPERATION_TYPE_CHAT,
+ apiType: 'chat',
+ });
+
+ const attributeKeys = (mockSpan.setAttribute as jest.Mock).mock.calls.map(([key]: [string]) => key);
+ expect(attributeKeys).not.toContain(SemanticConvention.GEN_AI_REQUEST_SEED);
+ expect(attributeKeys).not.toContain(SemanticConvention.GEN_AI_REQUEST_FREQUENCY_PENALTY);
+ expect(attributeKeys).not.toContain(SemanticConvention.GEN_AI_REQUEST_PRESENCE_PENALTY);
+ expect(attributeKeys).not.toContain(SemanticConvention.GEN_AI_REQUEST_MAX_TOKENS);
+ expect(attributeKeys).not.toContain(SemanticConvention.GEN_AI_REQUEST_STOP_SEQUENCES);
+ expect(attributeKeys).not.toContain(SemanticConvention.GEN_AI_REQUEST_CHOICE_COUNT);
+ });
+
+ it('sets seed / penalties when explicitly provided (Gradient is OpenAI-compatible)', async () => {
+ const mockArgs = [
+ {
+ messages: [{ role: 'user', content: 'Test' }],
+ model: 'llama3.3-70b-instruct',
+ seed: 42,
+ frequency_penalty: 0.5,
+ presence_penalty: 0.3,
+ stop: ['END'],
+ n: 2,
+ reasoning_effort: 'high',
+ stream: false,
+ },
+ ];
+
+ await GradientWrapper._chatCompletion({
+ args: mockArgs,
+ genAIEndpoint: 'digitalocean.chat.completions',
+ response: mockResponse(),
+ span: mockSpan,
+ ...SERVER,
+ operationName: SemanticConvention.GEN_AI_OPERATION_TYPE_CHAT,
+ apiType: 'chat',
+ });
+
+ expect(mockSpan.setAttribute).toHaveBeenCalledWith(SemanticConvention.GEN_AI_REQUEST_SEED, 42);
+ expect(mockSpan.setAttribute).toHaveBeenCalledWith(SemanticConvention.GEN_AI_REQUEST_FREQUENCY_PENALTY, 0.5);
+ expect(mockSpan.setAttribute).toHaveBeenCalledWith(SemanticConvention.GEN_AI_REQUEST_PRESENCE_PENALTY, 0.3);
+ expect(mockSpan.setAttribute).toHaveBeenCalledWith(SemanticConvention.GEN_AI_REQUEST_STOP_SEQUENCES, ['END']);
+ expect(mockSpan.setAttribute).toHaveBeenCalledWith(SemanticConvention.GEN_AI_REQUEST_CHOICE_COUNT, 2);
+ expect(mockSpan.setAttribute).toHaveBeenCalledWith(
+ SemanticConvention.GEN_AI_REQUEST_REASONING_EFFORT,
+ 'high'
+ );
+ });
+
+ it('does not throw and still records tokens when the response omits usage', async () => {
+ const mockArgs = [
+ { messages: [{ role: 'user', content: 'Test' }], model: 'llama3.3-70b-instruct', stream: false },
+ ];
+ const responseNoUsage: any = mockResponse();
+ delete responseNoUsage.usage;
+
+ await GradientWrapper._chatCompletion({
+ args: mockArgs,
+ genAIEndpoint: 'digitalocean.chat.completions',
+ response: responseNoUsage,
+ span: mockSpan,
+ ...SERVER,
+ operationName: SemanticConvention.GEN_AI_OPERATION_TYPE_CHAT,
+ apiType: 'chat',
+ });
+
+ expect(mockSpan.setAttribute).toHaveBeenCalledWith(SemanticConvention.GEN_AI_USAGE_INPUT_TOKENS, 0);
+ expect(mockSpan.setAttribute).toHaveBeenCalledWith(SemanticConvention.GEN_AI_USAGE_OUTPUT_TOKENS, 0);
+ });
+
+ it('should emit an inference event via the LoggerProvider', async () => {
+ const mockArgs = [
+ { messages: [{ role: 'user', content: 'Test' }], model: 'llama3.3-70b-instruct', stream: false },
+ ];
+
+ await GradientWrapper._chatCompletion({
+ args: mockArgs,
+ genAIEndpoint: 'digitalocean.chat.completions',
+ response: mockResponse(),
+ span: mockSpan,
+ ...SERVER,
+ operationName: SemanticConvention.GEN_AI_OPERATION_TYPE_CHAT,
+ apiType: 'chat',
+ });
+
+ expect((OpenLitHelper as any).emitInferenceEvent).toHaveBeenCalled();
+ });
+ });
+
+ describe('Agent Chat Completion Trace Consistency', () => {
+ it('emits invoke_agent operation in inference events (Python parity)', async () => {
+ const mockArgs = [
+ {
+ messages: [{ role: 'user', content: 'Run agent' }],
+ model: 'agent-model',
+ stream: false,
+ },
+ ];
+
+ await GradientWrapper._chatCompletion({
+ args: mockArgs,
+ genAIEndpoint: 'digitalocean.agents.chat.completions',
+ response: mockResponse(),
+ span: mockSpan,
+ ...AGENT_SERVER,
+ operationName: SemanticConvention.GEN_AI_OPERATION_TYPE_AGENT,
+ apiType: 'chat',
+ });
+
+ expect((OpenLitHelper as any).emitInferenceEvent).toHaveBeenCalledWith(
+ mockSpan,
+ expect.objectContaining({
+ [SemanticConvention.GEN_AI_OPERATION]: SemanticConvention.GEN_AI_OPERATION_TYPE_AGENT,
+ })
+ );
+ });
+ });
+
+ describe('Image Generation Trace Consistency', () => {
+ it('sets image output type and cost like Python process_image_response', async () => {
+ const mockArgs = [
+ {
+ prompt: 'A cute otter',
+ model: 'gpt-image-1',
+ size: '1024x1024',
+ quality: 'high',
+ },
+ ];
+ const response = {
+ created: 1710000000,
+ model: 'gpt-image-1',
+ data: [{ b64_json: 'abc', revised_prompt: 'A very cute otter' }],
+ };
+
+ GradientWrapper._imageGenerateCommonSetter({
+ args: mockArgs,
+ genAIEndpoint: 'digitalocean.images.generate',
+ response,
+ span: mockSpan,
+ ...SERVER,
+ });
+
+ expect(mockSpan.setAttribute).toHaveBeenCalledWith(SemanticConvention.GEN_AI_OUTPUT_TYPE, 'image');
+ expect(mockSpan.setAttribute).toHaveBeenCalledWith(
+ SemanticConvention.GEN_AI_RESPONSE_ID,
+ String(1710000000)
+ );
+ expect((OpenLitHelper as any).getImageModelCost).toHaveBeenCalledWith(
+ 'gpt-image-1',
+ {},
+ '1024x1024',
+ 'high'
+ );
+ });
+ });
+
+ describe('Streaming Trace Consistency', () => {
+ async function* mockStream() {
+ yield {
+ id: 'gradient-stream-id',
+ model: 'llama3.3-70b-instruct',
+ choices: [{ index: 0, delta: { role: 'assistant', content: 'Hello' }, finish_reason: null }],
+ };
+ yield {
+ id: 'gradient-stream-id',
+ model: 'llama3.3-70b-instruct',
+ choices: [{ index: 0, delta: { content: ' world' }, finish_reason: 'stop' }],
+ };
+ yield {
+ id: 'gradient-stream-id',
+ model: 'llama3.3-70b-instruct',
+ choices: [],
+ usage: { prompt_tokens: 7, completion_tokens: 11, total_tokens: 18 },
+ };
+ }
+
+ it('aggregates streamed content and reads usage from the final chunk', async () => {
+ const mockArgs = [
+ {
+ messages: [{ role: 'user', content: 'Hi' }],
+ model: 'llama3.3-70b-instruct',
+ stream: true,
+ },
+ ];
+
+ const generator = GradientWrapper._chatCompletionGenerator({
+ args: mockArgs,
+ genAIEndpoint: 'digitalocean.chat.completions',
+ response: mockStream(),
+ span: mockSpan,
+ ...SERVER,
+ operationName: SemanticConvention.GEN_AI_OPERATION_TYPE_CHAT,
+ apiType: 'chat',
+ });
+
+ let step = await generator.next();
+ while (!step.done) {
+ step = await generator.next();
+ }
+ const final: any = step.value;
+
+ expect(final.choices[0].message.content).toBe('Hello world');
+ expect(final.choices[0].finish_reason).toBe('stop');
+ expect(mockSpan.setAttribute).toHaveBeenCalledWith(SemanticConvention.GEN_AI_USAGE_INPUT_TOKENS, 7);
+ expect(mockSpan.setAttribute).toHaveBeenCalledWith(SemanticConvention.GEN_AI_USAGE_OUTPUT_TOKENS, 11);
+ expect(mockSpan.setAttribute).toHaveBeenCalledWith(SemanticConvention.GEN_AI_REQUEST_IS_STREAM, true);
+ });
+ });
+});
diff --git a/sdk/typescript/src/instrumentation/gradient/index.ts b/sdk/typescript/src/instrumentation/gradient/index.ts
new file mode 100644
index 00000000..7b76e4ed
--- /dev/null
+++ b/sdk/typescript/src/instrumentation/gradient/index.ts
@@ -0,0 +1,98 @@
+import {
+ InstrumentationBase,
+ InstrumentationModuleDefinition,
+ InstrumentationNodeModuleDefinition,
+ isWrapped,
+} from '@opentelemetry/instrumentation';
+import { InstrumentationConfig } from '@opentelemetry/instrumentation';
+import { INSTRUMENTATION_PREFIX } from '../../constant';
+import GradientWrapper from './wrapper';
+
+export interface GradientInstrumentationConfig extends InstrumentationConfig {}
+
+export default class OpenlitGradientInstrumentation extends InstrumentationBase {
+ constructor(config: GradientInstrumentationConfig = {}) {
+ super(`${INSTRUMENTATION_PREFIX}/instrumentation-gradient`, '1.0.0', config);
+ }
+
+ private safeWrap(target: any, method: string, patcher: (tracer: any) => any): void {
+ if (!target?.[method]) return;
+ if (isWrapped(target[method])) {
+ this._unwrap(target, method);
+ }
+ this._wrap(target, method, patcher(this.tracer));
+ }
+
+ protected init(): void | InstrumentationModuleDefinition | InstrumentationModuleDefinition[] {
+ const module = new InstrumentationNodeModuleDefinition(
+ '@digitalocean/gradient',
+ // @digitalocean/gradient currently ships only as a prerelease (0.1.0-alpha.*).
+ // A plain '>=0.1.0' range does NOT match prereleases under semver, so the hook
+ // would load the module but silently skip patching. Anchor at the prerelease
+ // tag (mirrors azure-ai-inference's '>=1.0.0-beta.1'); this still matches the
+ // eventual stable 0.1.0 and later. See semver.satisfies prerelease semantics.
+ ['>=0.1.0-alpha.0'],
+ (moduleExports) => {
+ this._patch(moduleExports);
+ return moduleExports;
+ },
+ (moduleExports) => {
+ if (moduleExports !== undefined) {
+ this._unpatch(moduleExports);
+ }
+ }
+ );
+ return [module];
+ }
+
+ public manualPatch(gradient: any): void {
+ this._patch(gradient);
+ }
+
+ protected _patch(moduleExports: any) {
+ try {
+ const Gradient = moduleExports?.Gradient;
+ if (!Gradient) return;
+
+ // Chat completions (inference)
+ this.safeWrap(
+ Gradient.Chat?.Completions?.prototype,
+ 'create',
+ GradientWrapper._patchChatCompletionCreate
+ );
+
+ // Agent chat completions
+ this.safeWrap(
+ Gradient.Agents?.Chat?.Completions?.prototype,
+ 'create',
+ GradientWrapper._patchAgentChatCompletionCreate
+ );
+
+ // Image generation
+ this.safeWrap(
+ Gradient.Images?.prototype,
+ 'generate',
+ GradientWrapper._patchImageGenerate
+ );
+ } catch (e) {
+ console.error('Error in _patch method:', e);
+ }
+ }
+
+ protected _unpatch(moduleExports: any) {
+ const Gradient = moduleExports?.Gradient;
+ if (!Gradient) return;
+
+ const targets: Array<[any, string]> = [
+ [Gradient.Chat?.Completions?.prototype, 'create'],
+ [Gradient.Agents?.Chat?.Completions?.prototype, 'create'],
+ [Gradient.Images?.prototype, 'generate'],
+ ];
+
+ for (const [target, method] of targets) {
+ if (target?.[method]) {
+ this._unwrap(target, method);
+ }
+ }
+ }
+}
diff --git a/sdk/typescript/src/instrumentation/gradient/utils.ts b/sdk/typescript/src/instrumentation/gradient/utils.ts
new file mode 100644
index 00000000..266583ba
--- /dev/null
+++ b/sdk/typescript/src/instrumentation/gradient/utils.ts
@@ -0,0 +1,124 @@
+import { Attributes } from '@opentelemetry/api';
+import SemanticConvention from '../../semantic-convention';
+
+export type GradientEndpointKind = 'inference' | 'agent';
+
+const DEFAULT_HOSTS: Record<GradientEndpointKind, [string, number]> = {
+ inference: ['inference.do-ai.run', 443],
+ agent: ['agents.do-ai.run', 443],
+};
+
+const ENDPOINT_ATTRS: Record<GradientEndpointKind, string> = {
+ inference: 'inferenceEndpoint',
+ agent: 'agentEndpoint',
+};
+
+/**
+ * Walk the Gradient APIResource `_client` chain and read the per-route endpoint
+ * from the root client (mirrors Python `_resolve_endpoint`).
+ */
+export function resolveGradientEndpoint(
+ instance: any,
+ kind: GradientEndpointKind
+): [string, number] {
+ const [defaultHost, defaultPort] = DEFAULT_HOSTS[kind];
+ const attr = ENDPOINT_ATTRS[kind];
+ const candidates: any[] = [];
+ const seen = new Set<any>();
+ let current = instance;
+ while (current && !seen.has(current)) {
+ seen.add(current);
+ candidates.push(current);
+ current = current._client;
+ }
+
+ for (const cand of candidates) {
+ const raw = cand?.[attr];
+ if (!raw) continue;
+ try {
+ const url = new URL(String(raw).includes('://') ? String(raw) : `https://${raw}`);
+ const host = url.hostname || defaultHost;
+ const port = url.port
+ ? Number(url.port)
+ : url.protocol === 'http:'
+ ? 80
+ : 443;
+ return [host, port];
+ } catch {
+ const host = String(raw).split(':')[0] || defaultHost;
+ return [host, defaultPort];
+ }
+ }
+
+ return DEFAULT_HOSTS[kind];
+}
+
+/** Extract agent UUID from `{uuid}.agents.do-ai.run` hostnames (Python parity). */
+export function agentIdFromHost(host: string): string | undefined {
+ if (!host || !host.includes('agents.do-ai.run')) return undefined;
+ const head = host.split('.agents.do-ai.run')[0];
+ return head || undefined;
+}
+
+export function gradientSpanCreationAttrs(
+ operationName: string,
+ requestModel: string,
+ serverAddress: string,
+ serverPort: number
+): Attributes {
+ return {
+ [SemanticConvention.GEN_AI_OPERATION]: operationName,
+ [SemanticConvention.GEN_AI_PROVIDER_NAME_OTEL]: SemanticConvention.GEN_AI_SYSTEM_DIGITALOCEAN,
+ [SemanticConvention.GEN_AI_REQUEST_MODEL]: requestModel,
+ [SemanticConvention.SERVER_ADDRESS]: serverAddress,
+ [SemanticConvention.SERVER_PORT]: serverPort,
+ };
+}
+
+/** Normalize OpenAI-style stop sequences (Python `_normalize_stop`). */
+export function normalizeStopSequences(stop: unknown): string[] | undefined {
+ if (stop == null) return undefined;
+ if (Array.isArray(stop)) {
+ const out = stop.filter((s) => s != null && String(s).length > 0).map(String);
+ return out.length > 0 ? out : undefined;
+ }
+ const s = String(stop);
+ return s ? [s] : undefined;
+}
+
+/** Request attributes shared by chat and agent-chat surfaces. */
+export function applyGradientChatRequestAttributes(span: any, body: Record<string, any>): void {
+ if (body.temperature != null) {
+ span.setAttribute(SemanticConvention.GEN_AI_REQUEST_TEMPERATURE, body.temperature);
+ }
+ if (body.top_p != null) {
+ span.setAttribute(SemanticConvention.GEN_AI_REQUEST_TOP_P, body.top_p);
+ }
+ const maxTokens = body.max_completion_tokens ?? body.max_tokens;
+ if (maxTokens != null) {
+ span.setAttribute(SemanticConvention.GEN_AI_REQUEST_MAX_TOKENS, maxTokens);
+ }
+ if (body.frequency_penalty != null) {
+ span.setAttribute(SemanticConvention.GEN_AI_REQUEST_FREQUENCY_PENALTY, body.frequency_penalty);
+ }
+ if (body.presence_penalty != null) {
+ span.setAttribute(SemanticConvention.GEN_AI_REQUEST_PRESENCE_PENALTY, body.presence_penalty);
+ }
+ const stopSequences = normalizeStopSequences(body.stop ?? body.stop_sequences);
+ if (stopSequences) {
+ span.setAttribute(SemanticConvention.GEN_AI_REQUEST_STOP_SEQUENCES, stopSequences);
+ }
+ if (body.seed != null) {
+ span.setAttribute(SemanticConvention.GEN_AI_REQUEST_SEED, Number(body.seed));
+ }
+ if (body.n != null && body.n !== 1) {
+ span.setAttribute(SemanticConvention.GEN_AI_REQUEST_CHOICE_COUNT, body.n);
+ }
+ if (body.user) {
+ span.setAttribute(SemanticConvention.GEN_AI_REQUEST_USER, body.user);
+ }
+ if (body.reasoning_effort) {
+ span.setAttribute(SemanticConvention.GEN_AI_REQUEST_REASONING_EFFORT, body.reasoning_effort);
+ }
+ span.setAttribute(SemanticConvention.GEN_AI_REQUEST_IS_STREAM, Boolean(body.stream));
+}
diff --git a/sdk/typescript/src/instrumentation/gradient/wrapper.ts b/sdk/typescript/src/instrumentation/gradient/wrapper.ts
new file mode 100644
index 00000000..5a0e4ca7
--- /dev/null
+++ b/sdk/typescript/src/instrumentation/gradient/wrapper.ts
@@ -0,0 +1,715 @@
+import { Span, SpanKind, Tracer, context, trace, Attributes } from '@opentelemetry/api';
+import OpenlitConfig from '../../config';
+import OpenLitHelper, {
+ isFrameworkLlmActive,
+ getFrameworkParentContext,
+ getCurrentAgentVersion,
+} from '../../helpers';
+import SemanticConvention from '../../semantic-convention';
+import BaseWrapper from '../base-wrapper';
+import {
+ agentIdFromHost,
+ applyGradientChatRequestAttributes,
+ gradientSpanCreationAttrs,
+ resolveGradientEndpoint,
+ GradientEndpointKind,
+} from './utils';
+
+const AI_SYSTEM = SemanticConvention.GEN_AI_SYSTEM_DIGITALOCEAN;
+
+type ChatPatchOptions = {
+ operationName: string;
+ endpointKind: GradientEndpointKind;
+ genAIEndpoint: string;
+ apiType: string;
+ isAgent?: boolean;
+};
+
+class GradientWrapper extends BaseWrapper {
+ static aiSystem = AI_SYSTEM;
+
+ static _patchChatCompletionCreate(tracer: Tracer): any {
+ return GradientWrapper._buildChatPatch(tracer, {
+ operationName: SemanticConvention.GEN_AI_OPERATION_TYPE_CHAT,
+ endpointKind: 'inference',
+ genAIEndpoint: 'digitalocean.chat.completions',
+ apiType: 'chat',
+ });
+ }
+
+ static _patchAgentChatCompletionCreate(tracer: Tracer): any {
+ return GradientWrapper._buildChatPatch(tracer, {
+ operationName: SemanticConvention.GEN_AI_OPERATION_TYPE_AGENT,
+ endpointKind: 'agent',
+ genAIEndpoint: 'digitalocean.agents.chat.completions',
+ apiType: 'chat',
+ isAgent: true,
+ });
+ }
+
+ static _buildChatPatch(tracer: Tracer, options: ChatPatchOptions): any {
+ const { operationName, endpointKind, genAIEndpoint, apiType, isAgent = false } = options;
+ return (originalMethod: (...args: any[]) => any) => {
+ return async function (this: any, ...args: any[]) {
+ if (isFrameworkLlmActive()) return originalMethod.apply(this, args);
+
+ const body = args[0] || {};
+ const requestModel = body.model || 'unknown';
+ const [serverAddress, serverPort] = resolveGradientEndpoint(this, endpointKind);
+ const spanName = `${operationName} ${requestModel}`;
+ const effectiveCtx = getFrameworkParentContext() ?? context.active();
+ const span = tracer.startSpan(
+ spanName,
+ {
+ kind: SpanKind.CLIENT,
+ attributes: gradientSpanCreationAttrs(operationName, requestModel, serverAddress, serverPort),
+ },
+ effectiveCtx
+ );
+
+ if (isAgent) {
+ const agentId = agentIdFromHost(serverAddress);
+ if (agentId) {
+ span.setAttribute(SemanticConvention.GEN_AI_AGENT_ID, agentId);
+ }
+ }
+
+ return context
+ .with(trace.setSpan(effectiveCtx, span), async () => originalMethod.apply(this, args))
+ .then((response: any) => {
+ if (body.stream) {
+ return OpenLitHelper.createStreamProxy(
+ response,
+ GradientWrapper._chatCompletionGenerator({
+ args,
+ genAIEndpoint,
+ response,
+ span,
+ serverAddress,
+ serverPort,
+ operationName,
+ apiType,
+ })
+ );
+ }
+ return GradientWrapper._chatCompletion({
+ args,
+ genAIEndpoint,
+ response,
+ span,
+ serverAddress,
+ serverPort,
+ operationName,
+ apiType,
+ });
+ })
+ .catch((e: any) => {
+ OpenLitHelper.handleException(span, e);
+ BaseWrapper.recordMetrics(span, {
+ genAIEndpoint,
+ model: requestModel,
+ aiSystem: AI_SYSTEM,
+ serverAddress,
+ serverPort,
+ errorType: e?.constructor?.name || '_OTHER',
+ });
+ span.end();
+ throw e;
+ });
+ };
+ };
+ }
+
+ static _patchImageGenerate(tracer: Tracer): any {
+ const genAIEndpoint = 'digitalocean.images.generate';
+ return (originalMethod: (...args: any[]) => any) => {
+ return async function (this: any, ...args: any[]) {
+ if (isFrameworkLlmActive()) return originalMethod.apply(this, args);
+
+ const body = args[0] || {};
+ const requestModel = body.model || 'unknown';
+ const [serverAddress, serverPort] = resolveGradientEndpoint(this, 'inference');
+ const spanName = `${SemanticConvention.GEN_AI_OPERATION_TYPE_CHAT} ${requestModel}`;
+ const effectiveCtx = getFrameworkParentContext() ?? context.active();
+ const span = tracer.startSpan(
+ spanName,
+ {
+ kind: SpanKind.CLIENT,
+ attributes: gradientSpanCreationAttrs(
+ SemanticConvention.GEN_AI_OPERATION_TYPE_CHAT,
+ requestModel,
+ serverAddress,
+ serverPort
+ ),
+ },
+ effectiveCtx
+ );
+
+ return context.with(trace.setSpan(effectiveCtx, span), async () => {
+ let metricParams;
+ try {
+ const response = await originalMethod.apply(this, args);
+ metricParams = GradientWrapper._imageGenerateCommonSetter({
+ args,
+ genAIEndpoint,
+ response,
+ span,
+ serverAddress,
+ serverPort,
+ });
+ return response;
+ } catch (e: any) {
+ OpenLitHelper.handleException(span, e);
+ BaseWrapper.recordMetrics(span, {
+ genAIEndpoint,
+ model: requestModel,
+ aiSystem: AI_SYSTEM,
+ serverAddress,
+ serverPort,
+ errorType: e?.constructor?.name || '_OTHER',
+ });
+ throw e;
+ } finally {
+ span.end();
+ if (metricParams) {
+ BaseWrapper.recordMetrics(span, metricParams);
+ }
+ }
+ });
+ };
+ };
+ }
+
+ static async _chatCompletion({
+ args,
+ genAIEndpoint,
+ response,
+ span,
+ serverAddress,
+ serverPort,
+ operationName,
+ apiType,
+ }: {
+ args: any[];
+ genAIEndpoint: string;
+ response: any;
+ span: Span;
+ serverAddress: string;
+ serverPort: number;
+ operationName: string;
+ apiType: string;
+ }): Promise<any> {
+ let metricParams;
+ try {
+ metricParams = await GradientWrapper._chatCompletionCommonSetter({
+ args,
+ genAIEndpoint,
+ result: response,
+ span,
+ serverAddress,
+ serverPort,
+ operationName,
+ apiType,
+ });
+ return response;
+ } catch (e: any) {
+ OpenLitHelper.handleException(span, e);
+ throw e;
+ } finally {
+ span.end();
+ if (metricParams) {
+ BaseWrapper.recordMetrics(span, metricParams);
+ }
+ }
+ }
+
+ static async *_chatCompletionGenerator({
+ args,
+ genAIEndpoint,
+ response,
+ span,
+ serverAddress,
+ serverPort,
+ operationName,
+ apiType,
+ }: {
+ args: any[];
+ genAIEndpoint: string;
+ response: any;
+ span: Span;
+ serverAddress: string;
+ serverPort: number;
+ operationName: string;
+ apiType: string;
+ }): AsyncGenerator<unknown, any, unknown> {
+ let metricParams;
+ const timestamps: number[] = [];
+ const startTime = Date.now();
+
+ try {
+ const { messages } = args[0];
+ let { tools } = args[0];
+ const result = {
+ id: '0',
+ created: -1,
+ model: '',
+ system_fingerprint: '',
+ choices: [
+ {
+ index: 0,
+ logprobs: null,
+ finish_reason: 'stop',
+ message: { role: 'assistant', content: '', reasoning_content: '' },
+ },
+ ],
+ usage: {
+ prompt_tokens: 0,
+ completion_tokens: 0,
+ total_tokens: 0,
+ output_tokens_details: { reasoning_tokens: 0 },
+ },
+ };
+
+ const toolCalls: any[] = [];
+ let reasoningText = '';
+
+ for await (const chunk of response) {
+ timestamps.push(Date.now());
+
+ if (chunk.id) result.id = chunk.id;
+ if (chunk.created) result.created = chunk.created;
+ if (chunk.model) result.model = chunk.model;
+ if (chunk.system_fingerprint) result.system_fingerprint = chunk.system_fingerprint;
+
+ if (chunk.choices?.[0]?.finish_reason) {
+ result.choices[0].finish_reason = chunk.choices[0].finish_reason;
+ }
+ if (chunk.choices?.[0]?.logprobs) {
+ result.choices[0].logprobs = chunk.choices[0].logprobs;
+ }
+ if (chunk.choices?.[0]?.delta?.content) {
+ result.choices[0].message.content += chunk.choices[0].delta.content;
+ }
+ if (chunk.choices?.[0]?.delta?.reasoning_content) {
+ reasoningText += chunk.choices[0].delta.reasoning_content;
+ (result.choices[0].message as any).reasoning_content = reasoningText;
+ }
+
+ if (chunk.choices?.[0]?.delta?.tool_calls) {
+ const deltaTools = chunk.choices[0].delta.tool_calls;
+ for (const tool of deltaTools) {
+ const idx = tool.index || 0;
+ while (toolCalls.length <= idx) {
+ toolCalls.push({
+ id: '',
+ type: 'function',
+ function: { name: '', arguments: '' },
+ });
+ }
+ if (tool.id) {
+ toolCalls[idx].id = tool.id;
+ toolCalls[idx].type = tool.type || 'function';
+ if (tool.function?.name) toolCalls[idx].function.name = tool.function.name;
+ if (tool.function?.arguments) toolCalls[idx].function.arguments = tool.function.arguments;
+ } else if (tool.function?.arguments) {
+ toolCalls[idx].function.arguments += tool.function.arguments;
+ }
+ }
+ tools = true;
+ }
+
+ if (chunk.usage) {
+ result.usage.prompt_tokens = chunk.usage.prompt_tokens || 0;
+ result.usage.completion_tokens = chunk.usage.completion_tokens || 0;
+ result.usage.total_tokens = chunk.usage.total_tokens || 0;
+ const details = chunk.usage.output_tokens_details || chunk.usage.completion_tokens_details;
+ if (details?.reasoning_tokens) {
+ result.usage.output_tokens_details.reasoning_tokens = details.reasoning_tokens;
+ }
+ }
+
+ yield chunk;
+ }
+
+ if (toolCalls.length > 0) {
+ result.choices[0].message = {
+ ...result.choices[0].message,
+ tool_calls: toolCalls,
+ } as any;
+ }
+
+ if (!result.usage.prompt_tokens && !result.usage.completion_tokens) {
+ let promptTokens = 0;
+ for (const message of messages || []) {
+ promptTokens += OpenLitHelper.openaiTokens(message.content as string, result.model) ?? 0;
+ }
+ const completionTokens = OpenLitHelper.openaiTokens(
+ result.choices[0].message.content ?? '',
+ result.model
+ );
+ if (completionTokens) {
+ result.usage = {
+ ...result.usage,
+ prompt_tokens: promptTokens,
+ completion_tokens: completionTokens,
+ total_tokens: promptTokens + completionTokens,
+ };
+ }
+ }
+
+ args[0].tools = tools;
+
+ const ttft = timestamps.length > 0 ? (timestamps[0] - startTime) / 1000 : 0;
+ let tbt = 0;
+ if (timestamps.length > 1) {
+ const timeDiffs = timestamps.slice(1).map((t, i) => t - timestamps[i]);
+ tbt = timeDiffs.reduce((a, b) => a + b, 0) / timeDiffs.length / 1000;
+ }
+
+ metricParams = await GradientWrapper._chatCompletionCommonSetter({
+ args,
+ genAIEndpoint,
+ result,
+ span,
+ ttft,
+ tbt,
+ serverAddress,
+ serverPort,
+ operationName,
+ apiType,
+ reasoningText,
+ });
+
+ return result;
+ } catch (e: any) {
+ OpenLitHelper.handleException(span, e);
+ throw e;
+ } finally {
+ span.end();
+ if (metricParams) {
+ BaseWrapper.recordMetrics(span, metricParams);
+ }
+ }
+ }
+
+ static _imageGenerateCommonSetter({
+ args,
+ genAIEndpoint,
+ response,
+ span,
+ serverAddress,
+ serverPort,
+ }: {
+ args: any[];
+ genAIEndpoint: string;
+ response: any;
+ span: Span;
+ serverAddress: string;
+ serverPort: number;
+ }) {
+ const captureContent = OpenlitConfig.captureMessageContent;
+ const body = args[0] || {};
+ const requestModel = body.model || 'unknown';
+ const responseModel = response?.model || requestModel;
+ const size = body.size || response?.size || '1024x1024';
+ const quality = body.quality || response?.quality || 'standard';
+ const pricingInfo = OpenlitConfig.pricingInfo || {};
+ const cost = OpenLitHelper.getImageModelCost(requestModel, pricingInfo, size, quality as any);
+
+ GradientWrapper.setBaseSpanAttributes(span, {
+ genAIEndpoint,
+ model: requestModel,
+ user: body.user,
+ cost,
+ aiSystem: AI_SYSTEM,
+ serverAddress,
+ serverPort,
+ });
+
+ span.setAttribute(SemanticConvention.GEN_AI_OUTPUT_TYPE, 'image');
+ if (response?.created != null) {
+ span.setAttribute(SemanticConvention.GEN_AI_RESPONSE_ID, String(response.created));
+ }
+ span.setAttribute(SemanticConvention.GEN_AI_RESPONSE_MODEL, responseModel);
+
+ if (captureContent && body.prompt) {
+ span.setAttribute(
+ SemanticConvention.GEN_AI_INPUT_MESSAGES,
+ JSON.stringify([
+ {
+ role: 'user',
+ parts: [{ type: 'text', content: String(body.prompt) }],
+ },
+ ])
+ );
+ }
+
+ return {
+ genAIEndpoint,
+ model: requestModel,
+ user: body.user,
+ cost,
+ aiSystem: AI_SYSTEM,
+ serverAddress,
+ serverPort,
+ };
+ }
+
+ static async _chatCompletionCommonSetter({
+ args,
+ genAIEndpoint,
+ result,
+ span,
+ ttft = 0,
+ tbt = 0,
+ serverAddress,
+ serverPort,
+ operationName = SemanticConvention.GEN_AI_OPERATION_TYPE_CHAT,
+ apiType = 'chat',
+ reasoningText,
+ }: {
+ args: any[];
+ genAIEndpoint: string;
+ result: any;
+ span: Span;
+ ttft?: number;
+ tbt?: number;
+ serverAddress: string;
+ serverPort: number;
+ operationName?: string;
+ apiType?: string;
+ reasoningText?: string;
+ }) {
+ const captureContent = OpenlitConfig.captureMessageContent;
+ const body = args[0] || {};
+ const requestModel = body.model || 'unknown';
+ const { messages, tools: _tools, stream: _stream = false } = body;
+
+ applyGradientChatRequestAttributes(span, body);
+ span.setAttribute(SemanticConvention.OPENAI_API_TYPE, apiType);
+
+ if (captureContent) {
+ span.setAttribute(
+ SemanticConvention.GEN_AI_INPUT_MESSAGES,
+ OpenLitHelper.buildInputMessages(messages || [])
+ );
+ }
+
+ if (result.id) {
+ span.setAttribute(SemanticConvention.GEN_AI_RESPONSE_ID, result.id);
+ }
+
+ const responseModel = result.model || requestModel;
+ const usage = result.usage || { prompt_tokens: 0, completion_tokens: 0, total_tokens: 0 };
+ const pricingInfo = OpenlitConfig.pricingInfo || {};
+ const cost = OpenLitHelper.getChatModelCost(
+ requestModel,
+ pricingInfo,
+ usage.prompt_tokens,
+ usage.completion_tokens
+ );
+
+ GradientWrapper.setBaseSpanAttributes(span, {
+ genAIEndpoint,
+ model: requestModel,
+ user: body.user,
+ cost,
+ aiSystem: AI_SYSTEM,
+ serverAddress,
+ serverPort,
+ });
+
+ span.setAttribute(SemanticConvention.GEN_AI_RESPONSE_MODEL, responseModel);
+
+ if (result.system_fingerprint) {
+ span.setAttribute(SemanticConvention.GEN_AI_RESPONSE_SYSTEM_FINGERPRINT, result.system_fingerprint);
+ }
+
+ const inputTokens = usage.prompt_tokens || 0;
+ const outputTokens = usage.completion_tokens || 0;
+ span.setAttribute(SemanticConvention.GEN_AI_USAGE_INPUT_TOKENS, inputTokens);
+ span.setAttribute(SemanticConvention.GEN_AI_USAGE_OUTPUT_TOKENS, outputTokens);
+ span.setAttribute(SemanticConvention.GEN_AI_CLIENT_TOKEN_USAGE, inputTokens + outputTokens);
+
+ const reasoningTokens =
+ usage.output_tokens_details?.reasoning_tokens ??
+ usage.completion_tokens_details?.reasoning_tokens ??
+ 0;
+ if (reasoningTokens) {
+ span.setAttribute(SemanticConvention.GEN_AI_USAGE_REASONING_TOKENS, reasoningTokens);
+ }
+
+ if (ttft > 0) {
+ span.setAttribute(SemanticConvention.GEN_AI_SERVER_TTFT, ttft);
+ }
+ if (tbt > 0) {
+ span.setAttribute(SemanticConvention.GEN_AI_SERVER_TBT, tbt);
+ }
+
+ if (result.choices?.[0]?.finish_reason) {
+ span.setAttribute(SemanticConvention.GEN_AI_RESPONSE_FINISH_REASON, [
+ result.choices[0].finish_reason,
+ ]);
+ }
+
+ const outputType =
+ (body.response_format as any)?.type === 'json_object'
+ ? SemanticConvention.GEN_AI_OUTPUT_TYPE_JSON
+ : SemanticConvention.GEN_AI_OUTPUT_TYPE_TEXT;
+ span.setAttribute(SemanticConvention.GEN_AI_OUTPUT_TYPE, outputType);
+
+ const message = result.choices?.[0]?.message || {};
+ const resolvedReasoning =
+ reasoningText ||
+ message.reasoning_content ||
+ '';
+ if (message.tool_calls) {
+ const toolCalls = message.tool_calls;
+ const toolNames = toolCalls.map((t: any) => t.function?.name || '').filter(Boolean);
+ const toolIds = toolCalls.map((t: any) => t.id || '').filter(Boolean);
+ const toolArgs = toolCalls.map((t: any) => t.function?.arguments || '').filter(Boolean);
+
+ if (toolNames.length > 0) {
+ span.setAttribute(SemanticConvention.GEN_AI_TOOL_NAME, toolNames.join(', '));
+ }
+ if (toolIds.length > 0) {
+ span.setAttribute(SemanticConvention.GEN_AI_TOOL_CALL_ID, toolIds.join(', '));
+ }
+ if (toolArgs.length > 0) {
+ span.setAttribute(SemanticConvention.GEN_AI_TOOL_ARGS, toolArgs.join(', '));
+ }
+ }
+
+ let inputMessagesJson: string | undefined;
+ let outputMessagesJson: string | undefined;
+ const toolDefinitionsJson = OpenLitHelper.buildToolDefinitions(_tools);
+ const systemInstructionsJson = OpenLitHelper.buildSystemInstructionsFromMessages(messages || []);
+
+ const versionExtras: Record<string, string> = {};
+ try {
+ const maxTokens = body.max_completion_tokens ?? body.max_tokens ?? null;
+ const versionHash = OpenLitHelper.computeAgentVersionHash({
+ systemInstructions: systemInstructionsJson ?? null,
+ toolDefinitions: toolDefinitionsJson ?? null,
+ primaryModel: responseModel || requestModel,
+ runtimeConfig: {
+ temperature: body.temperature ?? null,
+ top_p: body.top_p ?? null,
+ max_tokens: maxTokens,
+ provider: AI_SYSTEM,
+ },
+ providers: [AI_SYSTEM],
+ });
+ if (versionHash) {
+ versionExtras[SemanticConvention.OPENLIT_AGENT_VERSION_HASH] = versionHash;
+ span.setAttribute(SemanticConvention.OPENLIT_AGENT_VERSION_HASH, versionHash);
+ }
+ } catch {
+ // Never fail the wrapped call on hash issues.
+ }
+ const versionLabel = getCurrentAgentVersion();
+ if (versionLabel) {
+ versionExtras[SemanticConvention.GEN_AI_AGENT_VERSION] = versionLabel;
+ span.setAttribute(SemanticConvention.GEN_AI_AGENT_VERSION, versionLabel);
+ }
+
+ if (captureContent) {
+ const toolCalls = message.tool_calls;
+ outputMessagesJson = GradientWrapper._buildOutputMessages(
+ message.content || '',
+ result.choices?.[0]?.finish_reason || 'stop',
+ toolCalls,
+ resolvedReasoning || undefined
+ );
+ span.setAttribute(SemanticConvention.GEN_AI_OUTPUT_MESSAGES, outputMessagesJson);
+ inputMessagesJson = OpenLitHelper.buildInputMessages(messages || []);
+ if (systemInstructionsJson) {
+ span.setAttribute(SemanticConvention.GEN_AI_SYSTEM_INSTRUCTIONS, systemInstructionsJson);
+ }
+ }
+ if (toolDefinitionsJson) {
+ span.setAttribute(SemanticConvention.GEN_AI_TOOL_DEFINITIONS, toolDefinitionsJson);
+ }
+
+ if (!OpenlitConfig.disableEvents) {
+ const eventAttrs: Attributes = {
+ [SemanticConvention.GEN_AI_OPERATION]: operationName,
+ [SemanticConvention.GEN_AI_REQUEST_MODEL]: requestModel,
+ [SemanticConvention.GEN_AI_RESPONSE_MODEL]: responseModel,
+ [SemanticConvention.SERVER_ADDRESS]: serverAddress,
+ [SemanticConvention.SERVER_PORT]: serverPort,
+ [SemanticConvention.GEN_AI_RESPONSE_ID]: result.id,
+ [SemanticConvention.GEN_AI_RESPONSE_FINISH_REASON]: [result.choices?.[0]?.finish_reason],
+ [SemanticConvention.GEN_AI_OUTPUT_TYPE]: outputType,
+ [SemanticConvention.GEN_AI_USAGE_INPUT_TOKENS]: inputTokens,
+ [SemanticConvention.GEN_AI_USAGE_OUTPUT_TOKENS]: outputTokens,
+ ...versionExtras,
+ };
+ if (captureContent) {
+ if (inputMessagesJson) eventAttrs[SemanticConvention.GEN_AI_INPUT_MESSAGES] = inputMessagesJson;
+ if (systemInstructionsJson) {
+ eventAttrs[SemanticConvention.GEN_AI_SYSTEM_INSTRUCTIONS] = systemInstructionsJson;
+ }
+ if (outputMessagesJson) {
+ eventAttrs[SemanticConvention.GEN_AI_OUTPUT_MESSAGES] = outputMessagesJson;
+ }
+ }
+ if (toolDefinitionsJson) {
+ eventAttrs[SemanticConvention.GEN_AI_TOOL_DEFINITIONS] = toolDefinitionsJson;
+ }
+ OpenLitHelper.emitInferenceEvent(span, eventAttrs);
+ }
+
+ return {
+ genAIEndpoint,
+ model: requestModel,
+ user: body.user,
+ cost,
+ aiSystem: AI_SYSTEM,
+ serverAddress,
+ serverPort,
+ };
+ }
+
+ static _buildOutputMessages(
+ text: string,
+ finishReason: string,
+ toolCalls?: any[],
+ reasoning?: string
+ ): string {
+ try {
+ const parts: any[] = [];
+ if (reasoning) {
+ parts.push({ type: 'reasoning', content: reasoning });
+ }
+ if (text) {
+ parts.push({ type: 'text', content: text });
+ }
+ if (toolCalls?.length) {
+ for (const tc of toolCalls) {
+ let argsVal = tc.function?.arguments || tc.arguments || {};
+ if (typeof argsVal === 'string') {
+ try {
+ argsVal = JSON.parse(argsVal);
+ } catch {
+ argsVal = { raw: argsVal };
+ }
+ }
+ parts.push({
+ type: 'tool_call',
+ id: tc.id || '',
+ name: tc.function?.name || tc.name || '',
+ arguments: argsVal,
+ });
+ }
+ }
+ return JSON.stringify([
+ { role: 'assistant', parts, finish_reason: finishReason || 'stop' },
+ ]);
+ } catch {
+ return '[]';
+ }
+ }
+}
+
+export default GradientWrapper;
diff --git a/sdk/typescript/src/instrumentation/index.ts b/sdk/typescript/src/instrumentation/index.ts
index 2df5768d..45d500fd 100644
--- a/sdk/typescript/src/instrumentation/index.ts
+++ b/sdk/typescript/src/instrumentation/index.ts
@@ -7,6 +7,7 @@ import AnthropicInstrumentation from './anthropic';
import CohereInstrumentation from './cohere';
import GroqInstrumentation from './groq';
import AI21Instrumentation from './ai21';
+import GradientInstrumentation from './gradient';
import MistralInstrumentation from './mistral';
import GoogleAIInstrumentation from './google-ai';
import TogetherInstrumentation from './together';
@@ -79,6 +80,7 @@ export default class Instrumentations {
cohere: new CohereInstrumentation(),
groq: new GroqInstrumentation(),
ai21: new AI21Instrumentation(),
+ gradient: new GradientInstrumentation(),
mistral: new MistralInstrumentation(),
'google-ai': new GoogleAIInstrumentation(),
together: new TogetherInstrumentation(),
diff --git a/sdk/typescript/src/semantic-convention.ts b/sdk/typescript/src/semantic-convention.ts
index 46c45d68..1426eff3 100644
--- a/sdk/typescript/src/semantic-convention.ts
+++ b/sdk/typescript/src/semantic-convention.ts
@@ -233,6 +233,7 @@ export default class SemanticConvention {
static GEN_AI_SYSTEM_GOOGLE_AI_STUDIO = 'gcp.gemini';
static GEN_AI_SYSTEM_GROQ = 'groq';
static GEN_AI_SYSTEM_AI21 = 'ai21';
+ static GEN_AI_SYSTEM_DIGITALOCEAN = 'digitalocean';
static GEN_AI_SYSTEM_AZURE_AI_INFERENCE = 'azure.ai.inference';
static GEN_AI_SYSTEM_LLAMAINDEX = 'llamaindex';
static GEN_AI_SYSTEM_TOGETHER = 'together';
diff --git a/sdk/typescript/src/types.ts b/sdk/typescript/src/types.ts
index af418fc9..20e97f14 100644
--- a/sdk/typescript/src/types.ts
+++ b/sdk/typescript/src/types.ts
@@ -3,7 +3,7 @@ import { NodeTracerProvider } from '@opentelemetry/sdk-trace-node';
import { metrics } from '@opentelemetry/api';
import type { Guard } from './guard/base';
-export type InstrumentationType = 'openai' | 'anthropic' | 'cohere' | 'groq' | 'mistral' | 'google-ai' | 'together' | 'ollama' | 'vercel-ai' | 'langchain' | 'langgraph' | 'pinecone' | 'bedrock' | 'llamaindex' | 'huggingface' | 'replicate' | 'chroma' | 'qdrant' | 'milvus' | 'astra' | 'azure-ai-inference' | 'openai-agents' | 'strands' | 'google-adk' | 'claude-agent-sdk' | 'cursor-sdk' | 'ai21' | 'mcp';
+export type InstrumentationType = 'openai' | 'anthropic' | 'cohere' | 'groq' | 'mistral' | 'google-ai' | 'together' | 'ollama' | 'vercel-ai' | 'langchain' | 'langgraph' | 'pinecone' | 'bedrock' | 'llamaindex' | 'huggingface' | 'replicate' | 'chroma' | 'qdrant' | 'milvus' | 'astra' | 'azure-ai-inference' | 'openai-agents' | 'strands' | 'google-adk' | 'claude-agent-sdk' | 'cursor-sdk' | 'ai21' | 'gradient' | 'mcp';
export type OpenlitInstrumentations = Partial<Record<InstrumentationType, any>>;