52 lines
1.7 KiB
Markdown
52 lines
1.7 KiB
Markdown
---
|
|
name: Structured Logging with Zap
|
|
description: How to correctly use the zap structured logging library in this repository instead of standard log or string formatting.
|
|
---
|
|
|
|
# Structured Logging with Zap
|
|
|
|
When adding logs to the `hireme` repository, **always** use the global `logger.Log` (which is a `zap.SugaredLogger`).
|
|
|
|
Do **NOT** use `log.Printf` or `fmt.Printf`.
|
|
Do **NOT** use `logger.Log.Infof` to format strings with variables if those variables should be structured data.
|
|
|
|
## Proper Usage (The `w` methods)
|
|
|
|
Use the `w` variants of the log methods (`Infow`, `Debugw`, `Errorw`, `Warnw`). These methods take a message string as the first argument, followed by variadic key-value pairs.
|
|
|
|
### Example: API Endpoints
|
|
|
|
Always include a `"component", "API"` field.
|
|
|
|
```go
|
|
// GOOD
|
|
logger.Log.Infow("Triggered endpoint", "component", "API", "endpoint", "/applications", "status", "success")
|
|
|
|
// BAD - String interpolation hides the data from JSON parsers
|
|
logger.Log.Infof("[API] Triggered /applications with status %s", "success")
|
|
```
|
|
|
|
### Example: Background Workers
|
|
|
|
Include the worker ID and task ID.
|
|
|
|
```go
|
|
// GOOD
|
|
logger.Log.Errorw("Task processing failed", "component", "Worker", "worker_id", id, "task_id", task.ID, "error", err)
|
|
```
|
|
|
|
### Example: Database Operations
|
|
|
|
```go
|
|
// GOOD
|
|
logger.Log.Debugw("Running query", "component", "DB", "query", "SELECT * FROM jobs")
|
|
```
|
|
|
|
## Summary of `w` Methods
|
|
|
|
- `logger.Log.Debugw(msg string, keysAndValues ...interface{})`
|
|
- `logger.Log.Infow(msg string, keysAndValues ...interface{})`
|
|
- `logger.Log.Warnw(msg string, keysAndValues ...interface{})`
|
|
- `logger.Log.Errorw(msg string, keysAndValues ...interface{})`
|
|
- `logger.Log.Fatalw(msg string, keysAndValues ...interface{})` // Note: calls os.Exit(1)
|