Skip to content

Commit 0a923ad

Browse files
wderezinwderezin
authored
Add settings reference table and detailed configuration docs (#4)
Add agents.md as a quick-reference table for logger settings, env vars, middleware options, and request context inputs Add docs/settings.md with detailed behavior for each setting, including defaults, override paths, and source mapping Document configuration precedence and implementation caveats for current logger config behavior
1 parent fe812bc commit 0a923ad

9 files changed

Lines changed: 589 additions & 18 deletions

File tree

‎.idea/inspectionProfiles/Project_Default.xml‎

Lines changed: 25 additions & 5 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎README.md‎

Lines changed: 31 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -37,7 +37,8 @@ Start logging with `console.error`, `console.warn`, `console.log`,
3737

3838
# App Server Support
3939

40-
Preconfigured support for ExpressJS and Fresh V1 provides the following:
40+
Preconfigured support for ExpressJS, Fresh V1, Hono, and SolidStart provides the
41+
following:
4142

4243
- Metrics (Request and Logger)
4344
- Log Levels
@@ -73,6 +74,33 @@ export default defineConfig({
7374
});
7475
```
7576

77+
## Hono Configuration
78+
79+
```typescript
80+
import { Hono } from "hono";
81+
import { honoLoggerMiddleware, initLogger } from "@daringway/logger";
82+
83+
initLogger();
84+
85+
const app = new Hono();
86+
app.use("*", honoLoggerMiddleware());
87+
```
88+
89+
## SolidStart Configuration
90+
91+
In a SolidStart middleware file:
92+
93+
```typescript
94+
import { createMiddleware } from "@solidjs/start/middleware";
95+
import { initLogger, solidStartLoggerMiddleware } from "@daringway/logger";
96+
97+
initLogger();
98+
99+
export default createMiddleware({
100+
onRequest: solidStartLoggerMiddleware(),
101+
});
102+
```
103+
76104
## Request Context Information
77105

78106
```typescript
@@ -110,7 +138,8 @@ WebStorm testing. Default: false
110138
LOG_PRETTY: boolean Enable pretty printing of logs for development. Use for CLI
111139
testing. Default: false
112140

113-
LOG_WITH_CONSOLE: boolean Enable logging to console. Default: false, writes to STDOUT
141+
LOG_WITH_CONSOLE: boolean Enable logging to console. Default: false, writes to
142+
STDOUT
114143

115144
# Log Levels Explained
116145

‎agents.md‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
# Agents Reference Table
2+
3+
Use this file as the quick index. Follow each `Details` link for full behavior,
4+
caveats, and source mapping.
5+
6+
| Area | Setting | Default | Override Path | Details |
7+
| ------------- | ---------------------------------------------- | ----------------------: | ---------------------------------------------- | ---------------------------------------------------------------------------- |
8+
| Logger | `logLevel` | `"log"` | `initLogger`, `LOG_LEVEL` | [details](docs/settings.md#loglevel) |
9+
| Logger | `logSecondsBetweenMetrics` | `500` | `initLogger`, `LOG_SECONDS_BETWEEN_METRICS` | [details](docs/settings.md#logsecondsbetweenmetrics) |
10+
| Logger | `logPriorityThresholdBytes` | `1048576` | `initLogger`, `LOG_PRIORITY_THRESHOLD_BYTES` | [details](docs/settings.md#logprioritythresholdbytes) |
11+
| Logger | `logMeta` | `null` | `initLogger` | [details](docs/settings.md#logmeta) |
12+
| Logger | `logObjects` | `false` | `initLogger`, `LOG_OBJECTS` | [details](docs/settings.md#logobjects) |
13+
| Logger | `logPretty` | `false` | `initLogger`, `LOG_PRETTY` | [details](docs/settings.md#logpretty) |
14+
| Logger | `logWithConsole` | `false` | `initLogger`, `LOG_WITH_CONSOLE` | [details](docs/settings.md#logwithconsole) |
15+
| Logger | `silentInit` | `false` | `initLogger` | [details](docs/settings.md#silentinit) |
16+
| Env Var | `LOG_LEVEL` | n/a | environment | [details](docs/settings.md#log_level) |
17+
| Env Var | `LOG_SECONDS_BETWEEN_METRICS` | n/a | environment | [details](docs/settings.md#log_seconds_between_metrics) |
18+
| Env Var | `LOG_PRIORITY_THRESHOLD_BYTES` | n/a | environment | [details](docs/settings.md#log_priority_threshold_bytes) |
19+
| Env Var | `LOG_OBJECTS` | n/a | environment | [details](docs/settings.md#log_objects) |
20+
| Env Var | `LOG_PRETTY` | n/a | environment | [details](docs/settings.md#log_pretty) |
21+
| Env Var | `LOG_WITH_CONSOLE` | n/a | environment | [details](docs/settings.md#log_with_console) |
22+
| Express | `doNotLogURLs` | unset | `expressLoggerMiddleware({ doNotLogURLs })` | [details](docs/settings.md#donotlogurls-express) |
23+
| Fresh | `setCookies` | unset | `freshV1LoggerPlugin({ setCookies })` | [details](docs/settings.md#setcookies-fresh) |
24+
| Fresh | `doNotLogURLs` | unset | `freshV1LoggerPlugin({ doNotLogURLs })` | [details](docs/settings.md#donotlogurls-fresh) |
25+
| Hono | `doNotLogURLs` | unset | `honoLoggerMiddleware({ doNotLogURLs })` | [details](docs/settings.md#donotlogurls-hono) |
26+
| SolidStart | `doNotLogURLs` | unset | `solidStartLoggerMiddleware({ doNotLogURLs })` | [details](docs/settings.md#donotlogurls-solidstart) |
27+
| Context Input | `x-request-id` | generated | request header/cookie | [details](docs/settings.md#x-request-id) |
28+
| Context Input | `x-trace-path` | derived | request header | [details](docs/settings.md#x-trace-path) |
29+
| Context Input | `x-correlation-id` / `correlationId` | `"unknown"` | request header/cookie | [details](docs/settings.md#x-correlation-id--correlationid-cookie) |
30+
| Context Input | `authorization` / `session` | `"unknown"` | request header/cookie | [details](docs/settings.md#authorization--session-cookie) |
31+
| Context Input | `x-application-name` / `applicationName` | `"unknown"`/`"postman"` | request header/cookie | [details](docs/settings.md#x-application-name--applicationname-cookie) |
32+
| Context Input | `x-application-version` / `applicationVersion` | `"unknown"` | request header/cookie | [details](docs/settings.md#x-application-version--applicationversion-cookie) |
33+
| Context Input | `user-agent` | `"unknown"` | request header | [details](docs/settings.md#user-agent) |

‎deno.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"name": "@daringway/logger",
3-
"version": "0.0.8",
3+
"version": "0.0.9",
44
"license": "MIT",
55
"description": "A high-performance, drop-in replacement for console.log() that outputs structured JSON logs and metrics to STDOUT. Built for both Deno and Node.js, it delivers blazing-fast, non-blocking logging with optional request context, log levels, and ExpressJS/Fresh V1 integration—making it ideal for production apps that need speed, consistency, and easy observability.",
66
"exports": "./mod.ts",

‎docs/settings.md‎

Lines changed: 229 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,229 @@
1+
# Settings Reference
2+
3+
This document is the detailed companion for [`agents.md`](../agents.md).
4+
5+
## Configuration Precedence
6+
7+
For logger config (`initLogger`), values are resolved in this order:
8+
9+
1. Environment variable (if available for that setting)
10+
2. `initLogger({...})` argument
11+
3. Existing in-memory `logConfig`
12+
4. Built-in defaults
13+
14+
## Logger Settings (`initLogger`)
15+
16+
### logLevel
17+
18+
- Scope: logger
19+
- Type: `"metrics" | "error" | "warn" | "info" | "log" | "debug" | "trace"`
20+
- Default: `"log"`
21+
- Env override: `LOG_LEVEL`
22+
- Notes: controls which console methods are emitted (`error` and `metrics`
23+
always emit)
24+
- Source: `src/zod.ts`, `src/dare-console-logger.ts`
25+
26+
### logSecondsBetweenMetrics
27+
28+
- Scope: logger
29+
- Type: number (`>= 0`)
30+
- Default: `500`
31+
- Env override: `LOG_SECONDS_BETWEEN_METRICS`
32+
- Notes: `0` disables periodic metrics writes
33+
- Source: `src/zod.ts`, `src/dare-console-logger.ts`
34+
35+
### logPriorityThresholdBytes
36+
37+
- Scope: logger
38+
- Type: number (`>= 10`)
39+
- Default: `1048576` (1 MiB)
40+
- Env override: `LOG_PRIORITY_THRESHOLD_BYTES`
41+
- Notes: when queue size exceeds threshold, flushing is prioritized immediately
42+
- Source: `src/zod.ts`, `src/dare-console-logger.ts`
43+
44+
### logMeta
45+
46+
- Scope: logger
47+
- Type: `Record<string, string> | null`
48+
- Default: `null`
49+
- Env override: none
50+
- Notes: merged into emitted `context.meta`; merged shallowly on updates
51+
- Source: `src/zod.ts`, `src/dare-console-logger.ts`
52+
53+
### logObjects
54+
55+
- Scope: logger
56+
- Type: boolean (`true/false/yes/no` accepted by parser)
57+
- Default: `false`
58+
- Env override: `LOG_OBJECTS`
59+
- Notes: logs objects directly to console; forces `logSecondsBetweenMetrics=0`
60+
when enabled
61+
- Source: `src/zod.ts`, `src/dare-console-logger.ts`
62+
63+
### logPretty
64+
65+
- Scope: logger
66+
- Type: boolean (`true/false/yes/no`)
67+
- Default: `false`
68+
- Env override: `LOG_PRETTY`
69+
- Notes: pretty-prints JSON logs via `console.log`
70+
- Source: `src/zod.ts`, `src/dare-console-logger.ts`
71+
72+
### logWithConsole
73+
74+
- Scope: logger
75+
- Type: boolean (`true/false/yes/no`)
76+
- Default: `false`
77+
- Env override: `LOG_WITH_CONSOLE`
78+
- Notes: bypasses queue and writes via `console.log(JSON.stringify(...))`
79+
- Source: `src/zod.ts`, `src/dare-console-logger.ts`
80+
81+
### silentInit
82+
83+
- Scope: logger
84+
- Type: boolean (`true/false/yes/no`)
85+
- Default: `false`
86+
- Env override: none
87+
- Notes: intended to suppress init/update debug logs. Current implementation
88+
does not apply `initLogger({ silentInit })` into `newConfig`, so this setting
89+
is effectively always defaulted during init.
90+
- Source: `src/zod.ts`, `src/dare-console-logger.ts`
91+
92+
## Environment Variables
93+
94+
### LOG_LEVEL
95+
96+
- Maps to: `logLevel`
97+
- Example: `LOG_LEVEL=info`
98+
- Source: `src/dare-console-logger.ts`, `README.md`
99+
100+
### LOG_SECONDS_BETWEEN_METRICS
101+
102+
- Maps to: `logSecondsBetweenMetrics`
103+
- Example: `LOG_SECONDS_BETWEEN_METRICS=60`
104+
- Source: `src/dare-console-logger.ts`, `README.md`
105+
106+
### LOG_PRIORITY_THRESHOLD_BYTES
107+
108+
- Maps to: `logPriorityThresholdBytes`
109+
- Example: `LOG_PRIORITY_THRESHOLD_BYTES=262144`
110+
- Source: `src/dare-console-logger.ts`
111+
112+
### LOG_OBJECTS
113+
114+
- Maps to: `logObjects`
115+
- Example: `LOG_OBJECTS=true`
116+
- Source: `src/dare-console-logger.ts`, `README.md`
117+
118+
### LOG_PRETTY
119+
120+
- Maps to: `logPretty`
121+
- Example: `LOG_PRETTY=true`
122+
- Source: `src/dare-console-logger.ts`, `README.md`
123+
124+
### LOG_WITH_CONSOLE
125+
126+
- Maps to: `logWithConsole`
127+
- Example: `LOG_WITH_CONSOLE=true`
128+
- Source: `src/dare-console-logger.ts`, `README.md`
129+
130+
## Express Middleware Settings (`expressLoggerMiddleware`)
131+
132+
### doNotLogURLs (express)
133+
134+
- Scope: Express middleware
135+
- Type: `RegExp`
136+
- Default: unset
137+
- Notes: skip logging for matching `req.originalUrl`
138+
- Source: `src/express.ts`
139+
140+
## Fresh Middleware Settings (`freshV1LoggerPlugin`)
141+
142+
### setCookies (fresh)
143+
144+
- Scope: Fresh middleware
145+
- Type: `Cookie[]`
146+
- Default: unset
147+
- Notes: additional cookies appended to response
148+
- Source: `src/fresh.ts`
149+
150+
### doNotLogURLs (fresh)
151+
152+
- Scope: Fresh middleware
153+
- Type: `RegExp`
154+
- Default: unset
155+
- Notes: skip logging for matching route path
156+
- Source: `src/fresh.ts`
157+
158+
## Hono Middleware Settings (`honoLoggerMiddleware`)
159+
160+
### doNotLogURLs (hono)
161+
162+
- Scope: Hono middleware
163+
- Type: `RegExp`
164+
- Default: unset
165+
- Notes: skip logging for matching request path
166+
- Source: `src/hono.ts`
167+
168+
## SolidStart Middleware Settings (`solidStartLoggerMiddleware`)
169+
170+
### doNotLogURLs (solidstart)
171+
172+
- Scope: SolidStart middleware
173+
- Type: `RegExp`
174+
- Default: unset
175+
- Notes: skip logging for matching request path
176+
- Source: `src/solidstart.ts`
177+
178+
## Request Context Inputs (Header/Cookie Driven)
179+
180+
### x-request-id
181+
182+
- Scope: request context
183+
- Default/fallback: generated `"<app>-<timestamp>-<rand>"`
184+
- Source: `src/utils.ts`
185+
186+
### x-trace-path
187+
188+
- Scope: request context
189+
- Type: comma-separated list
190+
- Default/fallback: `[requestId]` when request id is generated
191+
- Source: `src/utils.ts`
192+
193+
### x-correlation-id / correlationId cookie
194+
195+
- Scope: request context
196+
- Default/fallback: `"unknown"`
197+
- Source: `src/utils.ts`
198+
199+
### authorization / session cookie
200+
201+
- Scope: request context
202+
- Notes: extracts `sessionId` from token payload when present
203+
- Default/fallback: `"unknown"`
204+
- Source: `src/utils.ts`
205+
206+
### x-application-name / applicationName cookie
207+
208+
- Scope: request context
209+
- Default/fallback: `"postman"` for Postman user-agent; otherwise `"unknown"`
210+
- Source: `src/utils.ts`
211+
212+
### x-application-version / applicationVersion cookie
213+
214+
- Scope: request context
215+
- Default/fallback: `"unknown"`
216+
- Source: `src/utils.ts`
217+
218+
### user-agent
219+
220+
- Scope: request context
221+
- Default/fallback: `"unknown"`
222+
- Source: `src/utils.ts`
223+
224+
## Implementation Notes
225+
226+
- `LoggingConfig` type in `src/zod.ts` does not currently include
227+
`logWithConsole`, but runtime schema/config uses it.
228+
- `silentInit` exists in schema/type, but is not wired into `initLogger`'s
229+
`newConfig` object.

‎mod.ts‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,4 +6,9 @@ export {
66
export { MetricsTracker } from "./src/dare-metrics.ts";
77
export { expressLoggerMiddleware, type ExpressOptions } from "./src/express.ts";
88
export { freshV1LoggerPlugin, type FreshV1Options } from "./src/fresh.ts";
9+
export { honoLoggerMiddleware, type HonoOptions } from "./src/hono.ts";
10+
export {
11+
solidStartLoggerMiddleware,
12+
type SolidStartOptions,
13+
} from "./src/solidstart.ts";
914
export { type LoggingConfig } from "./src/zod.ts";

0 commit comments

Comments
 (0)