ApplyGuardrailScope class

Package:

@microsoft/agents-a365-observability

Provides OpenTelemetry tracing scope for security guardrail evaluation operations.

Describes a security guardian evaluation. Multiple guardian spans MAY exist under a single operation span if multiple guardians are chained.

Guardian spans SHOULD be children of the operation span they are protecting (e.g., inference or execute_tool spans).

Extends

OpenTelemetryScope

Methods

recordContentOutput(string)	Records the output content value for the guardrail evaluation (opt-in).
recordDecision(GuardrailDecisionType, string)	Records an updated decision on the guardrail span. Use this when the guardrail decision is determined after span creation.
recordFinding(GuardrailFinding)	Records a security finding event on the current span. Multiple findings may be recorded per guardrail evaluation.
start(GuardrailDetails, AgentDetails, Request, UserDetails, SpanDetails)	Creates and starts a new scope for guardrail evaluation tracing.

Inherited Methods

dispose()	Legacy dispose method for compatibility
getSpanContext()	Gets the span context for this scope. This can be used to create a ParentSpanRef for explicit parent-child linking across async boundaries.
recordAttributes(Iterable<[string, AttributeValue], any, any> | Record<string, AttributeValue> | null | undefined)	Records multiple attribute key/value pairs for telemetry tracking.
recordCancellation(string)	Records a cancellation event on the span. Sets the span status to ERROR with the cancellation reason and marks the error type as 'TaskCanceledException'.
recordError(Error)	Records an error that occurred during the operation
setEndTime(TimeInput)	Sets a custom end time for the scope. When set, dispose will pass this value to span.end() instead of using the current wall-clock time. This is useful when the actual end time of the operation is known before the scope is disposed.
withActiveSpanAsync<T>(() => Promise<T>)	Makes this span active for the duration of the async callback execution
[dispose]()	Disposes the scope and finalizes telemetry data collection

Method Details

recordContentOutput(string)

Records the output content value for the guardrail evaluation (opt-in).

function recordContentOutput(outputValue: string)

Parameters

outputValue

string

The output content after guardrail processing.

recordDecision(GuardrailDecisionType, string)

Records an updated decision on the guardrail span. Use this when the guardrail decision is determined after span creation.

function recordDecision(decisionType: GuardrailDecisionType, reason?: string)

Parameters

decisionType

GuardrailDecisionType

The decision type made by the guardian.

reason

string

Optional human-readable explanation for the decision.

recordFinding(GuardrailFinding)

Records a security finding event on the current span. Multiple findings may be recorded per guardrail evaluation.

function recordFinding(finding: GuardrailFinding)

Parameters

finding

GuardrailFinding

The security finding to record.

start(GuardrailDetails, AgentDetails, Request, UserDetails, SpanDetails)

Creates and starts a new scope for guardrail evaluation tracing.

static function start(details: GuardrailDetails, agentDetails: AgentDetails, request?: Request, userDetails?: UserDetails, spanDetails?: SpanDetails): ApplyGuardrailScope

Parameters

details

GuardrailDetails

Details of the guardrail evaluation (target, decision, guardian info, policy).

agentDetails

AgentDetails

Information about the agent being guarded.

request

Request

Optional request details for conversation context.

userDetails

UserDetails

Optional human user details.

spanDetails

SpanDetails

Optional span configuration (parent context, timing, kind, span links).

Returns

ApplyGuardrailScope

A new ApplyGuardrailScope instance.

Inherited Method Details

dispose()

Legacy dispose method for compatibility

function dispose()

Inherited From OpenTelemetryScope.dispose

getSpanContext()

Gets the span context for this scope. This can be used to create a ParentSpanRef for explicit parent-child linking across async boundaries.

function getSpanContext(): SpanContext

Returns

SpanContext

The SpanContext containing traceId and spanId

Inherited From OpenTelemetryScope.getSpanContext

recordAttributes(Iterable<[string, AttributeValue], any, any> | Record<string, AttributeValue> | null | undefined)

Records multiple attribute key/value pairs for telemetry tracking.

function recordAttributes(attributes: Iterable<[string, AttributeValue], any, any> | Record<string, AttributeValue> | null | undefined)

Parameters

attributes

Iterable<[string, AttributeValue], any, any> | Record<string, AttributeValue> | null | undefined

Collection of attribute key/value pairs (array or iterable of [key, value] or object map).

Inherited From OpenTelemetryScope.recordAttributes

recordCancellation(string)

Records a cancellation event on the span. Sets the span status to ERROR with the cancellation reason and marks the error type as 'TaskCanceledException'.

function recordCancellation(reason?: string)

Parameters

reason

string

Optional cancellation reason. Defaults to 'Task was cancelled'.

Inherited From OpenTelemetryScope.recordCancellation

recordError(Error)

Records an error that occurred during the operation

function recordError(error: Error)

Parameters

error

Error

The error that occurred

Inherited From OpenTelemetryScope.recordError

setEndTime(TimeInput)

Sets a custom end time for the scope. When set, dispose will pass this value to span.end() instead of using the current wall-clock time. This is useful when the actual end time of the operation is known before the scope is disposed.

function setEndTime(endTime: TimeInput)

Parameters

endTime

TimeInput

The end time as milliseconds since epoch, a Date, or an HrTime tuple.

Inherited From OpenTelemetryScope.setEndTime

withActiveSpanAsync<T>(() => Promise<T>)

Makes this span active for the duration of the async callback execution

function withActiveSpanAsync<T>(callback: () => Promise<T>): Promise<T>

Parameters

callback

() => Promise<T>

Returns

Promise<T>

Inherited From OpenTelemetryScope.withActiveSpanAsync

[dispose]()

Disposes the scope and finalizes telemetry data collection

function [dispose]()

Inherited From OpenTelemetryScope.[dispose]