Communitygithub.com

Observabilidade e SLOs

Use ao adicionar logging, métricas, tracing, health checks, SLOs ou alertas — ou ao construir uma superfície de serviço que precisa ser operável e depurável. Palavras-chave — logs estruturados, OpenTelemetry, id de correlação, métricas RED, liveness, readiness, SLI, SLO, orçamento de erros, alertas.

O que é Observabilidade e SLOs?

Esta skill define um padrão abrangente de observabilidade e SLOs para serviços em nuvem. Ela estabelece que observabilidade deve ser projetada desde o início, não adicionada apressadamente após a primeira falha. A skill descreve os princípios universais: emitir logs estruturados, métricas e traces (os três sinais); instrumentar os sinais dourados (taxa, erros, duração — RED) para cada endpoint; expor endpoints de liveness e readiness; definir SLOs para jornadas críticas medidos por SLIs com um orçamento de erros; e alertar sobre sintomas, não causas. Ela também detalha os mecanismos específicos da stack, como logs JSON estruturados para stdout, OpenTelemetry para exportar traces/métricas para Azure Monitor/Application Insights, propagação de id de correlação ao longo do caminho de dados, e endpoints de liveness/readiness conectados a probes do Kubernetes. A skill suporta plataformas como AKS, Azure Monitor, Log Analytics e opções como Prometheus/Grafana. Útil para desenvolvedores que estão construindo serviços operáveis e depuráveis, ela orienta quando escalar a implementação (por exemplo, implementar logs estruturados e health checks imediatamente, mas adiar SLOs e alertas até haver usuários reais).

Funciona com~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/lguidolin/agent-skills/tree/main/skills/observability-and-slos
Ver original→Navegar por todas as habilidades

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

OpenAIChatGPTClaudeClaudeGeminiGeminiGrokGrokPerplexityPerplexityDeepSeekDeepSeek

Documentação

O que Observabilidade e SLOs faz?

Visão Geral

Você não pode operar, depurar ou melhorar o que não pode ver. Observabilidade é projetada, não adicionada após a primeira falha. A primeira pergunta em todo incidente é "o que mudou e quem foi afetado" — um sistema que não consegue responder transforma um conserto de cinco minutos em uma escavação arqueológica.

Os Princípios (universais)

  • Os três sinais. Emita logs estruturados (analisáveis por máquina, não texto livre), métricas (contagens, taxas, durações) e traces (o caminho de uma requisição entre serviços). Uma requisição carrega um id de correlação/trace de ponta a ponta.
  • Instrumente os sinais dourados para cada superfície: taxa, erros, duração (RED) por endpoint/operação, além de saturação de recursos. Um novo endpoint não está "pronto" até que seja observável.
  • Saúde é um endpoint, não um palpite. Exponha liveness ("estou rodando?") e readiness ("posso servir tráfego?") como verificações distintas.
  • Defina SLOs para jornadas críticas, com SLIs que os meçam e um orçamento de erros que transforme a troca entre confiabilidade e funcionalidades em uma decisão explícita baseada em dados.
  • Alerta sobre sintomas, não causas. Dispare quando os usuários estiverem sofrendo (queima de SLO, falha de readiness), não a cada oscilação interna. Todo alerta deve ser acionável — um alerta que ninguém age treina as pessoas a ignorar alertas.

Os Mecanismos (esta stack)

  • Logs JSON estruturados para stdout, coletados pela plataforma (ex.: AKS → Azure Monitor / Log Analytics). Sem logging de texto livre nos serviços.
  • OpenTelemetry no servidor de aplicação e no PostGraphile; exporte traces/métricas para Azure Monitor / Application Insights (ou Prometheus/Grafana).
  • Id de correlação propagado ao longo do caminho de dados — gerado na borda, passado Browser → App → PostGraphile junto com cabeçalhos de contexto, anexado a cada linha de log e span.
  • Métricas RED por rota HTTP e operação GraphQL; log de consultas lentas do Postgres + pg_stat_statements.
  • Endpoints de liveness/readiness conectados a probes do Kubernetes (veja cloud-delivery-aks). Readiness reflete a saúde real das dependências (consegue alcançar o BD?), não apenas o processo em execução.
  • Frontend: reporte web-vitals e erros de cliente para o mesmo backend.
  • SLOs por jornada com dashboards e alertas de taxa de queima.

Quando escalar isso

Um projeto pré-lançamento/local implementa logs estruturados + endpoints de saúde agora e adia SLOs/alertas até que haja usuários reais para proteger. Declare o modo no primeiro registro de decisão.

Justificativa completa: Artigos IX e XVI da constituição, agrupados em 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.

Habilidades Relacionadas

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