Skip to content

Commit cea43b1

Browse files
feat(server-utils): Decide gen_ai content recording per call for Mastra, TypeSafe, Workers AI and Bedrock
recordInputs and recordOutputs of mastraIntegration, typesafeIntegration, instrumentTypeSafeClient, instrumentWorkersAiClient and awsIntegration (Bedrock Runtime) can be functions that decide per call. They run once when the call starts, in the caller's async context, and the end and response paths reuse that decision. Mastra decides per span when the exporter receives its start, so its functions run at export time. Co-Authored-By: Francesco Gringl-Novy <2411343+mydea@users.noreply.github.com>
1 parent 5fa641d commit cea43b1

12 files changed

Lines changed: 521 additions & 67 deletions

File tree

‎packages/server-utils/src/ai/mastra/index.ts‎

Lines changed: 26 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -11,8 +11,8 @@ import {
1111
} from '@sentry/core';
1212
import { GEN_AI_RESPONSE_MODEL, SENTRY_OP, SENTRY_ORIGIN } from '@sentry/conventions/attributes';
1313
import { DEBUG_BUILD } from '../../debug-build';
14-
import type { GenAiOptions } from '../core/utils';
15-
import { resolveAIRecordingOptions } from '../core/utils';
14+
import type { GenAiCallOptions } from '../core/utils';
15+
import { resolveGenAiCallRecording } from '../core/utils';
1616
import {
1717
getOperation,
1818
getSpanAttributes,
@@ -43,12 +43,23 @@ import type {
4343
MastraTracingEvent,
4444
} from './types';
4545

46-
export type MastraExporterOptions = GenAiOptions;
46+
/** The span that `recordInputs`/`recordOutputs` decide on. */
47+
export interface MastraCallInfo {
48+
/** The Mastra span as exported, when it starts. */
49+
span: MastraExportedSpan;
50+
}
51+
52+
/**
53+
* `recordInputs`/`recordOutputs` functions run when the exporter receives the start of a Mastra span,
54+
* not in the async context of the code that started it.
55+
*/
56+
export type MastraExporterOptions = GenAiCallOptions<MastraCallInfo>;
4757

4858
interface TrackedSpan {
4959
span: Span;
5060
spanType: MastraSpanType;
5161
usage: SpanAttributes;
62+
recordingOptions: AttributeRecordingOptions;
5263
evaluation?: ClassifierEvaluationCall;
5364
}
5465

@@ -135,22 +146,23 @@ export class SentryMastraExporter implements MastraObservabilityExporter {
135146
return;
136147
}
137148

138-
// Per event: the exporter can be constructed before `Sentry.init()`, when `dataCollection.genAI` does not exist yet.
139-
const recordingOptions = resolveAIRecordingOptions(this._options);
140149
switch (event.type) {
141150
case 'span_started':
142-
this._onSpanStarted(span, recordingOptions);
151+
this._onSpanStarted(span);
143152
break;
144153
case 'span_updated':
145-
this._onSpanUpdated(span, recordingOptions);
154+
this._onSpanUpdated(span);
146155
break;
147156
case 'span_ended':
148-
this._onSpanEnded(span, recordingOptions);
157+
this._onSpanEnded(span);
149158
break;
150159
}
151160
}
152161

153-
private _onSpanStarted(span: MastraExportedSpan, recordingOptions: AttributeRecordingOptions): void {
162+
private _onSpanStarted(span: MastraExportedSpan): void {
163+
// Per span, not in the constructor: the exporter can be constructed before `Sentry.init()`, when
164+
// `dataCollection.genAI` does not exist yet.
165+
const recordingOptions = resolveGenAiCallRecording(this._options, { span });
154166
const parentId = this._resolveParentId(span.parentSpanId);
155167
const parentSpan = parentId ? this._spans.get(parentId)?.span : undefined;
156168
const activeSpan = getActiveSpan();
@@ -178,7 +190,7 @@ export class SentryMastraExporter implements MastraObservabilityExporter {
178190
});
179191
}
180192

181-
this._trackSpan(span.id, { span: sentrySpan, spanType: span.type, usage: {}, evaluation });
193+
this._trackSpan(span.id, { span: sentrySpan, spanType: span.type, usage: {}, recordingOptions, evaluation });
182194
}
183195

