logwarden 0.3.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- logwarden/__init__.py +7 -0
- logwarden/__main__.py +5 -0
- logwarden/_data/docs/rules.md +118 -0
- logwarden/_data/docs/standard.md +160 -0
- logwarden/_data/policies/logwarden.rego +101 -0
- logwarden/_data/registry/logwarden.yaml +33 -0
- logwarden/_data/registry/manifest.yaml +6 -0
- logwarden/_data/rules.json +56 -0
- logwarden/_data/templates/AGENTS.snippet.md +14 -0
- logwarden/_data/templates/logwarden-fields.yaml +24 -0
- logwarden/_data/weaver.toml +3 -0
- logwarden/check.py +222 -0
- logwarden/cli.py +187 -0
- logwarden/config.py +56 -0
- logwarden/data.py +30 -0
- logwarden/mcp_server.py +95 -0
- logwarden/output.py +37 -0
- logwarden/pytest_plugin.py +48 -0
- logwarden/weaver.py +123 -0
- logwarden-0.3.0.dist-info/METADATA +114 -0
- logwarden-0.3.0.dist-info/RECORD +24 -0
- logwarden-0.3.0.dist-info/WHEEL +4 -0
- logwarden-0.3.0.dist-info/entry_points.txt +5 -0
- logwarden-0.3.0.dist-info/licenses/LICENSE +202 -0
logwarden/__init__.py
ADDED
logwarden/__main__.py
ADDED
|
@@ -0,0 +1,118 @@
|
|
|
1
|
+
# Rules
|
|
2
|
+
|
|
3
|
+
Every rule logwarden reports, with a failing line and the fix. `logwarden rules <id>`
|
|
4
|
+
prints the short version. The standard behind them is in [standard.md](standard.md).
|
|
5
|
+
|
|
6
|
+
## adr_missing_required
|
|
7
|
+
|
|
8
|
+
A line has no `service.name`, `service.version` or `deployment.environment.name`.
|
|
9
|
+
|
|
10
|
+
```json
|
|
11
|
+
{"level":"info","event":"started","logger":"app"} ❌
|
|
12
|
+
{"level":"info","event":"started","logger":"app","service.name":"billing-api",
|
|
13
|
+
"service.version":"1.4.2","deployment.environment.name":"production"} ✅
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
**Fix:** add these fields in one shared processor or formatter that every log line passes
|
|
17
|
+
through, including third-party loggers. Don't add them at call sites. If only some lines
|
|
18
|
+
fail, those lines bypass the shared formatter, usually because a library logger isn't
|
|
19
|
+
routed through it.
|
|
20
|
+
|
|
21
|
+
## adr_event_name
|
|
22
|
+
|
|
23
|
+
`event` isn't a constant snake_case name.
|
|
24
|
+
|
|
25
|
+
```python
|
|
26
|
+
log.info(f"Loaded {n} models") # ❌ event = "Loaded 3 models"
|
|
27
|
+
log.info("models_loaded", models_count=n) # ✅
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
**Fix:** pick a fixed name in past tense or as a noun phrase, and move the variable parts into
|
|
31
|
+
fields. Lines from third-party libraries often fail this too. Map their message into a
|
|
32
|
+
field (e.g. `message`) and set a fixed `event` in the shared formatter, or silence the logger.
|
|
33
|
+
|
|
34
|
+
## adr_banned_synonym
|
|
35
|
+
|
|
36
|
+
A field uses a common ad-hoc name for something semconv already names. The message says
|
|
37
|
+
which name to use.
|
|
38
|
+
|
|
39
|
+
| Banned | Use |
|
|
40
|
+
|---|---|
|
|
41
|
+
| `status`, `status_code` | `http.response.status_code` |
|
|
42
|
+
| `path` | `url.path` or `http.route` |
|
|
43
|
+
| `method` | `http.request.method` |
|
|
44
|
+
| `url` | `url.full` |
|
|
45
|
+
| `host` | `server.address` |
|
|
46
|
+
| `model` | `gen_ai.request.model` |
|
|
47
|
+
| `error`, `err`, `exception`, `traceback` | log with `exc_info=True`, or `error.type` |
|
|
48
|
+
| `uid` | `user.id` |
|
|
49
|
+
| `env` | `deployment.environment.name` |
|
|
50
|
+
| `headers` | specific safe fields; never whole headers |
|
|
51
|
+
|
|
52
|
+
**Fix:** rename the field. In structlog, dotted names are passed as `**{"http.route": route}`.
|
|
53
|
+
|
|
54
|
+
## adr_semconv_prefix
|
|
55
|
+
|
|
56
|
+
A field looks like a semconv name written with underscores, like `http_route` or
|
|
57
|
+
`db_system_name`.
|
|
58
|
+
|
|
59
|
+
**Fix:** use the dotted name the message suggests (`http.route`). If it's really a
|
|
60
|
+
domain field, rename it so it doesn't start with a semconv namespace.
|
|
61
|
+
|
|
62
|
+
## adr_environment_value
|
|
63
|
+
|
|
64
|
+
`deployment.environment.name` isn't `development`, `staging`, `test` or `production`.
|
|
65
|
+
|
|
66
|
+
**Fix:** map your config values (`dev`, `prod`, `local`) to these four names in one place.
|
|
67
|
+
|
|
68
|
+
## adr_failure_context
|
|
69
|
+
|
|
70
|
+
A `warning`/`error` line, or an event ending in `_failed`, doesn't say what failed. It has
|
|
71
|
+
none of `exception.type`, `error.type` or `http.response.status_code`.
|
|
72
|
+
|
|
73
|
+
```python
|
|
74
|
+
except Exception:
|
|
75
|
+
log.error("sync_failed") # ❌
|
|
76
|
+
except Exception:
|
|
77
|
+
log.error("sync_failed", exc_info=True) # ✅ adds exception.type
|
|
78
|
+
log.warning("quota_low", **{"error.type": "quota"}) # ✅ no exception involved
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
**Fix:** pass `exc_info=True` inside `except`, or set `error.type` to a short stable code.
|
|
82
|
+
For HTTP failures, add `http.response.status_code`. If the line isn't a failure, lower its
|
|
83
|
+
level.
|
|
84
|
+
|
|
85
|
+
## missing_attribute
|
|
86
|
+
|
|
87
|
+
The field isn't in OTel semconv, isn't one of logwarden's shared fields, and isn't in the
|
|
88
|
+
project's `logwarden-fields.yaml`.
|
|
89
|
+
|
|
90
|
+
**Fix**, in this order:
|
|
91
|
+
1. A semconv name exists for it, so use that. Search the
|
|
92
|
+
[attribute registry](https://opentelemetry.io/docs/specs/semconv/registry/attributes/).
|
|
93
|
+
2. It's a real domain field (safe, snake_case, no semconv prefix), so declare it in
|
|
94
|
+
`logwarden-fields.yaml`.
|
|
95
|
+
3. It's noise, or it's sensitive (`payload`, `body`, `prompt`), so stop logging it.
|
|
96
|
+
|
|
97
|
+
Don't declare a field just to make the check pass. The fields file is the list of what
|
|
98
|
+
the service is allowed to log.
|
|
99
|
+
|
|
100
|
+
## deprecated
|
|
101
|
+
|
|
102
|
+
A semconv field has been renamed. The message gives the replacement.
|
|
103
|
+
|
|
104
|
+
**Fix:** rename it. Example: `gen_ai.system` → `gen_ai.provider.name`.
|
|
105
|
+
|
|
106
|
+
## type_mismatch
|
|
107
|
+
|
|
108
|
+
A field has a different type from the one semconv declares, e.g. `http.response.status_code` as
|
|
109
|
+
`"200"`.
|
|
110
|
+
|
|
111
|
+
**Fix:** log the declared type.
|
|
112
|
+
|
|
113
|
+
## Not failing
|
|
114
|
+
|
|
115
|
+
- `undefined_enum_variant` (information): a value isn't in a semconv enum. It's shown as a
|
|
116
|
+
count and doesn't fail the check.
|
|
117
|
+
- Non-JSON lines are counted as `skipped_lines`. They don't fail the check yet, but under
|
|
118
|
+
standard §1 they shouldn't exist.
|
|
@@ -0,0 +1,160 @@
|
|
|
1
|
+
# Logging standard
|
|
2
|
+
|
|
3
|
+
What a good log line looks like, for any service. logwarden checks the parts marked
|
|
4
|
+
**[checked]**. The rest is for code review. Each rule id links to its entry in
|
|
5
|
+
[rules.md](rules.md).
|
|
6
|
+
|
|
7
|
+
The standard builds on the OpenTelemetry
|
|
8
|
+
[Logs Data Model](https://opentelemetry.io/docs/specs/otel/logs/data-model/) and
|
|
9
|
+
[semantic conventions](https://opentelemetry.io/docs/specs/semconv/registry/attributes/)
|
|
10
|
+
(semconv), so logs use the same names as traces and metrics.
|
|
11
|
+
|
|
12
|
+
## 1. Format
|
|
13
|
+
|
|
14
|
+
- One JSON object per line, written to stdout. The platform collects it. The service
|
|
15
|
+
doesn't write log files or ship logs itself.
|
|
16
|
+
- Third-party library logs go through the same formatter, so every line is JSON.
|
|
17
|
+
- Human-readable console output is for local development only.
|
|
18
|
+
- `timestamp` is ISO-8601 UTC.
|
|
19
|
+
|
|
20
|
+
## 2. Field names
|
|
21
|
+
|
|
22
|
+
- **[checked]** If semconv has a name for something, use it. Don't invent a synonym.
|
|
23
|
+
[`adr_banned_synonym`](rules.md#adr_banned_synonym),
|
|
24
|
+
[`adr_semconv_prefix`](rules.md#adr_semconv_prefix),
|
|
25
|
+
[`missing_attribute`](rules.md#missing_attribute),
|
|
26
|
+
[`deprecated`](rules.md#deprecated)
|
|
27
|
+
|
|
28
|
+
| Concept | Use | Not |
|
|
29
|
+
|---|---|---|
|
|
30
|
+
| HTTP | `http.request.method`, `http.route`, `url.path`, `http.response.status_code` | `method`, `path`, `status` |
|
|
31
|
+
| Errors | `exception.type`, `exception.message`, `exception.stacktrace`, `error.type` | `error`, `err`, `traceback` |
|
|
32
|
+
| Outbound calls | `server.address`, `server.port` | `host`, `upstream` |
|
|
33
|
+
| DB | `db.system.name`, `db.operation.name`, `db.collection.name` | `table` |
|
|
34
|
+
| LLM | `gen_ai.provider.name`, `gen_ai.request.model`, `gen_ai.usage.input_tokens` | `model`, `tokens_in` |
|
|
35
|
+
| User | `user.id` | `uid`, `username` |
|
|
36
|
+
|
|
37
|
+
- **Domain fields** with no semconv name are `snake_case` without dots: `job_id`,
|
|
38
|
+
`rows_imported`. They must not start with a semconv namespace (`http_`, `db_`, `user_`, …).
|
|
39
|
+
Declare them in `logwarden-fields.yaml`, otherwise they fail as unknown.
|
|
40
|
+
- Units go in the name: `duration_ms`, `size_bytes`.
|
|
41
|
+
|
|
42
|
+
## 3. Required fields
|
|
43
|
+
|
|
44
|
+
**[checked]** Every line has:
|
|
45
|
+
|
|
46
|
+
| Field | Example |
|
|
47
|
+
|---|---|
|
|
48
|
+
| `timestamp`, `level`, `event`, `logger` | |
|
|
49
|
+
| `service.name` | `billing-api` |
|
|
50
|
+
| `service.version` | `1.4.2` |
|
|
51
|
+
| `deployment.environment.name` | one of `development`, `staging`, `test`, `production` |
|
|
52
|
+
| `trace_id`, `span_id` | when a trace span is active (W3C hex) |
|
|
53
|
+
|
|
54
|
+
Add the resource fields in one shared processor or formatter, not at each call site.
|
|
55
|
+
[`adr_missing_required`](rules.md#adr_missing_required),
|
|
56
|
+
[`adr_environment_value`](rules.md#adr_environment_value)
|
|
57
|
+
|
|
58
|
+
## 4. Event names
|
|
59
|
+
|
|
60
|
+
**[checked]** `event` is a constant snake_case name, like `import_completed` or
|
|
61
|
+
`upstream_call_failed`. Variable data goes in fields.
|
|
62
|
+
[`adr_event_name`](rules.md#adr_event_name)
|
|
63
|
+
|
|
64
|
+
```python
|
|
65
|
+
log.info(f"Imported {n} rows") # ❌
|
|
66
|
+
log.info("import_completed", rows_imported=n) # ✅
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
## 5. Levels
|
|
70
|
+
|
|
71
|
+
| Level | For |
|
|
72
|
+
|---|---|
|
|
73
|
+
| `error` | The operation failed and someone needs to look at it. |
|
|
74
|
+
| `warning` | Recovered, degraded or unexpected (a retry, a fallback). |
|
|
75
|
+
| `info` | Lifecycle and business events, a few per request or job. Never inside per-item loops. |
|
|
76
|
+
| `debug` | Developer detail. Off in production. |
|
|
77
|
+
|
|
78
|
+
## 6. Exceptions
|
|
79
|
+
|
|
80
|
+
- Log an exception once, where it's handled. Don't log it and then re-raise.
|
|
81
|
+
- Log it with the exception attached (`exc_info=True` / `log.exception`), so that
|
|
82
|
+
`exception.type`, `exception.message` and `exception.stacktrace` are filled in. Never
|
|
83
|
+
log `error=str(e)`.
|
|
84
|
+
|
|
85
|
+
## 7. Correlation
|
|
86
|
+
|
|
87
|
+
- Add `trace_id`/`span_id` from the active OTel span in a shared processor.
|
|
88
|
+
- Bind `request_id` and `job_id` once per request or job (contextvars), and clear them at
|
|
89
|
+
the start of each request or job.
|
|
90
|
+
|
|
91
|
+
## 8. Never log
|
|
92
|
+
|
|
93
|
+
Secrets, tokens, auth headers, credentials in DSNs. LLM prompts and completions, chat
|
|
94
|
+
messages, user-uploaded data, full request or response bodies. Personal data unless it's
|
|
95
|
+
required. Log IDs, sizes and counts instead.
|
|
96
|
+
|
|
97
|
+
## 9. Noise
|
|
98
|
+
|
|
99
|
+
Silence health-check and metrics paths. Set chatty third-party loggers to `WARNING`.
|
|
100
|
+
Logs explain *why*. Counts and latencies belong in metrics.
|
|
101
|
+
|
|
102
|
+
## 10. Debuggable failures
|
|
103
|
+
|
|
104
|
+
A failure line must be enough to diagnose the problem without turning on debug.
|
|
105
|
+
|
|
106
|
+
- **[checked]** Every `warning`/`error` line and every `*_failed` event has
|
|
107
|
+
`exception.type`, `error.type` or `http.response.status_code`.
|
|
108
|
+
[`adr_failure_context`](rules.md#adr_failure_context)
|
|
109
|
+
- Log the cause at `warning`/`error`. Never log it only at `debug`.
|
|
110
|
+
- For a failed outbound call, log:
|
|
111
|
+
|
|
112
|
+
| Field | Example |
|
|
113
|
+
|---|---|
|
|
114
|
+
| `server.address` | `api.provider.example` |
|
|
115
|
+
| `http.response.status_code` | `429` |
|
|
116
|
+
| `error.type` | `rate_limit_exceeded` (upstream code, or the exception class) |
|
|
117
|
+
| `duration_ms` | `30012.4` |
|
|
118
|
+
| `upstream_request_id` | the upstream's request id header |
|
|
119
|
+
| `upstream_error_message` | the upstream error message, scrubbed, at most 500 chars |
|
|
120
|
+
|
|
121
|
+
- Never log the raw upstream response body.
|
|
122
|
+
|
|
123
|
+
```python
|
|
124
|
+
except httpx.HTTPStatusError as e:
|
|
125
|
+
log.error("upstream_call_failed", exc_info=True,
|
|
126
|
+
duration_ms=elapsed_ms,
|
|
127
|
+
upstream_request_id=e.response.headers.get("x-request-id"),
|
|
128
|
+
**{"server.address": e.response.request.url.host,
|
|
129
|
+
"http.response.status_code": e.response.status_code,
|
|
130
|
+
"error.type": extract_error_code(e.response) or type(e).__name__})
|
|
131
|
+
raise
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
## Reference Python setup (structlog)
|
|
135
|
+
|
|
136
|
+
```python
|
|
137
|
+
shared = [
|
|
138
|
+
structlog.contextvars.merge_contextvars,
|
|
139
|
+
structlog.stdlib.add_logger_name,
|
|
140
|
+
structlog.stdlib.add_log_level,
|
|
141
|
+
structlog.processors.TimeStamper(fmt="iso", utc=True),
|
|
142
|
+
add_service_resource, # service.name / service.version / deployment.environment.name
|
|
143
|
+
add_otel_trace_context, # trace_id / span_id
|
|
144
|
+
exception_to_semconv, # exception.type / .message / .stacktrace
|
|
145
|
+
redact_sensitive,
|
|
146
|
+
]
|
|
147
|
+
# stdlib loggers: logging.Handler with structlog.stdlib.ProcessorFormatter(
|
|
148
|
+
# foreign_pre_chain=shared, processor=structlog.processors.JSONRenderer())
|
|
149
|
+
|
|
150
|
+
def add_otel_trace_context(_, __, event_dict):
|
|
151
|
+
ctx = opentelemetry.trace.get_current_span().get_span_context()
|
|
152
|
+
if ctx.is_valid:
|
|
153
|
+
event_dict["trace_id"] = format(ctx.trace_id, "032x")
|
|
154
|
+
event_dict["span_id"] = format(ctx.span_id, "016x")
|
|
155
|
+
return event_dict
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
Notes: `gen_ai.*` attributes now live in the
|
|
159
|
+
[OTel GenAI semantic conventions](https://github.com/open-telemetry/semantic-conventions-genai)
|
|
160
|
+
repository and are still changing. Follow logwarden's `deprecated` findings when they're renamed.
|
|
@@ -0,0 +1,101 @@
|
|
|
1
|
+
package live_check_advice
|
|
2
|
+
|
|
3
|
+
# Logging-standard rules evaluated by `weaver registry live-check --advice-policies`.
|
|
4
|
+
# Weaver runs this once per sample (one log record, or one attribute of it),
|
|
5
|
+
# so rules here can only judge a single line. Rule ids and fix hints are
|
|
6
|
+
# documented in lib/rules.json and docs/rules.md; keep all three in sync.
|
|
7
|
+
|
|
8
|
+
import rego.v1
|
|
9
|
+
|
|
10
|
+
# banned key -> what to log instead
|
|
11
|
+
banned := {
|
|
12
|
+
"status": "http.response.status_code",
|
|
13
|
+
"status_code": "http.response.status_code",
|
|
14
|
+
"path": "url.path or http.route",
|
|
15
|
+
"method": "http.request.method",
|
|
16
|
+
"url": "url.full",
|
|
17
|
+
"host": "server.address",
|
|
18
|
+
"model": "gen_ai.request.model",
|
|
19
|
+
"traceback": "exception.stacktrace (log with exc_info=True)",
|
|
20
|
+
"err": "exc_info=True or error.type",
|
|
21
|
+
"error": "exc_info=True or error.type",
|
|
22
|
+
"exception": "exception.type / exception.message (log with exc_info=True)",
|
|
23
|
+
"uid": "user.id",
|
|
24
|
+
"env": "deployment.environment.name",
|
|
25
|
+
"headers": "specific safe fields; never log whole headers",
|
|
26
|
+
}
|
|
27
|
+
|
|
28
|
+
semconv_roots := ["http_", "db_", "url_", "server_", "client_", "exception_",
|
|
29
|
+
"service_", "user_", "gen_ai_", "code_", "messaging_"]
|
|
30
|
+
|
|
31
|
+
required := {"service.name", "service.version", "deployment.environment.name"}
|
|
32
|
+
|
|
33
|
+
environments := {"development", "staging", "test", "production"}
|
|
34
|
+
|
|
35
|
+
# §12: at least one of these must be on every warning/error line.
|
|
36
|
+
failure_keys := {"exception.type", "error.type", "http.response.status_code"}
|
|
37
|
+
|
|
38
|
+
make_advice(advice_type, advice_level, advice_context, message) := {
|
|
39
|
+
"type": "advice",
|
|
40
|
+
"advice_type": advice_type,
|
|
41
|
+
"advice_level": advice_level,
|
|
42
|
+
"advice_context": advice_context,
|
|
43
|
+
"message": message,
|
|
44
|
+
}
|
|
45
|
+
|
|
46
|
+
present_keys := {a.name | some a in input.sample.log.attributes}
|
|
47
|
+
|
|
48
|
+
# §2 banned synonyms
|
|
49
|
+
deny contains make_advice("adr_banned_synonym", "violation", {"attribute_key": name}, msg) if {
|
|
50
|
+
name := input.sample.attribute.name
|
|
51
|
+
use := banned[name]
|
|
52
|
+
msg := sprintf("§2: '%s' is a banned synonym; use %s", [name, use])
|
|
53
|
+
}
|
|
54
|
+
|
|
55
|
+
# §2 undotted key that shadows a semconv namespace
|
|
56
|
+
deny contains make_advice("adr_semconv_prefix", "violation", {"attribute_key": name}, msg) if {
|
|
57
|
+
name := input.sample.attribute.name
|
|
58
|
+
not contains(name, ".")
|
|
59
|
+
some p in semconv_roots
|
|
60
|
+
startswith(name, p)
|
|
61
|
+
dotted := replace(replace(name, "_", "."), "gen.ai", "gen_ai")
|
|
62
|
+
msg := sprintf("§2: '%s' uses '_' where semconv uses '.'; probably '%s'", [name, dotted])
|
|
63
|
+
}
|
|
64
|
+
|
|
65
|
+
# §3 documented deployment.environment.name values
|
|
66
|
+
deny contains make_advice("adr_environment_value", "violation", {"attribute_key": name, "value": v}, msg) if {
|
|
67
|
+
name := input.sample.attribute.name
|
|
68
|
+
name == "deployment.environment.name"
|
|
69
|
+
v := input.sample.attribute.value
|
|
70
|
+
not environments[v]
|
|
71
|
+
msg := sprintf("§3: environment '%s' must be one of development, staging, test, production", [v])
|
|
72
|
+
}
|
|
73
|
+
|
|
74
|
+
# §3 required resource fields on every record
|
|
75
|
+
deny contains make_advice("adr_missing_required", "violation", {"attribute_key": k}, msg) if {
|
|
76
|
+
input.sample.log
|
|
77
|
+
some k in required
|
|
78
|
+
not present_keys[k]
|
|
79
|
+
msg := sprintf("§3: required field '%s' missing", [k])
|
|
80
|
+
}
|
|
81
|
+
|
|
82
|
+
# §4 event must be constant snake_case
|
|
83
|
+
deny contains make_advice("adr_event_name", "violation", {"event": ev}, msg) if {
|
|
84
|
+
input.sample.log
|
|
85
|
+
ev := input.sample.log.body
|
|
86
|
+
not regex.match(`^[a-z][a-z0-9_]*$`, ev)
|
|
87
|
+
msg := sprintf("§4: event '%s' must be a constant snake_case name", [ev])
|
|
88
|
+
}
|
|
89
|
+
|
|
90
|
+
# §12 warning/error lines and *_failed events must say what failed
|
|
91
|
+
deny contains make_advice("adr_failure_context", "violation", {"event": ev}, msg) if {
|
|
92
|
+
input.sample.log
|
|
93
|
+
ev := input.sample.log.body
|
|
94
|
+
is_failure(input.sample.log)
|
|
95
|
+
count(failure_keys & present_keys) == 0
|
|
96
|
+
msg := sprintf("§12: '%s' is a failure line without exception.type, error.type or http.response.status_code", [ev])
|
|
97
|
+
}
|
|
98
|
+
|
|
99
|
+
is_failure(log) if log.severity_number >= 13
|
|
100
|
+
|
|
101
|
+
is_failure(log) if endswith(log.body, "_failed")
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
# Non-semconv fields that ADR-0001 allows in every service (§2/§3/§12).
|
|
2
|
+
# Service-specific fields belong in the consuming repo's own registry overlay.
|
|
3
|
+
groups:
|
|
4
|
+
- id: registry.logwarden.log
|
|
5
|
+
type: attribute_group
|
|
6
|
+
display_name: logwarden common log fields
|
|
7
|
+
brief: Domain fields allowed in logs alongside OTel semantic conventions.
|
|
8
|
+
attributes:
|
|
9
|
+
- id: logger
|
|
10
|
+
type: string
|
|
11
|
+
stability: development
|
|
12
|
+
brief: Logger name (Python module path).
|
|
13
|
+
examples: ["app.core.app"]
|
|
14
|
+
- id: request_id
|
|
15
|
+
type: string
|
|
16
|
+
stability: development
|
|
17
|
+
brief: Correlation id taken from the x-request-id header.
|
|
18
|
+
examples: ["9f1c2d"]
|
|
19
|
+
- id: duration_ms
|
|
20
|
+
type: double
|
|
21
|
+
stability: development
|
|
22
|
+
brief: Duration in milliseconds.
|
|
23
|
+
examples: [12.5]
|
|
24
|
+
- id: upstream_request_id
|
|
25
|
+
type: string
|
|
26
|
+
stability: development
|
|
27
|
+
brief: Request id returned by an upstream service (ADR-0001 §12).
|
|
28
|
+
examples: ["req_abc123"]
|
|
29
|
+
- id: upstream_error_message
|
|
30
|
+
type: string
|
|
31
|
+
stability: development
|
|
32
|
+
brief: Scrubbed upstream error message, at most 500 chars (ADR-0001 §12).
|
|
33
|
+
examples: ["rate limit exceeded"]
|
|
@@ -0,0 +1,6 @@
|
|
|
1
|
+
name: logwarden
|
|
2
|
+
description: Domain log fields allowed on top of OpenTelemetry semantic conventions.
|
|
3
|
+
schema_url: https://github.com/Ingeniator/logwarden/schemas/0.1.0
|
|
4
|
+
dependencies:
|
|
5
|
+
- schema_url: https://opentelemetry.io/schemas/1.45.0
|
|
6
|
+
registry_path: https://github.com/open-telemetry/semantic-conventions@v1.45.0[model]
|
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
{
|
|
2
|
+
"adr_missing_required": {
|
|
3
|
+
"section": "§3",
|
|
4
|
+
"title": "Required resource fields on every line",
|
|
5
|
+
"hint": "Add service.name, service.version and deployment.environment.name in one shared processor/formatter, not at call sites.",
|
|
6
|
+
"doc": "docs/rules.md#adr_missing_required"
|
|
7
|
+
},
|
|
8
|
+
"adr_event_name": {
|
|
9
|
+
"section": "§4",
|
|
10
|
+
"title": "Event is a constant snake_case name",
|
|
11
|
+
"hint": "Use a fixed name like import_completed and move variable data into fields: log.info(\"import_completed\", rows_imported=n).",
|
|
12
|
+
"doc": "docs/rules.md#adr_event_name"
|
|
13
|
+
},
|
|
14
|
+
"adr_banned_synonym": {
|
|
15
|
+
"section": "§2",
|
|
16
|
+
"title": "Banned synonym for an OTel semconv field",
|
|
17
|
+
"hint": "Rename the field to the semconv name given in the message.",
|
|
18
|
+
"doc": "docs/rules.md#adr_banned_synonym"
|
|
19
|
+
},
|
|
20
|
+
"adr_semconv_prefix": {
|
|
21
|
+
"section": "§2",
|
|
22
|
+
"title": "Semconv name written with underscores",
|
|
23
|
+
"hint": "Use the dotted semconv key (http_route -> http.route). In structlog pass it as **{\"http.route\": value}.",
|
|
24
|
+
"doc": "docs/rules.md#adr_semconv_prefix"
|
|
25
|
+
},
|
|
26
|
+
"adr_environment_value": {
|
|
27
|
+
"section": "§3",
|
|
28
|
+
"title": "Environment value is not a documented one",
|
|
29
|
+
"hint": "Set deployment.environment.name to development, staging, test or production.",
|
|
30
|
+
"doc": "docs/rules.md#adr_environment_value"
|
|
31
|
+
},
|
|
32
|
+
"adr_failure_context": {
|
|
33
|
+
"section": "§12",
|
|
34
|
+
"title": "Failure line does not say what failed",
|
|
35
|
+
"hint": "On warning/error and *_failed lines log exc_info=True (gives exception.type), or error.type, or http.response.status_code.",
|
|
36
|
+
"doc": "docs/rules.md#adr_failure_context"
|
|
37
|
+
},
|
|
38
|
+
"missing_attribute": {
|
|
39
|
+
"section": "§2",
|
|
40
|
+
"title": "Unknown field",
|
|
41
|
+
"hint": "Use the OTel semconv name if one exists. If it is a real domain field, declare it in logwarden-fields.yaml.",
|
|
42
|
+
"doc": "docs/rules.md#missing_attribute"
|
|
43
|
+
},
|
|
44
|
+
"deprecated": {
|
|
45
|
+
"section": "§2",
|
|
46
|
+
"title": "Deprecated semconv field",
|
|
47
|
+
"hint": "Rename to the replacement named in the message.",
|
|
48
|
+
"doc": "docs/rules.md#deprecated"
|
|
49
|
+
},
|
|
50
|
+
"type_mismatch": {
|
|
51
|
+
"section": "§2",
|
|
52
|
+
"title": "Field has the wrong type",
|
|
53
|
+
"hint": "Log the type the registry declares (e.g. http.response.status_code is an int, not a string).",
|
|
54
|
+
"doc": "docs/rules.md#type_mismatch"
|
|
55
|
+
}
|
|
56
|
+
}
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
## Logging (logwarden)
|
|
2
|
+
|
|
3
|
+
This project follows the logging standard checked by
|
|
4
|
+
[logwarden](https://github.com/Ingeniator/logwarden). When you add or change code that logs:
|
|
5
|
+
|
|
6
|
+
- Use constant snake_case `event` names and OTel semconv field names
|
|
7
|
+
(`http.response.status_code`, not `status`). Log exceptions with `exc_info=True`, never
|
|
8
|
+
`error=str(e)`. Never log secrets, prompts or request/response bodies.
|
|
9
|
+
- Check what the code actually logs before you finish:
|
|
10
|
+
`LOGWARDEN_CAPTURE=/tmp/logs.jsonl pytest <tests>` and then
|
|
11
|
+
`uvx logwarden check /tmp/logs.jsonl --json`, or use the `check_logs` MCP tool.
|
|
12
|
+
- Fix findings from your own changes. Don't silence them. Project-only fields go
|
|
13
|
+
in `logwarden-fields.yaml`, but only when no semconv name exists.
|
|
14
|
+
- Details: `logwarden rules <id>` and https://github.com/Ingeniator/logwarden/blob/main/docs/rules.md.
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
# Project-only log fields for logwarden (https://github.com/Ingeniator/logwarden).
|
|
2
|
+
#
|
|
3
|
+
# Add a field here only when ALL of these are true:
|
|
4
|
+
# - OTel semantic conventions have no name for it. Check
|
|
5
|
+
# https://opentelemetry.io/docs/specs/semconv/registry/attributes/ first.
|
|
6
|
+
# - It is snake_case, has no dots and doesn't start with a semconv
|
|
7
|
+
# namespace (http_, db_, url_, server_, user_, gen_ai_, ...).
|
|
8
|
+
# - It's safe to log: no secrets, personal data, prompts or raw bodies.
|
|
9
|
+
# Fields that several services share belong in logwarden's registry/logwarden.yaml.
|
|
10
|
+
#
|
|
11
|
+
# Example:
|
|
12
|
+
#
|
|
13
|
+
# groups:
|
|
14
|
+
# - id: registry.myservice.log
|
|
15
|
+
# type: attribute_group
|
|
16
|
+
# display_name: myservice log fields
|
|
17
|
+
# brief: Fields only myservice logs.
|
|
18
|
+
# attributes:
|
|
19
|
+
# - id: job_id
|
|
20
|
+
# type: string # string | int | double | boolean | string[]
|
|
21
|
+
# stability: development
|
|
22
|
+
# brief: Background job id.
|
|
23
|
+
# examples: ["job_42"]
|
|
24
|
+
groups: []
|