Menu
>-
The review-first prompt is selected by default. You can switch to a direct command or download a local copy.
Read SKILL.md and any companion files shown by SkillsMP before deciding whether to install.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
npx skills add https://github.com/CleanExpo/ATO --skill structured-loggingThe command stays on one line. Scroll horizontally to inspect it before copying.
Prefer a local copy? Download the files currently available to SkillsMP.
Route complex requests to the right specialist agent or chain of agents. This skill acts as the central brain of an agent swarm — it analyses what the user needs, determines which specialist domain(s) are required, and coordinates parallel or sequential agent execution. Use this skill when a request spans multiple domains (e.g., "research competitors and create a pitch deck"), when you need to decide which specialist should handle an ambiguous request, or when a task requires a multi-step pipeline across different skills. Triggers on: multi-step requests, cross-domain tasks, "coordinate", "plan this out", "I need help with multiple things", or any complex request that touches more than one specialist area. Also triggers when the user seems unsure which tool or approach to use.
>-
>-
Showing SKILL.md
| id | structured-logging |
| name | structured-logging |
| type | skill |
| version | 1.0.0 |
| created | 20/03/2026 |
| modified | 20/03/2026 |
| status | active |
| metadata | {"author":"NodeJS-Starter-V1","version":"1.0.0","locale":"en-AU"} |
| description | >- |
| context | fork |
Consistent, machine-readable logging across the full stack. The backend uses structlog with JSON output; the frontend uses a custom Logger class. This skill codifies conventions for both and adds correlation IDs, log context, and level guidelines.
Enforces JSON-structured logging with correlation IDs, consistent log levels, and contextual metadata across the FastAPI backend (structlog) and Next.js frontend (Logger class). Covers sensitive data redaction, request tracing, and observability best practices.
error-taxonomy instead)metrics-collector when available)ci-cd-patterns when available)# GOOD: Structured with context
logger.info("Document created", document_id=doc.id, user_id=user.id)
# BAD: Unstructured string interpolation
logger.info(f"Document {doc.id} created by user {user.id}")
# BAD: print() for logging
print(f"Created doc: {doc.id}")
| Level | When to Use | Example |
|---|---|---|
| ERROR | Operation failed, needs attention | Database connection lost, agent execution failed |
| WARNING | Recoverable issue, degraded behaviour | Rate limit approaching, fallback provider used |
| INFO | Significant business events | User logged in, document created, agent run completed |
| DEBUG | Development-only detail | Query parameters, intermediate computation results |
The project configures structlog in apps/backend/src/utils/logging.py:
ConsoleRenderer() (human-readable)JSONRenderer() (machine-readable)merge_contextvars enables request-scoped contextfrom src.utils import get_logger
logger = get_logger(__name__)
# Logger name becomes the "logger" field in JSON output
# e.g., "logger": "src.api.routes.documents"
Add a middleware that generates a correlation ID per request and binds it to structlog context:
import uuid
import structlog
from starlette.middleware.base import BaseHTTPMiddleware
from starlette.requests import Request
class CorrelationIdMiddleware(BaseHTTPMiddleware):
"""Attach a correlation ID to every request for log tracing."""
async def dispatch(self, request: Request, call_next):
correlation_id = request.headers.get(
"X-Correlation-ID",
str(uuid.uuid4())
)
# Bind to structlog context (available to all loggers in this request)
structlog.contextvars.clear_contextvars()
structlog.contextvars.bind_contextvars(
correlation_id=correlation_id,
)
response = await call_next(request)
response.headers["X-Correlation-ID"] = correlation_id
return response
Register in apps/backend/src/api/main.py:
from .middleware.correlation import CorrelationIdMiddleware
app.add_middleware(CorrelationIdMiddleware)
Log every API request with timing:
import time
from src.utils import get_logger
logger = get_logger(__name__)
class RequestLoggingMiddleware(BaseHTTPMiddleware):
"""Log request method, path, status, and duration."""
async def dispatch(self, request: Request, call_next):
start = time.perf_counter()
response = await call_next(request)
duration_ms = (time.perf_counter() - start) * 1000
logger.info(
"Request completed",
method=request.method,
path=request.url.path,
status=response.status_code,
duration_ms=round(duration_ms, 2),
)
return response
Log agent lifecycle events consistently:
logger = get_logger(__name__)
async def execute_agent(agent_name: str, task: str):
logger.info("Agent started", agent=agent_name, task=task[:100])
try:
result = await agent.run(task)
logger.info(
"Agent completed",
agent=agent_name,
status="success",
duration_ms=result.duration_ms,
)
return result
except TimeoutError:
logger.error(
"Agent timed out",
agent=agent_name,
error_code="AGENT_RUNTIME_TIMEOUT",
)
raise
except Exception as exc:
logger.error(
"Agent failed",
agent=agent_name,
error_code="AGENT_RUNTIME_FAILED",
error=str(exc),
)
raise
In production, each log line is a single JSON object:
{
"timestamp": "2026-02-13T09:30:00.000Z",
"level": "info",
"event": "Request completed",
"logger": "src.api.middleware.logging",
"correlation_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"method": "POST",
"path": "/api/documents",
"status": 201,
"duration_ms": 42.5
}
The project has a Logger class in apps/web/lib/logger.ts:
LOG_LEVEL env varimport { logger } from '@/lib/logger';
// Business events
logger.info('Document created', { documentId: doc.id, userId: user.id });
// Warnings
logger.warn('API response slow', { endpoint: '/api/agents', durationMs: 2500 });
// Errors (always include the error object)
logger.error('Failed to fetch documents', error, { userId: user.id });
// Debug (stripped in production via LOG_LEVEL)
logger.debug('API response', { status: response.status, body: data });
Pass the correlation ID from backend responses to subsequent requests:
let correlationId: string | null = null;
export async function apiRequest(path: string, options?: RequestInit) {
const headers: Record<string, string> = {
'Content-Type': 'application/json',
...(correlationId ? { 'X-Correlation-ID': correlationId } : {}),
};
const response = await fetch(`${BACKEND_URL}${path}`, {
...options,
headers: { ...headers, ...options?.headers },
});
// Capture correlation ID from response
correlationId = response.headers.get('X-Correlation-ID');
return response;
}
All console.log, console.error, and console.warn calls should use the logger instead:
// BAD
console.log('User logged in');
console.error('Failed to load', error);
// GOOD
logger.info('User logged in', { userId: user.id });
logger.error('Failed to load', error, { component: 'Dashboard' });
Every log entry should include (automatically via middleware or manually):
| Field | Source | Example |
|---|---|---|
timestamp | Auto (structlog/Logger) | 2026-02-13T09:30:00.000Z |
level | Auto | info, error, warn, debug |
event | First argument | "Document created" |
correlation_id | Middleware | "a1b2c3d4-..." |
| Domain | Fields |
|---|---|
| API requests | method, path, status, duration_ms |
| Authentication | user_id, action (login/logout/token_refresh) |
| Agent execution | agent, task (truncated), status, duration_ms |
| Database operations | table, operation (select/insert/update/delete), row_count |
| External services | service, endpoint, status, duration_ms |
When adding or reviewing logging:
get_logger(__name__) (backend) or logger import (frontend)error_code from error-taxonomy where applicable| Pattern | Problem | Correct Approach |
|---|---|---|
Unstructured log.info(f"User {id} logged in") strings | Not machine-parseable, breaks log aggregation | Use structured key-value pairs: logger.info("User logged in", user_id=id) |
| Logging sensitive data (passwords, tokens, API keys) | Security breach via log exposure | Redact sensitive fields; never log credentials or session tokens |
| No correlation IDs across requests | Cannot trace a request through backend and frontend | Use CorrelationIdMiddleware and propagate X-Correlation-ID header |
| Inconsistent log levels (ERROR for warnings, INFO for debug) | Noisy alerts, missed critical errors | Follow the log level table: ERROR/WARNING/INFO/DEBUG |
Using console.log instead of the Logger class | No level filtering, no structured context, no timestamps | Import logger from @/lib/logger and use its methods |
JSONRenderer)X-Correlation-ID headerconsole.log calls replaced with logger methods in frontend codeerror_code from the error taxonomy[AGENT_ACTIVATED]: Structured Logging
[PHASE]: {Implementation | Review | Configuration}
[STATUS]: {in_progress | complete}
{logging analysis or implementation guidance}
[NEXT_ACTION]: {what to do next}
Error logs should include error_code from the error taxonomy:
logger.error("Agent failed", error_code="AGENT_RUNTIME_FAILED", agent=name)
Based on SOC occupation classification