184196
/** Track a started span, ending any Sentry span that would otherwise be dropped without `end()`. */
@@ -205,21 +217,21 @@ export class SentryMastraExporter implements MastraObservabilityExporter {
205217
return this._spans.remove(id);
206218
}
207219

208-
private _onSpanUpdated(span: MastraExportedSpan, recordingOptions: AttributeRecordingOptions): void {
220+
private _onSpanUpdated(span: MastraExportedSpan): void {
209221
const tracked = this._spans.get(span.id);
210222
if (tracked) {
211-
tracked.span.setAttributes(getSpanAttributes(span, recordingOptions));
223+
tracked.span.setAttributes(getSpanAttributes(span, tracked.recordingOptions));
212224
}
213225
}
214226

215-
private _onSpanEnded(span: MastraExportedSpan, recordingOptions: AttributeRecordingOptions): void {
227+
private _onSpanEnded(span: MastraExportedSpan): void {
216228
const tracked = this._spans.get(span.id);
217229
if (!tracked) {
218230
DEBUG_BUILD && debug.warn(`[Mastra] no Sentry span open for ended span ${span.id} (${span.name})`);
219231
return;
220232
}
221233

222-
const { span: sentrySpan } = tracked;
234+
const { span: sentrySpan, recordingOptions } = tracked;
223235
sentrySpan.setAttributes(getSpanAttributes(span, recordingOptions));
224236
sentrySpan.updateName(getSpanName(span));
225237

‎packages/server-utils/src/ai/typesafe/index.ts‎

Lines changed: 14 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -13,10 +13,19 @@ import {
1313
import { GEN_AI_DECIDE } from '@sentry/conventions/op';
1414
import type { Span, SpanAttributes } from '@sentry/core';
1515
import { isObjectLike, SPAN_STATUS_ERROR, startInactiveSpan, withActiveSpan } from '@sentry/core';
16-
import type { GenAiOptions } from '../core/utils';
17-
import { getEvaluationInputMessages, getEvaluationOutputMessages, resolveAIRecordingOptions } from '../core/utils';
16+
import type { GenAiCallOptions } from '../core/utils';
17+
import { getEvaluationInputMessages, getEvaluationOutputMessages, resolveGenAiCallRecording } from '../core/utils';
1818
import { TYPESAFE_ORIGIN, TYPESAFE_PROVIDER_NAME } from './constants';
1919

20+
/** The call that `recordInputs`/`recordOutputs` decide on. */
21+
export interface TypeSafeCallInfo {
22+
/** The request, the first argument of `systemOne` as passed. */
23+
request: unknown;
24+
}
25+
26+
/** Options for the TypeSafe integration. */
27+
export type TypeSafeOptions = GenAiCallOptions<TypeSafeCallInfo>;
28+
2029
/**
2130
* Start the span for a `systemOne(request)` call. The request model falls back to the client's
2231
* `defaultModel`, the same way the SDK resolves it.
@@ -119,7 +128,7 @@ export function onSystemOneResponse(
119128
/**
120129
* Instrument a TypeSafe client (`@typesafe-ai/sdk`) with Sentry tracing.
121130
*/
122-
export function instrumentTypeSafeClient<T extends object>(client: T, options?: GenAiOptions): T {
131+
export function instrumentTypeSafeClient<T extends object>(client: T, options?: TypeSafeOptions): T {
123132
return new Proxy(client, {
124133
get(target, prop) {
125134
// Read with the real client as receiver: the SDK keeps its API key in a private class field.
@@ -140,9 +149,9 @@ function instrumentSystemOne(
140149
systemOne: (...args: unknown[]) => unknown,
141150
client: object,
142151
args: unknown[],
143-
options: GenAiOptions | undefined,
152+
options: TypeSafeOptions | undefined,
144153
): unknown {
145-
const { recordInputs, recordOutputs } = resolveAIRecordingOptions(options);
154+
const { recordInputs, recordOutputs } = resolveGenAiCallRecording(options, { request: args[0] });
146155
const span = startDecideSpan(args[0], client, recordInputs);
147156
const endWithError = (): void => {
148157
span.setStatus({ code: SPAN_STATUS_ERROR, message: 'internal_error' });

‎packages/server-utils/src/ai/workers-ai/index.ts‎

Lines changed: 14 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
import { SENTRY_OP } from '@sentry/conventions/attributes';
22
import { getClient, hasSpanStreamingEnabled, SPAN_STATUS_ERROR, startSpan, startSpanManual } from '@sentry/core';
33
import type { Span } from '@sentry/core';
4-
import { isReadableStream, resolveAIRecordingOptions } from '../core/utils';
4+
import { isReadableStream, resolveGenAiCallRecording } from '../core/utils';
55
import { shouldSkipAiProviderSpan } from '../pi-ai/providers';
66
import { WORKERS_AI_INTEGRATION_NAME } from './constants';
77
import { instrumentWorkersAiStream } from './streaming';
@@ -20,7 +20,7 @@ import {
2020
function instrumentRun(
2121
originalRun: (...args: unknown[]) => Promise<unknown>,
2222
context: unknown,
23-
options: WorkersAiOptions & Required<Pick<WorkersAiOptions, 'recordInputs' | 'recordOutputs'>>,
23+
options: WorkersAiOptions,
2424
): (...args: unknown[]) => Promise<unknown> {
2525
return function instrumentedRun(...args: unknown[]): Promise<unknown> {
2626
if (shouldSkipAiProviderSpan(WORKERS_AI_INTEGRATION_NAME)) {
@@ -30,6 +30,12 @@ function instrumentRun(
3030
const [model, inputs, runOptions] = args as [unknown, unknown, Record<string, unknown> | undefined];
3131

3232
const operationName = getOperationName(model, inputs);
33+
const { recordInputs, recordOutputs } = resolveGenAiCallRecording(options, {
34+
operation: operationName,
35+
model,
36+
inputs,
37+
options: runOptions,
38+
});
3339
const requestAttributes = extractRequestAttributes(model, inputs, operationName);
3440
const modelName = typeof model === 'string' && model ? model : 'unknown';
3541
const client = getClient();
@@ -71,17 +77,17 @@ function instrumentRun(
7177
return handleError(error);
7278
}
7379

74-
if (options.recordInputs) {
80+
if (recordInputs) {
7581
addRequestAttributes(span, inputs, operationName);
7682
}
7783

7884
return originalResult.then(result => {
7985
if (isReadableStream<Uint8Array>(result)) {
80-
return instrumentWorkersAiStream(result, span, options.recordOutputs);
86+
return instrumentWorkersAiStream(result, span, recordOutputs);
8187
}
8288

8389
// The model did not actually return a stream — finalize the span eagerly.
84-
addResponseAttributes(span, result, options.recordOutputs, operationName);
90+
addResponseAttributes(span, result, recordOutputs, operationName);
8591
span.end();
8692
return result;
8793
}, handleError);
@@ -91,13 +97,13 @@ function instrumentRun(
9197
return startSpan(spanConfig, (span: Span) => {
9298
const originalResult = originalRun.apply(context, args) as Promise<unknown>;
9399

94-
if (options.recordInputs) {
100+
if (recordInputs) {
95101
addRequestAttributes(span, inputs, operationName);
96102
}
97103

98104
return originalResult.then(result => {
99105
if (!returnsRawResponse) {
100-
addResponseAttributes(span, result, options.recordOutputs, operationName);
106+
addResponseAttributes(span, result, recordOutputs, operationName);
101107
}
102108
return result;
103109
});
@@ -121,14 +127,12 @@ function instrumentRun(
121127
* ```
122128
*/
123129
export function instrumentWorkersAiClient<T extends object>(client: T, options?: WorkersAiOptions): T {
124-
const resolvedOptions = resolveAIRecordingOptions(options);
125-
126130
const instrumented = new Proxy(client, {
127131
get(target: object, prop: string | symbol, receiver: unknown): unknown {
128132
const value = Reflect.get(target, prop, receiver);
129133

130134
if (prop === 'run' && typeof value === 'function') {
131-
return instrumentRun(value as (...args: unknown[]) => Promise<unknown>, target, resolvedOptions);
135+
return instrumentRun(value as (...args: unknown[]) => Promise<unknown>, target, options ?? {});
132136
}
133137

134138
// Bind passed-through functions to the original target to preserve `this` (e.g. private fields).

‎packages/server-utils/src/ai/workers-ai/types.ts‎

Lines changed: 11 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,16 @@
1-
import type { GenAiOptions } from '../core/utils';
1+
import type { GenAiCallOptions } from '../core/utils';
2+
3+
/** The call that `recordInputs`/`recordOutputs` decide on: the arguments of `run()` as passed. */
4+
export interface WorkersAiCallInfo {
5+
/** The gen_ai operation of the call, such as `chat` or `embeddings`. */
6+
operation: string;
7+
model: unknown;
8+
inputs: unknown;
9+
options: Record<string, unknown> | undefined;
10+
}
211

312
/** Options for the Workers AI integration. */
4-
export type WorkersAiOptions = GenAiOptions;
13+
export type WorkersAiOptions = GenAiCallOptions<WorkersAiCallInfo>;
514

615
/**
716
* The token usage reported by Workers AI text generation models.

‎packages/server-utils/src/integrations/aws-sdk/index.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,6 @@ import {
1010
SENTRY_ORIGIN,
1111
} from '@sentry/conventions/attributes';
1212
import { RPC } from '@sentry/conventions/op';
13-
import type { GenAiOptions } from '../../ai/core/utils';
1413
import type { OrchestrionChannelContext } from '../../orchestrion/types';
1514
import { CHANNELS } from '../../orchestrion/channels';
1615
import { awsSdkModuleNames } from '../../orchestrion/config/aws-sdk';
@@ -19,6 +18,7 @@ import type { TracingChannelLifeCycleOptions } from '../../tracing-channel';
1918
import { bindTracingChannelToSpan, safeChannelCallback } from '../../tracing-channel';
2019
import { AWS_SDK_ORIGIN_INTEGRATION_NAME } from './constants';
2120
import { ServicesExtensions } from './services';
21+
import type { BedrockRuntimeOptions } from './services/bedrock-runtime';
2222
import type { NormalizedRequest, NormalizedResponse, RequestMetadata } from './types';
2323
import { extractAttributesFromNormalizedRequest, normalizeV3Request, removeSuffixFromStringIfExists } from './utils';
2424

@@ -65,7 +65,7 @@ function setMetadataAttributes(span: Span, metadata: Record<string, any> | undef
6565
}
6666

6767
// `recordInputs` and `recordOutputs` apply to Bedrock Runtime calls, the only AWS calls that carry prompts and responses.
68-
export type AwsIntegrationOptions = GenAiOptions;
68+
export type AwsIntegrationOptions = BedrockRuntimeOptions;
6969

7070
const _awsIntegration = ((options?: AwsIntegrationOptions) => {
7171
const servicesExtensions = new ServicesExtensions(options);

‎packages/server-utils/src/integrations/aws-sdk/services/ServicesExtensions.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
import type { Span } from '@sentry/core';
2-
import type { GenAiOptions } from '../../../ai/core/utils';
32
import type { NormalizedRequest, NormalizedResponse, RequestMetadata } from '../types';
3+
import type { BedrockRuntimeOptions } from './bedrock-runtime';
44
import { BedrockRuntimeServiceExtension } from './bedrock-runtime';
55
import { DynamodbServiceExtension } from './dynamodb';
66
import { KinesisServiceExtension } from './kinesis';
@@ -17,7 +17,7 @@ export class ServicesExtensions implements ServiceExtension {
1717
// registered extension still get the base rpc span from the subscriber.
1818
private _services: Map<string, ServiceExtension>;
1919

20-
public constructor(genAiOptions?: GenAiOptions) {
20+
public constructor(genAiOptions?: BedrockRuntimeOptions) {
2121
this._services = new Map<string, ServiceExtension>([
2222
['SecretsManager', new SecretsManagerServiceExtension()],
2323
['SFN', new StepFunctionsServiceExtension()],

0 commit comments

Comments
 (0)