Hello, Hannah!

2025.12.10 사내 발표 - 들쭉날쭉한 AI 품질, 팀 SSOT 문서로 해결하기

iia_hannah — Sat, 27 Dec 2025 20:18:00 +0900

최근 '팀 차원에서 시스템적으로 AI 품질을 어떻게 올릴 수 있을까?'에 대한 고민과 해결 방법에 대해 사내 발표를 했다. 되도록 개인의 역량에 의존하지 않고, 팀 차원에서 AI를 활용하여 시스템적으로 안정적으로 서비스를 운영할 수 있는 방법론에 대해 소개한다.

개발팀의 고민: AI 품질 문제

AI를 활용한 개발에서 가장 중요한 것은 '속도'가 아니라 '정확한 방향'입니다.

AI의 구조적 한계

프롬프트 의존성
개발자는 작업을 시작하기 전, 스스로 과거의 히스토리를 파악하고 도메인 정책을 검토합니다.
반면, AI는 사용자가 입력한 프롬프트와 연관된 코드만 읽습니다. 스스로 과거 작업이나 도메인 지식을 찾지 못하고, 오로지 입력된 프롬프트에만 의존합니다.
불확실한 요구사항(Gray Zone)의 임의 추론
명확하지 않은 요구사항은 가장 그럴듯한 로직으로 채워 넣기 때문에, 의도와 다른 구현이 반영될 가능성이 높습니다.

✅ 충분한 맥락을 제공한 경우

"구좌 신청 임시저장 API를 만들어줘. 임시저장은 제출하기 전에 사용자가 데이터를 보관하는 용도로 사용하는 것이야. 그래서 입력한 값에 대해서만 최소한의 Validation을 통과하면 DRAFT 상태로 저장해. 검증이 필요한 항목은 다음과 같이..."

→ 의도한 구현

❌ 컨텍스트가 부족한 경우

"구좌 신청 임시저장 API 만들어줘."

→ AI가 Gray 영역을 스스로 추론하여 개발하므로, 일관성이 없거나 도메인 정책 위반됨

이는 아래와 같은 문제를 야기합니다. 이것은 개인이 아닌 팀 전체의 비용입니다.

개인이 아닌 팀 전체의 비용

AI와 일을 잘 하려면?

위 비용을 개인의 문제가 아니라 팀의 부채로 보고, 팀 차원에서 어떻게 하면 의도한 대로 AI를 일 시킬 수 있을까 고민하게 되었습니다.
이 글에서는 두 가지 측면에서 해결 방법을 각각 제안합니다.

프롬프트 엔지니어링 : AI에게 어떻게 물어볼 것인가
충분한 컨텍스트 : AI에게 무엇을 알려줄 것인가

Step 1. 명세를 통한 정확한 구현 (SDD)

SDD 란?

SDD(Spec-Driven Development)는 코드를 작성하기 전에 먼저 명세(Specification)를 작성하고, 이를 기반으로 개발을 진행하는 방식입니다. AI에게 "무엇을 만들어야 하는지"를 명확하게 전달한다면 의도한 결과물을 얻을 수 있을 것입니다.

SDD 개발 방법론으로 구현하는 과정을 살펴보겠습니다.

프롬프트 엔지니어링은 SDD 도구가 책임진다

SDD 도구(spec-kit, task-master-ai 등)가 개발자가 구현을 위해 수행하던 프로세스들을 추상화하여 구조화된 명령어 로 제공합니다.

아래 더보기를 통해 spec-kit 기준으로 명령어별 어떤 개발 프로세스를 추상화했는지 간략히 소개합니다.

spec-kit에서 제공하는 /specify, /plan, /tasks 명령어 통해 명세와 Task 단위의 TODO List가 작성됩니다.
명령어는 주기적으로 추가되고 내용이 조금씩 변경되고 있어서 간략한 설명 위주로 안내드립니다.

/speckit.specify - 명세 작성

브랜치 자동 생성 (5-feature-name)
WHAT(무엇) + WHY(왜) 집중 - 기술 용어 금지
최대 3개 [NEEDS CLARIFICATION] 마커만 허용
품질 체크리스트 자동 생성

/speckit.clarify - 명확화 (Optional)

최대 5개 질문만 (우선순위: 범위 > 보안 > UX > 기술)
각 질문에 추천 옵션 제공
답변 즉시 spec.md에 반영

/speckit.plan - 구현 계획

constitution.md 원칙 준수 검증
research.md - 기술 결정 및 근거
data-model.md - 엔티티 설계
contracts/ - API 스펙

/speckit.tasks - 작업 분해

User Story 기반 Phase 구성
의존성 순서 정렬
병렬 실행 가능 태스크 [P] 표시
체크리스트 형식: - [ ] T001 [P] [US1] 설명 + 파일경로

/speckit.analyze - 일관성 검증 (Optional)

읽기 전용 (파일 수정 안 함)
누락된 요구사항 감지
constitution 위반 = CRITICAL

/speckit.implement - 자동 구현

체크리스트 완료 여부 확인
TDD: 테스트 먼저 → 구현 → 커밋
작업 완료 시 [X]로 자동 체크

각 명령어에는 이러한 복잡한 작업들을 수행하는 정교한 프롬프트가 내장되어 있습니다.

개발자는 복잡한 프롬프트 작성 대신, 무엇을 만들지 순수한 의도 전달에만 집중하면 됩니다.
개인의 프롬프트 작성 능력과 무관하게, 맥락을 충분히 제공하는 것만으로도 의도한 대로 정확한 구현이 가능합니다.

추천 도구 : spec-kit, task-master-ai

SDD 방법론을 적용한 API 구현 예시 (spec-kit 활용)

SDD 도구 중 하나인 spec-kit 을 이용해서 개발한 API PR을 살펴보겠습니다.
명세 기반 개발을 위한 AI 워크플로우 도구로 Specification → Plan → Tasks → Implementation 단계로 구조화 되어있다는 특징이 있습니다. (spec-kit 외에도 task-master 등 다양한 도구들이 있습니다.)

아래 펼치기를 통해 확인하실 수 있습니다.
spec-kit 사용하지 않으신 분들은 실제 사례를 통해, ‘나에게 정말 도움이 될까?’ 살펴보실 수 있습니다.

(1) 명세서 작성하기

 ▐▛███▜▌   Claude Code v2.0.25
▝▜█████▛▘  Opus 4.1 · Claude Max
  ▘▘ ▝▝    /Users/hannah/workspaces/my-project

────────────────────────────────────────────────────────────────────────────────────
# 명세 작성 - 무엇을, 왜
> /specify ExampleEntity을 읽어서 {uuid}/pre-application API를 완성해보자.
  ...

# 구현 계획
> /plan
  ...

# 작업 세분화
> /tasks
  ...
────────────────────────────────────────────────────────────────────────────────────

API 구현 시에는 API 인터페이스를 맥락으로 제공하는 것이 효과적이므로, Mock API와 참조해야하는 핵심 Entity 1개에 대한 정보만 제공하였습니다.
Mock API 대신 json이나 간단한 문서 형태를 전달해도 잘 이해합니다.

@RestController
@RequestMapping("/inventories")
class InventoryUiSchemaController {
    @GetMapping("{uuid}/ui-schema/pre-application")
    fun getPreApplicationSchema(): MarketingSlotApiSimpleResponse {
        // 사전신청 없으면 NotFound
        return MarketingSlotApiSimpleResponse(
            data =
                PreApplicationCreateUiSchemaResponse(
                    eventName = PreApplicationCreateUiSchemaResponse.CommonAttributeSchema(),
                    adAccountIds = PreApplicationCreateUiSchemaResponse.CommonAttributeSchema(),
                    requestedStartDateTime = PreApplicationCreateUiSchemaResponse.CommonAttributeSchema(),
                    requestedEndDateTime = PreApplicationCreateUiSchemaResponse.CommonAttributeSchema(),
                    specialNotes = PreApplicationCreateUiSchemaResponse.CommonAttributeSchema(),
                    targetRevenue = PreApplicationCreateUiSchemaResponse.CommonAttributeSchema(),
                    planningScale = PreApplicationCreateUiSchemaResponse.CommonAttributeSchema(),
                    additionalAttributes = null,
                ),
        )
    }
}

명령어 수행 결과로 아래와 같은 파일들이 생성됩니다.

(2) 구현하기

구현 시 spec-kit의 /implement 명령어을 이용한다면, 기존에 작성한 명세 문서들을 자동으로 활용하여 구현합니다.

이전 코드에서는 API Request, Response만 존재할뿐, 서비스도 없었습니다.
1번, 2번 명령어를 통해 명세(spec)을 구체화한 뒤 작업을 요청하였기에 기대한 구현 결과를 얻을 수 있습니다.

(3) Jira 티켓에 갱신

야무지게 만들어진 명세서, 이대로 휘발성으로 날리기에는 아쉽지 않나요?

Spec-kit이 생성한 spec.md와 tasks.md는 구현을 위한 명세서이자 최종 작업 결과에 대한 설명입니다. 이 문서를 요약해 Jira 티켓에 최종 반영함으로써 다음과 같은 이점을 얻을 수 있습니다.

지식의 영구 보존: 코드는 변경되지만, 무엇을 의도했는지에 대한 명확한 명세가 Jira 티켓에 남습니다. 향후 QA, PM, 신규 개발자가 이 기능을 다시 확인할 때 PR과 코드 베이스 전체를 탐색할 필요 없이 Jira 티켓 하나로 모든 맥락을 파악할 수 있습니다.
협업의 효율화: Spec-kit에 포함된 /summarize 등 요약 기능을 활용하거나, 직접 핵심 비즈니스 규칙과 최종 구현 결정 사항을 발췌하여 Jira 댓글 혹은 본문에 갱신해달라고 AI에게 요청합니다.
적용 예시: /summarize spec.md and tasks.md and update jira ticket #1234
검증의 편의성: PM/PO가 Jira 티켓만 보고도 최종 구현 결과가 요구사항을 충족했는지 명세를 통해 빠르고 쉽게 확인할 수 있습니다.

Atlassian MCP 추가하기

claude mcp add --transport sse atlassian https://mcp.atlassian.com/v1/sse

여전히 남아있는 컨텍스트 제공 문제

프롬프트 엔지니어링 문제는 Step1에서 SDD 도구를 통해 해결했습니다.
하지만 여전히 컨텍스트 제공에 대한 문제는 남아있습니다.

AI와 일을 잘 하기 위해서는 충분한 컨텍스트 제공에 대한 방법도 고민해야합니다.

그렇다면 명세서를 컨텍스트로 재활용할 수 없을까?

명세서는 특정 작업을 위한 명세서이자 구현을 위한 최고의 프롬프트입니다.
하지만 컨텍스트 문제 해결을 위해 명세서를 그대로 재활용하면 다음과 같은 리스크에 노출됩니다.

최신화 실패 : 일회성 명세 문서는 시간이 지날수록 쌓이기만 하고 최신화되지 않습니다. Outdated되어 최신 정책을 반영하지 못해 재활용이 불가능합니다.
지식의 파편화 : 도메인 지식이 N개의 명세 문서에 흩어져 있습니다. 어떤 문서가 최신이고 정확한지 판단하기 어렵습니다.

때문에 일회성 작업 명세서(spec.md, tasks.md 등)들은 .gitignore에 추가하여 폐기합니다.

핵심은 팀 SSOT 구축

일회성 작업 명세서에서 끝나는 것이 아니라,
그 안에 담긴 도메인 컨텍스트를 팀의 영구적인 지식 자산으로 전환해야 합니다.
이 과정을 통틀어 CI-SDD (Continuously Integrated Spec-Driven Development)라고 표현합니다.

Step 2. 팀 SSOT의 지속적 통합 (CI-SDD)

CI-SDD란?

Step 2에서는 컨텍스트 제공 문제를 해결합니다.

CI/CD가 "코드의 지속적 통합"을 의미하듯이,
이 글에서 CI-SDD는 SDD를 넘어 팀 SSOT(Single Source of Truth)로의 지속적 통합을 의미합니다. ( 개발자에게 개념을 직관적으로 이해시키기 위해 가상의 단어입니다)

선순환 구조의 지속적인 지식 통합

명세를 통해 정확한 구현을 하는 것(Step 1)을 넘어,
그 지식을 통합하고 축적하여 팀의 단일 진실 원천 자산으로 만들어내는 것(Step 2)까지 포함한 흐름을 설명합니다.

흐름 설명

작업에 필요한 풍부한 맥락을 제공
- SDD 도구 덕분에 프롬프트 엔지니어링에 대한 고민 불필요
- 무엇을 만들지에 대한 맥락 제공에 집중
AI는 사용자가 입력한 프롬프트와 팀의 SSOT 문서를 활용
명세를 기반으로 구현 완료
팀 SSOT 문서 최신화
1. 새롭게 발견/변경된 도메인 지식을 팀 SSOT 문서에 반영
다음 작업 시 AI가 더 완벽한 컨텍스트를 가지고 작업 시작!

시간이 지날수록…

팀의 SSOT의 품질 ↑
개발자가 제공해야할 맥락과 노력 ↓ (이미 SSOT 문서에 있는 내용)
AI의 품질 ↑ (SSOT를 기반으로 일관된 출력)

문서 관리 예시

프로젝트 구조

CLAUDE.md

작업 전 .team/prd 문서를 읽고, 작업 후 문서 최신화할 것을 명시하세요. Claude Code의 경우 CLAUDE.md 를 시스템 프롬프트로서 항상 작업전에 읽고 시작합니다. AI Agent별로 약속된 시스템 프롬프트에 작성하시면 됩니다.

PR 리뷰 시, AI에게 팀 SSOT 문서 검토 요청

AI PR 코드 리뷰 시에, 작업한 내용이 팀 SSOT 문서에 정책 반영이 되어있는지 혹은 문서와 다른 코드 반영이 있는지 등을 검토 요청합니다. 이 덕분에 코드가 변경되는 시점마다 문서가 최신화되었는지 작업자와 동료가 인지할 수 있도록 합니다.

AI PR 피드백 결과

활용하기

팀 SSOT 문서를 활용한다면 개발자는 간결한 지시로도 AI에게 풍부한 컨텍스트를 제공할 수 있습니다.

Before : 개인의 지식에 의존

PreApplicationController에 제출 API를 구현해줘. 사전신청서는 이벤트명, 광고계정ID, 요청 시작일시, 종료일시가 필요하고, 제출 시 Validation 로직은 CommonAttribute와 AdditionalAttribute에 있는... (30줄 설명)

→ 개발자가 인지하고 있는 범위의 맥락만 제공
→ 팀원마다 차이 발생

After : 팀 SSOT 문서 활용

.team/prd/사전신청서 생성 문서.md를 참조해서 PreApplicationController에 제출 API를 구현해

→ 팀 SSOT 문서에 정리된 완벽한 컨텍스트를 AI가 활용
→ 모든 팀원이 상향 평준화된 AI 품질 획득

팀 SSOT 문서가 쌓였기 때문에 짧은 프롬프트 요청만으로 원하던 요구사항을 충족한 API를 뚝딱 만들 수 있었습니다.

맺음말: 프롬프트 + 팀 SSOT = 완벽한 협업

AI와 잘 일하려면 두 가지가 필요합니다.

프롬프트 엔지니어링 (How to Ask) → Step 1 (SDD): 도구를 통한 구조화된 프롬프트 활용
충분한 컨텍스트 (What to Give) → Step 2 (CI-SDD): 선순환 구조의 팀 SSOT 문서 관리 체계 구축

이 글에서 제안하는 CI-SDD(Step 1 + Step 2)는 단순한 문서 작업이 아니라, AI 시대에 소프트웨어 개발팀이 가질 수 있는 가장 강력한 경쟁력입니다.

