mirror of
https://github.com/duthaho/claudekit.git
synced 2026-07-25 06:01:01 +03:00
feat: adding new skills, including testing patterns and methodologies, along with bundled resources for better usability.
This commit is contained in:
duthaho
@@ -0,0 +1,157 @@
|
||||
# Log Levels Quick Reference
|
||||
|
||||
## Level Summary
|
||||
|
||||
| Level | When to Use | Audience | Production Default |
|
||||
|-------|------------|----------|-------------------|
|
||||
| **DEBUG** | Detailed diagnostic info | Developers debugging | Off |
|
||||
| **INFO** | Routine operational events | Ops team monitoring | On |
|
||||
| **WARNING** | Something unexpected but handled | Ops + Devs | On |
|
||||
| **ERROR** | Operation failed, needs attention | On-call engineers | On |
|
||||
| **CRITICAL** | System is unusable or data at risk | On-call + management | On + alert |
|
||||
|
||||
---
|
||||
|
||||
## DEBUG
|
||||
|
||||
**Purpose**: Fine-grained information useful only when diagnosing problems.
|
||||
|
||||
**Turn on**: During local development or when investigating a specific issue.
|
||||
|
||||
| Good | Bad |
|
||||
|------|-----|
|
||||
| `Parsing config file: /etc/app/config.yaml` | `Entering function parse_config` |
|
||||
| `Cache miss for key user:123, fetching from DB` | `x = 5` |
|
||||
| `SQL: SELECT * FROM users WHERE id=$1 [params: 123]` | `Here we go!` |
|
||||
| `Retry attempt 2/3 for payment gateway` | `Debug debug debug` |
|
||||
| `JWT token expires at 2025-01-29T10:00:00Z` | `token = eyJhbG...` (secret!) |
|
||||
|
||||
**Rule**: Never log secrets, tokens, passwords, or PII at any level.
|
||||
|
||||
---
|
||||
|
||||
## INFO
|
||||
|
||||
**Purpose**: Confirm the system is working as expected. Key business events.
|
||||
|
||||
| Good | Bad |
|
||||
|------|-----|
|
||||
| `Server started on port 8080` | `Server is running` (which port? which version?) |
|
||||
| `User user:456 created account via OAuth (Google)` | `New user` |
|
||||
| `Order ord:789 placed, total=$45.00, items=3` | `Order created` |
|
||||
| `Migration v42 applied successfully (12 tables)` | `Migration done` |
|
||||
| `Scheduled job "daily-report" completed in 4.2s` | `Job finished` |
|
||||
| `Payment processed: txn:abc, amount=$99, method=card` | `Payment OK` |
|
||||
|
||||
**Rule**: Include enough context to answer "what happened, to what, and relevant numbers."
|
||||
|
||||
---
|
||||
|
||||
## WARNING
|
||||
|
||||
**Purpose**: Something unexpected happened, but the system handled it. May indicate a future problem.
|
||||
|
||||
| Good | Bad |
|
||||
|------|-----|
|
||||
| `Connection pool at 85% capacity (17/20)` | `Pool getting full` |
|
||||
| `Deprecated API v1 called by client app:legacy (use v2)` | `Old API used` |
|
||||
| `Disk space below 10% on /data (2.1 GB remaining)` | `Low disk` |
|
||||
| `Request took 4.8s (threshold: 5s) for GET /api/search` | `Slow request` |
|
||||
| `Config REDIS_URL missing, falling back to in-memory cache` | `No Redis` |
|
||||
| `Rate limit approaching for IP 10.0.0.5: 90/100 requests` | `Almost rate limited` |
|
||||
|
||||
**Rule**: Warnings should be actionable. If nobody would investigate, it's DEBUG or INFO.
|
||||
|
||||
---
|
||||
|
||||
## ERROR
|
||||
|
||||
**Purpose**: An operation failed. The system can continue, but something broke.
|
||||
|
||||
| Good | Bad |
|
||||
|------|-----|
|
||||
| `Failed to send email to user:123: SMTP timeout after 30s` | `Email error` |
|
||||
| `Payment declined for order:789: card_expired (Stripe)` | `Payment failed` |
|
||||
| `Database query timeout after 10s: SELECT FROM orders WHERE...` | `DB error` |
|
||||
| `File upload failed: S3 returned 503, bucket=media, key=img/456.jpg` | `Upload error` |
|
||||
| `Unhandled exception in POST /api/orders: ValueError("...")` | (stack trace only, no context) |
|
||||
|
||||
**Rule**: Include the operation, the target/ID, the error detail, and what was attempted.
|
||||
|
||||
---
|
||||
|
||||
## CRITICAL
|
||||
|
||||
**Purpose**: System is unusable or data integrity is at risk. Requires immediate human intervention.
|
||||
|
||||
| Good | Bad |
|
||||
|------|-----|
|
||||
| `Database connection lost, all pools exhausted, 0/20 available` | `DB down` |
|
||||
| `Disk full on /data, writes failing, data loss possible` | `No disk space` |
|
||||
| `Security: 500 failed login attempts from IP 10.0.0.5 in 60s` | `Too many logins` |
|
||||
| `Data corruption detected: order:789 total=-$50.00` | `Bad data` |
|
||||
| `TLS certificate expires in 24h, auto-renewal failed` | `Cert expiring` |
|
||||
|
||||
**Rule**: Every CRITICAL log should trigger an alert (PagerDuty, Slack, etc.).
|
||||
|
||||
---
|
||||
|
||||
## Structured Logging Format
|
||||
|
||||
### Python (structlog)
|
||||
|
||||
```python
|
||||
import structlog
|
||||
|
||||
log = structlog.get_logger()
|
||||
|
||||
log.info("order.placed", order_id="ord:789", total=45.00, items=3)
|
||||
log.error("email.send_failed", user_id="user:123", error="SMTP timeout", retry=2)
|
||||
```
|
||||
|
||||
### TypeScript (pino)
|
||||
|
||||
```typescript
|
||||
import pino from "pino";
|
||||
|
||||
const log = pino({ level: "info" });
|
||||
|
||||
log.info({ orderId: "ord:789", total: 45.0, items: 3 }, "order.placed");
|
||||
log.error({ userId: "user:123", err, retry: 2 }, "email.send_failed");
|
||||
```
|
||||
|
||||
### Key-Value Best Practices
|
||||
|
||||
| Field | Purpose | Example |
|
||||
|-------|---------|---------|
|
||||
| `event` / message | What happened | `"order.placed"` |
|
||||
| `request_id` | Trace across services | `"req_abc123"` |
|
||||
| `user_id` | Who triggered it | `"user:456"` |
|
||||
| `duration_ms` | How long it took | `142` |
|
||||
| `error` | Error message (not stack in prod) | `"connection refused"` |
|
||||
| `component` | Which module/service | `"payment-gateway"` |
|
||||
|
||||
---
|
||||
|
||||
## Configuration by Environment
|
||||
|
||||
| Environment | Minimum Level | Structured? | Destination |
|
||||
|-------------|--------------|-------------|-------------|
|
||||
| Local dev | DEBUG | No (human-readable) | stdout |
|
||||
| CI/Test | WARNING | No | stdout |
|
||||
| Staging | DEBUG | Yes (JSON) | Log aggregator |
|
||||
| Production | INFO | Yes (JSON) | Log aggregator |
|
||||
|
||||
---
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
| Anti-Pattern | Problem | Fix |
|
||||
|-------------|---------|-----|
|
||||
| Logging PII/secrets | Security/compliance violation | Redact or mask sensitive fields |
|
||||
| `log.error()` in a loop | Log flooding, storage cost | Log once with count |
|
||||
| `log.error("Error: " + err)` | Missing context, hard to search | Use structured fields |
|
||||
| Logging at wrong level | Alert fatigue or missed issues | Follow the guide above |
|
||||
| Catch-log-rethrow | Duplicate log entries | Log at the handling site only |
|
||||
| No request_id | Cannot correlate logs | Add correlation ID middleware |
|
||||
| Logging full request bodies | Performance, storage, PII risk | Log summary fields only |
|
||||
Reference in New Issue
Block a user