docs(10_Wiki): 위키 전체 재구성 — Topic_* 폴더를 4개 카테고리로 통합 + 대규모 중복 제거
Topic_Agent/Topic_Blog/Topics/Topics_Biz/Topics_Meeting/Topics_Rag의 마크다운 지식 문서를 Topic_General/Topic_Programming/Topic_Graphic/Topic_Business 4개 카테고리로 재분류. - 중복 제거: frontmatter의 status:duplicate/merged + duplicate_of/redirect_to 필드로 자기 자신을 중복으로 선언한 리다이렉트 stub 1032개 제거, 완전 동일 내용 파일 472개 제거, 동일 파일명·다른 내용 충돌 시 더 큰(완전한) 버전만 유지(162개 제거) — 총 1639개 중복 제거. - 분류: 폴더 단위로 명확한 항목(AI_and_ML/Coding/Architecture 등 → Programming, Comfyui/Visual_Effects → Graphic, Topics_Biz/Topics_Meeting/사업 등 → Business, Poetic_Blog_Writing/창의성/Game_Design 등 → General)은 폴더 우선순위로, 나머지 혼재 폴더(Topic_Agent/Topic_Blog/Topics 루트/Thinking & Reasoning/Other/UI_UX_Assets)는 title/tags 키워드 스코어링으로 파일 단위 분류(불명확한 경우 General로 폴백). 원본 폴더명은 "From_*" 서브폴더로 보존해 추적 가능성 유지. - 최종 배치: Programming 2784 / General 1608 / Graphic 285 / Business 249 = 4926개 문서. - 에이전트 운영 상태(.astra/.agent/.obsidian/sessions/memory/_company/docs/lessons/_shared/src)는 지식 콘텐츠가 아니므로 재분류 대상에서 제외하고 원위치 유지. - Topics/Topic_email(상위 보호 폴더 Topic_email과 파일명 100% 중복) 삭제 — 보호 폴더 자체는 미변경. - 완전히 비게 된 Topic_Agent/Topic_Blog/Topics_Biz/Topics_Rag 폴더 제거.
This commit is contained in:
Antigravity Agent
@@ -0,0 +1,115 @@
|
||||
---
|
||||
id: observability-structured-logging
|
||||
title: Structured Logging — JSON 첫 줄부터
|
||||
category: Coding
|
||||
status: draft
|
||||
source_trust_level: B
|
||||
verification_status: conceptual
|
||||
created_at: 2026-05-09
|
||||
updated_at: 2026-05-09
|
||||
tags: [observability, logging, json, vibe-coding]
|
||||
tech_stack: { language: "TypeScript / pino / winston", applicable_to: ["Backend"] }
|
||||
applied_in: []
|
||||
aliases: [JSON logs, log fields, log levels, redaction]
|
||||
---
|
||||
|
||||
# Structured Logging
|
||||
|
||||
> `console.log("user " + id + " did " + action)` 은 grep 으로 찾기 어렵다. **JSON 형태 + 일관된 필드명 + 적절한 level + 민감정보 redact** 4가지 = 운영 가능한 로그.
|
||||
|
||||
## 📖 핵심 개념
|
||||
- 한 로그 = 한 JSON 객체 (한 줄).
|
||||
- 핵심 필드: `time`, `level`, `msg`, `requestId`, `userId`, `service`, `version`.
|
||||
- 동적 데이터는 메시지에 끼우지 말고 **필드로**.
|
||||
- 민감정보 자동 redact (token, password, card).
|
||||
|
||||
## 💻 코드 패턴
|
||||
|
||||
### pino (Node, fast)
|
||||
```ts
|
||||
import pino from 'pino';
|
||||
|
||||
export const logger = pino({
|
||||
level: process.env.LOG_LEVEL || 'info',
|
||||
redact: {
|
||||
paths: ['req.headers.authorization', 'req.headers.cookie', '*.password', '*.token', '*.creditCard'],
|
||||
censor: '[REDACTED]',
|
||||
},
|
||||
base: {
|
||||
service: 'user-service',
|
||||
version: process.env.GIT_SHA,
|
||||
env: process.env.NODE_ENV,
|
||||
},
|
||||
timestamp: pino.stdTimeFunctions.isoTime,
|
||||
});
|
||||
|
||||
// 사용
|
||||
logger.info({ userId, action: 'login', ms: 42 }, 'user logged in');
|
||||
// → {"time":"2026-05-09T...","level":"info","userId":"1","action":"login","ms":42,"msg":"user logged in", ...}
|
||||
```
|
||||
|
||||
### Request-scoped child logger
|
||||
```ts
|
||||
import { AsyncLocalStorage } from 'node:async_hooks';
|
||||
|
||||
const als = new AsyncLocalStorage<{ requestId: string; userId?: string }>();
|
||||
|
||||
app.use((req, res, next) => {
|
||||
const requestId = req.header('x-request-id') ?? crypto.randomUUID();
|
||||
als.run({ requestId }, () => next());
|
||||
});
|
||||
|
||||
export function log() {
|
||||
const ctx = als.getStore() ?? {};
|
||||
return logger.child(ctx);
|
||||
}
|
||||
|
||||
// 어디서나
|
||||
log().info({ orderId }, 'created order');
|
||||
// → 자동으로 requestId 포함
|
||||
```
|
||||
|
||||
### Level 가이드
|
||||
- `fatal`: 프로세스 종료급.
|
||||
- `error`: 처리 가능하지만 비정상.
|
||||
- `warn`: 문제 신호 (재시도 발생, fallback 사용).
|
||||
- `info`: 정상 핵심 이벤트 (사용자 가입, 결제 완료).
|
||||
- `debug`: 흐름 추적. 운영에서는 끔.
|
||||
- `trace`: 매우 상세. 로컬만.
|
||||
|
||||
### 메시지 vs 필드
|
||||
```ts
|
||||
// ❌ 동적 값을 메시지에
|
||||
logger.info(`User ${userId} purchased ${productId} for ${amount}`);
|
||||
|
||||
// ✅ 필드로
|
||||
logger.info({ userId, productId, amount }, 'purchase completed');
|
||||
// 검색: amount > 100 같은 쿼리 가능
|
||||
```
|
||||
|
||||
## 🤔 의사결정 기준
|
||||
| 데이터 | 어디 |
|
||||
|---|---|
|
||||
| 식별자 (userId, orderId) | 항상 필드 |
|
||||
| 타이밍 (ms, duration) | 필드 |
|
||||
| 에러 객체 | `{ err }` (pino 자동 stack 추출) |
|
||||
| 요청 / 응답 본문 | 필드 + redact 정책 |
|
||||
| PII | 절대 X — 별도 audit log |
|
||||
|
||||
## ❌ 안티패턴
|
||||
- **stdout 에 plain text**: 파싱 불가. JSON 한 줄.
|
||||
- **stderr 와 stdout 혼용**: error 가 다른 stream 에. 한 곳으로 + level 필드.
|
||||
- **민감정보 raw**: token / password / 카드번호 / 주민번호. redact 정책 필수.
|
||||
- **메시지 안에 stack trace**: 한 줄 깨짐. 별도 err 필드.
|
||||
- **로그 너무 verbose (debug 가 prod)**: 비용 / 노이즈. 필요시 dynamic level.
|
||||
- **로그 너무 적음**: 사고 시 디버깅 불가. critical path 는 info.
|
||||
- **timestamp 가 local timezone**: 분산 시스템에서 헷갈림. ISO8601 UTC.
|
||||
- **한 줄에 여러 JSON 객체**: 파서 깨짐. 한 줄 = 한 JSON.
|
||||
|
||||
## 🤖 LLM 활용 힌트
|
||||
- "console.log 금지. logger 사용. 동적 값은 필드, 메시지는 정적" 강제.
|
||||
- AsyncLocalStorage 로 requestId 자동 주입.
|
||||
|
||||
## 🔗 관련 문서
|
||||
- [[Observability_Correlation_IDs]]
|
||||
- [[Observability_Error_Reporting]]
|
||||
Reference in New Issue
Block a user