첫째, 팀의 일관된 품질을 보장합니다.
개개인이 알고 있는 컨텍스트가 아닌, 팀 전체가 공유하는 단일 진실의 원천(Single Source of Truth)을 AI에게 제공함으로써, 개인 역량 차이에 관계없이 일관되고 높은 품질의 AI Output을 확보하게 됩니다. 이는 디버깅과 재작업 비용을 획기적으로 줄여주는 미래를 위한 투자입니다.

둘째, 지식의 복리 효과를 만듭니다.
일회성 명세가 아닌, 살아있는 도메인 지식 베이스를 구축하여 프로젝트의 핵심 자산을 영구적으로 보존합니다. 이는 시간이 지날수록 지식의 선순환 구조를 만들어 도메인 문서 품질과 AI의 개발 효율이 동시에 상승하는 복리 효과를 가져옵니다.

셋째, 지속 가능한 개발을 가능하게 합니다.
지속 가능한 도메인 관리를 통해, 티켓 단위의 빠른 성과를 넘어 프로젝트 전체의 안정성과 지속 가능성을 확보할 수 있습니다.

AI와 더 정확하고 빠르게 일해봅시다

제안하는 액션

SDD 도구 설치하기 (spec-kit, task-master-ai를 추천합니다)
작업마다 SDD 적용하기
팀 SSOT 문서 작성하기

10배 빠른 분산 시스템 디버깅: Micrometer Tracing으로 Trace ID 통합하기

iia_hannah — Wed, 19 Nov 2025 21:01:52 +0900

분산 추적으로 마이크로서비스의 복잡한 로그를 단 하나의 Trace ID로 추적하세요

1. 개요: 분산 추적의 필요성

배경

이런 경험 있으신가요?

시나리오 1: Slack 장애 알림

#server-error 채널
  [결제 API 처리 실패]
Error: Payment gateway timeout
Time: 2025-11-19 10:30:45

개발자: (OpenSearch/Kibana 접속)
개발자: (시간대 검색)
개발자: (에러 키워드 검색)
개발자: (수 많은 로그 중 관련 로그 찾기...  )

시나리오 2: 동시 실행 Batch Job 혼돈

[02:00:00] INFO - dailySettlementJob started
[02:00:01] INFO - monthlyReportJob started
[02:00:02] INFO - Processing settlement for 2025-11
[02:00:02] INFO - Generating report for 2025-11
[02:00:03] INFO - Settlement completed
[02:00:03] INFO - Report generation failed  ← 어느 Job의 로그?
[02:00:04] ERROR - Database connection timeout

개발자: "어느 Job에서 에러가 났지?"
개발자: "Settlement? Report? 둘 다 02시 처리 중이네..."
개발자: (로그 타임스탬프 하나하나 맞춰가며 추적...  )

시나리오 3: Kafka Consumer 메시지 추적 불가

[10:30:45.123] INFO - Received product event: productId=12345
[10:30:45.234] INFO - Updating inventory
[10:30:45.456] INFO - Received product event: productId=67890
[10:30:45.567] INFO - Publishing notification
[10:30:45.678] ERROR - Inventory update failed  ← 어떤 productId?

개발자: "12345 업데이트 실패? 67890 실패?"
개발자: "타임스탬프로 추론하면... 아니 동시 처리라 헷갈려  "
개발자: (동시 처리된 메시지들의 로그가 뒤섞여서 추적 불가능...)

이제는 이렇게 바뀌었습니다

Trace ID 하나로 모든 로그 추적

✅ 시나리오 1 해결: API/Slack 에러 추적

API 에러 응답:
{
  "message": "결제 처리 실패",
  "traceId": "690dae8f00000000de283d7148306199"  ← 이거 하나만 있으면!
}

Slack 알림:
  [결제 처리 실패] (log - 690dae8f00000000de283d7148306199)
                              ↑ 클릭 시 OpenSearch 자동 검색!

OpenSearch:
검색어: "690dae8f00000000de283d7148306199"
결과: 해당 요청의 모든 로그 (15개) - 1초 만에 조회 완료! ✨

✅ 시나리오 2 해결: Batch Job 로그 구분

[02:00:00] [trace=abc123...] INFO - dailySettlementJob started
[02:00:01] [trace=def456...] INFO - monthlyReportJob started
[02:00:02] [trace=abc123...] INFO - Processing settlement for 2025-11
[02:00:02] [trace=def456...] INFO - Generating report for 2025-11
[02:00:03] [trace=abc123...] INFO - Settlement completed
[02:00:03] [trace=def456...] INFO - Report generation failed  ← def456으로 즉시 식별!
[02:00:04] [trace=def456...] ERROR - Database connection timeout

OpenSearch 검색: "def456"
→ monthlyReportJob의 모든 로그만 필터링! (5초 완료) ✨

✅ 시나리오 3 해결: Kafka 메시지별 로그 추적

[10:30:45.123] [trace=aaa111...] INFO - Received product event: productId=12345
[10:30:45.234] [trace=aaa111...] INFO - Updating inventory
[10:30:45.456] [trace=bbb222...] INFO - Received product event: productId=67890
[10:30:45.567] [trace=bbb222...] INFO - Publishing notification
[10:30:45.678] [trace=aaa111...] ERROR - Inventory update failed  ← aaa111 = productId 12345!

OpenSearch 검색: "aaa111"
→ productId=12345 처리 과정의 모든 로그만 추출! ✨

Trace ID 활용 목적

API 요청 추적: 클라이언트 요청부터 응답까지의 전체 흐름
로그 통합: 동일 요청에서 발생한 모든 로그를 하나의 ID로 필터링
장애 대응: 에러 발생 시 관련 로그를 신속하게 검색
성능 모니터링: Zipkin 등에서 성능 병목 지점 식별

2. Spring Micrometer Tracing 핵심 이해

2.1. Spring Micrometer Tracing 소개

Spring Micrometer Tracing을 사용하여 분산 추적 시스템을 구축할 수 있습니다.

Micrometer Tracing이란?

Spring Boot의 공식 분산 추적 추상화 레이어
APM 도구에 종속되지 않는 벤더 중립적 설계
Zipkin, Jaeger 등 다양한 백엔드 지원

시스템 구성

애플리케이션 코드
      ↓
Micrometer Tracing API (벤더 중립)
      ↓
Brave 구현체 (Zipkin 기반)
      ↓
┌─────────────┬──────────────┬──────────────┐
│   Zipkin    │    Jaeger    │ Elastic APM  │  ← 선택 가능!
└─────────────┴──────────────┴──────────────┘

이 글에서는 Zipkin을 예시로 사용하지만 다른 도구로 교체 가능합니다.

핵심 가치

Micrometer 추상화 → APM 도구 독립성 → 요청/Job/메시지별 고유 ID
→ 로그 추적 간소화 → 장애 대응 시간 단축 → 개발 생산성 향상

통합 메커니즘: W3C TraceContext 표준 기반

APM agent가 HTTP 요청에 traceparent 헤더 주입
Brave (Micrometer 구현체)가 이 헤더를 읽어서 동일한 trace ID 사용
코드 변경 없이 표준 헤더만으로 APM 통합 완성
APM 도구 교체 코드 변경 없이 가능

2.2. Trace ID vs Span ID

Trace ID

정의: 전체 요청 흐름을 식별하는 고유 ID

특징

요청 전체 라이프사이클 동안 동일
여러 서비스를 거쳐도 변경되지 않음
128-bit hex 형식: 690dae8f00000000de283d7148306199

사용 시나리오

HTTP Request → Service A → Service B → Service C
     └─────────── 동일 Trace ID ─────────────┘

Span ID

정의: 요청 내 개별 작업 단위를 식별하는 ID

특징

각 작업마다 다른 ID
Thread가 바뀌면 새로운 Span 생성
64-bit hex 형식: 0123456789abcdef

사용 시나리오

HTTP Request (span: a1b2c3d4)
  ├─ DB Query (span: e5f6g7h8)
  ├─ External API Call (span: i9j0k1l2)
  └─ Cache Access (span: m3n4o5p6)

→ Trace ID: 동일
→ Span ID: 각각 다름

코드로 확인하기

@RestController
class ExampleController(
    private val tracer: Tracer,  // Micrometer Tracer
) {
    @GetMapping("/api/example")
    fun example(): Map<String, String> {
        val currentSpan = tracer.currentSpan()

        return mapOf(
            "traceId" to currentSpan.context().traceId(),     // 690dae8f00000000de283d7148306199
            "spanId" to currentSpan.context().spanId(),       // 0123456789abcdef
            "parentSpanId" to (currentSpan.context().parentId() ?: "none"),
        )
    }
}

응답 예시

{
  "traceId": "690dae8f00000000de283d7148306199",
  "spanId": "0123456789abcdef",
  "parentSpanId": "fedcba9876543210"
}

2.3. 전체 아키텍처 개요

Micrometer Tracing의 핵심은 추상화 레이어를 통해 APM 도구에 종속되지 않는 구조입니다.

레이어 아키텍처

┌─────────────────────────────────────────────────────────┐
│  Layer 1: Application Code                              │
│  ┌──────────────────────────────────────────────────┐   │
│  │  @RestController, @Service, @Repository          │   │
│  │  - 비즈니스 로직 작성                             │   │
│  │  - Micrometer API만 사용 (Tracer, Span)          │   │
│  └──────────────────────────────────────────────────┘   │
└────────────────────────┬────────────────────────────────┘
                         │ 의존성: Micrometer Tracer 인터페이스
                         ▼
┌─────────────────────────────────────────────────────────┐
│  Layer 2: Micrometer Tracing (추상화 레이어)            │
│  ┌──────────────────────────────────────────────────┐   │
│  │  io.micrometer.tracing.Tracer                    │   │
│  │  io.micrometer.tracing.Span                      │   │
│  │  - 벤더 중립적 API 제공                           │   │
│  │  - W3C TraceContext 표준 지원                    │   │
│  └──────────────────────────────────────────────────┘   │
└────────────────────────┬────────────────────────────────┘
                         │ 구현체 선택 (둘 중 하나)
                         ▼
┌─────────────────────────────────────────────────────────┐
│  Layer 3: Implementation Bridge (구현체)                │
│  ┌────────────────────┐   ┌─────────────────────────┐   │
│  │  Brave Bridge      │   │  OpenTelemetry Bridge   │   │
│  │  (Zipkin 기반)     │ OR│  (OTEL 기반)            │   │
│  │                    │   │                         │   │
│  │  - Trace 생성      │   │  - Trace 생성           │   │
│  │  - Span 관리       │   │  - Span 관리            │   │
│  │  - MDC 자동 설정   │   │  - MDC 자동 설정        │   │
│  │  - W3C 헤더 생성   │   │  - W3C 헤더 생성        │   │
│  └────────────────────┘   └─────────────────────────┘   │
└────────────────────────┬────────────────────────────────┘
                         │ W3C TraceContext 표준 헤더
                         │ (traceparent: 00-<trace-id>-...)
                         ▼
┌─────────────────────────────────────────────────────────┐
│  Layer 4: APM Backend (자유롭게 선택 가능  )           │
│  ┌──────┬──────┬──────────┬────────┬─────────────┐     │
│  │Zipkin│Jaeger│ Datadog  │ Elastic│New Relic 등 │     │
│  │      │      │   APM    │  APM   │             │     │
│  └──────┴──────┴──────────┴────────┴─────────────┘     │
│  - W3C 표준 헤더로 trace 수신                           │
│  - Trace 저장/집계/시각화                               │
│  - 알림 및 분석 기능                                    │
└─────────────────────────────────────────────────────────┘

핵심 설계 원칙

1️⃣ APM 도구는 자유롭게 교체 가능

Micrometer Tracing을 사용하면 애플리케이션 코드를 변경하지 않고 APM 도구를 교체할 수 있습니다.

// ✅ 이 코드는 어떤 APM 백엔드를 사용하든 동일!
@RestController
class UserController(
    private val tracer: Tracer,  // Micrometer 인터페이스
) {
    fun getUser(): UserResponse {
        val traceId = tracer.currentSpan().context().traceId()
        logger.info("Fetching user, traceId: $traceId")
        // ...
    }
}

APM 백엔드 교체 시나리오:

개발 환경: Zipkin (로컬 Docker)
   ↓
스테이징: Jaeger (쿠버네티스 클러스터)
   ↓
운영 환경: Elastic APM (매니지드 서비스)

→ 코드 변경 없이 설정만 변경!

2️⃣ W3C TraceContext 표준 기반

모든 APM 백엔드는 W3C 표준 헤더(traceparent)를 통해 통합됩니다.

┌─────────────────────────────────────────────────────────┐
│  1. HTTP Request 진입                                   │
│     GET /api/users/12345                                │
│     traceparent: 00-690dae8f...-fedcba...-01           │
└────────────────┬────────────────────────────────────────┘
                 │
                 ▼
┌─────────────────────────────────────────────────────────┐
│  2. Micrometer Tracing                                  │
│     - traceparent 헤더 파싱 ✅                          │
│     - Trace ID 추출: 690dae8f...                        │
│     - 새로운 Span 생성 (parent: fedcba...)              │
│     - MDC.put("traceId", "690dae8f...")                │
│     - MDC.put("spanId", "0123456789...")               │
└────────────────┬────────────────────────────────────────┘
                 │
                 ▼
┌─────────────────────────────────────────────────────────┐
│  3. Application Code                                    │
│     @RestController                                     │
│     fun getUser() {                                     │
│         logger.info("...")  ← MDC의 trace ID 자동 포함  │
│         // 비즈니스 로직 실행                            │
│     }                                                   │
└────────────────┬────────────────────────────────────────┘
                 │
                 ▼
┌─────────────────────────────────────────────────────────┐
│  4. 외부 서비스 호출 (RestTemplate/WebClient)            │
│     GET https://api.external.com/users/12345            │
│     traceparent: 00-690dae8f...-1122334455...-01       │
│                  └─ 동일한 Trace ID 자동 전파! ✅        │
└────────────────┬────────────────────────────────────────┘
                 │
                 ▼
┌─────────────────────────────────────────────────────────┐
│  5. APM Backend                                         │
│     - 모든 서비스의 로그를 Trace ID로 그룹화            │
│     - 분산 환경 전체 플로우 시각화                       │
└─────────────────────────────────────────────────────────┘

W3C traceparent 헤더 형식:

traceparent: 00-690dae8f00000000de283d7148306199-fedcba9876543210-01
             │   └─ 32자리 hex (128-bit)        └─ 16자리 hex (64-bit)
             │      Trace ID                       Span ID
             └─ version

3️⃣ 구현체 선택의 자유

구현체	선택 기준	APM 백엔드 예시
Brave	Spring Boot 중심 프로젝트	Zipkin, Jaeger, Elastic APM, Tempo
OpenTelemetry	다중 언어/플랫폼 환경	Jaeger, Tempo, Datadog, Elastic APM, New Relic

→ 핵심: 어떤 구현체를 선택하든 모든 주요 APM 백엔드와 호환됩니다!

2.4. Micrometer Tracing 핵심 이해

Micrometer Tracing이란?

Micrometer Tracing은 분산 추적(Distributed Tracing)을 위한 Spring Boot 공식 라이브러리입니다.

Spring Cloud Sleuth → Micrometer Tracing 전환

왜 Sleuth가 아니라 Micrometer Tracing인가?

항목	Spring Cloud Sleuth	Micrometer Tracing
지원 상태	⚠️ 유지보수 모드 (2021~)	✅ 활발한 개발
Spring Boot 3.x	❌ 공식 지원 중단	✅ 공식 채택
통합	독립 프로젝트	Micrometer 생태계 통합
벤더 중립성	부분적	완전한 추상화
커뮤니티	감소 추세	성장 중

전환 배경

Spring Boot 3.0 정책: Sleuth 공식 지원 중단, Micrometer Tracing 권장
통합 관측성: 메트릭(Micrometer Metrics) + 추적(Micrometer Tracing) 단일 프로젝트로 통합
표준 준수: W3C TraceContext, OpenTelemetry 등 최신 표준 적극 지원
장기 지원: Spring 팀의 직접 관리로 안정적인 유지보수 보장

