상세 매뉴얼

관측 가능성 & Inspector

ranvier-inspector 기반 프로덕션 트레이스 저장, 메트릭, 실시간 디버깅.

Inspector 예제 매뉴얼 허브 OpenTelemetry

핵심 개념

Inspector 런타임

TraceStore: 완료된 트레이스를 쿼리 및 보존 정책과 함께 영속 저장합니다.

BearerAuth: 프로덕션 Inspector 엔드포인트를 위한 토큰 기반 인증입니다.

AlertHook / AlertDispatcher: 장애 또는 임계값 조건에서 실시간 알림을 라우팅합니다.

메트릭 & 디버깅

MetricsCollector: 회로별 슬라이딩 윈도우 지연 시간 히스토그램(p50/p95/p99).

StallDetector: 응답 없는 Transition을 감지하는 임계값 기반 탐지.

ConditionalBreakpoint: 단계별 디버깅을 위한 JSON 경로 조건 평가기.

PayloadCapturePolicy: 컴플라이언스 및 디버깅을 위한 Off/Hash/Full 페이로드 캡처.

OTLP & 트레이스 파이프라인

회로 매핑: 모든 Axon 실행은 표준 OpenTelemetry Trace와 1:1로 매핑됩니다.

노드 스팬: 각 Transition은 메타데이터가 포함된 Span으로 자동 기록됩니다.

WebSocket 스트리밍: Inspector UI 및 외부 소비자를 위한 실시간 이벤트 피드.

역량 스냅샷

가능

Axon/Transition/Outcome 계약, 명시적 Bus 주입, 무결 파이프라인용 `Never` 에러 타입으로 타입 안전한 의사결정 흐름을 구성할 수 있습니다. 10개 크레이트 전체를 다루는 61개 유지보수 예제 포함.

프로토콜-애그노스틱 코어 회로를 HTTP 인그레스 어댑터에 연결하고 동적 라우팅, 요청 추출, 라이프사이클 제어, 미들웨어 조합, 경로 단위 정책 override를 구성할 수 있습니다.

`ranvier-std` Guard 노드(CorsGuard, RateLimit, SecurityHeaders, IpFilter)로 HTTP 보안/정책을 Schematic 내에서 적용할 수 있습니다.

`ranvier-openapi`로 요청/응답 계약 기반 OpenAPI 문서와 Swagger UI를 생성할 수 있습니다.

정적 디렉터리 서빙과 SPA fallback, cache/compression 옵션으로 풀스택형 제공 경로를 구성할 수 있습니다.

WebSocket/SSE 실시간 흐름을 처리하고 연결/세션 컨텍스트를 Bus에 주입할 수 있습니다.

LLM-as-Transition 패턴으로 AI 분류/모더레이션 파이프라인을 구축하고 콘텐츠 정책을 적용할 수 있습니다.

`TestApp/TestRequest/TestResponse`로 인-프로세스 HTTP 통합 테스트를 작성하고 `AxonTestKit`/`Timeline`으로 실행 경로를 단언할 수 있습니다.

`ranvier-inspector`로 TraceStore 영속 저장, BearerAuth 인증, AlertHook 알림, OTLP 연동을 구성할 수 있습니다.

session/job/persistence 패턴을 실행하고 PersistenceStore와 compensation hook으로 장애 워크플로를 체크포인트에서 재개할 수 있습니다.

cargo-semver-checks와 schematic diff/policy CLI 명령으로 API 호환성과 구조 드리프트를 검증할 수 있습니다.

내장 Inspector REST + WebSocket 서버로 노드별 메트릭(처리량, 레이턴시 백분위, 에러율) 수집, 페이로드 검사, DLQ 관리, 조건부 중단점, 정체 감지를 제공할 수 있습니다.

`.with_input_schema::<T>()` 빌더 API 또는 `#[transition(schema)]` 매크로 속성으로 회로 노드에 JSON Schema를 등록할 수 있습니다. Inspector가 스키마 포함 라우트 메타데이터 제공(`GET /api/v1/routes`), 실행 중인 회로에 HTTP 요청 릴레이(`POST /api/v1/relay`), 스키마 기반 빈 템플릿/랜덤 샘플 생성(`POST /api/v1/routes/schema`, `POST /api/v1/routes/sample`)을 제공합니다.

`RanvierConfig`(`ranvier.toml` + 환경변수 오버라이드 + 프로필 시스템)로 프로덕션 인프라를 구성하고 `init_logging()`(JSON/pretty/compact)으로 구조화 로깅을 초기화하며 `rustls` TLS를 선택적으로 활성화할 수 있습니다.

RFC 7807 `ProblemDetail`/`IntoProblemDetail`로 표준 에러 응답을 반환하고 `RetryPolicy`(고정/지수 백오프)와 `Axon::then_with_retry()`로 실패한 트랜지션을 재시도할 수 있습니다.

criterion 마이크로벤치마크(Axon 레이턴시, Bus 연산, Transition 체인)와 Axum/Actix-web 비교 서버로 정량 성능 기준을 제공합니다.

세 개의 참조 애플리케이션으로 실제 패턴을 보여줍니다: Todo API(CRUD + JWT 인증), Chat Server(다중 방 WebSocket), E-commerce Order Pipeline(4단계 Saga 보상 + 감사 추적 + 다중 테넌시).

