Communitygithub.com

lguidolin/observability-and-slos

로깅, 메트릭, 트레이싱, 상태 점검, SLO 또는 알림을 추가하거나 운영 및 디버깅 가능한 서비스 표면을 구축할 때 사용하세요. 키워드: 구조화된 로그, OpenTelemetry, 상관관계 ID, RED 메트릭, 활성 프로브, 준비 프로브, SLI, SLO, 에러 예산, 알림.

observability-and-slos란 무엇인가요?

이 스킬은 애플리케이션에 관측 가능성(observability)과 서비스 수준 목표(SLO)를 설계하는 방법을 제공합니다. 시스템이 '무엇이 변경되었고 누가 영향을 받았는지'에 답할 수 있도록 구조화된 로그, 메트릭, 트레이스를 포함한 세 가지 신호를 요구합니다. OpenTelemetry를 통해 상관관계 ID를 요청 전반에 전파하고, RED 메트릭(비율, 오류, 지속 시간)을 모든 엔드포인트와 GraphQL 연산에 계측합니다. 또한 Kubernetes 프로브에 연결된 활성/준비 프로브와 SLO 기반 번-레이트 알림을 지원합니다. 이 스킬은 Claude Code, Cursor, Codex와 같은 AI 에이전트 환경에서 사용 가능하며, 사전 출시 프로젝트는 구조화된 로그와 상태 점검만 구현하고 SLO/알림은 나중으로 미루는 단계적 접근을 권장합니다.

지원 대상~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/lguidolin/agent-skills/tree/main/skills/observability-and-slos
원본 보기→모든 스킬 둘러보기

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

OpenAIChatGPTClaudeClaudeGeminiGeminiGrokGrokPerplexityPerplexityDeepSeekDeepSeek

문서

관측 가능성과 SLO

개요

보이지 않는 것을 운영, 디버깅 또는 개선할 수 없습니다. 관측 가능성은 설계 단계에서 포함되어야 하며, 첫 번째 장애 발생 후에 덧붙이는 것이 아닙니다. 모든 인시던트에서 첫 번째 질문은 '무엇이 변경되었고 누가 영향을 받았는가'입니다. 이에 답할 수 없는 시스템은 5분이면 해결될 문제를 고고학적 발굴로 만듭니다.

원칙 (보편적)

  • 세 가지 신호. 구조화된 로그(기계가 파싱 가능한, 자유 텍스트 아님), 메트릭(개수, 비율, 지속 시간), 트레이스(서비스 전반의 요청 경로)를 출력하세요. 요청은 종단 간 상관관계/트레이스 ID를 전달합니다.
  • 모든 표면에 황금 신호 계측 (RED): 엔드포인트/연산당 비율, 오류, 지속 시간, 리소스 포화도 포함. 새 엔드포인트는 관측 가능해질 때까지 '완료'된 것이 아닙니다.
  • 상태는 추측이 아닌 엔드포인트입니다. 활성 프로브("실행 중인가?")와 준비 프로브("트래픽을 처리할 수 있는가?")를 별도의 점검으로 노출하세요.
  • 중요한 사용자 여정에 대해 SLO를 정의하고, 이를 측정하는 SLI와 신뢰성 대 기능을 명시적이고 데이터 기반으로 절충하는 에러 예산을 설정하세요.
  • 증상에 대해 알리고, 원인에 대해 알리지 마세요. 사용자가 피해를 입을 때(SLO 소진, 준비 프로브 실패) 페이징하고, 모든 내부적인 작은 문제에 대해서는 페이징하지 마세요. 모든 알림은 실행 가능해야 합니다. 아무도 실행하지 않는 알림은 사람들이 알림을 무시하도록 훈련시킵니다.

메커니즘 (이 스택)

  • 구조화된 JSON 로그를 stdout으로 출력, 플랫폼에서 수집 (예: AKS → Azure Monitor / Log Analytics). 서비스 내에서 자유 텍스트 로깅 금지.
  • 앱 서버와 PostGraphile에 OpenTelemetry 적용; 트레이스/메트릭을 Azure Monitor / Application Insights (또는 Prometheus/Grafana)로 내보냅니다.
  • 데이터 경로 전체에 상관관계 ID 전파 — 가장자리에서 생성되어 Browser → App → PostGraphile로 컨텍스트 헤더와 함께 전달되며, 모든 로그 라인과 스팬에 첨부됩니다.
  • 각 HTTP 라우트 및 GraphQL 연산에 대한 RED 메트릭; Postgres 느린 쿼리 로그 + pg_stat_statements.
  • 활성/준비 프로브 엔드포인트를 Kubernetes 프로브에 연결 (cloud-delivery-aks 참조). 준비 프로브는 실제 종속성 상태(데이터베이스에 연결 가능한가?)를 반영하며, 단순히 프로세스 실행 여부만 확인하지 않습니다.
  • 프론트엔드: web-vitals와 클라이언트 오류를 동일한 백엔드에 보고합니다.
  • 여정별 SLO와 대시보드, 번-레이트 알림.

확장 시점

사전 출시/로컬 프로젝트는 지금 구조화된 로그와 상태 점검 엔드포인트만 구현하고, 보호할 실제 사용자가 생길 때까지 SLO/알림을 연기합니다. 첫 번째 결정 레코드에서 이 모드를 명시하세요.

전체 근거: 헌법 제IX조 및 제XVI조, engineering-constitution/references/engineering-constitution.md에 번들로 제공됩니다.

Individual skills in this repo

This repo contains 18 individual skills — each has its own dedicated page.

lguidolin/change-hygiene-and-code-craft

Use when writing or refactoring code, structuring a commit or PR, or deciding whether to abstract duplication. Symptoms — mixing reorg with logic changes, a PR doing several things at once, a file growing large, the second copy of similar code, or unsure whether to DRY something up.