결론: 새 프로젝트는 반드시 Micrometer Tracing 사용, 기존 Sleuth 프로젝트는 마이그레이션 권장

핵심 장점

1. 벤더 중립성 (Vendor Neutrality)

코드는 Micrometer 에서 제공하는 인터페이스만 사용!

// ✅ 벤더 중립적 코드 - 어떤 APM 도구든 동작
@RestController
class UserController(
    private val tracer: Tracer,  // Micrometer 인터페이스
) {
    @GetMapping("/api/users/{userId}")
    fun getUser(@PathVariable userId: Long): UserResponse {
        val currentSpan = tracer.currentSpan()  // Micrometer API
        val traceId = currentSpan.context().traceId()

        logger.info("Fetching user: $userId, traceId: $traceId")
        // ...
    }
}

2. 자동 계측 (Auto Instrumentation)

Spring MVC, WebFlux, Kafka 등 자동 지원

@RestController
class OrderController {
    @GetMapping("/api/orders/{orderId}")
    fun getOrder(@PathVariable orderId: Long): Order {
        // ✅ 별도 코드 없이도 자동으로 Span 생성!
        return orderService.findById(orderId)
    }
}

3. MDC 통합

SLF4J MDC와 자동 통합

logger.info("Processing order")
// 출력: [traceId=690dae8f... spanId=0123456789...] Processing order
// ✅ MDC에 자동으로 trace ID 설정됨!

Trace ID 전파 (Propagation)

Micrometer는 W3C TraceContext 표준을 지원하여 서비스 간 trace ID를 자동으로 전파합니다.

HTTP Client 호출 예시

@Service
class ExternalApiService(
    private val restTemplate: RestTemplate,
) {
    private val logger = LoggerFactory.getLogger(javaClass)

    fun callExternalApi(userId: Long): ExternalUserResponse {
        logger.info("Calling external API for user: $userId")

        // ✅ RestTemplate이 자동으로 W3C traceparent 헤더 추가!
        val response = restTemplate.getForObject(
            "https://api.external.com/users/$userId",
            ExternalUserResponse::class.java
        )

        logger.info("External API call completed")
        return response
    }
}

실제 HTTP 요청

GET /users/12345 HTTP/1.1
Host: api.external.com
traceparent: 00-690dae8f00000000de283d7148306199-fedcba9876543210-01
           └─ Micrometer가 자동으로 추가한 trace ID!

W3C traceparent 헤더 형식

traceparent: 00-<trace-id>-<parent-id>-<trace-flags>
             │   │         │          │
             │   │         │          └─ 01 (sampled)
             │   │         └─ 16-digit hex span ID
             │   └─ 32-digit hex trace ID (128-bit)
             └─ version

2.5. Brave vs OpenTelemetry: 구현체 선택

Micrometer Tracing은 2가지 구현체를 지원하며, 하나를 선택해야 합니다.

구분	Brave	OpenTelemetry
의존성	`micrometer-tracing-bridge-brave`	`micrometer-tracing-bridge-otel`
백엔드	Zipkin (기본)	OTLP Collector, Jaeger 등
성숙도	✅ 성숙, 프로덕션 검증됨	⚠️ 빠르게 발전 중
성능	매우 빠름 (경량)	다소 무거움
생태계	Zipkin 중심	OpenTelemetry 표준
추천	Spring Boot 프로젝트	다중 언어/플랫폼 표준화 필요 시

이 가이드의 선택: Brave

이유:

✅ Spring 팀이 추천하는 성숙하고 안정적인 솔루션
✅ 경량이며 성능 오버헤드가 적음
✅ Zipkin과의 완벽한 통합
✅ Spring Boot 생태계에서 검증된 track record

Spring 공식 블로그 인용:

"Spring believes Micrometer and Brave are essential tools in the Spring Boot observability toolkit as mature, production tested solutions."

OpenTelemetry를 선택해야 하는 경우:

다중 언어 환경 (Java, Python, Go 등)
OpenTelemetry 표준 준수가 필수인 조직
Jaeger를 APM 백엔드로 사용

중요: 두 구현체 모두 동일한 Micrometer API를 사용하므로, 나중에 교체 가능합니다.

3. 주요 환경별 Trace ID 활용

이 섹션에서는 Spring MVC, Kafka Consumer, Spring Batch 환경에서 Micrometer Tracing을 활용하는 방법을 설명합니다.

3.1. Spring MVC (HTTP 요청)

자동 계측

Spring MVC에서는 아무것도 하지 않아도 Micrometer가 자동으로 trace를 생성합니다.

흐름

1. HTTP Request 진입
   │
   ▼
2. Micrometer Auto-Configuration
   ├─ W3C traceparent 헤더 읽기 (있는 경우)
   ├─ 또는 새 Trace ID 생성
   ├─ Root Span 생성
   └─ MDC에 traceId/spanId 자동 설정
   │
   ▼
3. Spring MVC Controller
   ├─ @RestController 메서드 실행
   └─ 모든 로그에 trace ID 자동 포함
   │
   ▼
4. Response 반환
   ├─ Span 종료
   └─ APM 백엔드로 전송 (설정된 경우)

실제 코드 예시

@RestController
@RequestMapping("/api/users")
class UserController(
    private val userService: UserService,
) {
    private val logger = LoggerFactory.getLogger(javaClass)

    @GetMapping("/{userId}")
    fun getUser(@PathVariable userId: Long): UserResponse {
        // ✅ 이 로그에는 trace ID가 자동으로 포함됨!
        logger.info("Fetching user: $userId")

        val user = userService.findById(userId)

        return UserResponse.from(user)
    }
}

@Service
class UserService(
    private val userRepository: UserRepository,
) {
    private val logger = LoggerFactory.getLogger(javaClass)

    fun findById(userId: Long): User {
        // ✅ Service 내부 로그도 Controller와 동일한 trace ID!
        logger.info("Querying database for user: $userId")

        return userRepository.findById(userId)
            .orElseThrow { UserNotFoundException(userId) }
    }
}

3.2. Kafka Consumer

자동 계측

Kafka Consumer도 자동으로 trace가 생성됩니다.

흐름

1. Kafka Message 수신
   │
   ▼
2. Micrometer Kafka Instrumentation
   ├─ Kafka 헤더에서 trace 정보 읽기 (Producer가 전파한 경우)
   ├─ 또는 새 Trace ID 생성
   ├─ Span 생성
   └─ MDC에 traceId/spanId 자동 설정
   │
   ▼
3. @KafkaListener 메서드 실행
   └─ 모든 로그에 trace ID 자동 포함
   │
   ▼
4. Message 처리 완료
   ├─ Span 종료
   └─ APM 백엔드로 전송 (설정된 경우)

실제 코드 예시

@Component
class ProductEventConsumer(
    private val productService: ProductService,
    private val eventPublisher: ApplicationEventPublisher,
) {
    private val logger = LoggerFactory.getLogger(javaClass)

    @Transactional
    @KafkaListener(
        topics = ["\${spring.kafka.topics.product-events}"],
        groupId = "\${spring.kafka.group.product-consumer}",
    )
    fun consumeProductEvent(@Payload eventJson: String) {
        val event = parseEvent(eventJson)

        // ✅ 메시지마다 고유한 trace ID 자동 생성됨!
        logger.info(
            "Processing product event - productId: ${event.productId}, eventType: ${event.eventType}"
        )

        when (event.eventType) {
            CREATE, UPDATE -> {
                productService.upsertProduct(
                    id = event.productId,
                    name = event.productName,
                    isActive = event.isActive,
                )
                eventPublisher.publishEvent(ProductChangedEvent(event.productId))
            }
            else -> logger.debug("Ignoring event type: ${event.eventType}")
        }
    }
}

핵심

각 Kafka 메시지마다 새로운 trace ID 생성
동일 메시지 처리 중 발생하는 모든 로그는 동일 trace ID 사용
코드 수정 불필요 - Micrometer가 자동 처리

3.3. Spring Batch (수동 계측)

문제 상황

Spring Batch는 자동 계측이 되지 않습니다!

이유

Batch Job은 HTTP 진입점이 아님
Kafka 메시지도 아님
Scheduler 또는 수동 실행 → Micrometer가 자동 감지 못함

해결: JobTracingListener 구현

핵심 아이디어: Job 시작 시 수동으로 Span을 생성하고 MDC에 trace ID 설정

구현 코드

@Component
class JobTracingListener(
    private val tracer: Tracer,  // ✅ Micrometer Tracer
) : JobExecutionListener {
    private val logger = LoggerFactory.getLogger(javaClass)
    private var currentSpan: Span? = null

    override fun beforeJob(jobExecution: JobExecution) {
        // 1️⃣ Micrometer로 새로운 Span 생성 (trace 시작)
        val span = tracer.nextSpan()
            .name("batch.job.${jobExecution.jobInstance.jobName}")
            .tag("job.name", jobExecution.jobInstance.jobName)
            .tag("job.execution.id", jobExecution.id.toString())
            .tag("service.name", "batch-service")
            .start()  // ← 여기서 실제로 trace ID 생성!

        // 2️⃣ Trace ID와 Span ID 추출
        val traceId = span.context().traceId()
        val spanId = span.context().spanId()

        // 3️⃣ MDC에 수동으로 설정
        // ✅ Application Log에 trace ID 포함하기 위해 MDC 설정
        MDC.put("traceId", traceId)
        MDC.put("spanId", spanId)
        MDC.put("job.name", jobExecution.jobInstance.jobName)

        // 4️⃣ JobExecutionContext에 저장 (Step 간 공유용)
        jobExecution.executionContext.put("traceId", traceId)
        jobExecution.executionContext.put("spanId", spanId)

        this.currentSpan = span

        logger.info(
            "Started batch job trace - job: {}, traceId: {}, spanId: {}",
            jobExecution.jobInstance.jobName,
            traceId,
            spanId,
        )
    }

    override fun afterJob(jobExecution: JobExecution) {
        // 5️⃣ Job 종료 시 태그 추가 및 Span 종료
        currentSpan?.tag("job.status", jobExecution.status.toString())
        currentSpan?.tag("exit.code", jobExecution.exitStatus.exitCode)
        currentSpan?.end()  // ← APM 백엔드에 전송

        logger.info(
            "Completed batch job trace - job: {}, status: {}",
            jobExecution.jobInstance.jobName,
            jobExecution.status,
        )

        // 6️⃣ MDC 정리
        MDC.remove("traceId")
        MDC.remove("spanId")
        MDC.remove("job.name")

        currentSpan = null
    }
}

Step Listener도 추가

class StepExecutionLoggingListener : StepExecutionListener {
    private val logger = LoggerFactory.getLogger(javaClass)

    override fun beforeStep(stepExecution: StepExecution): Unit? {
        val traceId = MDC.get("traceId") ?: "N/A"
        val spanId = MDC.get("spanId") ?: "N/A"

        logger.info(
            "Step starting - name: {}, jobExecutionId: {}, traceId: {}, spanId: {}",
            stepExecution.stepName,
            stepExecution.jobExecutionId,
            traceId,
            spanId,
        )

        return null
    }

    override fun afterStep(stepExecution: StepExecution): Unit? {
        logger.info(
            "Step completed - name: {}, readCount: {}, writeCount: {}, status: {}",
            stepExecution.stepName,
            stepExecution.readCount,
            stepExecution.writeCount,
            stepExecution.status,
        )

        return null
    }
}

Job 설정에 Listener 등록

@Configuration
class DailySettlementJobConfig(
    private val jobTracingListener: JobTracingListener,  // ← 주입
) {

    @Bean
    fun dailySettlementJob(
        jobRepository: JobRepository,
        settlementStep: Step,
        notificationStep: Step,
    ): Job {
        return JobBuilder("dailySettlementJob", jobRepository)
            .listener(jobTracingListener)  // ✅ 등록
            .start(settlementStep)
            .next(notificationStep)
            .build()
    }

    @Bean
    fun settlementStep(
        jobRepository: JobRepository,
        transactionManager: PlatformTransactionManager,
        settlementTasklet: SettlementTasklet,
    ): Step {
        return StepBuilder("settlementStep", jobRepository)
            .tasklet(settlementTasklet, transactionManager)
            .listener(StepExecutionLoggingListener())  // ✅ Step Listener 등록
            .build()
    }
}

핵심:

✅ Job 전체가 하나의 trace ID로 추적됨
✅ Step별로 다른 span ID 사용 (세부 작업 추적)
✅ MDC Key는 traceId/spanId 사용

4. 로그 통합 및 실전 활용

Micrometer Tracing이 생성한 trace ID를 로그에 통합하여 강력한 디버깅 도구로 활용하는 방법을 안내합니다.

4.1. Logback 설정

Spring Boot는 Micrometer Tracing이 활성화되면 자동으로 MDC에 traceId와 spanId를 설정합니다.
이를 로그에 포함하려면 Logback 설정을 조정해야 합니다.

기본 Console 로그 패턴

application.yml:

logging:
  pattern:
    console: "%d{yyyy-MM-dd HH:mm:ss} [%thread] %-5level [%X{traceId},%X{spanId}] %logger{36} - %msg%n"

로그 출력 예시:

2025-11-21 10:30:45 [http-nio-8080-exec-1] INFO  [690dae8f00000000de283d7148306199,0123456789abcdef] c.e.a.UserController - Fetching user: 12345

JSON 로그 형식 (운영 환경 권장)

logback-spring.xml:

<springProfile name="dev | prd">
    <appender name="JSON_CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
        <encoder class="net.logstash.logback.encoder.LoggingEventCompositeJsonEncoder">
            <providers>
                <!-- MDC (✅ Micrometer가 자동 설정한 trace ID) -->
                <mdc>
                    <includeMdcKeyName>traceId</includeMdcKeyName>
                    <includeMdcKeyName>spanId</includeMdcKeyName>
                </mdc>

                <!-- 메시지에 trace ID 포함 -->
                <pattern>
                    <pattern>
                        {
                        "message": "[traceId=%mdc{traceId:-none} spanId=%mdc{spanId:-none}] %message"
                        }
                    </pattern>
                </pattern>

                <!-- 로그 레벨, 타임스탬프, 로거 등 -->
                <timestamp>
                    <timeZone>Asia/Seoul</timeZone>
                    <fieldName>timestamp</fieldName>
                </timestamp>

                <logLevel>
                    <fieldName>level</fieldName>
                </logLevel>

                <loggerName>
                    <fieldName>logger</fieldName>
                </loggerName>
            </providers>
        </encoder>
    </appender>

    <root level="INFO">
        <appender-ref ref="JSON_CONSOLE"/>
    </root>
</springProfile>

JSON 로그 출력 예시:

{
  "timestamp": "2025-11-21 10:30:45.123",
  "traceId": "690dae8f00000000de283d7148306199",
  "spanId": "0123456789abcdef",
  "level": "INFO",
  "logger": "com.example.app.api.UserController",
  "message": "[traceId=690dae8f00000000de283d7148306199 spanId=0123456789abcdef] Fetching user: 12345"
}

4.2. 로그 기반 트러블슈팅 워크플로우

시나리오: 에러 알림 수신

1. Slack/이메일로 에러 알림 수신
   "API 에러 발생: NullPointerException"
   │
   ▼
2. 로그 시스템 (OpenSearch/Kibana/ELK) 접속
   │
   ▼
3. Trace ID로 검색
   검색어: "690dae8f00000000de283d7148306199"
   │
   ▼
4. 해당 요청의 전체 로그 확인
   ├─ HTTP 요청 파라미터
   ├─ 실행된 비즈니스 로직
   ├─ DB 쿼리 및 결과
   ├─ 외부 API 호출
   └─ 에러 스택 트레이스
   │
   ▼
5. 원인 파악 및 수정

핵심 가치

