observability-record

Guides writing structured log lines with scoped loggers, levels, and failure-store selection.

1|Updated Jan 14, 2024
One-click install
npx skills add https://github.com/Eyhenij/rt-tools --skill observability-record-eyhenij
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: observability-record
Source: https://github.com/Eyhenij/rt-tools/tree/main/.claude/skills/observability-record
Command: npx skills add https://github.com/Eyhenij/rt-tools --skill observability-record-eyhenij

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? When developers add logging to application code, they often reach for console.log or embed values directly into message strings, producing logs that cannot be grouped, filtered, or routed to a failure store. This Skill enforces a consistent pattern for writing log lines so failures actually reach the system owner. ## Core Features & Use Cases - Scoped logger setup: Take the domain logger once via logger.scope(LOG_CONTEXT) with the context as a module constant, letting the logger inject request number, procedure, and user automatically. - Constant line names with structured fields: Use dot-separated constant names like cache.refresh.rejected and pass all variable data as a fields object, so lines about the same event group together in the failure feed. - Level selection and failure-store routing: Choose levels by whether something broke (failure, below, message, detail), register lower-level line names in the selected list, parse external service errors with describeError, mask emails, and require a wait limit (e.g., AbortSignal.timeout) before any failure can be logged. - Use Case: While adding error handling to a mail-sending call, apply this Skill to write this.#log.error('mail.send.failed', { to: maskEmail(to), error: describeError(error) }) instead of string-interpolating the raw error. ## Quick Start Ask the AI to add a proper log line for a failed external service call in your TypeScript code following the observability pattern.

Frequently Asked Questions about observability-record

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I write a structured log line in TypeScript?

Create a scoped logger once with `logger.scope(LOG_CONTEXT)` using a module-level constant, then call it with a constant dot-separated name and a fields object, e.g. `this.#log.warn('cache.refresh.rejected', { url, attempt, status })`. Never interpolate values into the message string.

How do I choose the right log level for an event?

Choose the level by whether something broke: failure when the application did not do what it must, the level below when an automatic step did not fire, message for completed actions worth knowing, and detail for investigation-only data. A guest failing a validation check is below failure, not failure.

Why is console.log discouraged in production logging?

console.log has no level, no request number, and never enters the failure selection, so in production it becomes a line nobody will see. Use the scoped application logger instead so lines are grouped, scrubbed, and routed to the failure store.

Why does my log line not appear in the failure store?

Lines below the failure level reach the failure store only if their name is in the selected-names list, matched by name prefix. Add the line name to that list in the same commit as the code that writes the line, otherwise it stays only in container output.

How should I log errors from external service calls?

Parse the caught error with a helper like `describeError(error)` so class, message, code, and trimmed stack are recorded in a consistent shape, and mask emails at the call site. Also set a wait limit such as `AbortSignal.timeout`, since without a timeout the catch may never fire.

When should I not use this logging pattern?

Do not use it to edit the logger implementation itself or the request-context handling, which belong to the separate observability rule. It covers only adding new log lines in domain code, not changing the logging infrastructure.