|
| 1 | +# Style Guide |
| 2 | + |
| 3 | +## Overview |
| 4 | + |
| 5 | +The Strands Agents style guide aims to establish consistent formatting, naming conventions, and structure across all code in the repository. We strive to make our code clean, readable, and maintainable. |
| 6 | + |
| 7 | +Where possible, we will codify these style guidelines into our linting rules and pre-commit hooks to automate enforcement and reduce the manual review burden. |
| 8 | + |
| 9 | +## Log Formatting |
| 10 | + |
| 11 | +The format for Strands Agents logs is as follows: |
| 12 | + |
| 13 | +```python |
| 14 | +logger.debug("field1=<%s>, field2=<%s>, ... | human readable message", field1, field2, ...) |
| 15 | +``` |
| 16 | + |
| 17 | +### Guidelines |
| 18 | + |
| 19 | +1. **Context**: |
| 20 | + - Add context as `<FIELD>=<VALUE>` pairs at the beginning of the log |
| 21 | + - Many log services (CloudWatch, Splunk, etc.) look for these patterns to extract fields for searching |
| 22 | + - Use `,`'s to separate pairs |
| 23 | + - Enclose values in `<>` for readability |
| 24 | + - This is particularly helpful in displaying empty values (`field=` vs `field=<>`) |
| 25 | + - Use `%s` for string interpolation as recommended by Python logging |
| 26 | + - This is an optimization to skip string interpolation when the log level is not enabled |
| 27 | + |
| 28 | +1. **Messages**: |
| 29 | + - Add human readable messages at the end of the log |
| 30 | + - Use lowercase for consistency |
| 31 | + - Avoid punctuation (periods, exclamation points, etc.) to reduce clutter |
| 32 | + - Keep messages concise and focused on a single statement |
| 33 | + - If multiple statements are needed, separate them with the pipe character (`|`) |
| 34 | + - Example: `"processing request | starting validation"` |
| 35 | + |
| 36 | +### Examples |
| 37 | + |
| 38 | +#### Good |
| 39 | + |
| 40 | +```python |
| 41 | +logger.debug("user_id=<%s>, action=<%s> | user performed action", user_id, action) |
| 42 | +logger.info("request_id=<%s>, duration_ms=<%d> | request completed", request_id, duration) |
| 43 | +logger.warning("attempt=<%d>, max_attempts=<%d> | retry limit approaching", attempt, max_attempts) |
| 44 | +``` |
| 45 | + |
| 46 | +#### Poor |
| 47 | + |
| 48 | +```python |
| 49 | +# Avoid: No structured fields, direct variable interpolation in message |
| 50 | +logger.debug(f"User {user_id} performed action {action}") |
| 51 | + |
| 52 | +# Avoid: Inconsistent formatting, punctuation |
| 53 | +logger.info("Request completed in %d ms.", duration) |
| 54 | + |
| 55 | +# Avoid: No separation between fields and message |
| 56 | +logger.warning("Retry limit approaching! attempt=%d max_attempts=%d", attempt, max_attempts) |
| 57 | +``` |
| 58 | + |
| 59 | +By following these log formatting guidelines, we ensure that logs are both human-readable and machine-parseable, making debugging and monitoring more efficient. |
0 commit comments