D-SafeLogger 0.2.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.
- d_safelogger-0.2.0.dist-info/METADATA +295 -0
- d_safelogger-0.2.0.dist-info/RECORD +34 -0
- d_safelogger-0.2.0.dist-info/WHEEL +5 -0
- d_safelogger-0.2.0.dist-info/entry_points.txt +2 -0
- d_safelogger-0.2.0.dist-info/licenses/LICENSE +190 -0
- d_safelogger-0.2.0.dist-info/top_level.txt +1 -0
- dsafelogger/__init__.py +918 -0
- dsafelogger/_async.py +102 -0
- dsafelogger/_cli.py +271 -0
- dsafelogger/_color.py +71 -0
- dsafelogger/_config_validation.py +177 -0
- dsafelogger/_constants.py +48 -0
- dsafelogger/_context.py +80 -0
- dsafelogger/_env_parser.py +135 -0
- dsafelogger/_formatter.py +381 -0
- dsafelogger/_handler.py +205 -0
- dsafelogger/_ini_loader.py +474 -0
- dsafelogger/_integrity.py +107 -0
- dsafelogger/_levels.py +204 -0
- dsafelogger/_logger.py +35 -0
- dsafelogger/_mp_attach.py +459 -0
- dsafelogger/_mp_control.py +181 -0
- dsafelogger/_mp_protocol.py +208 -0
- dsafelogger/_mp_queue.py +93 -0
- dsafelogger/_mp_runtime.py +590 -0
- dsafelogger/_pipeline.py +243 -0
- dsafelogger/_purge.py +200 -0
- dsafelogger/_routing.py +392 -0
- dsafelogger/_sink.py +116 -0
- dsafelogger/_transport.py +170 -0
- dsafelogger/_validator.py +57 -0
- dsafelogger/_writer_formatter.py +158 -0
- dsafelogger/mp/__init__.py +948 -0
- dsafelogger/py.typed +1 -0
|
@@ -0,0 +1,295 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: D-SafeLogger
|
|
3
|
+
Version: 0.2.0
|
|
4
|
+
Summary: Zero-dependency, thread-safe, append-only logging library for Python with 3-layer config pipeline
|
|
5
|
+
Author: D
|
|
6
|
+
License-Expression: Apache-2.0
|
|
7
|
+
Project-URL: Homepage, https://github.com/nightmarewalker/D-SafeLogger
|
|
8
|
+
Project-URL: Repository, https://github.com/nightmarewalker/D-SafeLogger
|
|
9
|
+
Project-URL: Documentation, https://github.com/nightmarewalker/D-SafeLogger#readme
|
|
10
|
+
Project-URL: Bug Tracker, https://github.com/nightmarewalker/D-SafeLogger/issues
|
|
11
|
+
Keywords: logging,logger,thread-safe,append-only,zero-dependency,structured-logging,json-lines,file-rotation,routing,sha256,integrity,cli
|
|
12
|
+
Classifier: Development Status :: 4 - Beta
|
|
13
|
+
Classifier: Intended Audience :: Developers
|
|
14
|
+
Classifier: Programming Language :: Python :: 3
|
|
15
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
19
|
+
Classifier: Topic :: Software Development :: Libraries
|
|
20
|
+
Classifier: Topic :: System :: Logging
|
|
21
|
+
Classifier: Operating System :: OS Independent
|
|
22
|
+
Classifier: Typing :: Typed
|
|
23
|
+
Requires-Python: >=3.11
|
|
24
|
+
Description-Content-Type: text/markdown
|
|
25
|
+
License-File: LICENSE
|
|
26
|
+
Dynamic: license-file
|
|
27
|
+
|
|
28
|
+
# D-SafeLogger
|
|
29
|
+
|
|
30
|
+
[](https://github.com/nightmarewalker/D-SafeLogger/actions/workflows/ci.yml)
|
|
31
|
+
[](https://pypi.org/project/d-safelogger/)
|
|
32
|
+
[](https://pypi.org/project/d-safelogger/)
|
|
33
|
+
[](LICENSE)
|
|
34
|
+
[](#main-features)
|
|
35
|
+
|
|
36
|
+
Languages: [English](README.md) | [日本語](README_ja.md)
|
|
37
|
+
|
|
38
|
+
## Overview
|
|
39
|
+
|
|
40
|
+
D-SafeLogger is a zero-dependency, stdlib logging-compatible logger built on Python's standard `logging` module.
|
|
41
|
+
|
|
42
|
+
It extends the standard logging path instead of replacing it. Existing `logging.getLogger()` and `logger.info()` call sites can participate without modification, while D-SafeLogger adds append-only file routing, structured JSON Lines output, contextual logging, SHA-256 sidecars, environment-based operational overrides, and Writer-owned multiprocess logging.
|
|
43
|
+
|
|
44
|
+
Append-only routing means D-SafeLogger opens the next destination file instead of renaming or truncating the active log file. This avoids the common Windows file-lock failure mode of rename-based rotation. It also sidesteps the POSIX failure mode where a rename succeeds at the filesystem layer while existing file descriptors keep writing to the previous file.
|
|
45
|
+
|
|
46
|
+
The "Safe" in the name refers to operational safety: fail-fast setup, append-only file handling, producer-side context snapshots, bounded queues, explicit timeouts, and classified delivery-state accounting.
|
|
47
|
+
|
|
48
|
+
## Installation
|
|
49
|
+
|
|
50
|
+
```bash
|
|
51
|
+
pip install d-safelogger
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
The distribution name is `d-safelogger`; the import name is `dsafelogger`.
|
|
55
|
+
|
|
56
|
+
D-SafeLogger requires Python 3.11 or newer.
|
|
57
|
+
|
|
58
|
+
## Quick Start
|
|
59
|
+
|
|
60
|
+
```python
|
|
61
|
+
from dsafelogger import ConfigureLogger, GetLogger
|
|
62
|
+
|
|
63
|
+
ConfigureLogger(log_path="./logs", pg_name="MyApp")
|
|
64
|
+
|
|
65
|
+
logger = GetLogger(__name__)
|
|
66
|
+
logger.info("Application started")
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
`pg_name` is the application name used as the prefix of routed log file names, for example `MyApp_2026-04-03.log`.
|
|
70
|
+
|
|
71
|
+
Typical text output:
|
|
72
|
+
|
|
73
|
+
```text
|
|
74
|
+
2026-04-03 09:15:22.738 [INF][app.py:6:<module>] Application started
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
To emit JSON Lines instead, set `structured=True` at configure time:
|
|
78
|
+
|
|
79
|
+
```python
|
|
80
|
+
ConfigureLogger(log_path="./logs", pg_name="MyApp", structured=True)
|
|
81
|
+
logger = GetLogger(__name__)
|
|
82
|
+
logger.info("Application started")
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
```jsonl
|
|
86
|
+
{"timestamp":"2026-04-03 09:15:22.738","level":"INF","logger":"__main__","message":"Application started"}
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
For multiprocess setup, see [Multiprocess Logging](#multiprocess-logging). For INI configuration, request context, integrity sidecars, async logging, and CLI usage, see [Tutorials / Examples](#tutorials--examples).
|
|
90
|
+
|
|
91
|
+
Configuration is fail-fast. D-SafeLogger rejects feature combinations that cannot take effect, such as cyclic routing with hash/archive retention, `routing_mode='none'` with D-SafeLogger-owned retention, or `structured=True` with custom formatter strings.
|
|
92
|
+
|
|
93
|
+
## When to Use It
|
|
94
|
+
|
|
95
|
+
Use D-SafeLogger when you want to keep standard `logging.getLogger()` call sites while adding:
|
|
96
|
+
|
|
97
|
+
- append-only local file routing,
|
|
98
|
+
- environment-driven operational overrides,
|
|
99
|
+
- optional SHA-256 sidecars and manifests,
|
|
100
|
+
- Writer-owned multiprocess file output,
|
|
101
|
+
- classified delivery-state accounting.
|
|
102
|
+
|
|
103
|
+
You probably do not need it if your application only writes to stdout/stderr and an external collector owns routing, retention, aggregation, and durability.
|
|
104
|
+
|
|
105
|
+
## Why D-SafeLogger?
|
|
106
|
+
|
|
107
|
+
D-SafeLogger extends the standard logging path rather than replacing it: you keep using `logging.getLogger()` and existing `logger.info()` call sites, and the library adds safe local-file output on top: rename-free append-only routing, fail-fast configuration, SHA-256 sidecars, sensitive-data masking, environment-driven operational control, and a parent-side multiprocess Writer.
|
|
108
|
+
|
|
109
|
+
If you already use `structlog` as a structured-logging frontend, D-SafeLogger coexists rather than replaces. `structlog` builds the event dictionary; D-SafeLogger handles file output, routing, sidecars, masking, and operational control. See [Structlog Coexistence](examples/16_structlog_coexistence.md) for two integration patterns.
|
|
110
|
+
|
|
111
|
+
## Why Routing Instead of External Rotation?
|
|
112
|
+
|
|
113
|
+
External rotation typically renames or truncates an active log file, creates a replacement, and asks the application to reopen its sink. That is plumbing for a design that mutates the active file after the fact, not the core of writing log records.
|
|
114
|
+
|
|
115
|
+
On POSIX systems, the rename can succeed even while the writer keeps writing through the old file descriptor. The filesystem call returned success, but the logger never actually moved to the new file.
|
|
116
|
+
|
|
117
|
+
D-SafeLogger avoids that dependency by choosing the destination at write time. It opens the next destination at the routing boundary instead of mutating the active file and relying on a signal/reopen handshake.
|
|
118
|
+
|
|
119
|
+
## What "Safe" Means
|
|
120
|
+
|
|
121
|
+
The "Safe" in the name is a design stance that runs across several dimensions of everyday operation, not only failure handling:
|
|
122
|
+
|
|
123
|
+
- **Startup safety:** invalid settings, inconsistent options, and unwritable destinations fail during setup. D-SafeLogger stops a broken logging configuration before the application starts doing real work, instead of silently degrading later.
|
|
124
|
+
- **File safety:** the routing layer opens the next destination instead of renaming or truncating the active log file, which avoids the common Windows failure mode where active log files cannot be renamed. It also avoids the POSIX case where a successful rename leaves the writer appending to the previous file. Routed files can be paired with SHA-256 sidecars and an optional manifest, so log content is verifiable after the fact.
|
|
125
|
+
- **Record and context safety:** request IDs, user IDs, job IDs, and other context are snapshotted on the producer side at hand-off, so listeners and Writers do not depend on live `contextvars`. Sensitive-keyword masking is applied on the Writer side using the keyword set established at configure time.
|
|
126
|
+
- **Operational control:** environment variables provide explicit runtime overrides for diagnostics, routing, hashing, log levels, and queue/timeout behavior without rebuilding or editing application code.
|
|
127
|
+
- **Concurrency and multiprocess safety:** multiprocess workers do not open the shared log files themselves. A parent-side Writer owns the sinks and accepts records over IPC, with bounded queues and explicit timeouts that keep the host process from unbounded waits.
|
|
128
|
+
- **Failure observability:** when records cannot be delivered, the runtime classifies the outcome where it can: `KnownRejected`, `KnownDropped`, or `UnexplainedLost`. Counters and shutdown summaries make abnormal scenarios describable rather than silent.
|
|
129
|
+
- **Filesystem scope:** append-only routing avoids external rename/truncate of active log files. It does not make every destination filesystem equally safe. NFS, SMB/CIFS, FUSE mounts, cloud-synced folders, container bind mounts, and in-memory filesystems can have different rename, unlink, cache, durability, or lifetime semantics. For audit-oriented deployments, prefer writing active logs to a durable local filesystem and transferring closed routed files to archive or network storage.
|
|
130
|
+
|
|
131
|
+
## Feature Comparison
|
|
132
|
+
|
|
133
|
+
This table is not an overall ranking. It shows which concerns each project treats as part of its built-in design.
|
|
134
|
+
|
|
135
|
+
Legend:
|
|
136
|
+
|
|
137
|
+
- **◎** primary strength / design centerpiece
|
|
138
|
+
- **○** supported out of the box
|
|
139
|
+
- **△** officially supported through configuration or adapters, with limited scope
|
|
140
|
+
- **—** not provided as a library feature
|
|
141
|
+
- **※n** see note for scope or conditions
|
|
142
|
+
|
|
143
|
+
| Capability | stdlib `logging` | loguru | structlog | D-SafeLogger |
|
|
144
|
+
|---|:---:|:---:|:---:|:---:|
|
|
145
|
+
| Stdlib `logging` API compatibility | ◎ | △※2 | △※3 | ◎ |
|
|
146
|
+
| Existing `logger.info()` / `getLogger()` call sites preserved | ◎ | △※2 | △※3 | ◎ |
|
|
147
|
+
| Third-party libraries using `logging.getLogger()` participate | ◎ | △※2 | △※3 | ◎ |
|
|
148
|
+
| Zero external runtime dependencies | ◎ | — | — | ◎ |
|
|
149
|
+
| Centralized setup replacing handler/formatter wiring | △※1 | ◎ | △※3 | ◎ |
|
|
150
|
+
| Text file logging | ○ | ○ | △※3 | ○ |
|
|
151
|
+
| Structured JSON Lines | —※1 | ○ | ◎ | ○ |
|
|
152
|
+
| Context propagation | △※1 | ○ | ◎ | ○ |
|
|
153
|
+
| Fail-fast configuration validation | △※4 | △※4 | △※4 | ◎ |
|
|
154
|
+
| Append-only file routing without rename/truncate | —※5 | —※6 | —※3 | ◎ |
|
|
155
|
+
| Purge / archive maintenance for routed files | —※5 | ○※6 | —※3 | ○ |
|
|
156
|
+
| SHA-256 sidecars / manifest output | — | — | —※3 | ◎ |
|
|
157
|
+
| Code / INI-dict / environment configuration layers | △※1 | △※7 | △※7 | ○ |
|
|
158
|
+
| Environment-only diagnostic mode | — | —※8 | — | ◎ |
|
|
159
|
+
| Async hand-off with context snapshot | △※1 | ○※9 | △※3 | ○ |
|
|
160
|
+
| Multiprocess file output via parent-side Writer | —※10 | —※9 | —※3 | ◎ |
|
|
161
|
+
| Delivery-state accounting (multiprocess) | — | — | — | ◎ |
|
|
162
|
+
|
|
163
|
+
Notes:
|
|
164
|
+
|
|
165
|
+
- **※1** stdlib `logging` provides primitives such as handlers, filters, formatters, `dictConfig`, `QueueHandler`, and `QueueListener`; JSON formatting, context policy, layered environment handling, and end-to-end validation require application composition or custom classes.
|
|
166
|
+
- **※2** loguru can coexist with stdlib logging through documented handler patterns, but it is primarily a replacement-style logger API rather than native stdlib API compatibility.
|
|
167
|
+
- **※3** structlog is primarily a structured-logging frontend. It integrates with stdlib logging and selected output backends, but file lifecycle, retention, integrity sidecars, and multiprocess sink ownership are backend or application responsibilities.
|
|
168
|
+
- **※4** these projects validate parts of their own configuration, but D-SafeLogger treats merged configuration, writable destinations, and safety invariants as a startup contract.
|
|
169
|
+
- **※5** stdlib rotation handlers are not append-only rerouting facilities; rename-free routing and routed-file maintenance require custom handlers or external operational tooling. On POSIX systems, a successful rename can still leave the writer attached to the previous file descriptor, so filesystem-level rotation success does not guarantee that new records are going to the new file.
|
|
170
|
+
- **※6** loguru provides built-in rotation, retention, and compression, but not D-SafeLogger-style append-only rerouting that avoids renaming or truncating the active file. D-SafeLogger avoids the pattern where an active file is changed first and correctness depends on a later reopen.
|
|
171
|
+
- **※7** loguru and structlog support code-based configuration and selected defaults; D-SafeLogger's explicit code / INI-dict / environment precedence model is a separate built-in configuration layer.
|
|
172
|
+
- **※8** loguru provides rich exception diagnostics, but D-SafeLogger's diagnostic mode is intentionally environment-only as a safety boundary.
|
|
173
|
+
- **※9** loguru's `enqueue=True` provides queued, multiprocessing-safe logging, but it is not a parent-side Writer ownership model and does not expose D-SafeLogger-style delivery-state accounting.
|
|
174
|
+
- **※10** stdlib logging can be assembled into a listener/queue architecture, but this is not a packaged parent-side Writer API.
|
|
175
|
+
|
|
176
|
+
**Delivery-state accounting** refers to per-record classification (`KnownRejected`, `KnownDropped`, `UnexplainedLost`) exposed through counters and shutdown summaries. See [`examples/12_multiprocess_logging.md`](examples/12_multiprocess_logging.md) and [BENCHMARK.md](BENCHMARK.md).
|
|
177
|
+
|
|
178
|
+
## Main Features
|
|
179
|
+
|
|
180
|
+
- **Zero runtime dependencies:** the package uses only the Python standard library at runtime.
|
|
181
|
+
- **Stdlib logging compatibility:** existing `logger.info()` calls and libraries that use `logging.getLogger()` participate in the same logging setup.
|
|
182
|
+
- **Centralized setup:** replace common `basicConfig()`, `dictConfig()`, formatter, handler, and rotating-file boilerplate with `ConfigureLogger()`.
|
|
183
|
+
- **Fail-fast initialization:** invalid configuration and unwritable log destinations fail during setup instead of degrading silently.
|
|
184
|
+
- **Append-only file routing:** the routing layer opens the next destination instead of renaming or truncating the active log file. This avoids the common Windows failure mode where active log files cannot be renamed, and it avoids the POSIX case where a writer may continue writing to the previous file after a successful rename.
|
|
185
|
+
- **Classified delivery state:** loss, reject, and drop events are not treated as invisible file gaps. When records cannot be delivered, the runtime classifies the outcome as known-rejected, known-dropped, or unexplained-lost where applicable.
|
|
186
|
+
- **Bounded logging path:** D-SafeLogger uses bounded queues, explicit timeouts, and explicit rejection paths to avoid unbounded logging-side waits in the host process.
|
|
187
|
+
- **Structured JSON Lines:** emit log records as JSON fields for log collectors and observability pipelines.
|
|
188
|
+
- **Contextual logging:** attach request IDs, user IDs, job IDs, or other context with thread-safe and async-safe propagation. Producer-side context snapshots are taken at hand-off so listeners and Writers do not look up live `contextvars`.
|
|
189
|
+
- **Integrity sidecars:** generate SHA-256 sidecars and optional manifest entries for routed log files.
|
|
190
|
+
- **Operational overrides:** change log level, module routing, console output, color, hashing, config file path, and queue/timeout parameters through environment variables, typically to raise diagnostics in production without code changes.
|
|
191
|
+
- **Environment-only diagnostic mode:** opt in via `D_LOG_DIAGNOSE=1` for `f_locals` expansion of selected frames; deliberately not exposed through INI or arguments, so it cannot be enabled by an unowned configuration file.
|
|
192
|
+
- **Async transport:** opt in to queue-backed logging when application threads should avoid direct sink writes.
|
|
193
|
+
- **Custom log levels:** `register_level()` to add named levels alongside the built-in five before `ConfigureLogger()`.
|
|
194
|
+
- **External rotation reopen:** `ReopenLogFiles()` and its multiprocess equivalent reopen sinks after external log rotators such as `logrotate`.
|
|
195
|
+
- **Delivery-state visibility (multiprocess):** worker logging exposes per-record delivery-state counters and shutdown summaries, so abnormal shutdowns, sink unavailability, and worker crashes are described rather than silent.
|
|
196
|
+
|
|
197
|
+
## Multiprocess Logging
|
|
198
|
+
|
|
199
|
+
`dsafelogger.mp` is for applications where multiple worker processes need to send logs to shared destinations without each worker independently opening the same files.
|
|
200
|
+
|
|
201
|
+
In this mode, a parent-side Writer owns the file sinks. Workers attach to the Writer and submit log records through IPC. This centralizes file ownership and exposes delivery-state counters such as accepted, delivered, rejected, dropped, and unexplained-lost.
|
|
202
|
+
|
|
203
|
+
For setup code, the `multiprocessing` context rules, pool initializer, `ProcessPoolExecutor` integration, Windows spawn caveats, custom log levels, attach/detach lifecycle, environment-variable knobs, and shutdown handling, see [`examples/12_multiprocess_logging.md`](examples/12_multiprocess_logging.md).
|
|
204
|
+
|
|
205
|
+
Public API in `dsafelogger.mp`: `ConfigureLogger`, `AttachCurrentProcess`, `DetachCurrentProcess`, `GetLogger`, `GetWorkerInitializer`, `ReopenLogFiles`.
|
|
206
|
+
|
|
207
|
+
## Configuration
|
|
208
|
+
|
|
209
|
+
D-SafeLogger combines three configuration layers:
|
|
210
|
+
|
|
211
|
+
| Layer | Purpose |
|
|
212
|
+
|---|---|
|
|
213
|
+
| Code | Application defaults passed to `ConfigureLogger()` |
|
|
214
|
+
| INI or dict | Deployment configuration without changing application code |
|
|
215
|
+
| Environment variables | Operational and emergency overrides |
|
|
216
|
+
|
|
217
|
+
Common environment overrides, using the default `D_LOG_*` prefix; the prefix is configurable through `ConfigureLogger(env_prefix=...)`:
|
|
218
|
+
|
|
219
|
+
- Single-process: `D_LOG_LEVEL`, `D_LOG_MODULES`, `D_LOG_CONFIG`, `D_LOG_DIAGNOSE`, `D_LOG_CONSOLE`, `D_LOG_COLOR`, `D_LOG_HASH`, `D_LOG_MANIFEST`, plus the industry-standard `NO_COLOR`, which is not affected by `env_prefix`.
|
|
220
|
+
- Multiprocess (`dsafelogger.mp`): `D_LOG_IPC_LOG_TIMEOUT`, `D_LOG_IPC_LOG_QUEUE_MAXSIZE`, `D_LOG_IPC_CLIENT_QUEUE_MAXSIZE`, `D_LOG_WRITER_FLUSH_BATCH`. These tune backpressure behavior and are normally left at defaults.
|
|
221
|
+
|
|
222
|
+
See [Configuration Guide](examples/02_configuration_guide.md) for INI files, dict configuration, module-specific routing, and precedence rules.
|
|
223
|
+
|
|
224
|
+
## Tutorials / Examples
|
|
225
|
+
|
|
226
|
+
Suggested reading paths:
|
|
227
|
+
|
|
228
|
+
- **Getting started:** 01, 02, 03
|
|
229
|
+
- **Stdlib and ecosystem integration:** 03, 04, 15, 16
|
|
230
|
+
- **Windows and service operations:** 05, 07, 13, 14
|
|
231
|
+
- **Application patterns:** 06, 10, 11, 17
|
|
232
|
+
- **Audit and incident response:** 08, 09, 10
|
|
233
|
+
- **Multiprocess logging:** 12
|
|
234
|
+
|
|
235
|
+
| # | Guide | Topic |
|
|
236
|
+
|---|---|---|
|
|
237
|
+
| 1 | [Quick Start](examples/01_quick_start.md) | Install, configure, and write the first log |
|
|
238
|
+
| 2 | [Configuration Guide](examples/02_configuration_guide.md) | Code, INI/dict, and environment configuration |
|
|
239
|
+
| 3 | [Migrating from stdlib](examples/03_migration_from_stdlib.md) | Migration from standard-library logging |
|
|
240
|
+
| 4 | [Stdlib Ecosystem Coexistence](examples/04_stdlib_ecosystem_coexistence.md) | Collect logs from existing stdlib-based libraries |
|
|
241
|
+
| 5 | [Windows Service and Scheduled Batch](examples/05_windows_service_and_scheduled_batch.md) | Append-only files for Windows services and scheduled jobs |
|
|
242
|
+
| 6 | [Web API Logging](examples/06_web_api_logging.md) | Request-correlated structured logs |
|
|
243
|
+
| 7 | [Long-Running Service](examples/07_long_running_service.md) | Routing, retention, and archival |
|
|
244
|
+
| 8 | [Compliance & Audit Logging](examples/08_compliance_audit.md) | SHA-256 integrity files and audit logs |
|
|
245
|
+
| 9 | [Debugging in Production](examples/09_debugging_production.md) | Diagnostic mode and masking |
|
|
246
|
+
| 10 | [Incident Response Bundle](examples/10_incident_response_bundle.md) | Gather structured logs, diagnostics, hashes, and manifests |
|
|
247
|
+
| 11 | [Async & High Throughput](examples/11_async_performance.md) | Queue-backed async logging |
|
|
248
|
+
| 12 | [Multiprocess Logging](examples/12_multiprocess_logging.md) | Worker logging through a parent-side Writer |
|
|
249
|
+
| 13 | [External Rotation and Reopen](examples/13_external_rotation_reopen.md) | Reopening files after external rotation |
|
|
250
|
+
| 14 | [CLI Operations](examples/14_cli_operations.md) | `dsafelogger` command usage |
|
|
251
|
+
| 15 | [OpenTelemetry Logging](examples/15_opentelemetry_logging.md) | Trace correlation with stdlib instrumentation |
|
|
252
|
+
| 16 | [Structlog Coexistence](examples/16_structlog_coexistence.md) | Using structlog alongside D-SafeLogger |
|
|
253
|
+
| 17 | [Container and Collector Coexistence](examples/17_container_collector_coexistence.md) | Write local JSONL while external collectors ship logs |
|
|
254
|
+
|
|
255
|
+
## Benchmarks
|
|
256
|
+
|
|
257
|
+
D-SafeLogger is competitive in the selected single-process async benchmark runs. In multiprocess benchmarks, raw throughput is not the differentiator; parent-side file output and classified delivery-state accounting are.
|
|
258
|
+
|
|
259
|
+
See [BENCHMARK.md](BENCHMARK.md) for the selected runs, methodology, and the explicit "what to claim / what not to claim" boundaries, and [`benchmarks/summary/`](benchmarks/summary/) for the published summaries.
|
|
260
|
+
|
|
261
|
+
## Testing / Quality
|
|
262
|
+
|
|
263
|
+
The release gate runs the full dev test suite across Windows, macOS, and Linux on Python 3.11-3.14. Publication checks also verify generated API docs, public design documents, benchmark summaries, and package build output.
|
|
264
|
+
|
|
265
|
+
See [TESTING.md](TESTING.md) for details.
|
|
266
|
+
|
|
267
|
+
## Compatibility / Non-goals
|
|
268
|
+
|
|
269
|
+
- Python: 3.11 or newer.
|
|
270
|
+
- OS: Windows, macOS, and Linux.
|
|
271
|
+
- Runtime dependencies: none.
|
|
272
|
+
- Typing: includes `py.typed`.
|
|
273
|
+
- API docs: [`docs/api/`](docs/api/).
|
|
274
|
+
- Design docs: [`docs/design/`](docs/design/).
|
|
275
|
+
- Distribution name is `d-safelogger` (with hyphen); import name is `dsafelogger` (no separator).
|
|
276
|
+
|
|
277
|
+
D-SafeLogger is not a log shipper, metrics pipeline, distributed tracing backend, or access-control system. Use tools such as Fluent Bit, Vector, Filebeat, OpenTelemetry Collector, or a tracing backend for those roles.
|
|
278
|
+
|
|
279
|
+
For vulnerability reporting, see [SECURITY.md](SECURITY.md).
|
|
280
|
+
|
|
281
|
+
## Design Documents
|
|
282
|
+
|
|
283
|
+
For deeper architectural rationale and specification details, see:
|
|
284
|
+
|
|
285
|
+
- [Architecture Analysis White Paper](docs/design/D-SafeLogger_v23j_WhitePaper_en.md)
|
|
286
|
+
- [Basic Design Specification](docs/design/D_SafeLogger_Specification_v23j_full_en.md)
|
|
287
|
+
- [API Reference](docs/api/index.md)
|
|
288
|
+
|
|
289
|
+
Japanese design documents are also available under [`docs/design/`](docs/design/).
|
|
290
|
+
|
|
291
|
+
## License
|
|
292
|
+
|
|
293
|
+
Apache License 2.0. See [LICENSE](LICENSE).
|
|
294
|
+
|
|
295
|
+
© D-SafeLogger contributors
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
d_safelogger-0.2.0.dist-info/licenses/LICENSE,sha256=gM9HNV6uKQphQIpdTs9I-PbqYQ2JZr2g9dR7sebOj7c,10752
|
|
2
|
+
dsafelogger/__init__.py,sha256=VBf_qa_5DZotY8EoM_QBZC5HZFJGLbrWBIBhkkHH0xs,33059
|
|
3
|
+
dsafelogger/_async.py,sha256=6E-nd6slLCPgLpiQ6gj03s8qVMQsJUUz22tJts6uLQU,3726
|
|
4
|
+
dsafelogger/_cli.py,sha256=UJw2PxFeuUCTBEKlPm37UPlV4TUQhwZ26dR7nwtsjfQ,7894
|
|
5
|
+
dsafelogger/_color.py,sha256=D0abSab3gwjb0sSFJiNruuqPd_jAGcNRg3vwvNHPv_8,2709
|
|
6
|
+
dsafelogger/_config_validation.py,sha256=AMGnnpLEht4f73fKd5bkFT_j7MUCGvIrQrvblnoPZqg,7325
|
|
7
|
+
dsafelogger/_constants.py,sha256=T0Ijjtox4h1tR98JfDqMEkSQMObVIeMDr7B1Llcfk3M,1817
|
|
8
|
+
dsafelogger/_context.py,sha256=vYkC2udeTFsXehVZxhl_zOmCZ1l_8yuZk_14e1u_HH8,2709
|
|
9
|
+
dsafelogger/_env_parser.py,sha256=rCBk6z4XgkLlzTg0pu_REhpbkhu51bGjRQe2ra9rydU,4174
|
|
10
|
+
dsafelogger/_formatter.py,sha256=x7-dBf-vpy47k8NMd5BM0NTo7MIpRKVWSfzZRKz8O2w,13853
|
|
11
|
+
dsafelogger/_handler.py,sha256=K2-nG2Ry30rQEZCH4vnwpz-qck1Bs2wJdarzfeFkQgQ,7388
|
|
12
|
+
dsafelogger/_ini_loader.py,sha256=Kv99ft2T-CxbeBIBfcIrNtWPhfAa5qWq7YYezy5aG4c,16778
|
|
13
|
+
dsafelogger/_integrity.py,sha256=eUBRqQw4e8sGit7QVT79kx4SrG6zoOaVsqBRyTcQjXY,3355
|
|
14
|
+
dsafelogger/_levels.py,sha256=vngboNvbkpcqdIrkhy_94oYE-J_KGfZPa9a8oBSTcyk,6530
|
|
15
|
+
dsafelogger/_logger.py,sha256=JqlEixYuOgEUDiF-Eqce0i6rLJi_MqQ_des0Zi1fZFk,1154
|
|
16
|
+
dsafelogger/_mp_attach.py,sha256=ZB8Od8eSR6RtTbWz_9l1iqvXyP1MwFG062QfnLA63kw,17478
|
|
17
|
+
dsafelogger/_mp_control.py,sha256=bY8ddbJmRNNGTnPh9cztLIqpBKUlam8B7v4oLWIqe2E,5791
|
|
18
|
+
dsafelogger/_mp_protocol.py,sha256=uKGoojCfFqCY3PwbP4wm25Yf53lL6cpJWvVJnfEtPZ0,6944
|
|
19
|
+
dsafelogger/_mp_queue.py,sha256=Cok14yC9SfFJpFftE8qQik7RZ_78PAseYY64jKlA5z0,3565
|
|
20
|
+
dsafelogger/_mp_runtime.py,sha256=7v8Hkqx2GEgXQSuItzUF8dCNb9TkuakOHdfgHtB6zso,25390
|
|
21
|
+
dsafelogger/_pipeline.py,sha256=lVyLUW6kg_d4hof1ZmpBGXHD11lRFEVzU-IxuO9OYPk,9072
|
|
22
|
+
dsafelogger/_purge.py,sha256=VvycIJNZxoMA77zbwZSlFamyhEs9AX6_xM5ag6Ydh1w,7394
|
|
23
|
+
dsafelogger/_routing.py,sha256=i1gwnXpuXxPF5QpGmgxkTn-kGXqfaWZvPZR40JrZZq0,13157
|
|
24
|
+
dsafelogger/_sink.py,sha256=6nqy6PRF7w6hM71x5TvyZkHSRdTyp1EIkvQ3cRBwXJE,3184
|
|
25
|
+
dsafelogger/_transport.py,sha256=GMhTPa1IC6uP_8vZ4r8BblYpBLGrao26t2Ycc8kYYQI,6002
|
|
26
|
+
dsafelogger/_validator.py,sha256=AvJTFVt8iCYyExwbT9Vh_BahYerz_u9vqnkyAgGQLDI,1780
|
|
27
|
+
dsafelogger/_writer_formatter.py,sha256=8dSpFDKAgxk7B03GEtRsVYnAr-WsMtRsfopYrywNxEc,5089
|
|
28
|
+
dsafelogger/py.typed,sha256=ZSegze1ahS5tlaVlEVAF0HG-jTkkScOwTjUnglYQOS8,22
|
|
29
|
+
dsafelogger/mp/__init__.py,sha256=u1c_zK1iUObAwTQWWSnz-ZVd8mvMzip7eYavjx9rArk,38949
|
|
30
|
+
d_safelogger-0.2.0.dist-info/METADATA,sha256=ELLD5PgU9RX6UE5zpPqJfIlSTayLyHjFDzUJwOIXQ4o,21896
|
|
31
|
+
d_safelogger-0.2.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
|
|
32
|
+
d_safelogger-0.2.0.dist-info/entry_points.txt,sha256=aFAVgpEDolohU04OTxcunAvhtYfy27NH91IQjgtdqZQ,54
|
|
33
|
+
d_safelogger-0.2.0.dist-info/top_level.txt,sha256=QWdxyriAlvlE3K7odCpfdYPHgihceW0Yr3DUp3sw_sI,12
|
|
34
|
+
d_safelogger-0.2.0.dist-info/RECORD,,
|
|
@@ -0,0 +1,190 @@
|
|
|
1
|
+
Apache License
|
|
2
|
+
Version 2.0, January 2004
|
|
3
|
+
http://www.apache.org/licenses/
|
|
4
|
+
|
|
5
|
+
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
|
|
6
|
+
|
|
7
|
+
1. Definitions.
|
|
8
|
+
|
|
9
|
+
"License" shall mean the terms and conditions for use, reproduction,
|
|
10
|
+
and distribution as defined by Sections 1 through 9 of this document.
|
|
11
|
+
|
|
12
|
+
"Licensor" shall mean the copyright owner or entity authorized by
|
|
13
|
+
the copyright owner that is granting the License.
|
|
14
|
+
|
|
15
|
+
"Legal Entity" shall mean the union of the acting entity and all
|
|
16
|
+
other entities that control, are controlled by, or are under common
|
|
17
|
+
control with that entity. For the purposes of this definition,
|
|
18
|
+
"control" means (i) the power, direct or indirect, to cause the
|
|
19
|
+
direction or management of such entity, whether by contract or
|
|
20
|
+
otherwise, or (ii) ownership of fifty percent (50%) or more of the
|
|
21
|
+
outstanding shares, or (iii) beneficial ownership of such entity.
|
|
22
|
+
|
|
23
|
+
"You" (or "Your") shall mean an individual or Legal Entity
|
|
24
|
+
exercising permissions granted by this License.
|
|
25
|
+
|
|
26
|
+
"Source" form shall mean the preferred form for making modifications,
|
|
27
|
+
including but not limited to software source code, documentation
|
|
28
|
+
source, and configuration files.
|
|
29
|
+
|
|
30
|
+
"Object" form shall mean any form resulting from mechanical
|
|
31
|
+
transformation or translation of a Source form, including but
|
|
32
|
+
not limited to compiled object code, generated documentation,
|
|
33
|
+
and conversions to other media types.
|
|
34
|
+
|
|
35
|
+
"Work" shall mean the work of authorship, whether in Source or
|
|
36
|
+
Object form, made available under the License, as indicated by a
|
|
37
|
+
copyright notice that is included in or attached to the work
|
|
38
|
+
(an example is provided in the Appendix below).
|
|
39
|
+
|
|
40
|
+
"Derivative Works" shall mean any work, whether in Source or Object
|
|
41
|
+
form, that is based on (or derived from) the Work and for which the
|
|
42
|
+
editorial revisions, annotations, elaborations, or other modifications
|
|
43
|
+
represent, as a whole, an original work of authorship. For the purposes
|
|
44
|
+
of this License, Derivative Works shall not include works that remain
|
|
45
|
+
separable from, or merely link (or bind by name) to the interfaces of,
|
|
46
|
+
the Work and Derivative Works thereof.
|
|
47
|
+
|
|
48
|
+
"Contribution" shall mean any work of authorship, including
|
|
49
|
+
the original version of the Work and any modifications or additions
|
|
50
|
+
to that Work or Derivative Works thereof, that is intentionally
|
|
51
|
+
submitted to the Licensor for inclusion in the Work by the copyright owner
|
|
52
|
+
or by an individual or Legal Entity authorized to submit on behalf of
|
|
53
|
+
the copyright owner. For the purposes of this definition, "submitted"
|
|
54
|
+
means any form of electronic, verbal, or written communication sent
|
|
55
|
+
to the Licensor or its representatives, including but not limited to
|
|
56
|
+
communication on electronic mailing lists, source code control systems,
|
|
57
|
+
and issue tracking systems that are managed by, or on behalf of, the
|
|
58
|
+
Licensor for the purpose of discussing and improving the Work, but
|
|
59
|
+
excluding communication that is conspicuously marked or otherwise
|
|
60
|
+
designated in writing by the copyright owner as "Not a Contribution."
|
|
61
|
+
|
|
62
|
+
"Contributor" shall mean Licensor and any individual or Legal Entity
|
|
63
|
+
on behalf of whom a Contribution has been received by the Licensor and
|
|
64
|
+
subsequently incorporated within the Work.
|
|
65
|
+
|
|
66
|
+
2. Grant of Copyright License. Subject to the terms and conditions of
|
|
67
|
+
this License, each Contributor hereby grants to You a perpetual,
|
|
68
|
+
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
|
69
|
+
copyright license to reproduce, prepare Derivative Works of,
|
|
70
|
+
publicly display, publicly perform, sublicense, and distribute the
|
|
71
|
+
Work and such Derivative Works in Source or Object form.
|
|
72
|
+
|
|
73
|
+
3. Grant of Patent License. Subject to the terms and conditions of
|
|
74
|
+
this License, each Contributor hereby grants to You a perpetual,
|
|
75
|
+
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
|
76
|
+
(except as stated in this section) patent license to make, have made,
|
|
77
|
+
use, offer to sell, sell, import, and otherwise transfer the Work,
|
|
78
|
+
where such license applies only to those patent claims licensable
|
|
79
|
+
by such Contributor that are necessarily infringed by their
|
|
80
|
+
Contribution(s) alone or by combination of their Contribution(s)
|
|
81
|
+
with the Work to which such Contribution(s) was submitted. If You
|
|
82
|
+
institute patent litigation against any entity (including a
|
|
83
|
+
cross-claim or counterclaim in a lawsuit) alleging that the Work
|
|
84
|
+
or a Contribution incorporated within the Work constitutes direct
|
|
85
|
+
or contributory patent infringement, then any patent licenses
|
|
86
|
+
granted to You under this License for that Work shall terminate
|
|
87
|
+
as of the date such litigation is filed.
|
|
88
|
+
|
|
89
|
+
4. Redistribution. You may reproduce and distribute copies of the
|
|
90
|
+
Work or Derivative Works thereof in any medium, with or without
|
|
91
|
+
modifications, and in Source or Object form, provided that You
|
|
92
|
+
meet the following conditions:
|
|
93
|
+
|
|
94
|
+
(a) You must give any other recipients of the Work or
|
|
95
|
+
Derivative Works a copy of this License; and
|
|
96
|
+
|
|
97
|
+
(b) You must cause any modified files to carry prominent notices
|
|
98
|
+
stating that You changed the files; and
|
|
99
|
+
|
|
100
|
+
(c) You must retain, in the Source form of any Derivative Works
|
|
101
|
+
that You distribute, all copyright, patent, trademark, and
|
|
102
|
+
attribution notices from the Source form of the Work,
|
|
103
|
+
excluding those notices that do not pertain to any part of
|
|
104
|
+
the Derivative Works; and
|
|
105
|
+
|
|
106
|
+
(d) If the Work includes a "NOTICE" text file as part of its
|
|
107
|
+
distribution, then any Derivative Works that You distribute must
|
|
108
|
+
include a readable copy of the attribution notices contained
|
|
109
|
+
within such NOTICE file, excluding any notices that do not
|
|
110
|
+
pertain to any part of the Derivative Works, in at least one
|
|
111
|
+
of the following places: within a NOTICE text file distributed
|
|
112
|
+
as part of the Derivative Works; within the Source form or
|
|
113
|
+
documentation, if provided along with the Derivative Works; or,
|
|
114
|
+
within a display generated by the Derivative Works, if and
|
|
115
|
+
wherever such third-party notices normally appear. The contents
|
|
116
|
+
of the NOTICE file are for informational purposes only and
|
|
117
|
+
do not modify the License. You may add Your own attribution
|
|
118
|
+
notices within Derivative Works that You distribute, alongside
|
|
119
|
+
or as an addendum to the NOTICE text from the Work, provided
|
|
120
|
+
that such additional attribution notices cannot be construed
|
|
121
|
+
as modifying the License.
|
|
122
|
+
|
|
123
|
+
You may add Your own copyright statement to Your modifications and
|
|
124
|
+
may provide additional or different license terms and conditions
|
|
125
|
+
for use, reproduction, or distribution of Your modifications, or
|
|
126
|
+
for any such Derivative Works as a whole, provided Your use,
|
|
127
|
+
reproduction, and distribution of the Work otherwise complies with
|
|
128
|
+
the conditions stated in this License.
|
|
129
|
+
|
|
130
|
+
5. Submission of Contributions. Unless You explicitly state otherwise,
|
|
131
|
+
any Contribution intentionally submitted for inclusion in the Work
|
|
132
|
+
by You to the Licensor shall be under the terms and conditions of
|
|
133
|
+
this License, without any additional terms or conditions.
|
|
134
|
+
Notwithstanding the above, nothing herein shall supersede or modify
|
|
135
|
+
the terms of any separate license agreement you may have executed
|
|
136
|
+
with Licensor regarding such Contributions.
|
|
137
|
+
|
|
138
|
+
6. Trademarks. This License does not grant permission to use the trade
|
|
139
|
+
names, trademarks, service marks, or product names of the Licensor,
|
|
140
|
+
except as required for reasonable and customary use in describing the
|
|
141
|
+
origin of the Work and reproducing the content of the NOTICE file.
|
|
142
|
+
|
|
143
|
+
7. Disclaimer of Warranty. Unless required by applicable law or
|
|
144
|
+
agreed to in writing, Licensor provides the Work (and each
|
|
145
|
+
Contributor provides its Contributions) on an "AS IS" BASIS,
|
|
146
|
+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
|
|
147
|
+
implied, including, without limitation, any warranties or conditions
|
|
148
|
+
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
|
|
149
|
+
PARTICULAR PURPOSE. You are solely responsible for determining the
|
|
150
|
+
appropriateness of using or redistributing the Work and assume any
|
|
151
|
+
risks associated with Your exercise of permissions under this License.
|
|
152
|
+
|
|
153
|
+
8. Limitation of Liability. In no event and under no legal theory,
|
|
154
|
+
whether in tort (including negligence), contract, or otherwise,
|
|
155
|
+
unless required by applicable law (such as deliberate and grossly
|
|
156
|
+
negligent acts) or agreed to in writing, shall any Contributor be
|
|
157
|
+
liable to You for damages, including any direct, indirect, special,
|
|
158
|
+
incidental, or consequential damages of any character arising as a
|
|
159
|
+
result of this License or out of the use or inability to use the
|
|
160
|
+
Work (including but not limited to damages for loss of goodwill,
|
|
161
|
+
work stoppage, computer failure or malfunction, or any and all
|
|
162
|
+
other commercial damages or losses), even if such Contributor
|
|
163
|
+
has been advised of the possibility of such damages.
|
|
164
|
+
|
|
165
|
+
9. Accepting Warranty or Additional Liability. While redistributing
|
|
166
|
+
the Work or Derivative Works thereof, You may choose to offer,
|
|
167
|
+
and charge a fee for, acceptance of support, warranty, indemnity,
|
|
168
|
+
or other liability obligations and/or rights consistent with this
|
|
169
|
+
License. However, in accepting such obligations, You may act only
|
|
170
|
+
on Your own behalf and on Your sole responsibility, not on behalf
|
|
171
|
+
of any other Contributor, and only if You agree to indemnify,
|
|
172
|
+
defend, and hold each Contributor harmless for any liability
|
|
173
|
+
incurred by, or claims asserted against, such Contributor by reason
|
|
174
|
+
of your accepting any such warranty or additional liability.
|
|
175
|
+
|
|
176
|
+
END OF TERMS AND CONDITIONS
|
|
177
|
+
|
|
178
|
+
Copyright 2026 D
|
|
179
|
+
|
|
180
|
+
Licensed under the Apache License, Version 2.0 (the "License");
|
|
181
|
+
you may not use this file except in compliance with the License.
|
|
182
|
+
You may obtain a copy of the License at
|
|
183
|
+
|
|
184
|
+
http://www.apache.org/licenses/LICENSE-2.0
|
|
185
|
+
|
|
186
|
+
Unless required by applicable law or agreed to in writing, software
|
|
187
|
+
distributed under the License is distributed on an "AS IS" BASIS,
|
|
188
|
+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
189
|
+
See the License for the specific language governing permissions and
|
|
190
|
+
limitations under the License.
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
dsafelogger
|