@microsoft/agents-a365-observability package
클래스
| Agent365ExporterOptions |
내보내기 일괄 처리당 최대 범위 수입니다. |
| BaggageBuilder |
OpenTelemetry 컨텍스트 전파에 대한 요청별 수하물 작성기. 이 클래스는 OpenTelemetry 컨텍스트에서 전파될 수하물 값을 설정하기 위한 흐름 API를 제공합니다. 예시
|
| BaggageScope |
수하물 범위에 대한 컨텍스트 관리자입니다. 이 클래스는 수하물 값의 수명 주기를 관리하여 입력할 때 설정하고 출구에서 이전 컨텍스트를 복원합니다. |
| Builder |
OpenTelemetry 추적을 사용하여 에이전트 365를 구성하기 위한 작성기 |
| ExecuteToolScope |
AI 도구 실행 작업에 대한 OpenTelemetry 추적 범위를 제공합니다. |
| InferenceScope |
생성 AI 유추 작업에 대한 OpenTelemetry 추적 범위를 제공합니다. |
| InvokeAgentScope |
AI 에이전트 호출 작업에 대한 OpenTelemetry 추적 범위를 제공합니다. |
| ObservabilityConfiguration |
관찰성 패키지에 대한 구성입니다. 런타임 설정을 상속하고 관찰 기능별 설정을 추가합니다. |
| ObservabilityManager |
AI 에이전트 및 도구용 OpenTelemetry 추적을 제공하는 에이전트 365의 주요 진입점 |
| OpenTelemetryConstants |
에이전트 365에 대한 OpenTelemetry 상수 |
| OpenTelemetryScope |
OpenTelemetry 추적 범위에 대한 기본 클래스 |
| OutputScope |
부모 범위 연결을 사용하여 출력 메시지 추적에 대한 OpenTelemetry 추적 범위를 제공합니다. |
| PerRequestSpanProcessorConfiguration |
PerRequestSpanProcessor에 대한 구성입니다. 런타임 설정(clusterCategory, isNodeEnvDevelopment)을 상속하고 요청당 프로세서 가드레일을 추가합니다. PerRequestSpanProcessor는 특정 시나리오에서만 사용되며 이러한 설정은 일반적인 ObservabilityConfiguration에 노출되어서는 안 되므로 ObservabilityConfiguration과 분리됩니다. |
인터페이스
| AgentDetails |
AI 에이전트에 대한 세부 정보 |
| BlobPart |
인라인 이진 데이터(base64로 인코딩됨). |
| BuilderOptions |
에이전트 365 Observability Builder에 대한 구성 옵션 |
| CallerDetails |
범위 만들기에 대한 호출자 세부 정보입니다. 사람 호출자, 에이전트 호출자 또는 둘 다(체인에 사람이 있는 A2A)를 지원합니다.
마이그레이션 참고 사항: v1에서 이름은
UserDetails - 사용자 호출자 ID(이전 |
| Channel |
호출에 대한 채널을 나타냅니다. |
| ChatMessage |
모델에 전송된 입력 메시지(OTEL gen-ai 의미 체계 규칙). |
| FilePart |
미리 업로드된 파일에 대한 참조입니다. |
| GenericPart |
사용자 지정/이후 형식에 대한 확장 가능한 파트입니다. |
| GenericServerToolCall |
확장 가능한 서버 도구는 형식 판별자를 사용하여 세부 정보를 호출합니다. |
| GenericServerToolCallResponse |
형식 판별자를 사용하여 확장 가능한 서버 도구 호출 응답입니다. |
| ILogger |
에이전트 365 관찰성에 대한 사용자 지정 로거 인터페이스 백 엔드를 지원하도록 이 인터페이스 구현 |
| InferenceDetails |
유추 호출에 대한 세부 정보 |
| InferenceResponse |
유추 호출에서 응답을 기록하기 위한 세부 정보 |
| InputMessages | |
| InvokeAgentScopeDetails |
에이전트 범위를 호출하기 위한 세부 정보입니다. |
| OutputMessage |
모델(OTEL gen-ai 의미 체계 규칙)에서 생성된 출력 메시지입니다. |
| OutputMessages | |
| OutputResponse |
에이전트의 출력 메시지를 포함하는 응답을 나타냅니다. 출력 메시지 추적에 OutputScope와 함께 사용됩니다. 일반 문자열, 구조적 OTEL OutputMessage 개체 또는 원시 받아쓰기(OTEL 사양별 도구 호출 결과로 처리됨)를 허용합니다. |
| ParentSpanRef |
비동기 경계를 넘어 명시적 부모-자식 연결에 대한 부모 범위에 대한 참조입니다. 자동 컨텍스트 전파가 실패할 때 사용됩니다(예: WebSocket 콜백, 외부 이벤트 처리기). |
| ReasoningPart |
모델 추론/생각의 체인 콘텐츠입니다. |
| Request |
원격 분석 컨텍스트가 있는 요청을 나타냅니다. 채널 및 대화 추적에 대한 모든 범위 유형에서 사용됩니다. |
| ServerToolCallPart |
서버 쪽 도구 호출. |
| ServerToolCallResponsePart |
서버 쪽 도구 응답입니다. |
| ServiceEndpoint |
에이전트 호출에 대한 엔드포인트를 나타냅니다. |
| SpanDetails |
범위 만들기에 대한 구성 세부 정보를 확장합니다. OpenTelemetry 범위 옵션을 단일 개체로 그룹화하여 새 옵션이 추가되면 범위 메서드 시그니처가 안정적으로 유지됩니다. |
| TextPart |
일반 텍스트 콘텐츠입니다. |
| ToolCallDetails |
에이전트가 수행한 도구 호출의 세부 정보 |
| ToolCallRequestPart |
모델에서 요청한 도구 호출입니다. |
| ToolCallResponsePart |
도구 호출의 결과입니다. |
| UriPart |
외부 URI 참조입니다. |
| UserDetails |
사용자 호출자에 대한 세부 정보입니다. |
형식 별칭
| EnhancedAgentDetails | |
| HeadersCarrier |
추적 컨텍스트 전파에 사용되는 HTTP 헤더에 대한 캐리어 형식입니다. Node.js IncomingHttpHeaders 및 일반 문자열 맵과 호환됩니다. |
| InputMessagesParam |
에 대한 허용된 입력입니다 |
| MessagePart |
OTEL gen-ai 의미 체계 규칙당 모든 메시지 파트 형식의 통합입니다. 참고: GenericPart 는 사용자 지정 또는 이후 파트 형식과의 앞으로 호환성을 위한 catch-all 역할을 합니다.
|
| ObservabilityConfigurationOptions |
관찰성 구성 옵션 - 런타임 옵션을 확장합니다. 모든 재정의는 각 속성 액세스에서 호출되는 함수입니다. RuntimeConfigurationOptions에서 상속됩니다.
참고: |
| OutputMessagesParam |
에 대한 허용된 입력입니다 |
| ParentContext |
범위 만들기를 위한 부모 컨텍스트입니다. 다음 중 하나를 수락합니다:
|
| PerRequestSpanProcessorConfigurationOptions |
PerRequestSpanProcessor에 대한 구성 옵션 - 런타임 옵션을 확장합니다. 모든 재정의는 각 속성 액세스에서 호출되는 함수입니다. RuntimeConfigurationOptions에서 상속됩니다.
|
| ResponseMessagesParam |
에 대한 허용된 입력입니다 |
열거형
| ExporterEventNames |
로깅 및 모니터링을 위해 Agent365Exporter에서 사용하는 이벤트 이름입니다. 효율적인 모니터링 및 집계를 보장하기 위해 카디널리티가 낮은 이벤트 유형입니다. |
| FinishReason |
모델이 OTEL gen-ai 의미 체계 규칙에 따라 생성을 중지한 이유입니다. |
| InferenceOperationType |
모델 유추에 대한 형식에 대한 다양한 연산을 나타냅니다. |
| InvocationRole |
에이전트를 호출할 수 있는 다양한 역할을 나타냅니다. |
| MessageRole |
OTEL gen-ai 의미 체계 규칙에 따라 메시지 참가자의 역할입니다. |
| Modality |
Blob, 파일 및 URI 부분에 대한 미디어 형식입니다. |
함수
| create |
명시적 부모 범위 참조를 사용하여 새 컨텍스트를 만듭니다. 이렇게 하면 비동기 컨텍스트가 끊어진 경우에도 자식 범위를 올바르게 부모로 사용할 수 있습니다. |
| extract |
전역적으로 등록된 W3C 전파자를 사용하여 들어오는 HTTP 헤더에서 추적 컨텍스트를 추출합니다. 범위 클래스에 ParentContext로 전달할 수 있는 OTel 을 반환합니다. 예시
|
| format |
메시지 및 스택 추적을 사용하여 로깅에 대한 형식 오류 개체 |
| get |
지정된 OTel 컨텍스트(또는 활성 OTel 컨텍스트)에서 요청별 내보내기 토큰을 검색합니다. |
| get |
현재 로거 인스턴스 가져오기 |
| inject |
전역적으로 등록된 W3C 전파자를 사용하여 제공된 헤더 개체에 현재 추적 컨텍스트( 예시
|
| is |
요청별 내보내기가 사용되는지 확인합니다. 우선 순위: 내부는 구성 공급자 > 환경 변수를 재정의합니다>. 사용하도록 설정하면 BatchSpanProcessor 대신 PerRequestSpanProcessor가 사용됩니다. 토큰은 내보내기 시 OTel 컨텍스트(비동기 로컬 스토리지)를 통해 전달됩니다. |
| normalize |
버전
|
| normalize |
버전
|
| reset |
기본 콘솔 로거로 다시 설정(주로 테스트용) |
| run |
요청별 내보내기 토큰을 전달하는 컨텍스트 내에서 함수를 실행합니다. 이렇게 하면 토큰이 OTel 컨텍스트(ALS)에서만 유지됩니다. 레지스트리에서는 유지되지 않습니다. 나중에 추적이 플러시되기 전에 토큰을 업데이트 |
| run |
들어오는 HTTP 헤더에서 추적 컨텍스트를 추출하고 해당 컨텍스트 내에서 콜백을 실행합니다. 콜백 내에서 만든 모든 범위는 추출된 추적에 부모가 됩니다. 예시
|
| run |
명시적 부모 범위 참조가 있는 컨텍스트 내에서 콜백 함수를 실행합니다. 컨텍스트 전파가 끊어진 비동기 콜백에서 자식 범위를 만드는 데 유용합니다. |
| safe |
값이 항상 JSON 구문 분석 가능한 문자열인지 확인합니다.
|
| serialize |
버전이 지정된 메시지 래퍼를 JSON으로 직렬화합니다. 출력은 전체 래퍼 개체입니다 try/catch는 메시지 파트에 JSON 직렬화할 수 없는 값(예: BigInt, 순환 참조)이 포함된 경우에도 원격 분석 기록이 throw되지 않도록 합니다. |
| set |
관찰성 SDK에 대한 사용자 지정 로거 구현 설정 Winston의 예:
|
| update |
활성 OTel 컨텍스트에서 내보내기 토큰을 업데이트합니다. 장기 실행 요청 중에 원래 토큰이 만료되었을 수 있는 경우 루트 범위를 종료하기 전에 토큰을 새로 고치려면 이 호출을 호출합니다. 에서 만든 |
변수
| A365_MESSAGE_SCHEMA_VERSION | |
| default |
ObservabilityConfiguration에 대한 공유 기본 공급자입니다. |
| default |
PerRequestSpanProcessorConfiguration에 대한 공유 기본 공급자입니다. |
| logger | 이전 버전과의 호환성을 위한 기본 로거 인스턴스입니다. setLogger()를 통해 바꿀 수 있는 전역 로거에 대한 대리자입니다. |
함수 세부 정보
createContextWithParentSpanRef(Context, ParentSpanRef)
명시적 부모 범위 참조를 사용하여 새 컨텍스트를 만듭니다. 이렇게 하면 비동기 컨텍스트가 끊어진 경우에도 자식 범위를 올바르게 부모로 사용할 수 있습니다.
function createContextWithParentSpanRef(base: Context, parent: ParentSpanRef): Context
매개 변수
- base
-
Context
확장할 기본 컨텍스트(일반적으로 context.active())
- parent
- ParentSpanRef
traceId 및 spanId를 포함하는 부모 범위 참조
반품
Context
부모 범위가 설정된 새 컨텍스트
extractContextFromHeaders(HeadersCarrier, Context)
전역적으로 등록된 W3C 전파자를 사용하여 들어오는 HTTP 헤더에서 추적 컨텍스트를 추출합니다. 범위 클래스에 ParentContext로 전달할 수 있는 OTel 을 반환합니다.
예시
const parentCtx = extractContextFromHeaders(req.headers);
const scope = InvokeAgentScope.start(request, scopeDetails, agentDetails, undefined, { parentContext: parentCtx });
function extractContextFromHeaders(headers: HeadersCarrier, baseCtx?: Context): Context
매개 변수
- headers
- HeadersCarrier
를 포함하는 들어오는 HTTP 요청 헤더입니다 traceparent/tracestate.
- baseCtx
-
Context
확장할 선택적 기본 컨텍스트입니다. 기본값은 활성 컨텍스트입니다.
반품
Context
추출된 추적 정보를 포함하는 OTel 컨텍스트입니다.
formatError(unknown)
메시지 및 스택 추적을 사용하여 로깅에 대한 형식 오류 개체
function formatError(error: unknown): string
매개 변수
- error
-
unknown
반품
string
getExportToken(Context)
지정된 OTel 컨텍스트(또는 활성 OTel 컨텍스트)에서 요청별 내보내기 토큰을 검색합니다.
function getExportToken(ctx?: Context): string | undefined
매개 변수
- ctx
-
Context
반품
string | undefined
getLogger()
injectContextToHeaders(Record<string, string>, Context)
전역적으로 등록된 W3C 전파자를 사용하여 제공된 헤더 개체에 현재 추적 컨텍스트(traceparent/tracestate 헤더)를 삽입합니다.
예시
const headers: Record<string, string> = {};
injectContextToHeaders(headers);
await fetch('http://service-b/process', { headers });
function injectContextToHeaders(headers: Record<string, string>, ctx?: Context): Record<string, string>
매개 변수
- headers
-
Record<string, string>
추적 컨텍스트 헤더를 쓸 변경 가능한 개체입니다.
- ctx
-
Context
삽입할 선택적 OTel 컨텍스트입니다. 기본값은 활성 컨텍스트입니다.
반품
Record<string, string>
연결 편의를 위해 동일한 headers 개체입니다.
isPerRequestExportEnabled(IConfigurationProvider<PerRequestSpanProcessorConfiguration>)
요청별 내보내기가 사용되는지 확인합니다. 우선 순위: 내부는 구성 공급자 > 환경 변수를 재정의합니다>. 사용하도록 설정하면 BatchSpanProcessor 대신 PerRequestSpanProcessor가 사용됩니다. 토큰은 내보내기 시 OTel 컨텍스트(비동기 로컬 스토리지)를 통해 전달됩니다.
function isPerRequestExportEnabled(configProvider?: IConfigurationProvider<PerRequestSpanProcessorConfiguration>): boolean
매개 변수
- configProvider
-
IConfigurationProvider<PerRequestSpanProcessorConfiguration>
선택적 구성 공급자입니다. 기본값은 defaultPerRequestSpanProcessorConfigurationProvider(지정되지 않은 경우)입니다.
반품
boolean
normalizeInputMessages(InputMessagesParam)
버전 InputMessagesParam 이 지정된 InputMessages 래퍼로 정규화합니다.
-
string/string[]변환 및 래핑된ChatMessage[]→ -
InputMessages반환된 → as-is
function normalizeInputMessages(param: InputMessagesParam): InputMessages
매개 변수
- param
- InputMessagesParam
반품
normalizeOutputMessages(OutputMessagesParam)
버전 OutputMessagesParam 이 지정된 OutputMessages 래퍼로 정규화합니다.
-
string/string[]변환 및 래핑된OutputMessage[]→ -
OutputMessages반환된 → as-is
function normalizeOutputMessages(param: OutputMessagesParam): OutputMessages
매개 변수
- param
- OutputMessagesParam
반품
resetLogger()
기본 콘솔 로거로 다시 설정(주로 테스트용)
function resetLogger()
runWithExportToken<T>(string, () => T)
요청별 내보내기 토큰을 전달하는 컨텍스트 내에서 함수를 실행합니다. 이렇게 하면 토큰이 OTel 컨텍스트(ALS)에서만 유지됩니다. 레지스트리에서는 유지되지 않습니다.
나중에 추적이 플러시되기 전에 토큰을 업데이트 updateExportToken() 할 수 있습니다. 콜백이 오래 실행되고 원래 토큰이 내보내기 전에 만료될 수 있는 경우에 유용합니다.
function runWithExportToken<T>(token: string, fn: () => T): T
매개 변수
- token
-
string
- fn
-
() => T
반품
T
runWithExtractedTraceContext<T>(HeadersCarrier, () => T)
들어오는 HTTP 헤더에서 추적 컨텍스트를 추출하고 해당 컨텍스트 내에서 콜백을 실행합니다. 콜백 내에서 만든 모든 범위는 추출된 추적에 부모가 됩니다.
예시
runWithExtractedTraceContext(req.headers, () => {
const scope = InvokeAgentScope.start(request, scopeDetails, agentDetails);
scope.dispose();
});
function runWithExtractedTraceContext<T>(headers: HeadersCarrier, callback: () => T): T
매개 변수
- headers
- HeadersCarrier
를 포함하는 들어오는 HTTP 요청 헤더입니다 traceparent/tracestate.
- callback
-
() => T
추출된 컨텍스트 내에서 실행할 함수입니다.
반품
T
콜백의 결과입니다.
runWithParentSpanRef<T>(ParentSpanRef, () => T)
명시적 부모 범위 참조가 있는 컨텍스트 내에서 콜백 함수를 실행합니다. 컨텍스트 전파가 끊어진 비동기 콜백에서 자식 범위를 만드는 데 유용합니다.
function runWithParentSpanRef<T>(parent: ParentSpanRef, callback: () => T): T
매개 변수
- parent
- ParentSpanRef
부모 범위 참조
- callback
-
() => T
부모 컨텍스트를 사용하여 실행할 함수입니다.
반품
T
콜백의 결과
safeSerializeToJson(string | Record<string, unknown>, string)
값이 항상 JSON 구문 분석 가능한 문자열인지 확인합니다.
- 개체는 JSON.stringify를 통해 직렬화됩니다.
- 이미 유효한 JSON 개체/배열인 문자열은 전달됩니다.
- 다른 모든 문자열(bare JSON 기본 형식 포함)은 래핑
{ [key]: value }됩니다.
function safeSerializeToJson(value: string | Record<string, unknown>, key: string): string
매개 변수
- value
-
string | Record<string, unknown>
serialize할 값입니다.
- key
-
string
일반 문자열을 래핑할 때 사용할 키입니다.
반품
string
serializeMessages(InputMessages | OutputMessages)
버전이 지정된 메시지 래퍼를 JSON으로 직렬화합니다.
출력은 전체 래퍼 개체입니다 {"version":"0.1.0","messages":[...]}.
try/catch는 메시지 파트에 JSON 직렬화할 수 없는 값(예: BigInt, 순환 참조)이 포함된 경우에도 원격 분석 기록이 throw되지 않도록 합니다.
function serializeMessages(wrapper: InputMessages | OutputMessages): string
매개 변수
- wrapper
반품
string
setLogger(ILogger)
관찰성 SDK에 대한 사용자 지정 로거 구현 설정
Winston의 예:
import * as winston from 'winston';
import { setLogger } from '@microsoft/agents-a365-observability';
const winstonLogger = winston.createLogger({
level: 'info',
format: winston.format.json(),
transports: [
new winston.transports.File({ filename: 'error.log', level: 'error' }),
new winston.transports.File({ filename: 'combined.log' })
]
});
setLogger({
info: (msg, ...args) => winstonLogger.info(msg, ...args),
warn: (msg, ...args) => winstonLogger.warn(msg, ...args),
error: (msg, ...args) => winstonLogger.error(msg, ...args),
event: (eventType, isSuccess, durationMs, message, details) => {
// eventType is ExporterEventNames enum value
winstonLogger.log({ level: isSuccess ? 'info' : 'error', eventType, isSuccess, durationMs, message, ...details });
}
});
function setLogger(customLogger: ILogger)
매개 변수
- customLogger
- ILogger
사용자 지정 로거 구현
updateExportToken(string)
활성 OTel 컨텍스트에서 내보내기 토큰을 업데이트합니다. 장기 실행 요청 중에 원래 토큰이 만료되었을 수 있는 경우 루트 범위를 종료하기 전에 토큰을 새로 고치려면 이 호출을 호출합니다.
에서 만든 runWithExportToken것과 동일한 비동기 컨텍스트 내에서 호출해야 합니다.
function updateExportToken(token: string): boolean
매개 변수
- token
-
string
내보내기에서 사용할 새 토큰입니다.
반품
boolean
토큰이 성공적으로 업데이트되었으면 true, 토큰 소유자를 찾을 수 없으면 false입니다.
변수 세부 정보
A365_MESSAGE_SCHEMA_VERSION
A365_MESSAGE_SCHEMA_VERSION: "0.1.0"
형식
string
defaultObservabilityConfigurationProvider
ObservabilityConfiguration에 대한 공유 기본 공급자입니다.
defaultObservabilityConfigurationProvider: DefaultConfigurationProvider<ObservabilityConfiguration>
형식
defaultPerRequestSpanProcessorConfigurationProvider
PerRequestSpanProcessorConfiguration에 대한 공유 기본 공급자입니다.
defaultPerRequestSpanProcessorConfigurationProvider: DefaultConfigurationProvider<PerRequestSpanProcessorConfiguration>