lguidolin/cloud-delivery-aks

Use when deploying to Kubernetes or Azure Kubernetes Service (AKS), configuring cloud secrets, setting up progressive rollout/canary, per-PR ephemeral environments, or k8s health probes. Keywords — Kubernetes, AKS, Key Vault, Argo Rollouts, Flagger, canary, blue-green, liveness, readiness, PodDisruptionBudget, HPA, rollback, GHCR.

lguidolin/commit-history-rewrite

Use when an existing repository has messy commit history that needs to conform to conventional commits before adopting release-please, or when intermediate WIP/fixup/merge commits need to be cleaned up.

lguidolin/conventional-commits-and-releases

Use when committing, writing a commit message, opening a PR that will be squash-merged, or configuring automated versioning/changelogs. Keywords — conventional commits, release-please, semver, feat/fix/chore, breaking change, changelog.

lguidolin/defense-in-depth-security

Use when handling untrusted input, secrets, authentication/authorization, or dependencies — or threat-modeling a new surface. Keywords — STRIDE, threat model, least privilege, secrets management, supply chain, dependency scanning, input validation, audit log, defense in depth.

lguidolin/designing-before-building

Use when starting a feature, fixing a non-trivial bug, or about to write implementation code — before any code exists. Symptoms you need this: "this is simple, I'll just code it", reaching for the editor before a design is approved, or an idea that hasn't been turned into a spec and plan.

lguidolin/engineering-constitution

Use when starting work in a project that follows the engineering constitution, orienting to its rules, or deciding which engineering practice applies to a task — spec writing, commits, testing, security, deploys, database, or UI work.

lguidolin/graphql-contract-testing

Use when writing a GraphQL query/mutation that the UI and a test will share, or building route/schema contract or smoke tests. Symptoms — copying a query into a test, a test asserting on query text, schema change that didn't break the UI build, or RLS/permission drift. Keywords — graphql-codegen, typed document, contract test, route smoke test.

lguidolin/init-repo-CI

Use when setting up a new repository with conventional commits, release-please, and CI automation, or when retrofitting an existing repository that lacks automated versioning and PR validation workflows.

lguidolin/interface-craft-and-accessibility

Use when building or styling UI — components, layouts, forms, design tokens — or making accessibility decisions. Keywords — a11y, WCAG, keyboard navigation, focus state, contrast, design system, minimalist UI, component reuse, ARIA, semantic HTML.

lguidolin/merge-gates-and-automation

Use when setting up or changing CI, pre-push hooks, or a task runner, or deciding what must pass before merge. Symptoms — tempted to put authoritative checks only in a local hook, skip CI, bypass with --no-verify, or unsure what gates a merge vs. runs locally.

lguidolin/performance-and-scale

Use when working on hot paths, list endpoints, pagination, data-access in loops, or public interfaces/schemas. Symptoms — unbounded queries, N+1 access, no latency budget, optimizing without measuring, or changing an interface many consumers depend on. Keywords — pagination, N+1, Hyrum's Law, performance budget, bundle size.

lguidolin/postgres-postgraphile-rls-and-sql

Use when writing PostgreSQL, PostGraphile config, Row-Level Security policies, SQL schema files, or working on the Browser→App→PostGraphile→Postgres data path. Keywords — RLS, SECURITY DEFINER, search_path, pgSettings, grants, roles, GraphQL depth limit, query cost, statement_timeout, SQL file organization.

lguidolin/recording-decisions

Use when a design or architecture decision has been made and needs to be captured — writing a decision record or ADR, updating a decision index, noting a deferred idea, or superseding a past decision. Keywords — ADR, decision record, rationale, rejected alternatives, dependency index.

lguidolin/resilience-and-deploy-safety

Use when planning a deploy, designing a rollback, or responding to an incident or writing a postmortem. Keywords — deploy safety, rollback, immutable artifact, progressive delivery, canary, blast radius, incident response, blameless postmortem, error budget.

lguidolin/ship-it

Use when the user wants to ship work — push, PR, archive decision records, merge, and clean up. Handles the full lifecycle from committing final changes through post-merge cleanup including converting specs/plans to compact decision records.

lguidolin/tests-as-a-control

Use when writing or modifying tests, when a test breaks during a refactor, or when testing permission/role rules. Symptoms — tempted to edit a test to make it pass, testing only the happy path, a deny-test that started passing, flaky tests, or unsure what to assert.

lguidolin/zero-downtime-migrations

Use when changing a database schema where data must survive the change — adding/removing/renaming columns, constraints, indexes, or backfilling. Symptoms — a destructive migration bundled with a code deploy, a NOT NULL column with a backfill, a table-locking UPDATE, or a rename. Keywords — expand/contract, parallel change, backfill, NOT VALID, CREATE INDEX CONCURRENTLY, graphile-migrate.

관련 스킬

steipete/sag

ElevenLabs text-to-speech with mac-style say UX.

community

steipete/oracle

Oracle CLI second-model review/debug/refactor/design with selected files, dry-run token checks, API or browser engine.

community

steipete/peekaboo

Capture and automate macOS UI with the Peekaboo CLI.

community

mattpocock/design-an-interface

Generate multiple radically different interface designs for a module using parallel sub-agents. Use when user wants to design an API, explore interface options, compare module shapes, or mentions "design it twice".

community

mattpocock/prototype

Build a throwaway prototype to flesh out a design — a runnable terminal app for state/business-logic questions, or several radically different UI variations toggleable from one route.

community

mattpocock/grill-me

Interview the user relentlessly about a plan or design until reaching shared understanding, resolving each branch of the decision tree. Use when user wants to stress-test a plan, get grilled on their design, or mentions "grill me".

community