Skip to content
BranchesTags

Repository files navigation

Observability Lab

Codex에서 시작해 개인 개발 환경의 logs, metrics, traces를 수집하고 실제 사용 개선 인사이트로 연결하는 로컬 관측성 실험실이다.

현재 범위

Codex native OpenTelemetry 경로와 실제 사용 개선을 위한 dashboard를 실행 데이터로 검증했다. Codex Observatory에서 30일 사용 분석인 Codex Usage와 24시간 수집·성능 진단인 Codex Operations로 들어간다. Operations의 수집기·event 진단 10개 panel은 필요할 때만 펼친다.

Codex native OTel exporter
  -> OTLP/HTTP
  -> OpenTelemetry Collector Contrib
     -> privacy processors
     -> Prometheus (metrics)
     -> Loki native OTLP (logs/events)
     -> sanitized rotating archive
  -> Collector internal telemetry -> Prometheus
  -> Grafana: Codex Observatory
     -> Codex Usage (30일 event 분석)
     -> Codex Operations (24시간 운영·성능)

Tempo는 확인된 trace가 운영 질문에 실질적인 답을 줄 때 도입한다. Claude와 Windows source는 실제 source를 추가하는 단계에서 분리한다.

빠른 시작

요구 사항:

  • WSL2 Ubuntu
  • Docker Desktop WSL integration
  • curl
  • jq
./scripts/validate.sh
./scripts/up.sh
./scripts/codex-otel-doctor.sh
./scripts/inventory.sh

Codex의 사용자 전역 [otel] 설정이 127.0.0.1:4318을 향한다면 Codex보다 먼저 ./scripts/up.sh를 실행한다. up.sh는 Collector와 dashboard 검증 후 활성 exporter와 실제 listener가 일치하는지도 확인한다.

대시보드는 로그인 없이 로컬 Viewer로 접속한다.

3000처럼 개발 프로젝트와 충돌하기 쉬운 포트는 사용하지 않는다. 18300도 겹치면 다음처럼 바꿀 수 있다.

OBSERVABILITY_GRAFANA_PORT=18437 ./scripts/up.sh

이 경우 접속 주소도 http://127.0.0.1:18437로 바뀐다. Prometheus와 Loki는 Docker 내부 network에서만 접근하며 host port를 공개하지 않는다. Collector의 OTLP와 health endpoint만 127.0.0.1:4317, 4318, 13133에 bind한다.

실제 Codex 데이터까지 확인하려면 Codex task를 한 번 실행한 뒤 다음을 사용한다.

./scripts/dashboard-smoke.sh --require-data
./scripts/usage-calendar-smoke.sh
./scripts/coverage-audit.sh

최근 7개 완료일을 이전 7일과 비교하고 다음 실험 한 가지를 고르는 report:

./scripts/weekly-insight.sh

실제 사용량이 포함된 생성물은 Git에서 제외된 reports/generated/에만 둔다.

자세한 사용법과 패널 해석은 docs/runbooks/dashboard.md에 있다. ChatGPT 제품 분석 화면과 local OTel의 재현 가능 범위, Claude Code 및 community 사례 비교는 docs/research/2026-08-09-codex-usage-analytics-gap.md에 있다. 사용 분석은 Loki event 30일, 운영 metric은 Prometheus 7일을 기준으로 하며 세부 데이터 상태와 시간 의미는 docs/adr/0001-codex-usage-data-contract.md에 있다. 공식 OpenAI telemetry catalog 대비 관측 범위와 재현 시나리오는 docs/runbooks/telemetry-coverage.md에 있다.

Codex 활성화

sources/codex/config.example.toml을 참고한다. log_user_prompt = false와 Collector privacy processor를 함께 사용한다. Codex 앱은 설정 변경 후 새 task 또는 앱 재시작부터 적용 여부를 확인한다.

고정 버전

  • OpenTelemetry Collector Contrib: 0.157.0
  • Prometheus: 3.13.2
  • Loki: 3.7.6
  • Grafana: 13.1.3

설정 또는 이미지 버전을 바꾸면 정적 검증, runtime smoke와 검증 기록을 함께 갱신한다.

데이터 경계

저장소에는 재현 가능한 구성, 스크립트, 비식별 fixture와 문서만 둔다. 실제 telemetry와 database는 Git에서 분리된 Docker named volume에 보관한다.

  • observability-lab-collector-data
  • observability-lab-prometheus-data
  • observability-lab-loki-data
  • observability-lab-grafana-data

sanitized archive도 개인 사용 패턴을 포함하므로 Git에 커밋하지 않는다. raw prompt, reasoning, tool argument/result, 계정 식별자, path와 URL content는 Collector에서 exporter보다 먼저 제거한다.

평소 Codex 사용이 끝났다고 stack을 내리지 않는다. 컨테이너의 restart: unless-stopped 정책이 Docker Desktop 재시작 후 수집을 복구하며 runtime volume도 유지한다.

./scripts/down.sh는 사용자 전역 Codex 설정이 여전히 로컬 Collector를 향하면 중단을 거부한다. 유지보수를 위해 의도적으로 내릴 때는 먼저 [otel]의 exporter, metrics_exporter, trace_exporter를 모두 "none"으로 바꾸고 Codex 앱과 CLI를 재시작한다. --force는 telemetry 유실과 연결 오류를 감수하는 예외다.

./scripts/down.sh

공개 저장소 경계

이 저장소는 재현 가능한 설정과 비식별 fixture만 공개한다. 실제 telemetry, prompt, reasoning, tool payload, 개인정보, secret, 생성 report와 runtime database는 커밋 대상이 아니다. GitHub Actions는 읽기 전용 권한으로 실행하며, 고정된 Gitleaks image로 도달 가능한 Git history를 검사한다.

기본 구성은 로컬 단일 사용자 환경을 전제로 한다. Grafana와 OTLP endpoint를 외부 network에 공개하려면 인증, TLS, 접근 제어와 별도 위협 모델이 필요하다. 취약점 신고 방법과 지원 범위는 SECURITY.md, 사용 조건은 LICENSE를 따른다.

문서

About

Local-first OpenTelemetry observability lab for coding agents and developer systems

Resources

Readme
MIT license

Security policy

Security policy
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Used by

Contributors

Languages