08. Observability diagnostics¶

레퍼런스 목차

이 category는 trace·metric·log 기록 수준을 구성하는 IZLinkDiagnosticsOptions/ IZLinkDiagnosticsRuntime과, 모든 category의 실패를 판단하는 ZLinkFrameworkErrorKind 대응표를 다룬다. 정확한 signature는 Topology monitoring exact interface와 Framework 오류 exact interface가 소유한다.

`ConfigureDispatch().Diagnostics` (구성 시점)¶

Trace·metric 기록 수준과 sampling을 설정한다.

services.AddZLinkFramework(options =>
{
    options.ConfigureDispatch().Diagnostics
        .SetLevel(ZLinkDiagnosticsLevel.Detailed)
        .SetSampleRate(0.1)
        .IncludeMessageSizes(true);
});

옵션. 이 호출에는 다음 modifier가 붙는다.

Modifier	기본값	의미
`.SetLevel(ZLinkDiagnosticsLevel)`	exact interface에 명시된 기본값 없음(`Off`/`Errors`/`Normal`/`Detailed` 중 하나)	기록할 상세도
`.SetSampleRate(double)`	exact interface에 명시된 기본값 없음	`0.0`..`1.0`. 범위를 벗어나면 `ArgumentOutOfRangeException`
`.IncludeMessageSizes(bool)`	exact interface에 명시된 기본값 없음	Payload 크기 분포를 telemetry에 포함할지 여부. Payload 내용 자체는 절대 기록하지 않는다

각 modifier는 IZLinkDiagnosticsOptions를 반환하는 동기 fluent 호출이다 — 반환값 없는 등록이 아니다.

완료 결과. Trace는 ActivitySource, metric은 이름 zlink.framework의 Meter, log는 ILogger category로 노출한다 — exporter와 원격 backend는 application이 구성한다.

선택 기준. Startup 시점에 기본 기록 수준을 정할 때 쓴다. 실행 중 level만 바꾸려면 IZLinkDiagnosticsRuntime을 쓴다.

`IZLinkDiagnosticsRuntime.Level` (읽기·변경)¶

실행 중인 process의 diagnostics level을 조회하거나 바꾼다.

ZLinkDiagnosticsLevel current = diagnosticsRuntime.Level;
diagnosticsRuntime.Level = ZLinkDiagnosticsLevel.Detailed; // 장애 진단 동안 일시적으로 올린다

옵션. 이 진입점에는 단일 property만 있다.

Property	기본값	의미
`Level`	`ConfigureDispatch().Diagnostics.SetLevel(...)`로 등록한 값	현재 적용 중인 level

완료 결과. 동기 get/set이다. 값을 바꾸면 이후 시작하는 message 처리부터 새 level을 적용하는 원자적 상태 변경이며, 이미 telemetry queue에 들어간 기록에는 영향을 주지 않는다.

선택 기준. 배포를 다시 하지 않고 특정 시점에만 상세 기록으로 올리거나 내릴 때 쓴다.

`ZLinkFrameworkErrorKind` 대응표¶

Framework operation이 실패하면 ZLinkFrameworkException.Kind로 원인 계열을 판단한다. 이 표는 모든 category의 완료 kind 설명이 공유하는 근거다.

Kind	Application에서 확인할 내용
`NotFound`	요청한 Actor, Spot, handler, route 또는 target이 존재하는지 확인한다
`AlreadyExists`	create와 registration이 멱등하게 처리되어야 하는지 확인한다
`TypeMismatch`	stable type과 요청한 application type이 일치하는지 확인한다
`NotConfigured`	필요한 role, handler, Store 또는 object client가 startup에 등록되었는지 확인한다
`Rejected`	Typed 결과가 없는 Framework admission, filter 또는 runtime policy가 operation을 거부했다
`Unavailable`	target, route, Store 또는 worker가 현재 operation을 처리할 수 없다
`CapacityExceeded`	placement, queue 또는 bounded resource의 여유가 없다
`DeadlineExceeded`	operation이 정한 deadline 안에 완료되지 않았다. 결과의 side effect 여부는 해당 operation 계약을 따른다
`ShuttingDown`	runtime이 신규 admission을 받지 않는 상태다. 다른 serving instance를 사용해야 한다
`ProtocolError`	peer와 protocol 또는 reply 계약이 일치하는지 확인한다
`InvalidOperation`	현재 object·session·runtime 상태에서는 요청한 operation이 허용되지 않는다
`DataLost`	공개된 relocation payload를 찾을 수 없거나 검증에 실패했다. 이전 owner로 임의 rollback하지 않는다
`InternalFailure`	위 분류로 표현할 수 없는 Framework 실패다. Log와 trace의 correlation 정보로 원인을 확인한다

완료 결과. ZLinkFrameworkException은 Framework만 생성하며 Message는 사람이 진단하기 위한 설명이지 programmatic 분기 대상이 아니다. ZLinkConfigurationException(startup 검증 실패)과 ArgumentException 계열(잘못된 인자)은 이 kind 분류와 다른 층이다. 재시도 여부는 이 kind가 알려주지 않는다 — operation의 완료 조건, idempotency와 업무 상태를 확인해 application이 직접 판단한다.

선택 기준. 각 category 항목의 "완료 결과"에 나온 kind를 이 표로 되짚어 대응 방법을 정할 때 쓴다.

전체 근거는 Topology monitoring exact interface와 Framework 오류 exact interface를 참고한다.

08. Observability diagnostics¶

ConfigureDispatch().Diagnostics (구성 시점)¶

IZLinkDiagnosticsRuntime.Level (읽기·변경)¶

ZLinkFrameworkErrorKind 대응표¶

`ConfigureDispatch().Diagnostics` (구성 시점)¶

`IZLinkDiagnosticsRuntime.Level` (읽기·변경)¶

`ZLinkFrameworkErrorKind` 대응표¶