✅ 빠른 원인 파악: Trace ID 하나로 전체 요청 흐름 추적
✅ 정확한 로그 검색: 관련 없는 로그에 방해받지 않음
✅ 동시 요청 구분: 여러 요청이 동시 처리되어도 각각 추적 가능
✅ 마이크로서비스 추적: 서비스 경계를 넘어 전체 플로우 확인

5. 실무 활용 꿀팁

5.1. API 에러 응답에 Trace ID 포함

TraceIdProvider 구현

Micrometer에서 trace ID를 가져오는 Provider 패턴:

fun interface TraceIdProvider {
    fun provide(): String
}

구현체 (Micrometer 기반)

@Component
class MicrometerTraceIdProvider(
    private val tracer: Tracer,  // ✅ Micrometer Tracer
) : TraceIdProvider {
    override fun provide(): String {
        return tracer.currentSpan()?.let { span ->
            span.context().traceId()  // Micrometer API
        } ?: run {
            // Batch: MDC fallback (JobTracingListener가 설정)
            // ✅ 운영 환경 기준 traceId 사용
            MDC.get("traceId") ?: ""
        }
    }
}

에러 응답 DTO

data class ApiErrorResponse(
    val httpStatus: HttpStatus,
    val errorCode: String?,
    val message: String,
    val timestamp: ZonedDateTime = ZonedDateTime.now(),
    val traceId: String,  // ✅ trace ID 포함!
)

에러 핸들러

@RestControllerAdvice
class GlobalExceptionHandler(
    private val traceIdProvider: TraceIdProvider,  // ✅ 주입
) {
    private val logger = LoggerFactory.getLogger(javaClass)

    @ExceptionHandler(UserNotFoundException::class)
    fun handleUserNotFound(e: UserNotFoundException): ResponseEntity<ApiErrorResponse> {
        val traceId = traceIdProvider.provide()
        logger.error("User not found: userId=${e.userId}, traceId=$traceId", e)

        return ResponseEntity
            .status(HttpStatus.NOT_FOUND)
            .body(
                ApiErrorResponse(
                    httpStatus = HttpStatus.NOT_FOUND,
                    errorCode = "error.user.not-found",
                    message = "사용자를 찾을 수 없습니다.",
                    traceId = traceId,
                )
            )
    }
}

에러 응답 예시

{
  "httpStatus": "NOT_FOUND",
  "errorCode": "error.user.not-found",
  "message": "사용자를 찾을 수 없습니다.",
  "timestamp": "2025-11-19T10:30:45.123+09:00",
  "traceId": "690dae8f00000000de283d7148306199"
}

5.2. Slack 알림에 OpenSearch 바로 랜딩

@Service
class SlackNotificationService(
    private val traceIdProvider: TraceIdProvider,  // ✅ Micrometer 기반
    private val slackWebHookClient: SlackWebHookClient,
    @Value("\${logging.opensearch-url}")
    val logUrl: String,
) {
    private val logger = LoggerFactory.getLogger(javaClass)

    fun sendErrorNotification(
        title: String,
        message: String,
    ) {
        val traceId = traceIdProvider.provide()  // ✅ Micrometer에서 trace ID
        val logSearchUrl = buildLogUrl(traceId)

        logger.warn("Sending error notification: title=$title, traceId=$traceId")

        slackWebHookClient.sendWebHook(
            text = "*[$title]* (<$logSearchUrl|log - $traceId>)\n$message",
        )
    }

    private fun buildLogUrl(traceId: String): String =
        if (traceId.isNotEmpty()) {
            logUrl.replace("{keyword}", "\"$traceId\"")
        } else {
            logUrl.replace("{keyword}", "*")
        }
}

Slack 메시지 예시

api-service (prd)
[결제 처리 실패] (log - 690dae8f00000000de283d7148306199)
Order ID: 123456
Error: Payment gateway timeout

"log - 690dae8f..." 클릭 시

OpenSearch가 자동으로 열림
검색어: "690dae8f00000000de283d7148306199"
해당 요청의 모든 로그 자동 필터링!

6. 최종 구현 및 트러블슈팅

️ 전체 아키텍처

┌──────────────────────────────────────────────────────────────┐
│                     클라이언트 요청                           │
│              (iOS, Android, Web, Postman)                     │
└────────────────────────┬─────────────────────────────────────┘
                         │
                         ▼
┌──────────────────────────────────────────────────────────────┐
│  Micrometer Tracing Auto-Configuration                       │
│  - Brave Tracer (Zipkin 기반)                                │
│  - W3C TraceContext 표준 지원                                │
│  - MDC 자동 설정 (traceId/spanId)                   │
└────────────────────────┬─────────────────────────────────────┘
                         │
         ┌───────────────┼───────────────┬──────────────┐
         │               │               │              │
         ▼               ▼               ▼              ▼
    ┌────────┐     ┌────────┐     ┌─────────┐    ┌──────────┐
    │ API    │     │Consumer│     │ Batch   │    │ Logger   │
    │ Error  │     │ Event  │     │ Job     │    │ (MDC)    │
    │Response│     │        │     │ Listener│    │          │
    └────┬───┘     └────┬───┘     └────┬────┘    └────┬─────┘
         │              │              │              │
         └──────────────┴──────────────┴──────────────┘
                         │
                         ▼
         ┌───────────────────────────────────┐
         │   TraceIdProvider                 │
         │   (Micrometer 기반)               │
         │   - provide(): String             │
         └───────────────┬───────────────────┘
                         │
         ┌───────────────┴───────────────┐
         │                               │
         ▼                               ▼
    ┌─────────┐                     ┌────────┐
    │ Slack   │                     │OpenSearch│
    │ Alert   │                     │ Logs   │
    └─────────┘                     └────────┘

핵심 컴포넌트

1. Micrometer Tracing

의존성 (build.gradle.kts)

dependencies {
    // Spring Boot Actuator (Micrometer 포함)
    implementation("org.springframework.boot:spring-boot-starter-actuator")

    // Micrometer Tracing
    api("io.micrometer:micrometer-tracing-bridge-brave")

    // Zipkin Reporter (Brave)
    implementation("io.zipkin.reporter2:zipkin-reporter-brave")

    // JSON 로그
    implementation("net.logstash.logback:logstash-logback-encoder:7.4")
}

설정 (application.yml)

management:
  tracing:
    sampling:
      probability: 1.0  # 100% 샘플링

logging:
  opensearch-url: "https://opensearch.example.com/app/discover#/?_g=(filters:!(),query:(language:kuery,query:'{keyword}'))&_a=(columns:!(message,level),filters:!(),index:'logs-*')"

2. TraceIdProvider

역할: Micrometer에서 trace ID 추출

@Component
class MicrometerTraceIdProvider(
    private val tracer: Tracer,  // Micrometer Tracer
) : TraceIdProvider {
    override fun provide(): String {
        return tracer.currentSpan()?.context()?.traceId()
            ?: MDC.get("traceId") ?: ""  // ✅ traceId 사용
    }
}

3. JobTracingListener (Batch)

역할: Micrometer로 Batch Job trace 생성

@Component
class JobTracingListener(
    private val tracer: Tracer,  // Micrometer Tracer
) : JobExecutionListener {
    private val logger = LoggerFactory.getLogger(javaClass)

    override fun beforeJob(jobExecution: JobExecution) {
        val span = tracer.nextSpan().start()  // Micrometer API
        val traceId = span.context().traceId()

        // ✅ traceId 사용 (운영 환경 통일)
        MDC.put("traceId", traceId)
        MDC.put("spanId", span.context().spanId())
    }
}

트러블슈팅

문제 1: Trace ID가 로그에 없음

증상

2025-11-19 10:30:45.123  INFO 12345 --- [nio-8080-exec-1] com.example.app.api.UserController : Fetching user

원인

로컬 환경에서 실행 (정상 - Micrometer만 동작)
logback-spring.xml에서 MDC Key 설정 누락

해결

Micrometer 기본 키(traceId/spanId) 또는 설정 안 됨

필요 시 logback에서 traceId/spanId 포함

<mdc>
  <includeMdcKeyName>traceId</includeMdcKeyName>
  <includeMdcKeyName>spanId</includeMdcKeyName>
</mdc>

문제 2: Batch Job에서 Trace ID가 없음

증상

{
  "timestamp": "2025-11-19 02:00:00.123",
  "level": "INFO",
  "message": "[traceId=none spanId=none] Starting settlement job"
}

원인

JobTracingListener가 Job에 등록되지 않음

해결

1) JobTracingListener 빈 등록 확인

@Component
class JobTracingListener(
    private val tracer: Tracer,
) : JobExecutionListener {
    // ...
}

2) Job에 Listener 등록 확인

@Bean
fun dailySettlementJob(
    jobRepository: JobRepository,
    jobTracingListener: JobTracingListener,  // ← 주입
): Job {
    return JobBuilder("dailySettlementJob", jobRepository)
        .listener(jobTracingListener)  // ← 등록
        .start(settlementStep)
        .build()
}

3) MDC Key 확인

// ✅ 운영 환경 기준
MDC.put("traceId", traceId)
MDC.put("spanId", spanId)

문제 3: APM에 Trace가 안 보임

증상

로그에는 trace ID 있음
Zipkin UI에는 없음

원인

APM agent 없음 (로컬 환경)
Sampling 설정 0%

해결

management:
  tracing:
    sampling:
      probability: 1.0  # 100%

참고 자료

Micrometer

W3C TraceContext

W3C Trace Context Specification

Zipkin

@Transactional만으로 DB 읽기/쓰기 분산하기 (Writer/Reader Datasource 자동 라우팅)

iia_hannah — Thu, 31 Oct 2024 07:30:28 +0900

들어가며

트래픽이 증가하면서 데이터베이스 부하 관리는 모든 백엔드 시스템이 직면하는 과제입니다. 특히 읽기와 쓰기 작업의 비율이 불균형할 때, 단일 데이터베이스 구조는 병목 지점이 됩니다.

이 글에서는 Writer/Reader Multi-DataSource 라우팅 아키텍처를 통해 이러한 문제를 해결한 경험을 공유합니다. Spring Boot 환경에서 @Transactional(readOnly=true) 어노테이션만으로 자동으로 읽기/쓰기 데이터베이스를 분산하는 방법을 소개합니다.

문제 상황

기존 시스템은 단일 Writer DataSource만 사용하여 모든 조회/변경 쿼리를 처리했습니다

// 기존 구조: 모든 쿼리가 Writer DB로
@Transactional(readOnly = true)
fun findProducts(): List<Product> {
    return productRepository.findAll()  // Writer DB 사용
}

@Transactional
fun createProduct(dto: CreateDto): Product {
    return productRepository.save(entity)  // Writer DB 사용
}

발생한 문제들

읽기 부하 집중: 모든 조회 쿼리가 Writer DB에 집중되어 쓰기 성능 저하 가능성
확장성 제약: DB 부하 분산을 위한 Read Replica 활용 불가
리소스 비효율: 읽기 전용 쿼리도 Writer 커넥션 풀을 소비하여 쓰기 트랜잭션 대기 발생 가능

해결 방법: Multi-DataSource 라우팅 아키텍처

아키텍처 개요

Spring의 AbstractRoutingDataSource와 LazyConnectionDataSourceProxy를 활용하여 트랜잭션 메타데이터 기반 자동 라우팅을 구현했습니다

핵심 구현 코드

1. DataSource 설정

@Configuration
class DataSourceConfig {
    @Bean
    @Primary
    fun dataSource(): DataSource =
        LazyConnectionDataSourceProxy(routingDataSource())

    @Bean
    fun routingDataSource(): RoutingDataSource =
        RoutingDataSource(
            writerDataSource = Pair("WRITER", writerDataSource()),
            readerDataSource = Pair("READER", readerDataSource()),
        )

    @Bean
    @ConfigurationProperties("spring.datasource.hikari")
    fun writerDataSource(): HikariDataSource = HikariDataSource()

    @Bean
    @ConfigurationProperties("spring.datasource.hikari.slaves.first")
    fun readerDataSource(): HikariDataSource =
        HikariDataSource().apply {
            isReadOnly = true  // PostgreSQL 최적화 활성화
        }
}

주요 포인트

LazyConnectionDataSourceProxy로 Primary DataSource를 래핑하여 트랜잭션 컨텍스트가 완전히 설정된 후 Connection을 획득
Reader DataSource에 isReadOnly=true 설정으로 PostgreSQL JDBC 드라이버 최적화 활성화
잘못된 라우팅으로 Reader에서 쓰기 쿼리 실행 시 DB 레벨에서 즉시 거부 (안전장치)
이 글에서는 Reader Replica가 1개라고 가정합니다. AWS Aurora DB를 사용하는 경우 Reader Endpoint로 자동으로 여러 Reader 인스턴스에 로드 밸런싱을 제공하므로, 어플리케이션에서는 하나의 Reader DataSource만 설정합니다.

2. 라우팅 로직

class RoutingDataSource(
    writerDataSource: Pair<String, DataSource>,
    readerDataSource: Pair<String, DataSource>,
) : AbstractRoutingDataSource() {

    private val writerDataSourceId = writerDataSource.first
    private val readerDataSourceId = readerDataSource.first

    init {
        val writer = writerDataSource.second
        super.setDefaultTargetDataSource(writer)

        val targetDataSources: MutableMap<Any, Any> = mutableMapOf(
            writerDataSourceId to writer,
            readerDataSourceId to readerDataSource.second,
        )
        super.setTargetDataSources(targetDataSources)
    }

    override fun determineCurrentLookupKey(): String {
        val isReadOnlyTransaction =
            TransactionSynchronizationManager.isCurrentTransactionReadOnly()

        val selectedDataSource = if (isReadOnlyTransaction) {
            readerDataSourceId
        } else {
            writerDataSourceId
        }

        logger.debug("DataSource routing: readOnly=$isReadOnlyTransaction → $selectedDataSource")

        return selectedDataSource
    }

    // 런타임 수정 방지 (안정성 보장)
    override fun setDefaultTargetDataSource(defaultTargetDataSource: Any) =
        throw UnsupportedOperationException()

    override fun setTargetDataSources(targetDataSources: MutableMap<Any, Any>) =
        throw UnsupportedOperationException()
}

핵심 메커니즘

TransactionSynchronizationManager.isCurrentTransactionReadOnly()로 현재 트랜잭션이 읽기 전용인지 판단
readOnly=true면 READER, 그렇지 않으면 WRITER DataSource 선택
DEBUG 로그로 실시간 라우팅 확인 가능

3. HikariCP 설정 표준화

spring:
  datasource:
    hikari:
      jdbc-url: ${app.db.writer.jdbc-url}
      username: ${app.db.username}
      password: ${app.db.password}
      driver-class-name: org.postgresql.Driver

      # 핵심 설정값 및 근거
      connection-timeout: 30000      # 30초: DB 장애 시 빠른 실패 (Circuit Breaker 효과)
      idle-timeout: 600000           # 10분: 불필요한 커넥션 유지 방지
      max-lifetime: 1800000          # 30분: DB max connection lifetime과 동기화
      maximum-pool-size: ${app.db.writer.max-pool-size}
      minimum-idle: ${app.db.writer.max-pool-size}  # Fixed-Size Pool
      auto-commit: false             # Spring @Transactional이 트랜잭션 제어

      slaves:
        first:
          jdbc-url: ${app.db.reader.jdbc-url}
          # ... 동일한 설정 ...
          maximum-pool-size: ${app.db.reader.max-pool-size}

  jpa:
    properties:
      hibernate:
        connection.provider_disables_autocommit: true  # Hibernate autocommit 확인 쿼리 생략

설정 값 선정 근거