`ranvier migrate --from 0.20 --to 0.25`로 버전 간 import 경로 교체, 크레이트 의존성 전환을 자동화할 수 있습니다. TOML 기반 마이그레이션 규칙(text_replace, rename_import, warn)과 --dry-run 모드를 제공합니다.

Inspector `/metrics` Prometheus 포맷 메트릭 내보내기, TelemetryConfig으로 OTLP TracerProvider 자동 초기화, AccessLogGuard 경로 마스킹 HTTP 요청 로깅, PostgresAuditSink 해시 체인 감사 이벤트 영속 저장, OpenAPI SecurityScheme(bearerAuth) + ProblemDetail(RFC 7807) 에러 응답 자동 등록을 수행할 수 있습니다.

PHILOSOPHY.md('Opinionated Core, Flexible Edges' 원칙)를 통해 프레임워크 설계 철학을 이해하고 DESIGN_PRINCIPLES.md(Paradigm Test, Tower 분리, Opinionated Core 적용을 다루는 ADR 형식)로 아키텍처 결정 근거를 파악할 수 있습니다.

두 가지 인증 접근법을 구현할 수 있습니다: Transition 기반(examples/auth-transition — Bus 컨텍스트 전파, Schematic 시각화, 쉬운 테스트) 또는 Tower 통합(examples/auth-tower-integration — 생태계 호환성을 위한 AsyncAuthorizeRequest 트레잇).

docs/guides/auth-comparison.md로 인증 전략을 비교할 수 있습니다: 7개 항목 비교 표, 성능 벤치마크(둘 다 ~1-2μs 오버헤드), 사용 시기 결정 트리, Transition과 Tower 접근법 간 마이그레이션 경로 제공.

제한

role/tenant header의 토큰/클레임 검증 매핑은 게이트웨이/배포 인프라 측 통합이 필요합니다.

빠른 시작

let inspector = Inspector::builder()
  .with_bearer_token_from_env()
  .with_trace_store(InMemoryTraceStore::new(1000))
  .build(axon);
// GET /api/v1/metrics, /api/v1/traces/stored
inspector.serve("0.0.0.0:9090").await?;

주요 워크플로

워크스페이스 의존성에 ranvier-inspector를 추가합니다.

RANVIER_INSPECTOR_TOKEN 환경변수로 BearerAuth를 설정합니다.

TraceStore 백엔드를 선택합니다 (개발: InMemoryTraceStore, 운영: SqliteTraceStore).

표준 OTLP 엑스포터를 통해 Jaeger, Tempo, Datadog에 연결합니다.

Inspector UI 또는 Ranvier Studio에서 노드 단위 히트맵을 모니터링합니다.

검증 명령

워크스페이스 예제 빌드 확인 cargo check --workspace

타입 흐름 예제 실행 확인 cargo run -p typed-state-tree

Guard 노드 (CorsGuard/RateLimit/SecurityHeaders/IpFilter) 테스트 확인 cargo run -p routing-params-demo

OpenAPI 생성기 회귀 테스트 확인 cargo test -p ranvier-http

OpenAPI 데모 컴파일 확인 cargo test -p ranvier-http --test test_app_health

정적 서빙/SPA fallback 회귀 테스트 확인 cargo test -p ranvier-http --features validation

정적 SPA 데모 컴파일 확인 cargo run -p ranvier-http --example validation_struct_level --features validation

WebSocket ingress 업그레이드/이벤트 브리지 테스트 확인 cargo test -p ranvier-std guard

WebSocket ingress 데모 컴파일 확인 cargo test -p ranvier-openapi

Inspector TraceStore + BearerAuth 테스트 확인 cargo check -p openapi-demo

워크스페이스 전체 테스트 스윕 확인 cargo test -p ranvier-http

예제 회귀 스모크(M119) 확인 cargo check -p static-spa-demo

Inspector quick-view 스모크 확인 cargo test -p ranvier-http

Schematic diff/policy 스모크 확인 cargo check -p websocket-ingress-demo

Fullstack embedded static 스모크 확인 cargo test -p ranvier-inspector

M132 ecosystem reference 조합 스모크 확인 cargo test --workspace

Session 패턴 예제 컴파일 확인 ./scripts/m119_examples_smoke.ps1

Inspector 메트릭 수집 + stall 감지 테스트 확인 ./scripts/m131_inspector_quickview_smoke.ps1

Inspector 조건부 중단점 + 페이로드 캡처 테스트 확인 ./scripts/m131_schematic_diff_policy_smoke.ps1

Fullstack embedded static smoke ./scripts/m131_fullstack_embedded_smoke.ps1

Runtime timeline integration assertion cargo test -p ranvier-runtime timeline_assertion_works_in_integration_test

M132 SeaORM ecosystem reference run cargo run -p ecosystem-seaorm-demo

M132 Diesel ecosystem reference run cargo run -p ecosystem-diesel-demo

M132 Redis ecosystem reference run cargo run -p ecosystem-redis-demo

M132 NATS ecosystem reference run cargo run -p ecosystem-nats-demo

M132 Meilisearch ecosystem reference run cargo run -p ecosystem-meilisearch-demo

Session pattern example compile cargo check -p session-pattern

Inspector metrics + stall detection tests cargo test -p ranvier-inspector metrics stall

Inspector conditional breakpoint + payload capture tests cargo test -p ranvier-inspector breakpoint payload

Ecosystem: crates.io

Version: 0.30.0

Status: released

최신 capability 상태와 버전 산출물은 /ko/status에서 확인하세요.