@luanpdd/kit-mcp 1.8.1 → 1.9.0

package/kit/skills/opentelemetry-standard/SKILL.md

@@ -0,0 +1,351 @@
+---
+name: opentelemetry-standard
+description: Use ao adotar OTel — SDK + API + Tracer + Meter + Exporter + OTLP + Collector. Auto-instrumentation primeiro, custom attrs depois. Vendor-neutral por design.
+---
+
+# Observabilidade — OpenTelemetry (OTel)
+
+## Quando usar
+
+LLM carrega esta skill ao instrumentar código com OpenTelemetry. Trigger phrases:
+
+- "OpenTelemetry", "OTel"
+- "instrumentação vendor-neutral"
+- "OTel SDK Tracer Meter Exporter Collector"
+- "OTLP exporter"
+- "auto-instrumentation"
+- "OTel para Edge Function Deno", "OTel Node.js"
+
+## Regras absolutas
+
+- **Use OTel sempre** — vendor-neutral por design. Não adote APM proprietário no código aplicacional. Trocar backend = trocar exporter, não código.
+- **API ≠ SDK** — `@opentelemetry/api` é o que devs importam (especificação). `@opentelemetry/sdk-*` é a implementação. Use API em libs, SDK no entry-point do app.
+- **Auto-instrumentation primeiro** — instale `@opentelemetry/auto-instrumentations-node` (ou Deno equivalente) e tenha tracing de HTTP/gRPC/DB grátis em minutos. Depois adicione custom attrs.
+- **Configure SDK NO ENTRY-POINT** — antes de qualquer outro require/import. Caso contrário, instrumentation patches não pegam.
+- **Use OTLP como wire format** — porta 4318 (HTTP) ou 4317 (gRPC). É o padrão; todos os backends modernos aceitam.
+- **Collector como sidecar** — em produção, app envia OTLP para Collector local (porta 4318). Collector roteia para destino final. Permite trocar destino sem redeploy.
+- **Tracer name = component name** — `trace.getTracer('orders-service')`, não `trace.getTracer('default')`.
+- **Resource attributes obrigatórios** — `service.name`, `service.version`, `deployment.environment`. Setados 1× no SDK setup.
+- **Não polua o tracer global** — em libs, exponha como parâmetro ou use named tracer. Não dependa de tracer global.
+
+## Componentes OTel
+
+| Componente | Responsabilidade | Exemplo de uso |
+|---|---|---|
+| **API** | Especificação (interface) | `import { trace } from '@opentelemetry/api'` |
+| **SDK** | Implementação concreta | `import { NodeSDK } from '@opentelemetry/sdk-node'` |
+| **Tracer** | Cria e gerencia spans | `trace.getTracer('my-service')` |
+| **Meter** | Cria e gerencia métricas | `metrics.getMeter('my-service')` |
+| **Context propagation** | Serializa/extrai contexto entre services | `propagation.inject()`, `propagation.extract()` |
+| **Exporter** | Envia dados para backend | `OTLPTraceExporter`, `JaegerExporter`, etc. |
+| **Collector** | Proxy/sidecar standalone | Binário `otelcol` |
+| **OTLP** | Wire protocol default | HTTP 4318, gRPC 4317, Protobuf |
+
+## Patterns canônicos
+
+### Pattern: SDK setup Node.js (entry-point)
+
+```ts
+// PT-BR: arquivo `instrumentation.ts` — IMPORTAR ANTES de qualquer outra coisa
+// Em package.json: "node --import ./instrumentation.ts ./src/index.ts"
+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'
+import { resourceFromAttributes } from '@opentelemetry/resources'
+import {
+  ATTR_SERVICE_NAME,
+  ATTR_SERVICE_VERSION,
+} from '@opentelemetry/semantic-conventions'
+
+const sdk = new NodeSDK({
+  resource: resourceFromAttributes({
+    [ATTR_SERVICE_NAME]: 'orders-service',
+    [ATTR_SERVICE_VERSION]: process.env.BUILD_ID ?? 'dev',
+    'deployment.environment': process.env.NODE_ENV ?? 'development',
+  }),
+  traceExporter: new OTLPTraceExporter({
+    url: 'http://localhost:4318/v1/traces',  // PT-BR: Collector local
+  }),
+  metricReader: new PeriodicExportingMetricReader({
+    exporter: new OTLPMetricExporter({
+      url: 'http://localhost:4318/v1/metrics',
+    }),
+    exportIntervalMillis: 10_000,
+  }),
+  instrumentations: [getNodeAutoInstrumentations()],
+})
+
+sdk.start()
+
+// PT-BR: graceful shutdown — flush pending traces
+process.on('SIGTERM', () => {
+  sdk.shutdown().finally(() => process.exit(0))
+})
+```
+
+### Pattern: SDK setup Deno (Edge Function)
+
+```ts
+// PT-BR: setup OTel em Edge Function — pode ser arquivo `_otel.ts` importado primeiro
+import { NodeSDK } from 'npm:@opentelemetry/sdk-node@0.55.0'
+import { OTLPTraceExporter } from 'npm:@opentelemetry/exporter-trace-otlp-http@0.55.0'
+import { resourceFromAttributes } from 'npm:@opentelemetry/resources@1.27.0'
+
+const sdk = new NodeSDK({
+  resource: resourceFromAttributes({
+    'service.name': 'edge-process-emails',
+    'service.version': Deno.env.get('SUPABASE_GIT_SHA') ?? 'local',
+    'deployment.environment': Deno.env.get('SUPABASE_ENV') ?? 'production',
+  }),
+  traceExporter: new OTLPTraceExporter({
+    // PT-BR: em Supabase, OTLP collector pode rodar como sidecar ou
+    //         enviar direto para destino externo (Honeycomb, etc.)
+    url: Deno.env.get('OTLP_ENDPOINT') ?? 'http://localhost:4318/v1/traces',
+    headers: {
+      // PT-BR: backends comerciais usam header de auth aqui
+      authorization: `Bearer ${Deno.env.get('OTLP_TOKEN') ?? ''}`,
+    },
+  }),
+})
+
+sdk.start()
+```
+
+### Pattern: usar Tracer em código
+
+```ts
+import { trace, SpanKind, SpanStatusCode } from '@opentelemetry/api'
+
+// PT-BR: 1× por arquivo/módulo — nome do componente
+const tracer = trace.getTracer('orders-service')
+
+export async function placeOrder(req: Request) {
+  return tracer.startActiveSpan(
+    'place_order',
+    { kind: SpanKind.SERVER },
+    async (span) => {
+      span.setAttribute('user.id', req.user.id)
+      try {
+        const order = await db.insertOrder(req.body)
+        span.setAttribute('order.id', order.id)
+        span.setStatus({ code: SpanStatusCode.OK })
+        return order
+      } catch (e) {
+        span.recordException(e as Error)
+        span.setStatus({ code: SpanStatusCode.ERROR, message: e.message })
+        throw e
+      } finally {
+        span.end()
+      }
+    }
+  )
+}
+```
+
+### Pattern: usar Meter (métricas)
+
+```ts
+import { metrics } from '@opentelemetry/api'
+
+const meter = metrics.getMeter('orders-service')
+
+// PT-BR: counter para eventos contáveis
+const ordersCreated = meter.createCounter('orders.created.total', {
+  description: 'Total orders created',
+})
+
+// PT-BR: histogram para distribuições (latency)
+const orderDuration = meter.createHistogram('orders.duration_ms', {
+  description: 'Order placement duration in ms',
+  unit: 'ms',
+})
+
+export async function placeOrder(req: Request) {
+  const start = Date.now()
+  try {
+    const order = await db.insertOrder(req.body)
+    ordersCreated.add(1, {
+      'tenant_id': req.user.tenant,
+      'customer.tier': req.user.tier,
+      'result.success': true,
+    })
+    return order
+  } finally {
+    orderDuration.record(Date.now() - start, {
+      'tenant_id': req.user.tenant,
+    })
+  }
+}
+```
+
+### Pattern: OTel Collector config (otelcol-config.yaml)
+
+```yaml
+# PT-BR: collector como sidecar — recebe OTLP, processa, exporta para múltiplos destinos
+receivers:
+  otlp:
+    protocols:
+      http:
+        endpoint: 0.0.0.0:4318
+      grpc:
+        endpoint: 0.0.0.0:4317
+
+processors:
+  batch:
+    timeout: 10s
+    send_batch_size: 1024
+  # PT-BR: tail-based sampling — 100% errors, 1% successes
+  tail_sampling:
+    decision_wait: 10s
+    policies:
+      - name: errors-policy
+        type: status_code
+        status_code: { status_codes: [ERROR] }
+      - name: probabilistic-policy
+        type: probabilistic
+        probabilistic: { sampling_percentage: 1 }
+
+exporters:
+  # PT-BR: para Honeycomb (exemplo)
+  otlphttp/honeycomb:
+    endpoint: https://api.honeycomb.io
+    headers:
+      x-honeycomb-team: ${env:HONEYCOMB_API_KEY}
+  # PT-BR: para arquivo local — debug
+  file:
+    path: /var/log/otel-traces.json
+  # PT-BR: para Logflare (Supabase)
+  otlphttp/logflare:
+    endpoint: https://api.logflare.app/otel
+    headers:
+      x-api-key: ${env:LOGFLARE_API_KEY}
+
+service:
+  pipelines:
+    traces:
+      receivers: [otlp]
+      processors: [tail_sampling, batch]
+      exporters: [otlphttp/honeycomb, file]
+```
+
+### Pattern: rodar Collector via Docker (dev)
+
+```bash
+# PT-BR: Collector local com config customizado
+docker run -p 4317:4317 -p 4318:4318 \
+  -v "$(pwd)/otelcol-config.yaml":/etc/otelcol/config.yaml \
+  -e HONEYCOMB_API_KEY="$HONEYCOMB_API_KEY" \
+  otel/opentelemetry-collector:latest \
+  --config=/etc/otelcol/config.yaml
+```
+
+### Pattern: tracegen — testar pipeline
+
+```bash
+# PT-BR: gera 100 traces sintéticos, 10/segundo, valida que pipeline está vivo
+go install github.com/open-telemetry/opentelemetry-collector-contrib/cmd/telemetrygen@latest
+telemetrygen traces --otlp-insecure --otlp-endpoint=localhost:4317 --traces 100 --rate 10
+```
+
+## Anti-patterns
+
+### ANTI: configurar SDK depois de imports
+
+```ts
+// PT-BR: BAD — instrumentation patches não pegam código já carregado
+import express from 'express'   // express já carregado, sem patches OTel
+import { NodeSDK } from '@opentelemetry/sdk-node'
+new NodeSDK({...}).start()       // tarde demais
+
+// PT-BR: GOOD — SDK no entry-point com `--import`
+// node --import ./instrumentation.ts ./src/index.ts
+// (instrumentation.ts inicializa SDK antes de qualquer outro código)
+```
+
+### ANTI: usar SDK em libs
+
+```ts
+// PT-BR: BAD — lib importa SDK, força app a usar mesma versão
+import { NodeSDK } from '@opentelemetry/sdk-node'  // em uma lib
+
+// PT-BR: GOOD — lib só importa API, app traz SDK
+import { trace } from '@opentelemetry/api'  // lib usa só API
+```
+
+### ANTI: tracer global anônimo
+
+```ts
+// PT-BR: BAD — sem nome de componente, dificulta filtrar por service em queries
+const tracer = trace.getTracer('default')
+
+// PT-BR: GOOD — nome do component
+const tracer = trace.getTracer('orders-service')
+```
+
+### ANTI: backend proprietary direto
+
+```ts
+// PT-BR: BAD — code aplicacional acoplado a vendor
+import { Datadog } from 'dd-trace'  // 6 meses depois quer trocar = refactor massivo
+
+// PT-BR: GOOD — OTel + exporter trocável via config
+import { trace } from '@opentelemetry/api'
+// trocar backend = trocar exporter no SDK setup, não código
+```
+
+### ANTI: instrumentar sem resource attributes
+
+```ts
+// PT-BR: BAD — sem service.name, query SELECT WHERE service = ? não funciona
+new NodeSDK({ traceExporter: ... })
+
+// PT-BR: GOOD — resource sempre presente
+new NodeSDK({
+  resource: resourceFromAttributes({
+    'service.name': 'orders-service',
+    'service.version': BUILD_ID,
+    'deployment.environment': ENV,
+  }),
+  traceExporter: ...
+})
+```
+
+### ANTI: enviar OTLP direto para múltiplos backends
+
+```ts
+// PT-BR: BAD — app conhece todos os destinos (Honeycomb, Datadog, Logflare)
+//                 redeploy obrigatório para mudar destino
+new NodeSDK({
+  traceExporter: new OTLPTraceExporter({ url: 'https://honeycomb.io...' }),
+})
+
+// PT-BR: GOOD — app envia para Collector local; Collector roteia
+new NodeSDK({
+  traceExporter: new OTLPTraceExporter({ url: 'http://localhost:4318/v1/traces' }),
+})
+// PT-BR: Collector decide para onde mandar (Honeycomb + Logflare + arquivo) via config
+```
+
+## Verificação
+
+1. **SDK iniciou** — log no setup: "OTel SDK started for service=orders-service version=...". Sem isso, traces não saem.
+2. **Auto-instrumentation ativa** — fazer 1 request HTTP via fetch ou axios → span aparece em `select * from spans` sem código manual.
+3. **OTLP sendo enviado** — `tcpdump port 4318` durante request real → tráfego POST visível.
+4. **Resource attributes corretos** — `select distinct service_name, service_version FROM spans` → resultado esperado.
+5. **Tracer custom funciona** — adicionar `tracer.startSpan('custom')` → span aparece queryable.
+6. **Collector roteando** — fazer request → trace aparece em DESTINO 1 (Honeycomb) e DESTINO 2 (arquivo local) simultaneamente.
+7. **Graceful shutdown** — `kill -TERM` no app → SDK flush pendente; sem traces perdidos no shutdown.
+
+---
+
+## Ver também
+
+- `kit/skills/_shared-observability/glossary.md` — termos OTel canônicos
+- `kit/skills/structured-events/SKILL.md` — campos canônicos por span
+- `kit/skills/distributed-tracing/SKILL.md` — context propagation cross-service
+- `kit/skills/telemetry-pipelines/SKILL.md` *(Phase 34)* — Collector config avançada
+- `kit/skills/telemetry-sampling/SKILL.md` *(Phase 34)* — sampling no Collector
+
+*Material-fonte: Observability Engineering (O'Reilly, 2022) — Cap 7: "Instrumentation with OpenTelemetry".*

package/kit/skills/structured-events/SKILL.md

@@ -0,0 +1,265 @@
+---
+name: structured-events
+description: Use ao instrumentar — wide events de alta cardinalidade (1/request), campos canônicos com dot notation, evite logs unstructured e métricas pre-aggregated.
+---
+
+# Observabilidade — Structured Events (Wide Events)
+
+## Quando usar
+
+LLM carrega esta skill quando instrumentar código para emitir telemetria. Trigger phrases:
+
+- "structured logging", "wide events", "observability events"
+- "instrumentar handler", "emitir telemetria", "log estruturado"
+- "como salvar evento de request"
+- "campos canônicos", "atributos de span"
+- "alta cardinalidade", "debug por user_id"
+
+## Regras absolutas
+
+- **1 evento por request** — não múltiplos. Acumule contexto durante o request, emita 1 wide event no final (ou em erros).
+- **Wide é melhor que narrow** — adicione campos liberalmente. Custo de 100 campos/evento ≈ 10 campos. Disco é barato; falta de campo no incidente é caro.
+- **Alta cardinalidade é OBRIGATÓRIA** — `user.id`, `tenant_id`, `request.id`, `customer.email`. Sem isso, observabilidade não funciona (Cap 1).
+- **Dot notation OTel** — `user.id` (não `userId` nem `user_id`). `error.type`, `http.status_code`, `db.query`. Snake_case apenas em colunas de DB.
+- **NUNCA pre-aggregate** — não emita "p99 latency = 247ms"; emita o `duration_ms` cru de cada request. Aggregation no read time.
+- **Estruturado, não texto livre** — JSON, OTel attributes, ou colunas tipadas. **Nunca** `console.log("user 123 did X at 12:34")`.
+- **Errors são especiais** — sample 100% de eventos com `result.success = false`. Sucesso pode ser samplado (skill `telemetry-sampling`).
+- **Capture context, não code** — emita atributos de business logic (`customer.tier`, `feature_flag.x`), não estado interno de código (`var_x_value_at_line_42`).
+
+## Patterns canônicos
+
+### Pattern: handler instrumentado (Node/TypeScript)
+
+```ts
+// PT-BR: 1 evento por request, alta cardinalidade, atributos canônicos
+import { trace, SpanStatusCode } from '@opentelemetry/api'
+
+const tracer = trace.getTracer('orders-service')
+
+export async function handlePlaceOrder(req: Request) {
+  return tracer.startActiveSpan('place_order', async (span) => {
+    // PT-BR: campos canônicos sempre — alta cardinalidade
+    span.setAttribute('user.id', req.user.id)
+    span.setAttribute('tenant_id', req.user.tenant)
+    span.setAttribute('customer.tier', req.user.tier)
+    span.setAttribute('request.id', req.headers['x-request-id'])
+    span.setAttribute('endpoint', '/api/v1/orders')
+    span.setAttribute('http.method', 'POST')
+    span.setAttribute('build_id', process.env.BUILD_ID ?? 'dev')
+
+    // PT-BR: feature flags como dimensões
+    span.setAttribute('feature_flag.new_pricing', req.flags.newPricing)
+
+    try {
+      const order = await createOrder(req.body)
+
+      // PT-BR: result e atributos de domínio
+      span.setAttribute('result.success', true)
+      span.setAttribute('order.id', order.id)
+      span.setAttribute('order.amount_cents', order.amount)
+      span.setAttribute('order.items_count', order.items.length)
+      span.setAttribute('http.status_code', 200)
+      span.setStatus({ code: SpanStatusCode.OK })
+      return order
+    } catch (e) {
+      // PT-BR: erros — sample 100%, classificar por tipo
+      span.setAttribute('result.success', false)
+      span.setAttribute('error.type', classifyError(e))
+      span.setAttribute('error.message', e.message)
+      span.setAttribute('http.status_code', e.statusCode ?? 500)
+      span.setStatus({ code: SpanStatusCode.ERROR, message: e.message })
+      throw e
+    } finally {
+      span.end()  // PT-BR: SEMPRE — duration_ms é calculado aqui
+    }
+  })
+}
+
+function classifyError(e: any): string {
+  if (e.code === 'P2002') return 'db_conflict'
+  if (e.statusCode === 401) return 'auth'
+  if (e.statusCode === 403) return 'authz'
+  if (e.statusCode === 422) return 'validation'
+  if (e.statusCode === 429) return 'rate_limit'
+  if (e.code === 'ETIMEDOUT') return 'timeout'
+  return 'unknown'
+}
+```
+
+### Pattern: Edge Function (Deno) com structured event
+
+```ts
+// PT-BR: Supabase Edge Function — 1 evento estruturado por invocação
+import { trace } from 'npm:@opentelemetry/api@1.9.0'
+
+const tracer = trace.getTracer('edge-process-emails')
+
+Deno.serve(async (req) => {
+  return tracer.startActiveSpan('process_emails', async (span) => {
+    const requestId = crypto.randomUUID()
+    span.setAttribute('request.id', requestId)
+    span.setAttribute('build_id', Deno.env.get('SUPABASE_GIT_SHA') ?? 'local')
+
+    try {
+      const body = await req.json()
+      span.setAttribute('user.id', body.user_id)
+      span.setAttribute('tenant_id', body.tenant_id)
+      span.setAttribute('email.batch_size', body.emails?.length ?? 0)
+
+      const result = await processBatch(body.emails)
+
+      span.setAttribute('result.success', true)
+      span.setAttribute('email.sent_count', result.sent)
+      span.setAttribute('email.failed_count', result.failed)
+      span.setAttribute('duration_ms', result.duration)
+
+      return new Response(JSON.stringify(result), { status: 200 })
+    } catch (e) {
+      span.setAttribute('result.success', false)
+      span.setAttribute('error.type', classify(e))
+      span.setAttribute('error.message', String(e))
+      return new Response(JSON.stringify({ error: 'failed' }), { status: 500 })
+    } finally {
+      span.end()
+    }
+  })
+})
+```
+
+### Pattern: campos canônicos por categoria
+
+| Categoria | Campos | Exemplo |
+|---|---|---|
+| **Identidade** | `user.id`, `tenant_id`, `session.id` | `"550e8400-e29b-41d4-..."` |
+| **Request** | `request.id`, `endpoint`, `http.method`, `http.status_code` | `"req_abc123"`, `"/api/v1/orders"`, `"POST"`, `200` |
+| **Resultado** | `result.success`, `error.type`, `error.message` | `true`, `"validation"`, `"email already exists"` |
+| **Performance** | `duration_ms`, `db.query_count`, `cache.hit` | `127`, `3`, `true` |
+| **Build/Deploy** | `build_id`, `service.version`, `region` | `"abc123f"`, `"v1.9.0"`, `"us-east-1"` |
+| **Business** | `customer.tier`, `order.amount_cents`, `feature_flag.<name>` | `"pro"`, `4990`, `true` |
+| **Tracing** | `trace.id`, `span.id`, `span.parent_id` | (auto via OTel) |
+
+### Pattern: query observability — encontrar pattern em wide events
+
+```sql
+-- PT-BR: alta cardinalidade permite group by ad hoc — sem schema rigido
+-- Exemplo: qual tenant + endpoint + error_type domina os erros da última hora?
+select
+  tenant_id,
+  endpoint,
+  error_type,
+  count(*) as error_count,
+  avg(duration_ms) as avg_duration
+from observability.events
+where 
+  result_success = false
+  and timestamp > now() - interval '1 hour'
+group by tenant_id, endpoint, error_type
+order by error_count desc
+limit 20;
+```
+
+## Anti-patterns
+
+### ANTI: log unstructured
+
+```ts
+// PT-BR: BAD — não estruturado, não queryable, sem alta cardinalidade
+console.log(`User ${userId} placed order ${orderId} for $${amount}`)
+
+// PT-BR: GOOD — structured wide event
+span.setAttribute('user.id', userId)
+span.setAttribute('order.id', orderId)
+span.setAttribute('order.amount_cents', amount * 100)
+```
+
+### ANTI: pre-aggregate em métricas
+
+```ts
+// PT-BR: BAD — pre-aggregation perde alta cardinalidade
+metrics.histogram('order_latency_ms').record(duration, { service: 'orders' })
+
+// PT-BR: GOOD — emit raw event, agregue no read
+span.setAttribute('duration_ms', duration)
+// PT-BR: ao queryar: SELECT percentile_cont(0.99) WITHIN GROUP (ORDER BY duration_ms)
+//        FROM events GROUP BY tenant_id, endpoint  -- alta cardinalidade preservada!
+```
+
+### ANTI: múltiplos eventos por request
+
+```ts
+// PT-BR: BAD — 5 eventos para 1 request, sem trace context
+log('user_action_started', { user_id })
+log('user_action_db_query', { user_id, query })
+log('user_action_email_sent', { user_id, to })
+log('user_action_completed', { user_id })
+log('user_action_response_sent', { user_id, status })
+
+// PT-BR: GOOD — 1 wide event acumulando contexto
+const span = tracer.startSpan('user_action')
+span.setAttribute('user.id', user_id)
+// ... ao longo do handler, span.setAttribute('email.recipient', ...) etc.
+span.end()  // 1 evento emitido com todos os atributos
+```
+
+### ANTI: cardinalidade baixa
+
+```ts
+// PT-BR: BAD — apenas service e endpoint, sem identidade
+span.setAttribute('service', 'orders')
+span.setAttribute('endpoint', '/place')
+// PT-BR: durante incident você não consegue responder "afeta quem?"
+
+// PT-BR: GOOD — adicione identidades de alta cardinalidade
+span.setAttribute('user.id', '550e8400-...')
+span.setAttribute('tenant_id', 'acme-corp')
+span.setAttribute('customer.tier', 'pro')
+// PT-BR: durante incident: "afeta quem?" → group by customer.tier, tenant_id
+```
+
+### ANTI: capturar valores internos de código
+
+```ts
+// PT-BR: BAD — atributos sobre estado de variáveis, não sobre business
+span.setAttribute('var_temp_array_length', tempArr.length)
+span.setAttribute('loop_iteration', i)
+
+// PT-BR: GOOD — atributos sobre business + identidade
+span.setAttribute('order.items_count', items.length)
+span.setAttribute('user.id', userId)
+```
+
+### ANTI: nomes inconsistentes de atributos
+
+```ts
+// PT-BR: BAD — mesmo conceito com nomes diferentes em handlers diferentes
+span.setAttribute('userId', user.id)        // handler A
+span.setAttribute('user_id', user.id)       // handler B
+span.setAttribute('user', user.id)          // handler C
+// PT-BR: query `WHERE user_id = X` falha em handler A; agg cross-handler quebra
+
+// PT-BR: GOOD — convenção única em todo o projeto
+span.setAttribute('user.id', user.id)       // sempre dot notation OTel
+```
+
+## Verificação
+
+Antes de marcar instrumentação completa:
+
+1. **1 evento por request** — em request de exemplo, contar eventos emitidos. Deve ser 1 (ou 2 se houver retry interno).
+2. **Atributos canônicos presentes** — checar `user.id`, `tenant_id`, `request.id`, `result.success`, `endpoint`, `duration_ms` no evento emitido.
+3. **Alta cardinalidade verificada** — `select count(distinct user_id)` deve crescer com tráfego real (não estagnar em N pequeno).
+4. **`result.success` define SLI** — boolean confiável para alimentar SLO downstream (ver skill `event-based-slos`).
+5. **Erros têm `error.type` enum** — não `error.message` cru. Permite group by por categoria.
+6. **Build_id presente** — permite comparar versão antes vs depois de deploy.
+7. **Smoke local** — emitir 100 eventos sintéticos, queryar via `select * from events where user_id = X` deve retornar todos.
+
+---
+
+## Ver também
+
+- `kit/skills/_shared-observability/glossary.md` — termos canônicos, campos canônicos, anti-patterns
+- `kit/skills/distributed-tracing/SKILL.md` — como spans se conectam em traces
+- `kit/skills/opentelemetry-standard/SKILL.md` — SDK e exporters
+- `kit/skills/core-analysis-loop/SKILL.md` — como queryar wide events para debug
+
+*Material-fonte: Observability Engineering (O'Reilly, 2022) — Cap 5: "Structured Events Are the Building Blocks of Observability".*