설정	값	근거
`connection-timeout`	30초	DB 장애 시 빠른 실패로 Circuit Breaker 효과
`minimum-idle = maximum-pool-size`	Fixed-Size Pool	트래픽 급증 시 커넥션 생성 지연 없이 즉시 대응, 성능 예측 가능
`auto-commit`	false	Spring `@Transactional`이 트랜잭션 경계 제어 (true면 각 쿼리마다 즉시 커밋되어 원자성 깨짐)
`provider_disables_autocommit`	true	Hibernate가 autocommit 상태 확인 쿼리 생략하여 성능 개선

계층적 설정 구조 (멀티모듈 패턴)

참고: Multi-DataSource 라우팅 자체는 모놀리식 애플리케이션에서도 동일하게 구현 가능합니다. 이 글에서는 멀티모듈 MSA 구조를 예시로 설명하지만, 모놀리식의 경우 단일 application.yml에 모든 설정을 통합하여 더 간단하게 구성할 수 있습니다.

모듈 아키텍처

이 패턴은 MSA(Microservice Architecture) 환경 또는 멀티모듈 구조에서 특히 유용합니다

┌─────────────────────────────────────────────┐
│         Application Layer                   │
├──────────────────┬──────────────────────────┤
│ admin-api        │  public-api    │  batch  │ ← 각 서비스별 독립 배포
│ (내부 관리용)     │  (외부 API)    │         │
├──────────────────┴──────────────────────────┤
│              Domain Layer                   │ ← 공통 비즈니스 로직 + DataSource 설정
│        (JPA Entities, Services)            │
└─────────────────────────────────────────────┘

핵심 개념

Domain 모듈: DataSource 설정을 포함한 공통 인프라 제공
Application 모듈: Domain을 의존하며, 각자의 트래픽 특성에 맞는 Pool Size 설정

설정 파일 계층

각 Application 모듈은 공통 설정을 import하고 Pool Size만 재정의:

1. Domain 모듈 (공통 설정)

# domain/src/main/resources/config-db-common.yml
spring:
  datasource:
    hikari:
      connection-timeout: 30000
      idle-timeout: 600000
      max-lifetime: 1800000
      auto-commit: false
      # ... 공통 HikariCP 설정

2. Admin API 모듈 (내부 사용자용, 낮은 동시성)

# admin-api/src/main/resources/application.yml
spring:
  config:
    import:
      - classpath:config-db-common.yml  # 공통 설정 import

app:
  db:
    writer:
      max-pool-size: 10
    reader:
      max-pool-size: 15

3. Public API 모듈 (외부 트래픽, 높은 동시성)

# public-api/src/main/resources/application.yml
spring:
  config:
    import:
      - classpath:config-db-common.yml

app:
  db:
    writer:
      max-pool-size: 20
    reader:
      max-pool-size: 40  # 조회 위주 트래픽

4. Batch 모듈 (순차 처리, 최소 Pool)

# batch/src/main/resources/application.yml
spring:
  config:
    import:
      - classpath:config-db-common.yml

app:
  db:
    writer:
      max-pool-size: 5
    reader:
      max-pool-size: 5

장점

변경 지점 최소화: HikariCP 타임아웃 변경 시 Domain 설정 파일 1곳만 수정
모듈별 특화: Pool Size는 각 모듈의 트래픽 특성에 맞게 독립 설정
설정 누락 방지: 공통 기본값이 자동 적용
DRY 원칙 준수: ~100줄의 중복 코드 제거
독립 배포: 각 Application 모듈은 독립적으로 배포 및 확장 가능

사용 방법

개발자 입장에서의 사용법

변경 전

// 모든 쿼리가 Writer DB로
@Service
class ProductService(
    private val productRepository: ProductRepository
) {
    fun findProducts(): List<Product> {
        return productRepository.findAll()  // Writer DB
    }
}

변경 후

// @Transactional 어노테이션만 추가하면 자동 라우팅
@Service
class ProductService(
    private val productRepository: ProductRepository
) {
    @Transactional(readOnly = true)  // ← READER DataSource 자동 선택
    fun findProducts(): List<Product> {
        return productRepository.findAll()  // Reader DB로 자동 라우팅
    }

    @Transactional  // ← readOnly 미지정 시 기본값 false → WRITER
    fun createProduct(dto: CreateDto): Product {
        return productRepository.save(entity)  // Writer DB
    }
}

핵심 개발자는 @Transactional 어노테이션만 적절히 선택하면 되고, 뒷단에서 자동으로 라우팅됩니다.

주의사항

1. @Transactional 어노테이션 누락 시 라우팅 실패

@Transactional 어노테이션이 없으면 isCurrentTransactionReadOnly()가 false를 반환하여 무조건 WRITER로 라우팅됩니다.

// ❌ 안티패턴: @Transactional 누락
fun findProducts(): List<Product> {
    return productRepository.findAll()  // Writer DB 사용 (의도와 다름)
}

// ✅ 올바른 사용
@Transactional(readOnly = true)
fun findProducts(): List<Product> {
    return productRepository.findAll()  // Reader DB 사용
}

대응 방안

모든 Service 메서드에 @Transactional 명시
ArchUnit 테스트로 누락 검출 자동화
DEBUG 로그 활성화로 라우팅 동작 확인

2. Reader DB Replication Lag

Reader DB가 Writer DB와 동기화되지 않은 경우 조회 데이터 최신성 문제 발생 가능:

// 시나리오: 데이터 생성 직후 조회
@Transactional
fun create(dto: CreateDto): Product {
    return productRepository.save(entity)  // Writer DB에 저장
}

@Transactional(readOnly = true)
fun findById(id: Long): Product {
    // Replication Lag로 인해 방금 생성한 데이터가 보이지 않을 수 있음
    return productRepository.findById(id).orElseThrow()
}

해결 방법

// Critical Path에서는 Writer 직접 사용
@Transactional  // readOnly=false → Writer 사용
fun createAndGet(dto: CreateDto): Product {
    val created = productRepository.save(entity)
    return productRepository.findById(created.id).orElseThrow()  // Writer에서 조회
}

테스트 전략

통합 테스트 (MultiDataSourceRoutingTest)

@SpringBootTest
@DisplayName("Multi-DataSource 라우팅 테스트")
class MultiDataSourceRoutingTest : BaseRepositoryTest() {

    @Test
    @DisplayName("DataSource Bean이 LazyConnectionDataSourceProxy로 래핑되어 있어야 한다")
    fun `should wrap routing datasource with lazy proxy`() {
        assertThat(dataSource).isInstanceOf(LazyConnectionDataSourceProxy::class.java)
    }

    @Test
    @DisplayName("Reader DataSource는 readOnly로 설정되어 있어야 한다")
    fun `should configure reader datasource as readonly`() {
        assertThat(readerDataSource.isReadOnly).isTrue()
    }

    @Test
    @Transactional(readOnly = true)
    @DisplayName("읽기 전용 트랜잭션에서 JDBC로 테이블 조회가 가능해야 한다")
    fun `should execute jdbc query in readonly transaction`() {
        val count = jdbcTemplate.queryForObject(
            "SELECT COUNT(*) FROM products",
            Long::class.java
        ) ?: 0L

        assertThat(count).isGreaterThanOrEqualTo(0L)
    }
}

검증 항목

LazyConnectionDataSourceProxy 래핑 확인
Writer/Reader DataSource Bean 등록 확인
Reader DataSource readOnly 설정 검증
쓰기/읽기 트랜잭션에서 JDBC 쿼리 실행 성공

TestContainers 설정 (Optional)

object PostgresTestContainer {
    fun configureProperties(registry: DynamicPropertyRegistry) {
        val jdbcUrl = instance.jdbcUrl
        val username = instance.username
        val password = instance.password

        // Writer DataSource
        registry.add("spring.datasource.hikari.jdbc-url") { jdbcUrl }
        registry.add("spring.datasource.hikari.username") { username }
        registry.add("spring.datasource.hikari.password") { password }

        // Reader DataSource (테스트에서는 Writer와 동일)
        registry.add("spring.datasource.hikari.slaves.first.jdbc-url") { jdbcUrl }
        registry.add("spring.datasource.hikari.slaves.first.username") { username }
        registry.add("spring.datasource.hikari.slaves.first.password") { password }
    }
}

테스트 환경에서도 프로덕션과 동일한 Multi-DataSource 구조를 유지하되, Writer/Reader가 동일한 PostgreSQL 컨테이너를 사용합니다.

결론

Spring Boot의 AbstractRoutingDataSource와 LazyConnectionDataSourceProxy를 활용하면 @Transactional(readOnly=true) 어노테이션만으로 읽기/쓰기 데이터베이스를 자동 분산할 수 있습니다.

개발자 친화적인 아키텍처

이 패턴의 가장 큰 장점은 개발자의 추가 노력이나 복잡한 구현 없이 즉시 사용 가능하다는 점입니다:

기존 코드 수정 최소화: 이미 사용 중인 @Transactional 어노테이션에 readOnly=true만 추가
휴먼 에러 방지: 개발자가 수동으로 DataSource를 선택할 필요 없음
자동화된 라우팅: 트랜잭션 메타데이터 기반으로 시스템이 자동 판단
일관성 보장: 모든 팀원이 동일한 패턴으로 DB 접근

잘못된 접근 방식 (수동 관리):

// ❌ 개발자가 매번 DataSource를 명시 (휴먼 에러 가능성)
@Autowired
@Qualifier("readerDataSource")
private lateinit var readerDataSource: DataSource

fun findProducts(): List<Product> {
    val connection = readerDataSource.connection  // 실수로 writerDataSource 사용 가능
    // ...
}

올바른 접근 방식 (자동 라우팅):

// ✅ 어노테이션만으로 자동 라우팅 (실수 불가능)
@Transactional(readOnly = true)
fun findProducts(): List<Product> {
    return productRepository.findAll()  // 시스템이 자동으로 Reader DB 선택
}

핵심 포인트

LazyConnectionDataSourceProxy: 트랜잭션 컨텍스트 완전 설정 후 Connection 획득
AbstractRoutingDataSource: isCurrentTransactionReadOnly() 기반 자동 라우팅
HikariCP 표준화: Fixed-Size Pool, auto-commit=false 등 최적화 설정
계층적 설정: 공통 설정 + 모듈별 Pool Size 특화
Zero-Touch: 개발자는 @Transactional 어노테이션만 신경 쓰면 됨

이 아키텍처는 실제 프로덕션 환경에서 검증된 패턴이며, 개발자의 실수를 시스템적으로 방지하면서 트래픽 증가에 대비한 안정적인 DB 부하 분산 솔루션입니다.

참고 자료

[월간회고] 2024년 9월, 생각 정리와 루틴

iia_hannah — Wed, 2 Oct 2024 07:34:53 +0900

지난 달 되돌아보기

지난 달 액션

1. 저녁 루틴에 '독서' 추가하기 (= 수면을 위한 저녁 루틴 가꾸기)
저녁 루틴에 독서를 넣은 후로 책 읽는 빈도가 엄청 늘었다. 책 읽기가 익숙해져서 그런지 저녁시간 뿐만 아니라 대중교통 이용할 때에도 많이 읽게 된다.
저녁에 책을 읽고 나면 비교적 잡생각도 줄어들고 머리가 조용해지는 것 같다.
아직 저녁 루틴에 넣은 지 얼마 안되서 빠르게 잠들기에 효과적인지는 좀 더 지켜봐야할 것 같아
효과가 조금 있긴 한데, 침대에 누워서 생각이 시작될 때도 있어서 주의가 필요함!

2. 주 3회 운동
제대로 워킹한 것 같다! 일정이 있었던 주만 빼고 주 3회 운동 했다!
되도록 필라테스도 주 3회 신청하려고 노력했는데, 예약이 치열할 때가 있어서 다른 운동도 병행해야할 것 같다.
다음 달에는 클라이밍 주말 강습 시작할 예정이다!
컨디션이 안좋을 때에는 필라테스 대신 가벼운 홈트나 걷기 해야할 것 같다.

이번 달

주요 이벤트

스터디 완료
드디어 책 소프트웨어 아키텍처 101 스터디(4월 17일~9월 3일)가 끝났다.
혼자였으면 못읽었을 책이라서 뿌듯하다.
다들 중간에 회사 일이 바쁘고 일정이 있어서 스킵된 주가 좀 있어서 오래 걸렸는데, 스터디 오래 하니까 좀 괴로웠다.
이번년도는 이제 스터디 그만...

베란다 페인트칠
미루고 미루던 베란다 페인트 칠을 추석에 했다.
원래 3월에 한번 했는데 날이 너무 추워서 페인트가 습이 먹고 얼어서 흘러내렸다.
날 풀리면 해야지 하다가 시간 순식간에 지나버려서 이제함..!
추석이 생각보다 시원하지 않아서 베란다칠할때 진짜 덥고 힘들었는데, 결과물 보고 나니까 뿌듯하다.

한 달 모아보기

운동 : 11일
독서 : 13일
아침루틴 : 11일 => 이번달은 1/3밖에 못했네. 다음달에는 비율 높이자!

회고 & 액션아이템

1. 생각을 비우고 마음을 평온하게 하기

불필요하고 부정적인 가정에 의한 상상을 의식적으로 멈추자
사실에 기반한 일에 대해서 생각하도록 노력하자

2. 늦게 자면 아침 루틴을 실패한다

밤 10시에는 집에 있자. (오후 9시에는 집으로 출발하고, 저녁에 과식 금지)

3. 주말 루틴이 워킹하지 않음

주말/휴일에도 아침 루틴을 하자!

[소프트웨어 아키텍처 101] 13. 서비스 기반 아키텍처 스타일

iia_hannah — Sat, 14 Sep 2024 11:14:11 +0900

인상깊은 부분

분산 시스템에서의 데이터 무결성

BASE 분산 트랜잭션라는 새로운 개념의 존재를 알게 됨
분산도가 높은 아키텍처에서는 최종 일관성 기반의 BASE 분산 트랜잭션 활용. 이 기법은 최종 일관성 기반이므로 ACID 트랜잭션 레벨의 데이터 무결성은 지원하지 않음

최종 일관성이란 별도로 분리된 배포 단위에서 처리된 데이터를 미리 알 수 없는 어느 시점에 모두 일관된 상태로 동기화한다.
확장성, 성능, 가용성을 얻는 대가로 데이터 일관성과 무결성을 희생하는 트레이드오프인 셈이다

트랜잭션 사가

오케스트레이션 및 코레오그래피

DB 분리 시 도메인 서비스 간 상호 통신 방지와 데이터베이스 간 중복 데이터 방지를 고려

서비스 기반 아키텍처에서 단일 모놀리식 데이터베이스를 개별 데이터베이스로 분리할 수 있고, 마이크로서비스와 비슷하게 각 도메인 서비스의 전용 데이터베이스들로도 쪼갤 수도 있음
여기서 포인트는 각 데이터베이스에 있는 도메인 데이터를 다른 도메인의 서비스가 필요로 하지 않도록 설계하는 것임
그래야 도메인 서비스 간 상호 통신을 방지하고 데이터베이스 간의 중복 데이터가 방지됨

서비스 단위에 따른 트레이드 오프

서비스 기반 아키텍처는 도메인 서비스의 단위가 크기 때문에 데이터 무결성, 일관성 측면에서 유리하다.
반면 서비 스규모가 작은 MSA와 같은 아키텍처는 작은 서비스 하나만 변경 영향도가 있고, 서비스가 한 가지 역할만 수행하므로 변경을 해도 다른 기능이 망가질 일이 거의 없다.

요약

서비스 기반 아키텍처(service-based architecture)는 마이크로서비스 아키텍처 스타일의 일종으로, 가장 실용적인 아키텍처 스타일 중 하나
유연하고 비교적 덜 복잡하고 비용이 많이 들지 않아서 널리 채택됨

13.1 기본 토폴리지

