abrahamvilchesdelacruz/ididntcatchthat/api-observability

Claude Code and agent skill by abrahamvilchesdelacruz/ididntcatchthat

Trust tier 3
  • community
Source check pending

Checking that the SKILL.md file is still in the repository.

Logger interface, pino, métricas Prometheus, OTel traces en apps/api/. Trigger: Al añadir logging en use cases, configurar métricas Prometheus, o setup de OpenTelemetry.

Install

npx vskill@latest install abrahamvilchesdelacruz/ididntcatchthat/api-observability

SKILL.md

The same SKILL.md was published earlier as abrahamvilchesdelacruz/ididntcatchthat/api-observability.

When to Use

  • Al añadir logging en un use case, subscriber o filter
  • Al decidir qué nivel de log usar (info/warn/error/debug)
  • Al añadir métricas de negocio custom
Lee references/docs.md para skills relacionadas, ADRs y documentación externa.
Lee references/implementations.md para PinoLogger, MetricsService, logging en subscribers y en HttpExceptionFilter.
Setup de infraestructura (Loki, Prometheus, Grafana, OTel): ver resources/setup.md.

Las 3 señales

SignalQué capturaStorageConsultado en
LogsQué pasó y cuándoLokiGrafana
MetricsCuánto y con qué frecuenciaPrometheusGrafana
TracesCómo viajó un request por dentroTempoGrafana

OpenTelemetry es el SDK que instrumenta y exporta — no es un storage.


Logger Interface (domain)

typescript
// src/shared/domain/logger.ts
export type LogContext = Record<string, unknown>;
export interface Logger {
info(message: string, context?: LogContext): void;
warn(message: string, context?: LogContext): void;
error(message: string, error?: Error, context?: LogContext): void;
debug(message: string, context?: LogContext): void;
}
export const LOGGER_SERVICE = Symbol('Logger');
MétodoCuándo
infoAcción de negocio completada (flashcard creada, sesión iniciada)
warnSituación inesperada pero recuperable (retry, fallback)
errorError que impacta al usuario o rompe el flujo
debugDetalle técnico — solo en desarrollo

AppMetrics Interface (domain)

typescript
// src/shared/domain/app-metrics.ts
export interface AppMetrics {
increment(metric: string, labels?: Record<string, string>): void;
}
export const APP_METRICS = Symbol('AppMetrics');

Solo tiene increment — todos los contadores de negocio son Counter de Prometheus. No hay gauge ni histogram en la interfaz de dominio: el MetricsInterceptor gestiona los histogramas HTTP directamente.

MétricaLabelsDónde se incrementa
app_flashcards_created_total—FlashcardCreator
app_games_started_total—GameStarter
app_games_completed_total—GameCompleter
app_audio_generated_totalproviderFlashcardAudioGenerator
app_auth_logins_totalproviderUserAuthenticator
app_auth_registrations_totalproviderUserRegistrar
Inyección en use case
typescript
constructor(
@Inject(LOGGER_SERVICE)
private readonly logger: Logger,
@Inject(APP_METRICS)
private readonly metrics: AppMetrics,
) {}
async execute(request: ...): Promise<...> {
// ... lógica ...
this.logger.info('Flashcard created', { flashcardId: id, expression, createdBy });
this.metrics.increment('app_flashcards_created_total');
}
// Con labels:
this.metrics.increment('app_audio_generated_total', { provider: 'elevenlabs' });
APP_METRICS se inyecta igual que LOGGER_SERVICE — el módulo ObservabilityModule lo exporta como global.

Dónde loguear

Use Case — eventos de negocio
typescript
async execute(params: { id: string; phrase: string }): Promise<void> {
const flashcard = Flashcard.create(params);
await this.repository.save(flashcard);
await this.eventBus.publish(flashcard.pullDomainEvents());
this.logger.info('Flashcard created', {
flashcardId: params.id,
phrase: params.phrase,
});
}
Contexto siempre útil
typescript
// ✅ Con identificador del aggregate
this.logger.info('Flashcard updated', { flashcardId, userId, field: 'phrase' });
this.logger.error('Audio generation failed', error, { flashcardId, provider: 'elevenlabs' });
// ❌ Sin contexto
this.logger.info('Updated');
this.logger.error(error.message);

Reglas

  • Logger y AppMetrics interfaces viven en shared/domain/ — nunca importar pino, prom-client u OTel en domain/application
  • Loguear eventos de negocio en use cases (info)
  • Incrementar métricas de negocio en use cases con this.metrics.increment('app_<metric>_total')
  • Loguear errores con el objeto `Error` completo — preserva stack trace
  • No loguear en controllers — el filter e interceptor lo hacen automáticamente
  • Re-throw en subscribers después de loguear — para retry y DLQ
  • APP_METRICS se registra en ObservabilityModule, no en SharedModule

Security

  • Security scanPassed, 90 of 100Pattern checks on the skill's files.
  • Model reviewPassed

Quality evaluation

  • Task evaluationNot runNo evaluation yet. Run one in Skill Studio.

Source

Popularity

7-day trend score
0

Not refreshed yet.

Works with

Any agent vskill installs to: 56 targets in all. These 39 have a page on this site.

  • Claude Code
  • Cursor
  • GitHub Copilot
  • Windsurf
  • Codex
  • Gemini CLI
  • Cline
  • Amp
  • Roo Code
  • Goose
  • Continue
  • Kilo Code
  • Junie
  • Trae
  • OpenHands
  • Qwen Code
  • AI Agent
  • Tabnine Chat
  • Sourcegraph Cody
  • Amazon Q
  • Firebase Genkit
  • Sweep
  • Devin
  • Phind
  • Mentat
  • Claude Desktop
  • Aider
  • GPT Pilot
  • Plandex
  • bolt.new
  • v0
  • Replit Agent
  • Anse
  • TypingMind
  • BetterChatGPT
  • LibreChat
  • Warp AI
  • Pieces
  • Fig AI
Embed badge
vskill VERIFIED badge
[![vskill VERIFIED](https://verified-skill.com/api/v1/skills/abrahamvilchesdelacruz/ididntcatchthat/api-observability/badge)](https://verified-skill.com/skills/abrahamvilchesdelacruz/ididntcatchthat/api-observability)

Something wrong with this skill or its page? Tell us.