playbooks

home / skills / williamzujkowski / standards / logging

logging skill

/skills/observability/logging

This skill helps you implement secure, well-documented logging patterns for observability in Python applications, improving reliability and debugging

npx playbooks add skill williamzujkowski/standards --skill logging

Review the files below or copy the command above to add this skill to your agents.

Files (4)
SKILL.md
2.0 KB
---
name: logging
description: Logging standards for logging in Observability environments. Covers best
---

# Logging

> **Quick Navigation:**
> Level 1: [Quick Start](#level-1-quick-start) (5 min) → Level 2: [Implementation](#level-2-implementation) (30 min) → Level 3: [Mastery](#level-3-mastery-resources) (Extended)

---

## Level 1: Quick Start

### Core Principles

1. **Best Practices**: Follow industry-standard patterns for observability
2. **Security First**: Implement secure defaults and validate all inputs
3. **Maintainability**: Write clean, documented, testable code
4. **Performance**: Optimize for common use cases

### Essential Checklist

- [ ] Follow established patterns for observability
- [ ] Implement proper error handling
- [ ] Add comprehensive logging
- [ ] Write unit and integration tests
- [ ] Document public interfaces

### Quick Links to Level 2

- [Core Concepts](#core-concepts)
- [Implementation Patterns](#implementation-patterns)
- [Common Pitfalls](#common-pitfalls)

---

## Level 2: Implementation

### Core Concepts

This skill covers essential practices for observability.

**Key areas include:**

- Architecture patterns
- Implementation best practices
- Testing strategies
- Performance optimization

### Implementation Patterns

Apply these patterns when working with observability:

1. **Pattern Selection**: Choose appropriate patterns for your use case
2. **Error Handling**: Implement comprehensive error recovery
3. **Monitoring**: Add observability hooks for production

### Common Pitfalls

Avoid these common mistakes:

- Skipping validation of inputs
- Ignoring edge cases
- Missing test coverage
- Poor documentation

---

## Level 3: Mastery Resources

### Reference Materials

- [Related Standards](../../docs/standards/)
- [Best Practices Guide](../../docs/guides/)

### Templates

See the `templates/` directory for starter configurations.

### External Resources

Consult official documentation and community best practices for observability.

Overview

This skill defines logging standards for observability environments to make services diagnosable, secure, and performant. It gives concise guidance on what to log, how to structure logs, and how to integrate logs with monitoring and alerting. The goal is consistent, actionable logs across projects so teams can troubleshoot and measure behavior quickly.

How this skill works

The skill inspects logging needs across layers (application, middleware, and integrations) and prescribes patterns for message structure, severity levels, and context propagation. It recommends secure defaults (no secrets in logs), standard formats (JSON with stable fields), and hooks for exporting logs to observability backends. It also outlines testing and performance considerations to prevent logging from becoming a reliability bottleneck.

When to use it

  • When starting a new service or microservice and defining observability requirements
  • When standardizing logs across multiple teams or repositories
  • When onboarding monitoring/alerting or correlating traces and metrics
  • When troubleshooting production incidents and needing consistent context
  • When auditing for sensitive data exposure or compliance needs

Best practices

  • Use structured logs (JSON) with stable field names: timestamp, level, service, trace_id, span_id, message
  • Log at appropriate levels: DEBUG for dev-only details, INFO for normal operations, WARN for recoverable issues, ERROR for failures
  • Never log secrets or PII; sanitize inputs and apply allowlists for fields
  • Attach context (request id, user id, tenant id) to correlate logs, traces, and metrics
  • Keep logging fast and non-blocking; batch and export asynchronously to avoid latency spikes
  • Write unit tests for log outputs and integration tests to validate log shipping and formatting

Example use cases

  • Instrumenting a Python web API: add middleware to inject trace/request ids and use structured loggers
  • Standardizing logs across services: adopt a shared logging helper that enforces fields and level mapping
  • Incident response: use consistent severity and context fields to filter and pivot during postmortems
  • Performance tuning: measure logging overhead and switch heavy debug statements to sampling
  • Compliance review: run static checks to ensure no secrets are emitted and logs meet retention rules

FAQ

Should I use JSON or plain text for logs?

Prefer structured JSON because it enables reliable parsing, indexing, and querying in observability backends; reserve plain text for local debugging only.

How do I avoid logging sensitive data?

Adopt a deny-by-default approach: sanitize known sensitive fields, enforce field allowlists, and run automated scans on logs and configs.