기본 구성
- 각각 따로 배포된 유저 인터페이스, N개의 원격 서비스, 그리고 모놀리스 데이터베이스
- 이 아키텍처 스타일에서 '서비스'는 큼지막한 단위로 분리해 별도로 배포하는 어플리케이션의 일부 (보통 도메인 서비스라고 함)
- 여러 서비스가 단일 모놀리식 데이터베이스를 공유하며, 서비스는 보통 4개~12개, 평균 7개 정도
배포 : 도메인 서비스는 각각 단일 인스턴스로 배포되지만, 확장성/내고장성/처리량 요구사항에 따라 N개의 인스턴스를 둘 수 있음
통신
- 유저 인터페이스 외부에서 원격 액세스 프로토콜로 서비스에 접속 가능함. 프로토콜은 일반적으로 REST를 많이 쓰며, 메시징, 원격 프로시저 호출(RPC), SOAP도 사용 가능함
- 유저 인터페이스(또는 외부 요청)은 프록시나 게이트웨이로 구성된 API 레이어를 통해 서비스 접속 가능하지만, 대개는 [[서비스 로케이터 패턴(service locator pattern)]]에 따라 유저 인터페이스, API 게이트웨이, 프록시에 내장된 유저 인터페이스를 직접 액세스함
서비스 기반 아키텍처는 중앙 공유 데이터베이스를 사용한다는 특징이 중요. 서비스는 기존 모놀리식 레이어드 아키텍처와 동일한 방식으로 쿼리와 조인 기능을 사용함

13.2 토폴로지 변형 (다양한 구성)

유저 인터페이스 변형 (그림 13-2)
데이터베이스 변형 (그림 13-3)
- 단일 모놀리식 데이터베이스 역시 개별 데이터베이스로 분리할 수 있고, 각 도메인 서비스 전용 데이터베이스들로도 쪼갤 수 있음
- 데이터베이스 분리 시 중요한 점은, 각 데이터베이스에 있는 도메인 데이터를 다른 도메인 서비스가 필요로 하지 않도록 설계하는 것.그래야 도메인 서비스 간 상호 통신을 방지하고 데이터베이스 간의 중복 데이터를 방지할 수 있음
API 레이어 추가 (그림 13-4)
- 리버스 프록시 또는 게이트웨이로 구성된 API 추가 가능
- 도메인 서비스의 기능을 외부 시스템에 표출하거나 공통 관심사를 통합해서 유저 인터페이스 밖으로 떼어낼 경우에도 유용한 방법
  ![[소프트웨어 아키텍처 101 13장 다양한 토폴로지.png]]

13.3 서비스 설계 및 세분도 (최상위 분할)

서비스 기반 아키텍처의 도메인 서비스는 보통 단위가 크기 때문에 레이어드 아키텍처 스타일로 기술 분할하는 방법이 일반적이지만, 도메인 분할도 쓰인다.
API 액세스 퍼사드(access facade)
- 유저 인터페이스를 통해 유입된 비즈니스 요청을 오케스트레이트
- 어떻게 분할하든 도메인 서비스는 유저 인터페이스에서 비즈니스 기능을 호출하기 위해 접속할 수 있게 API 액세스 퍼사드를 제공해야함
세분도 관점에서의 서비스 아키텍처와 MSA의 차이 (API 액세스 퍼사드)
- 서비스 기반 아키텍처는 내부 클래스 수준의 오케스트레이션
  예를 들어, 유저 인터페이스에서 주문이 접수되면 OrderService 도메인 서비스의 API 액세스 퍼사드가 받아 내부 처리 후, 재고 차감 등의 일련의 비즈니스 요청을 오케스트레이트함
- MSA는 외부 서비스의 오케스트레이션
  - 예를 들어, 위와 같은 요청을 MSA에서 처리한다면 별도 배포된 다수의 원격 서비스를 오케스트레이션 해야함
데이터 무결성
- 단일 도메인 서비스 - 커밋/롤백이 수반되는 [[ACID 트랜잭션]] 데이터베이스 트랜잭션 활용
  예를 들어, 고객이 주문 후 만료된 신용카드로 결제를 했다면, 동일 서비스에서 발생한 원자적 트랜잭션이니 데이터베이스에 추가된 주문 관련 데이터를 롤백해서 모두 삭제하고 해당 고객에게 더 이상 결제 진행이 불가함을 알릴 수 있음
- 분산도가 높은 아키텍처(ex: 마이크로 서비스) - 최종 일관성 기반의 [[BASE 분산 트랜잭션]] 활용. 이 기법은 최종 일관성 기반이므로 ACID 트랜잭션 레벨의 데이터 무결성은 지원하지 않음
  서비스를 잘게 나눈 MSA에서 위와 동일하게 만료된 신용카드로 결제를 했다면, 주문 데이터는 데이터베이스에 삽입되었으나 결제는 불가하고 주문 처리를 진행할 수 없어서 비일관된 상태(inconsistent state)가 됨. 그렇다면 주문과 관련된 재고 정보는 주문이 성공한 것으로 보고 재고 차감을 해야할까요? 만약 재고가 없는 상태에서 다른 고객이 동일 제품을 주문한다면 새 고객이 구매할 수 있게 해야할까, 아니면 신용카드가 만료된 고객이 주문을 마칠 수 있도록 재고를 확보해두어야할까?
- 서비스가 잘게 나누어진 아키텍처에서 비즈니스 프로세스를 오케스트레이트하려면 신경 써야 할 문제가 많다.
트레이드 오프
- 서비스 기반 아키텍처의 도메인 서비스는 단위가 커서 데이터 무결성과 일관성 측면에서는 유리하지만 배포와 변경 영향도 측면에서는 트레이드오프가 존재함
- 서비스 기반 아키텍처는 일부 기능이 변경되어도 서비스 전체를 테스트해야함
- 반면, 규모가 작은 서비스 단위의 아키텍처는 작은 서비스 하나만 변경 영향도가 있고, 서비스가 한 가지 역할만 수행하므로 변경을 해도 다른 기능이 망가질 일이 거의 없음

13.4 데이터베이스 분할

단일 모놀리식 데이터베이스 공유 시 문제
- 서비스 기반 아키텍처는 서비스 수가 적은 편이라 보통 단일 모놀리식 데이터베이스를 공유함
- 데이터베이스 커플링은 테이블 스키마 변경 시 문제가 될 수 있음
- 테이블 스키마를 올바르게 변경하지 않을 경우 모든 서비스에 악영향을 미침
공용 스키마 관리
- 단일 공유 라이브러리 활용 (그림 13-6)
  - 테이블 구조를 조금이라도 변경하게 되면, 변경된 테이블의 사용 여부와 상관없이 전체 서비스를 일제히 변경 후 재배포할 수 밖에 었음
- 여러 공유 라이브러리 활용 (그림 13-7)
  - 변경 영향도와 리스크를 낮추기 위해 데이터베이스를 논리적으로 분할하고 이러한 논리 분할을 연합 공유 라이브러리를 통해 명시 (논리적으로 분할 시 변경 관리에 용이함)
  - 단, 모든 서비스가 참조하는 공통 테이블을 변경하려면 전체 서비스와 미리 조율이 필요함. 테이블 변경 영향도를 낮추는 방법 중 하나는 공통 엔티티 객체를 버전 관리 시스템에서 락킹하고 수정 권한을 DBA팀에만 부여하는 것임. 이렇게 해야 변경을 통제할 수 있고 모든 서비스의 공용 테이블 변경하는 작업의 중요성이 부각됨

13.5 아키텍처 예시

전자제품 재활용 시스템을 예로 서비스 기반 아키텍처의 유연함과 강점을 살펴보자. 중고 전자 제품 재활용 프로세스는 아래와 처리 순서로 이뤄진다.
- 견적 (quoting) : 고객이 자신의 중고 제품을 얼마에 보상받을 수 있는지 문의
- 수취 (receiving) : 고객이 보상가에 만족하면 회사에 제품을 보내고 회사는 실물을 받음
- 감정 (assessment) : 고객이 보낸 제품의 작동 상태를 꼼꼼히 평가
- 회계 (accounting) : 상태가 좋을 경우 회사는 고객에게 약속한 보상가를 지불
- 제품 상태 (item status) : 이 과정 중 고객은 언제든 회사 웹사이트에 접속하여 진행 상황 확인 가능
- 재활용 (recycling) : 감정 결과에 따라 제품은 해제 후 재활용되거나 재판매
- 리포팅 (reporting) : 재활용 성과에 따른 임시/정기 재무 리포트를 정기적으로 체크
전자 제품 재활용 서스템을 서비스 기반 아키텍처로 설계 (그림 13-8)
- 유저 인터페이스와 각 도메인의 연합 덕분에 유저 인터페이스의 내고장성, 확장성, 보안이 실현됨
- 퀀텀 (2개)
  - 외부에서 고객을 상대하는 퀀텀 - 높은 처리량이 필요한 서비스의 확장성 확보
  - 내부 운영 퀀텀 - 그 밖에 서비스는 내부 운영이므로 확장할 필요가 없으니 단일 인스턴스로 설정
- 보안
  - 외부 고객은 내부 기능으로 향하는 네트워크에 접속 불가
  - 내부 데이터와 기능을 외부 작업과 분리된 별도 네트워크 영역에 두어 데이터 보안에 긍정적 요소
  - 방화벽을 통해 내부 서비스는 단방향으로 외부 서비스에 접근 가능하지만, 반대 케이스는 불가
- 데이터베이스 분리
  - 외부 고객 처리용 데이터베이스와 내부 처리용 데이터베이스를 물리적으로 분할
  - 데이터베이스에 따라서 내부 테이블을 미러링하고 테이블을 동기화할 수 있음
- 변경이 잦은 서비스를 단일 도메인 서비스로 격리하여 민첩성(얼마나 빨리 변화에 대응할 수 있나), 시험성(테스트하기 얼마나 쉽고 완전한가), 배포성(배포의 난이도, 빈도, 리스크)을 높일 수 있음

13.6 아키텍처 특성

등급별점 5개 받은 특성은 없지만 두루두루 밸런스 좋은 아키텍처이다.

아키텍처 특성	별점	설명
분할 유형	도메인	도메인 위주로 구성된 아키텍처
퀀텀 수	하나 또는 여러 개	동일한 데이터베이스나 유저 인터페이스를 공유할 경우 전체 시스템의 퀀텀은 1이지만, 유저 인터페이스와 데이터베이스는 분리되어 연합될 수 있으므로 전체 시스템 내부에 여러 퀀텀이 생길 수 있음 그림 13-8 전자 제품 재활용 시스템의 퀀텀은 2임
배포성	⭐️⭐️⭐️⭐️	개별 배포되는 여러 도메인 서비스로 나누기 때문에 덩치 큰 모놀리스보다 덜 위험하게, 더 자주 배포할 수 있음
탄력성	⭐️⭐️	서비스를 나누는 단위가 크기 때문에 별점 2점 프로그램 방식으로 탄력성을 추구할 수 있지만 중복되는 기능이 많아 머신 리소스 및 비용 측면에서 효율적이지 않음 그리고 처리량이나 페일오버를 개선해야하는 요건이 따로 없다면 서비스 인스턴스는 1개임. 단일 인스턴스는 인메모리 캐시, 데이터베이스 커넥션 풀링 지원이 더 간편함
진화성	⭐️⭐️⭐️	-
내고장성&가용성	⭐️⭐️⭐️⭐️	자기 완비형이고 데이터베이스와 코드를 공유하는 까닭에 서비스 간 통신이 거의 없고, 어느 도메인 서비스가 잘못돼도 다른 서비스는 옇양을 받지 않음
모듈성	⭐️⭐️⭐️⭐️	-
전체 비용	⭐️⭐️⭐️⭐️	가장 구현하기 쉽고 비용면에서도 효율적인 분산 아키텍처로, 단순성과 전체 비용 측면에서 다른 분산 아키텍처와 차별화됨
성능	⭐️⭐️⭐️	-
신뢰성	⭐️⭐️⭐️⭐️	도메인 서비스를 굵직하게 나누기 때문에 다른 분산 아키텍처에 비해 신뢰성이 우수함. 서비스 간 네트워크 트래픽이 적고 대역폭을 덜 사용하며, 분산 트랜잭션이 많지 않기 때문에 전반적으로 네트워크 측면에서 신뢰성이 좋음
확장성	⭐️⭐️⭐️	서비스를 나누는 단위가 크기 때문에 별점 3점 프로그램 방식으로 확장성을 추구할 수 있지만 중복되는 기능이 많아 머신 리소스 및 비용 측면에서 효율적이지 않음 그리고 처리량이나 페일오버를 개선해야하는 요건이 따로 없다면 서비스 인스턴스는 1개임. 단일 인스턴스는 인메모리 캐시, 데이터베이스 커넥션 풀링 지원이 더 간편함
단순성	⭐️⭐️⭐️	가장 구현하기 쉽고 비용면에서도 효율적인 분산 아키텍처로, 단순성과 전체 비용 측면에서 다른 분산 아키텍처와 차별화됨
시험성	⭐️⭐️⭐️⭐️	개별 배포되는 여러 도메인 서비스로 나누기 때문에 도메인 범위가 한정되므로 테스트 커버리지가 향상
민첩성	⭐️⭐️⭐️⭐️	개별 배포되는 여러 도메인 서비스로 나누기 때문에 신속한 변경이 가능함

13.7 언제 서비스 기반 아키텍처를 사용하는가

단순성과 비용 측면에서 가장 실용적인 아키텍처
- 이보다 더 강력한 분산 아키텍처 스타일도 있지만, 그 강력함은 곧 가파른 비용 상승을 동반하고 그렇게 까지 강력할 필요가 없음을 알게됨
도메인 주도 설계와 궁합이 좋음
ACID 트랜잭션 사용 비율이 높음
- 분산 아키텍처에서는 전통적인 ACID 트랜잭션이 아닌 최종 일관성에 의존하는 방식으로 수행되기 때문에 데이터베이스 트랜잭션을 관리하고 조율하는 일이 늘 골칫거리임
- 그러나 서비스 기반 아키텍처의 도메인 서비스는 큼지막한 단위로 구성되므로 다른 분산 아키텍처에 비해 ACID 트랜잭션이 더 잘 보존됨
- 물론, 유저 인터페이스나 API 게이트웨이가 둘 이상의 도메인 서비스를 오케스트레이션하는 경우도 있는데, 이럴 때에는 트랜잭션이 사가와 BASE 트랜잭션에 의존해야함
- 그러나 대부분 트랜잭션은 특정 도메인 서비스에 한정되므로 전통적인 커밋/롤백 트랜잭션 기능을 그대로 사용할 수 있음
아키텍처 모듈성
- 복잡도와 세분도의 함정에 허우적거리지 않고도 모듈성을 괜찮은 수준으로 달성할 수 있음
- 서비스를 더 잘게 나눌수록 [[오케스트레이션]] 및 [[코레오그래피]] 관련 이슈가 발생함. 여러 서비스를 조율해서 비즈니스 트랜잭션을 완성하려면 이 둘 다 필요함
- 그러나 서비스 기반 아키텍처의 서비스는 더 큰 단위로 나뉘어지는 편이라서 다른 분산 아키텍처 만큼 정교한 조율이 필요하지 않음

[월간회고] 2024년 8월, 삶의 질(식단과 수면)

iia_hannah — Thu, 12 Sep 2024 08:02:22 +0900

지난 달 되돌아보기

지난 달 액션

1. 실수를 통해 배우자! 체크리스트 만들기!
여러 개 모아봤음 ㅎㅎ 조만간 팀원들에게 공유하면서 더 취합해봐야겠다!

2. 잠들기 전 일기로 하루에 있었던 일을 적자
하루 마무리를 통해 기억력을 높이고 잠들기 전 잡생각을 떨쳐내기 위함이었는데, 수면 측면에서는 효과적이지는 않았다. 한 달 중 10일 정도 일기 쓴 것 같은데, 하루를 되짚어보는 건 여러모로 좋은 것 같아서 루틴 유지하려고 한다.
근데 야근이나 약속이 있으면 저녁 루틴을 잘 안하게 되서, 저녁 루틴은 optional 성격이 있는 것들만 넣어놔야겠다.

