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,181 @@
|
||||
---
|
||||
id: devops-observability-stack
|
||||
title: Observability — Logs / Metrics / Traces
|
||||
category: Coding
|
||||
status: draft
|
||||
source_trust_level: B
|
||||
verification_status: conceptual
|
||||
created_at: 2026-05-09
|
||||
updated_at: 2026-05-09
|
||||
tags: [devops, observability, prometheus, grafana, opentelemetry, vibe-coding]
|
||||
tech_stack: { language: "TS / Prometheus / Grafana / OTEL", applicable_to: ["DevOps", "Backend"] }
|
||||
applied_in: []
|
||||
aliases: [observability, OpenTelemetry, OTEL, Prometheus, Grafana, Loki, Tempo, distributed tracing]
|
||||
---
|
||||
|
||||
# Observability Stack
|
||||
|
||||
> 3가지: **Logs (무엇이 일어났나) + Metrics (얼마나) + Traces (어디서)**. **OpenTelemetry** 가 vendor-neutral 표준. Grafana stack (Prometheus + Loki + Tempo) 또는 Datadog / Honeycomb / SigNoz.
|
||||
|
||||
## 📖 핵심 개념
|
||||
- Logs: structured (JSON). Loki / Elastic / Datadog Logs.
|
||||
- Metrics: 시계열 숫자. Prometheus / Mimir / Datadog.
|
||||
- Traces: request 의 service 간 이동 + timing. Tempo / Jaeger / Honeycomb.
|
||||
- OTEL: 통합 SDK + collector. exporter 만 갈아끼움.
|
||||
|
||||
## 💻 코드 패턴
|
||||
|
||||
### Node + OTEL
|
||||
```ts
|
||||
// otel.ts (entry point 가장 위)
|
||||
import { NodeSDK } from '@opentelemetry/sdk-node';
|
||||
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
|
||||
import { OTLPMetricExporter } from '@opentelemetry/exporter-metrics-otlp-http';
|
||||
import { PeriodicExportingMetricReader } from '@opentelemetry/sdk-metrics';
|
||||
import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';
|
||||
|
||||
const sdk = new NodeSDK({
|
||||
serviceName: 'api',
|
||||
traceExporter: new OTLPTraceExporter({ url: process.env.OTEL_ENDPOINT }),
|
||||
metricReader: new PeriodicExportingMetricReader({
|
||||
exporter: new OTLPMetricExporter({ url: process.env.OTEL_ENDPOINT }),
|
||||
}),
|
||||
instrumentations: [getNodeAutoInstrumentations()],
|
||||
});
|
||||
|
||||
sdk.start();
|
||||
```
|
||||
|
||||
자동: HTTP / DB / Redis / fetch span 만들어줌.
|
||||
|
||||
### Manual span
|
||||
```ts
|
||||
import { trace, SpanStatusCode } from '@opentelemetry/api';
|
||||
|
||||
const tracer = trace.getTracer('app');
|
||||
|
||||
async function processOrder(id: string) {
|
||||
return tracer.startActiveSpan('processOrder', async (span) => {
|
||||
span.setAttributes({ 'order.id': id });
|
||||
try {
|
||||
const result = await doWork(id);
|
||||
span.setStatus({ code: SpanStatusCode.OK });
|
||||
return result;
|
||||
} catch (e) {
|
||||
span.recordException(e as Error);
|
||||
span.setStatus({ code: SpanStatusCode.ERROR });
|
||||
throw e;
|
||||
} finally {
|
||||
span.end();
|
||||
}
|
||||
});
|
||||
}
|
||||
```
|
||||
|
||||
### Metrics
|
||||
```ts
|
||||
import { metrics } from '@opentelemetry/api';
|
||||
|
||||
const meter = metrics.getMeter('app');
|
||||
const orderCount = meter.createCounter('orders_total');
|
||||
const orderLatency = meter.createHistogram('order_latency_ms');
|
||||
|
||||
orderCount.add(1, { region: 'us', plan: 'pro' });
|
||||
const t = Date.now();
|
||||
await doWork();
|
||||
orderLatency.record(Date.now() - t);
|
||||
```
|
||||
|
||||
### Structured logs (Pino)
|
||||
```ts
|
||||
import pino from 'pino';
|
||||
|
||||
const log = pino({
|
||||
level: 'info',
|
||||
formatters: {
|
||||
level(label) { return { level: label }; },
|
||||
},
|
||||
});
|
||||
|
||||
log.info({ userId, orderId }, 'order created');
|
||||
// {"level":"info","time":...,"userId":"u1","orderId":"o2","msg":"order created"}
|
||||
```
|
||||
|
||||
Logs ↔ Traces 연결: trace_id / span_id 자동 inject (OTEL).
|
||||
```ts
|
||||
import { context, trace } from '@opentelemetry/api';
|
||||
|
||||
const span = trace.getSpan(context.active());
|
||||
log.info({ traceId: span?.spanContext().traceId, ...attrs }, 'event');
|
||||
```
|
||||
|
||||
### Prometheus metrics (legacy)
|
||||
```ts
|
||||
import client from 'prom-client';
|
||||
|
||||
const counter = new client.Counter({ name: 'orders_total', help: 'orders' });
|
||||
|
||||
app.get('/metrics', async (req, res) => {
|
||||
res.set('Content-Type', client.register.contentType);
|
||||
res.end(await client.register.metrics());
|
||||
});
|
||||
```
|
||||
|
||||
### RED method — 모든 service 의 기본 metrics
|
||||
- **R**ate: 요청 / 초.
|
||||
- **E**rrors: 에러율.
|
||||
- **D**uration: latency p50/p95/p99.
|
||||
|
||||
```ts
|
||||
// 모든 endpoint 자동
|
||||
app.use(otelHttpMetricsMiddleware);
|
||||
// 결과: http_server_duration_milliseconds, http_server_active_requests
|
||||
```
|
||||
|
||||
### Trace + log 연결 (Grafana)
|
||||
```
|
||||
Grafana Loki → Tempo:
|
||||
log line 의 trace_id 클릭 → 해당 trace 의 span 보기
|
||||
```
|
||||
|
||||
### Alert (Prometheus)
|
||||
```yaml
|
||||
groups:
|
||||
- name: api
|
||||
rules:
|
||||
- alert: HighErrorRate
|
||||
expr: |
|
||||
sum(rate(http_server_request_count{status=~"5.."}[5m])) /
|
||||
sum(rate(http_server_request_count[5m])) > 0.05
|
||||
for: 5m
|
||||
labels: { severity: page }
|
||||
annotations: { summary: "API 5xx > 5%" }
|
||||
```
|
||||
|
||||
## 🤔 의사결정 기준
|
||||
| 단계 | 추천 |
|
||||
|---|---|
|
||||
| MVP | Sentry (errors) + 기본 logs |
|
||||
| Scale | OTEL + Grafana stack (Prom + Loki + Tempo) |
|
||||
| 복잡 분산 | Honeycomb (high-cardinality 우월) |
|
||||
| ZeroOps | Datadog / New Relic (비쌈) |
|
||||
| Self-hosted | SigNoz (OTEL native, 단일 도구) |
|
||||
| Open source | Grafana Cloud (free tier) |
|
||||
|
||||
## ❌ 안티패턴
|
||||
- **Logs 만**: high-cardinality query 비싸 / 느림.
|
||||
- **Metric label cardinality 폭발**: userId / requestId 절대 라벨 X.
|
||||
- **Trace 100% sampling prod**: 비용 폭발. Head-based 1% 또는 tail-based.
|
||||
- **Log 안 structured**: grep 만 됨, query 어려움.
|
||||
- **Trace_id 분산 안 됨**: cross-service 연결 안 됨. OTEL propagator 자동.
|
||||
- **Alert noise**: 5분 미만 burst → 너무 trigger. for: 5m+.
|
||||
- **Dashboard 없는 metric**: 데이터만 있고 안 봄.
|
||||
|
||||
## 🤖 LLM 활용 힌트
|
||||
- OTEL = vendor-neutral, 갈아끼움 가능.
|
||||
- RED 모든 service.
|
||||
- Logs JSON + trace_id link.
|
||||
|
||||
## 🔗 관련 문서
|
||||
- [[Native_Crash_Reporting]]
|
||||
- [[Backend_Webhook_Patterns]]
|
||||
Reference in New Issue
Block a user