[Rust 공식문서 한국어 정리] 78. Rust Tracing 가이드

[Rust 공식문서 한국어 정리] 78. Rust Tracing 가이드



원문 제목: tracing — Application-level tracing for Rust

작성자: Tokio Contributors



━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📌 1. 서론 — 이 문서가 다루는 내용

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━



이 문서는 Rust의 구조화된 로깅 및 분산 추적 프레임워크인 tracing을 소개합니다.

전통적인 텍스트 로그 대신 span과 event 기반의 계측 방식을 사용하여, 비동기/분산 환경에서의 요청 흐름을 추적합니다.

tokio의 공식 프로젝트로 개발되었으며, OpenTelemetry, Jaeger, Zipkin 등과의 통합도 활발합니다.

성능과 생산성을 모두 고려한 설계로, Rust 현대 서비스 개발의 관찰 가능성(observability) 기반을 제공합니다.



━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

🔑 2. 핵심 개념 4가지

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━



① Span: 특정 작업의 범위와 문맥을 나타낸며, 부모-자식 관계로 트리를 형성합니다.

② Event: 특정 시점의 순간적 기록으로, 로그 메시지와 유사하지만 span 문맥 내에서 기록됩니다.

③ Subscriber: span과 event를 수집하고 처리하는 백엔드로, 출력 형식과 저장소를 결정합니다.

④ Instrument: Future나 함수에 span을 자동으로 부여하여 비동기 코드의 추적을 가능하게 합니다.



━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📖 3. 주요 내용 상세

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━



tracing은 기존 log 크레이트와 다른 철학을 가집니다.

단순한 텍스트 로그 대신, span이라는 범위 단위로 요청의 생명주기를 추적합니다.

각 span은 ID, 메타데이터, 시작/종료 시점을 가지며, 자식 span을 가질 수 있습니다.



#[tracing::instrument] 매크로는 함수에 자동으로 span을 부여합니다.

함수 이름과 인자가 span의 메타데이터로 포함되며, 함수 진입 시 span이 시작되고 종료 시 종료됩니다.

async fn에 적용하면, Future가 poll될 때마다 span이 활성화되어 비동기 문맥이 보존됩니다.



Subscriber는 tracing-subscriber 크레이트에서 제공합니다.

fmt::layer()로 콘솔 출력을, json()으로 JSON 출력을, with_env_filter()로 로그 레벨 필터링을 구성합니다.

tracing-opentelemetry로 OpenTelemetry collector에 직접 전송할 수도 있습니다.



비동기 코드에서의 문맥 전파는 tracing의 핵심 강점입니다.

.await 지점에서도 span 문맥이 자동으로 전파되므로, 콜백 기반 로깅에서 발생하는 문맥 단절 문제가 없습니다.

info_span!("request", id = %request_id)로 생성한 span이, 이후의 모든 비동기 연산에 전달됩니다.



━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

🛠 4. 실전 활용

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━



#[tracing::instrument]로 모든 서비스 핸들러에 자동 span을 부여하고, 요청 ID로 분산 추적을 연결합니다.

tracing-opentelemetry로 Jaeger에 스팬을 전송하여, 분산 시스템의 지연 시간 병목을 시각화합니다.

에러 발생 시 current span의 문맥을 함께 기록하여, 디버깅에 필요한 컨텍스트를 보존합니다.



━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

✅ 5. 정리

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━



tracing은 Rust의 현대적 관찰 가능성 프레임워크입니다.

span 기반 추적은 비동기/분산 환경에서 로그 문맥을 완벽하게 보존합니다.

OpenTelemetry와의 통합으로, Rust 서비스도 클라우드 네이티브 관찰 가능성 표준에 참여할 수 있습니다.



━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

🔗 출처 링크

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━



원문: https://docs.rs/tracing/latest/tracing/

tracing-subscriber: https://docs.rs/tracing-subscriber/latest/tracing_subscriber/



#Rust #Tracing #Observability #OpenTelemetry #Async #Span #번역