3. 주말 활용하기 - 주말 아침도 평일과 동일한 루틴을 하되, 블로그 포스팅이나 이력서 갱신 같은 Task를 하는 날로 활용하자!
쉽지 않다. 결국 주말을 야무지게 활용한 날은 적어서 아쉽다.
나태하게 아무 생각 없이 집에만 있는 게 좋기도 하고, 주말에 약속이 있으면 미루다 잘 안하게 되는 것 같아.
되도록 주말도 아침 루틴을 챙겨서, 기술 블로그나 이력서 갱신처럼 계속 미뤄지거나 까먹는 일을 하도록 하면 좋겠는데...
뭔가 평일처럼 출근같은 강제성이 없으니까 어떻게 해야할지 모르겠군!
주말루틴은 다시 생각해보도록하자!

4. 업무 중 답답하더라도 스트레스와 동요를 드러내고 표현하지 말자
딱히 스트레스 받는 일이 없었어서 회고가 어렵다. 범위를 사람으로 넓혀야겠다.

5. 새로운 팀원들과 친해져보자!
새로운 사람들과 다양한 대화를 해보자!
ㅎㅎ팀원분들의 좋은 점을 조금씩 발견하고 있어서 친밀감이 많이 생겼음! 하지만 서로를 알아가기에는 대화 시간이 부족하긴 해서 종종 티타임을 제안하면 좋을 것 같다.

이번 달

주요 이벤트

수면 습관
요즘도 잡생각이 많아서 졸리고 피곤한데도 잠에 바로 들지 못해서 힘들었는데, 최근에 적당히 재미없는 책 30분 정도 읽으니까 잡념도 사라지고 잠에도 금방 들 수 있었다. 저녁 루틴에 책 읽기 넣어봐야겠음!

건강한 식사
요즘 그릭요거트 만들어 먹는 거에 푹 빠져서 5번째 만들어 먹는 중
유투브에도 저속노화나 거꾸로식단 관련된 추천이 많이 뜬다.
요즘 아침에는 그릭요거트, 블루베리, MCT 오일, 올리브오일 섞어서 먹는 중!

광고 관련 업무
경험해보지 못한 도메인이라서 재미있고, 드디어 돈 버는 업무를 하게 되서 기대가 많이 된다.
대규모 이벤트 전에 개발되어야해서 제 시간 내에 개발하는 것이 중요하다.
커머스의 꽃 결제, 포인트 관련 코어 로직을 새로 개발하게 되서 챌린지되고 좋다.
낯선 도메인이다보니 업무 불확실성을 빠르고 명확하게 하는 게 중요한데, 다행히 팀에서 서포트를 많이 해주셔서 도움이 많이 된다.
요즘 일하는거 너무 재밌음 ㅎㅎ

한 달 모아보기

반복되는 생각/다짐/할 일

수면 습관, 잠에 빨리 들지 못함, 잡생각이 많음
운동 -> 필테 예약 성공하지 못하면 주 1회만 운동하게 되는 경우가 있음. 보충할 방법 필요
주말 루틴 -> ㅋㅎ... 활용하지 못해서 아쉬움
건강한 식단
업무 관련 이야기

회고

다음 달 액션

저녁 루틴에 책읽기 넣기 (소설류는 흥미진진하니까 제외하고, 경제나 자기계발 혹은 상식 관련된 책을 읽는 게 좋겠음)
주 3회 운동하기 (필테 수업 못듣는 때면 홈트와 클라이밍을 다녀오자!)
체크리스트 만들기 세분화 - PR 체크리스트 만들기

다음달 목표 정하기

수면을 위한 저녁 루틴 가꾸기
운동 주 3회
실수를 통해 배우자! PR 체크리스트 만들기

[소프트웨어 아키텍처 101] 12. 마이크로커널 아키텍처 스타일

iia_hannah — Sat, 7 Sep 2024 13:01:58 +0900

인상깊은 부분

보험 청구처럼 비즈니스 케이스가 복잡한 경우에도 사용이 용이하겠다

요약

마이크로커널 아키텍처(microkernel architecture) 혹은 플러그인 아키텍처(plug-in architechture)
- 제품 기반 어플리케이션(단일 모놀리식 배포 단위로 패키징해서 다운로드 및 설치가 가능하며, 보통 고객 사이트에서 서드파티 제품으로 설치되는)에 적합
- 비제품(nonproduct) 고객 비즈니스 어플리케이션에서도 많이 사용
- 예시) IDE와 같은 텍스트 에디터
- 예시) Payment Processing이 코어 시스템을 나타내는 도메인이라면, 결제 수단(신용카드, 페이팔, 선불 카드 등)이 플러그인 컴포넌트

12.1 토폴로지

마이크로커널 아키텍처 스타일은 코어 시스템과 플러그인 컴포넌트라는 두 가지 아키텍처 요소로 구성된 모놀리식 아키텍처

코어 시스템
- 시스템을 실행시키는 데 필요한 최소한의 기능으로 정의
- 규모와 복잡도에 따라 레이어드 아키텍처나 모듈러 모놀리스로 구현 가능하며, 전체 모놀리스 어플리케이션은 하나의 데이터베이스를 공유하는 것이 보통임
- 순환 복잡도를 없애고 별도의 플러그인 컴포넌트를 통해 확장성, 유지보수성, 시험성을 가질 수 있음
플러그인 컴포넌트
- 플러그인 컴포넌트란?
  - 특수한 처리, 부가 기능, 그리고 코어 시스템을 개선/확장하기 위한 커스텀 코드가 구현된 스탠드얼론 컴포넌트
  - 변동성이 매우 큰 코드를 분리하여 어플리케이션 내부의 유지보수성, 시험성을 높임.클라이언트에 종속된 코드를 각 전자 제품마다 플러그인 컴포넌트를 따로 제작 (코어에 두면 순환복잡도가 높아지기 때문)
  - 이상적인 플러그인 컴포넌트는 상호독립적이며 의존성이 없음
- 통신 방식 (점대점 통신 or 원격 액세스)
  - 플러그인 컴포넌트와 코어 시스템은 일반적으로 점대점(point-to-point) 통신
  - 하지만 REST나 메시징 등 다른 방법으로 기능 호출하는 방법도 있음. 플러그인 컴포넌트를 개별 서비스로 구현해서 원격 액세스하는 방법은 전체 컴포넌트의 커플링이 낮아져 성과 처리량이 개선되고, 런타임 변경이 가능하다는 장점이 있음. 비동기 통신도 가능하므로 경우에 따라 전체 유저 반응성을 엄청나게 끌어올릴 수 있음
  - 하지만 위와 같은 원격 통신은 전체 확장성을 개선하는 좋은 방법 같지만, 이 토폴로지는 코어 시스템이 모놀리식이므로 여전히 단일 아키텍처 퀀텀임. 즉, 모든 요청이 무조건 코어 시스템을 거쳐 각 플러그인 서비스로 호출하는 구조
  - 개별 서비스로 구현 시 마이크로커널 아키텍처를 모놀리식이 아닌 분산 아키텍처로 바꿔야함
    - 이 경우, 대부분의 서드파티 온프렘 제품은 그렇게 구현/배포하기가 쉽지 않고 전반적으로 복잡도와 비용이 높아져 전체 배포 포톨리지가 상당히 난해해짐
    - 플러그인이 무응답이거나 작동하지 않는 경우 (특히 REST 사용 시) 요청은 완료될 수 없음 (모놀리식이었다면 이런 일은 없을 것)

12.2 레지스트리

플러그인 레지스트리 : 코어시스템이 어떤 플러그인을 사용할 수 있는지, 그 플러그인을 가져오려면 어떻게 해야하는 지 알기 위해 사용하는 일반적인 구현 방법 중 하나
플러그인 레지스트리에 담긴 정보
- 플러그인 명칭
- 데이터 계약
- 플러그인에서 코어 시스템으로 접속하는 방법과 원격 액세스 프로토콜 정보

12.3 계약

코어 시스템과 플러그인 컴포넌트 간의 계약
- 보통 플러그인 컴포넌트의 도메인 단위로 표준화되어 있고, 플러그인 컴포넌트가 수행하는 기능 및 입출력 데이터가 계약에 명시되어 있음
- 일반적으로 컹 시스템이 각 플러그인별 코드를 필요로 하지 않도록 플러그인 계약과 우리가 저한 표준 계약 간의 어댑터를 만듬

12.4 실제 용례

이클립스 IDE, 인터넷 웹 브라우저
대규모 비즈니스 어플리케이션에도 적용 가능
- ex) 보험금 청구 처리 어플리케이션
  - 대부분 아주 크고 복잡한 규칙 엔진을 이용해서 복잡한 로직을 처리하지만, 자칫 이 규칙 엔진이 진흙잡탕이 되어 규칙 하나를 변경하면 다른 규칙들이 연쇄적으로 영향을 받거나, 단순한 규칙 하나를 바꾸려해도 여러 직군이 모여 검토하는 과정을 거쳐야함
  - 이런 경우 마이크로커널 아키텍처 패턴을 활용할 수 있음
  - 관할 구역별 보험금 청구 규칙을 별도의 스탠드얼론 플러그인 컴포넌트에 보관하는 것임. 그러면 다른 시스템 파트에 영향을 주지 않고 특정 관할 구역의 규칙을 추가, 삭제, 변경할 수 있음. 그리고 관할 구역을 새로 추가하거나 기존 관할 구혁을 삭제해도 다른 시스템 파트에는 영향이 없음. 코어 시스템은 바뀔 일이 거의 없는, 청구건을 접수 받아 처리하는 표준 프로세스가 될 것임

12.5 아키텍처 특성 등급

마이크로커널 아키텍처도 레이어드 아키텍처처럼 단순성과 전체 비용이 주요 강점임. 반면, 고질적인 모놀리식 배포 탓에 탄력성, 내고장성, 확장성이 문제가 될 때가 많음. 퀀텀 수는 언제나 1. 레이어드 아키텍처 스타일과의 유사성은 여기까지
위치나 클라이언트에 따라 설정이 달라지는 문제는 이 아키텍처가 제격
커스터마이징, 기능 신장성에 중점을 둔 제품도 이 아키텍처가 제격

아키텍처 특성	별점	설명
분할 유형	도메인 및 기술	도메인 분할과 기술 분할이 모두 가능한 유일한 아키텍처 스타일
퀀텀 수	1	모든 요청은 코어시스템을 통해 유입되어 독립적인 플러그인 컴포넌트로 흘러가므로 퀀텀은 언제나 1
배포성	⭐️⭐️⭐️	기능을 독립적인 플러그인 컴포넌트로 분리 가능하므로 평균(별3)보다 약간 높게 매김. 잘 분할하면 변경분에 대한 테스트 범위와 배포 리스크가 줄어듬
탄력성	⭐️	모놀리식 배포탓에 탄력성 낮음
진화성	⭐️⭐️⭐️	-
내고장성	⭐️	모놀리식 배포탓에 내고장성 낮음
모듈성	⭐️⭐️⭐️	플러그인 컴포넌트를 통해 기능을 추가, 삭제, 변경할 수 있고, 덕분에 어플리케이션 개선/확장 작업이 비교적 용이해 팀 차원에서 더욱 신속하게 변경에 대응할 수 있다는 점 때문에 평균(별3)보다 조금 높게 측정
전체 비용	⭐️⭐️⭐️⭐️⭐️	굿굿!! 주요 강점
성능	⭐️⭐️⭐️	애매하지만 평균(별3)보다 약간 높게 측정 이 아키텍처는 대부분 규모가 작으며, 레이어드 아키텍처처럼 갈수록 커지지 않기 때문임. 또 아키텍처 싱크홀 안티패턴으로 고생할 필요도 없고 불필요한 기능은 해제하여 처리 흐름을 간소화할 수 있음
신뢰성	⭐️⭐️⭐️	기능을 독립적인 플러그인 컴포넌트로 분리 가능하므로 평균(별3)보다 약간 높게 매김. 잘 분할하면 변경분에 대한 테스트 범위와 배포 리스크가 줄어듬
확장성	⭐️	모놀리식 배포탓에 확장성 낮음
단순성	⭐️⭐️⭐️⭐️	굿굿!! 주요 강점
시험성	⭐️⭐️⭐️	기능을 독립적인 플러그인 컴포넌트로 분리 가능하므로 평균(별3)보다 약간 높게 매김. 잘 분할하면 변경분에 대한 테스트 범위와 배포 리스크가 줄어듬

[소프트웨어 아키텍처 101] 11. TODO

iia_hannah — Sat, 31 Aug 2024 12:59:08 +0900

[소프트웨어 아키텍처 101] 9. 아키텍처 스타일 기초

iia_hannah — Sat, 10 Aug 2024 13:29:54 +0900

인상깊은 부분/내 생각

실무에서 순수하게 모놀리식을 쓰는 경우가 많을까?

s3, serverless, firebase 등을 활용하는 순간 내 시스템 배포는 모놀리식 이어도 전체적인 모습은 분산 아키텍처를 사용하게 되는 거 아닐까?
이 경우 분산아키텍처에서 고려해야하는 요소들을 제3자(네트워크를 이용하는) 연동 파트에서도 고려해야한다.
비중의 문제인걸까? 완전한 모놀리식은 보기 어려운 것 같다.
으음! 아키텍처 차원에서는 모놀리식이라고 보는게 맞으려나? 내가 컨트롤할 수 있는 영역을 어떻게 바라보고 다루느냐도 중요하니까..

분산 아키텍처에서의 트랜잭션

최종일관성을 기반으로 트랜잭셔널 사가와 BASE 기법을 사용한다.
확장성, 성능, 가용성을 얻는 대가로 데이터 일관성과 무결성을 희생하는 트레이드오프인 셈이다

요약

아키텍처 스타일은 아키텍처 패턴이라도 부르며, 다양한 아키텍처 특성을 다루는 컴포넌트의 명명된 관계를 기술함9.1 기초 패턴 (기본적인 패턴)
소프트웨어 아키텍처의 역사를 통틀어 끊임없이 나타나고 있는 패턴들
9.1.1 진흙잡탕
- 뭐 하나 뚜렷한 아키텍처 구조가 전무한 상태
9.1.2 유니터리 아키텍처
9.1.3 클라이언트/서버
- 프론트엔드와 백엔드로 기술적으로 기능을 분리한 2티어 또는 클라이언트/서버 아키텍처
- 데스트콥 + 데이터베이스 서버
  - 표준 네트워크 프로토콜을 통해 접속가능한 스탠드얼론 데이터베이스 서버와 궁합이 좋음
  - 프레젠테이션 로직은 데스트콥에 두고 계산량이 많은 액션은 사양이 탄탄한 데이터베이스 서버에서 실행
- 브라우저 + 웹서버
- 3티어
  - 1990년대 후반 인기를 끈 3티어 아키텍처
  - 고성능 데이터베이스 서버를 사용하는 데이터베이스 티어, 애플리케이션 서버가 관리하는 어플리케이션 티어, 그리고 처음에는 HTML로 시작하여 기능이 점점 많아진 프론트엔드 티어
  - 3티어 아키텍처는 분산 아키텍처에 적합한 공통 객체 요청 브로커 아키텍처(Common Object Request Broker Architecture), 분산 컴포넌트 객체 모델(Distributed Component Object Model)과 같은 네트워크 수준의 프로토콜과 잘 맞음9.2 모놀리식 대 분산 아키텍처
아키텍처 스타일의 두가지 종류
- 모놀리식 : 크게 전체 코드를 단일 단위로 배포하는 모놀리식
  - 레이어드 아키텍처 (10장)
  - 파이프라인 아키텍처 (11장)
  - 마이크로커널 아키텍처 (12장)
- 분산형 : 원격 액세스 프로토콜을 통해 여러 단위로 배포하는 분산형. 모놀리식 아키텍처 스타일에 비해 성능, 확장성, 가용성 측면에서 훨씬 강력하지만 무시할 수 없는 트레이드오프가 존재함
  - 서비스 기반 아키텍처(13장)
  - 이벤트 기반 아키텍처 (14장)
  - 공간 기반 아키텍처 (15장)
  - 서비스 지향 아키텍처 (16장)
  - 마이크로서비스 아키텍처 (17장)
분산 컴퓨팅의 오류
- 9.2.1 분산 컴퓨팅의 오류 #1 : 네트워크는 믿을 수 있다
  - 네트워크 신뢰도는 점점 좋아지고 있지만 아직도 못미덥다
  - 그래서 타임아웃 장치나 서비스 사이에 [[서킷 브레이커(circuit breaker)]]를 마련하는 것
  - MSA처럼 네트워크에 의존할 수록 시스템의 신뢰도는 잠재적으로 떨어질 가능성이 있음
- 9.2.2 분산 컴퓨팅의 오류 #2 : 레이턴시는 0이다
  - 아키텍트는 어떤 분산 아키텍처를 구축하든지 간에 평균 레이턴시를 반드시 알아야한다
  - 특히 MSA(17장)은 서비스가 잘게 나뉘기 때문에 서비스 간 통신량도 만만치 않음
  - 평균 레이턴시도 중요하지만 95~99번째 백분위수를 이해하는 것은 더 중요함
  - 평균 레이턴시가 60밀리초에 불과해도 95번째 백분위수는 400밀리초일 수 있음. 보통 이런 긴 꼬리 레이턴시가 분산 아키텍처의 성능을 저해하는 주범이 됨
- 9.2.3 분산 컴퓨팅의 오류 #3 : 대역폭은 무한하다
  - MSA에서 시스템이 자잘한 배포 단위(서비스)로 쪼개지면 이 서비스들 간에 주고받는 통신이 대역폭을 상당히 점유하여 네트워크가 느려지고, 결국 레이턴시(오류#2)와 신뢰성(오류#1)에도 영향을 미친다
  - [[스탬프 커플링(stamp coupling)]] : 스탬프 커플링은 분산 아키텍처에서 상당히 많은 대역폭을 차지한다. 분산 아키텍처 서비스 또는 시스템 간에 최소한의 데이터만 주고받도록 하는 것이 최선의 해결 방법이다.
- 9.2.4 분산 컴퓨팅의 오류 #4 : 네트워크는 안전하다
  - 가상사설망(VPN), 실뢰할 수 있는 네트워크, 방화벽 이외의 나머지 네트워크는 안전하지 않다.
  - 알려지지 않은, 또는 악의적인 요청이 해당 서비스로 유입되지 않게 철저한 보안 대책을 강구해야 한다
  - 모든 엔드포인트에, 서비스 간 통신에도 보안이 적용돼야 하므로 MSA나 서비스 기반 아키텍처처럼 고도로 분산된 동기 아키텍처에서 당연히 성능이 떨어질 수 밖에 없다
- 9.2.5 분산 컴퓨팅의 오류 #5 : 토폴로지는 절대 안 바뀐다
  - 네트워크를 구성하는 모든 라우터, 허브, 스위치, 방화벽, 네트워크, 어플라이언스 등 전체 네트워크 토폴리지가 불변할 것이라는 가정은 섣부른 오해이다
  - 아키텍트는 운영자, 네트워크 관리자와 항시 소통하며 무엇이, 언제 변경되는지 알고 있어야한다.
- 9.2.6 분산 컴퓨팅의 오류 #6 : 관리자는 한 사람뿐이다
  - 대기업의 경우 네트워크 관리자만 해도 보통 수십 명에 이른다. 레이턴시나 토폴로지 변경 문제는 누구와 상의해야할까?
  - 그래서 분산 아키텍처는 복잡할 수 밖에 없고 모든 것을 정상 궤도에 올려놓으려면 상당히 많은 조율 과정이 필요하다
  - 반면, 보놀리식은 단일 단위로 배포하기 때문에 이 정도의 소통과 협력까지는 필요하지 않다.
- 9.2.7 분산 컴퓨팅의 오류 #7 : 네트워크 운송비는 0이다
  - 여기에서 운송비란, 단순 레이턴시가 아니라 'REST 호출'하는 데 소요되는 진짜 비용을 의미함
  - 분산 아키텍처는 하드웨어, 서버, 게이트웨이, 방화벽, 신규 서브넷, 프록시 등 리소스가 더 많이 동원되므로 모놀리식 아키텍처보다 비용이 훨씬 더 든다.
- 9.2.8 분산 컴퓨팅의 오류 #8 : 네트워크는 균일하다
  - 온갖 종류의 하드웨어가 서로 다 잘 맞물려 동작하는 것은 아니다
  - 모든 상황과 부하, 환경에서 100% 완벽하게 테스트를 마친 것은 아니므로 실제로 간혹 네트워크 패킷이 유실되는 사고도 심심찮게 일어난다
9.2.9 다른 분산 아키텍처 고려 사항 : 분산 아키텍처를 설계할 때 맞딱드리게 될 이슈 및 해결해야할 난제들
- 분산 로깅 : 분산 아키텍처는 로그 종류만 해도 수백 가지에 달하고 위치도 제각각, 포맷도 제각각이라서 문제를 집어내기가 참 어렵다
- 분산 트랜잭션
  - 모놀리식 아키텍처에서는 퍼시스턴스 프레임워크가 대신 실행하는 표준 커밋/롤백 기능인 ACID 트랜잭션을 걸어 데이터 일관성과 무결성을 강제한다.
  - 하지만 분산 아키텍처는 사정이 다르다.
  - 분산 아키텍처는 최종 일관성(eventual consistency) 이라는 개념을 바탕으로 별도로 분리된 배포 단위에서 처리된 데이터를 미리 알 수 없는 어느 시점에 모두 일관된 상태로 동기화한다. 확장성, 성능, 가용성을 얻는 대가로 데이터 일관성과 무결성을 희생하는 트레이드오프인 셈이다
  - 분산 트랜잭션을 관리하는 방법으로 트랜잭셔널 사가(transactional saga), BASE 분산 트랜잭션이 있음
- 계약 관리 및 버저닝
  - 계약은 클라이언트와 서비스 모두 합의한 행위와 데이터이다
  - 분리된 서비스와 시스템을 제각기 다른 팀과 부서가 소유하기 때문에 계약 유지보수가 특히 어렵다
  - 버전 구식화(deprecation)에 필요한 통신 모델은 더 더욱 복잡하다.

[월간회고] 2024년 7월, 아침 루틴 가꾸기 성공

iia_hannah — Sat, 3 Aug 2024 21:32:24 +0900

지난 달 되돌아보기

지난 달 액션

1. 리듬감 있는 일상 만들기
일찍자고 일찍 일어나려고 노력중이다!
최대한 규칙적인 생활을 할 수 있도록 재택하는 날짜도 고정하려고 한다.
그리고 8시 기준으로 재택 시에는 바로 출근을 하거나, 사무실 출근하는 날이면 출근 준비를 하는 것으로 기준 삼았다.
수면 패턴이 정리되서 좀 더 일찍 일어나게 되면 아침 시간을 더 늘릴 수 있을 것 같다!

2. 변수에 영향받지 않는 여유시간 확보하기
아침 시간 1시간 30분 확보!
요즘 일찍 자고, 알림 2번 이내로 정신이 바로 깬다. 일찍 잠든 날에는 몸도 개운에서 더 잘 일어나게 된다.
종종 잠을 설친 날은 뭔가 피로하고 의욕이 없어서 루틴을 스킵하게 되지만, 잘 자고 일어난 날은 아침 시간이 여유롭다.
아침에는 루티너리 앱으로 이런 루틴을 실행하고 있다.

루티너리 앱

3. 할일 관리 도구 사용
틱틱이랑 구글 캘린더 조합으로 할 일과 일정을 관리하고 있다.
캘린더에 넣기에 애매했던 일들(ex: 장보기, 오리고기 언제까지 먹기 등)을 가볍게 관리하기 좋다.
까먹지 않게 잔잔한 일들을 챙길 수 있고 머릿속이 복잡하지 않아서 좋다.
Task를 생성할 때 데드라인과 중요도도 지정할 수 있어서 우선순위 관리할 수도 있음 :)
위젯도 다양해서 핸드폰 바탕화면에 띄워놓으면 자주 일감 확인이 가능하고, 오늘 할 일만 따로 볼 수도 있다.

틱틱 앱 - 할일 관리와 위젯 활용

틱틱으로 관리하면 추적이나 집계가 용이해서, 습관 만들기랑 위클리 TODO, 먼슬리 TODO 일감을 관리하고 있다.
유료 버전을 활용하게 되면 더 많은 기능이 있다고 하는데, 일단은 무료 버전으로도 충분히 잘 활용하고 있다.
아마 더 잘 활용하고 싶어질 때 쯤 유료 버전을 고민해볼 것 같다.

4. one thing! 한 달에 목표 하나!
한번에 너무 많은 걸 해내고 싶은 욕심으로 이것저것 시작했다가, 머리만 복잡해지고 결국 해내는게 거의 없었다.
7월부터는 제일 중요한 목표 하나를 나에게 와닿는 문구로 만들어서 다이어리 먼슬리에 작성하고 있다.
7월의 문구는 "리듬감 있는 일상 만들기" 였다.
정말 한 달에 목표 하나만 세우지는 않았다. 왜냐면 내가 가용한 시간 유형이 아침과, 출퇴근, 평일 저녁, 주말인데!
아침용 목표와 평일 저녁용 목표 이렇게 구분해서 세우니까 적절한 것 같다!
내가 가용할 수 있는 시간과 그 때 이룰 수 있는 목표 세우기!

이번 달

주요 이벤트

루틴 재정비
상반기 회고를 통해 루틴을 재정비했는데 효과가 좋다 :)
나한테 잘 워킹하고 있고, 잡생각이나 혼란스러운 마음도 정리되고 목표도 깨끗하게 정리되서 좋다.

내 생일
생일과 관련된 여러 이벤트들이 있었다

맥북 구매
고민하다가 M3 맥북프로 램 18GB 로 구매했다!
이제 무겁게 16인치 회사 맥북을 들고 다니지 않아도 된다!

블로그 체험단 첫 체험
네이버 블로그를 시작한지 한 달 정도 되었는데, 처음으로 식사권 지원받아서 남편이랑 외식했다 :)
한 달에 1-2번 정도 이렇게 외식 데이트하면 좋을 것 같다!

자동차 주차 접촉 사고
ㅎㅎ후.. 열받지만 내 잘못이지..

한 달 모아보기

반복되는 생각/다짐/할 일

루틴
아침 루틴은 잘 정착했는데, 평일 저녁과 주말 루틴이 아직 정착이 되지 않았다.
일단 짧은 시간에 아침 루틴이 잘 정착했고, 이게 큰 힘이 되어줘서 좋다!
저녁과 주말도 잘 활용하게 되면 뿌듯할 것 같다

스터디- 책 소프트웨어 아키텍처 101

기술 블로그 포스팅
한동안 기술 블로그를 멈춰왔기 때문에 루틴에 넣어야 할 것 같다.
계속 꾸준히 포스팅하지 못해서 아쉬움이 있어서 모닝페이지에 자주 언급했다

수면 패턴
일찍 자고 일찍 일어날 땐 기쁘다.
그런데 어떨 땐 잡생각으로 머리가 꽉 차서 거의 밤을 셀 정도로 잠을 못잔다.
그런 날에는 아침 루틴을 할 의욕도 없어서 그냥 패스해버리게 된다.

이력서 갱신
해야지, 해야지 하면서 아직까지도 안하고 있는 것ㅋㅋㅋ

운동
에너지량을 기르기 위해서라도 운동을 시작해야할 필요를 느꼈음
필라테스 결제해서 8월부터는 운동 배우기 시작!

맥북
드디어 샀다. 어찌나 많이 언급했던지 ㅋ

인간 관계와 자아성찰

회고

잠들기 전 일기로 하루에 있었던 일을 적자 => 하루 마무리를 통해 기억력을 높이고, 잠들기 전 잡생각을 떨쳐내기 위함
주말 아침도 평일과 동일한 루틴을 하되, 블로그 포스팅이나 이력서 갱신 같은 Task를 하는 날로 활용하자 => 기술 블로그나 이력서 갱신처럼 계속 미뤄지거나 까먹는 일을 주말에 하기
업무 중 답답하더라도 스트레스와 동요를 드러내고 표현하지 말자
새로운 팀원들과 친해져보자! 새로운 사람들과 다양한 대화를 해보자!

다음 달 액션

이번 달은 회고와 다음달 액션이 섞여있다 :)
위 회고 내용으로 대체!

다음달 목표 정하기

실수를 통해 배우자! 체크리스트 만들기!

Hello, Hannah!

2025.12.10 사내 발표 - 들쭉날쭉한 AI 품질, 팀 SSOT 문서로 해결하기

개발팀의 고민: AI 품질 문제

AI의 구조적 한계

✅ 충분한 맥락을 제공한 경우

❌ 컨텍스트가 부족한 경우

개인이 아닌 팀 전체의 비용

AI와 일을 잘 하려면?

Step 1. 명세를 통한 정확한 구현 (SDD)

SDD 란?

프롬프트 엔지니어링은 SDD 도구가 책임진다

SDD 방법론을 적용한 API 구현 예시 (spec-kit 활용)

(1) 명세서 작성하기

(2) 구현하기

(3) Jira 티켓에 갱신

여전히 남아있는 컨텍스트 제공 문제

그렇다면 명세서를 컨텍스트로 재활용할 수 없을까?

핵심은 팀 SSOT 구축

Step 2. 팀 SSOT의 지속적 통합 (CI-SDD)

CI-SDD란?

선순환 구조의 지속적인 지식 통합

흐름 설명

문서 관리 예시

프로젝트 구조

CLAUDE.md

PR 리뷰 시, AI에게 팀 SSOT 문서 검토 요청

활용하기

맺음말: 프롬프트 + 팀 SSOT = 완벽한 협업

제안하는 액션

10배 빠른 분산 시스템 디버깅: Micrometer Tracing으로 Trace ID 통합하기

목차

1. 개요: 분산 추적의 필요성

배경

이런 경험 있으신가요?

이제는 이렇게 바뀌었습니다

2. Spring Micrometer Tracing 핵심 이해

2.1. Spring Micrometer Tracing 소개

2.2. Trace ID vs Span ID

Trace ID

Span ID

코드로 확인하기

2.3. 전체 아키텍처 개요

레이어 아키텍처

핵심 설계 원칙

2.4. Micrometer Tracing 핵심 이해

Micrometer Tracing이란?

Spring Cloud Sleuth → Micrometer Tracing 전환

핵심 장점

Trace ID 전파 (Propagation)

2.5. Brave vs OpenTelemetry: 구현체 선택

3. 주요 환경별 Trace ID 활용

3.1. Spring MVC (HTTP 요청)

자동 계측

실제 코드 예시

3.2. Kafka Consumer

자동 계측

실제 코드 예시

3.3. Spring Batch (수동 계측)

문제 상황

해결: JobTracingListener 구현

구현 코드

Step Listener도 추가

Job 설정에 Listener 등록

4. 로그 통합 및 실전 활용

4.1. Logback 설정

기본 Console 로그 패턴

JSON 로그 형식 (운영 환경 권장)

4.2. 로그 기반 트러블슈팅 워크플로우

시나리오: 에러 알림 수신

핵심 가치

5. 실무 활용 꿀팁

5.1. API 에러 응답에 Trace ID 포함

TraceIdProvider 구현

5.2. Slack 알림에 OpenSearch 바로 랜딩

6. 최종 구현 및 트러블슈팅

️ 전체 아키텍처

핵심 컴포넌트

1. Micrometer Tracing

2. TraceIdProvider

3. JobTracingListener (Batch)