source: project/release/3/logging/notes.txt @ 9025

Last change on this file since 9025 was 9025, checked in by Kon Lovett, 12 years ago

Canon dir struct

File size: 8.6 KB
Line 
1Logger
2======
3
4A log library for Chicken Scheme.
5
6
7Example
8-------
9
10- External Notation One
11
12stream          : channel
13                | ( channel stream )
14                | ( 'not stream )
15                | ( 'seq stream )
16                | ( 'alt stream )
17
18channel         : functioncall
19
20There is an implicit 'alt' at the toplevel.
21
22(define-log example-log
23  "A slightly silly example of a log definition"
24  ((level foo bar)
25    (seq (console) (syslog "foo") ) )
26  ((level debug)
27    ((prefix (srfi-19-date-format "[%d-%m-%Y/%H:%M:%S] " (current-date)))
28      ((buffer #:size 16384)
29        (file "foo.log" #:mode truncate))))
30  ((level error)
31    ((prefix timestamp " " level " " (? source " ") pid)
32      (syslog "foo" #:facility user #:host "syslog.example.com")))
33  ((level panic)
34    (smtp "mail.example.com" "foo@example.com")) )
35
36- External Notation Two
37
38stream          : channel
39                | channel -> stream
40                | ~ channel -> stream
41                | channel & stream
42                | channel : stream
43
44channel         : ( identifier parameters )
45
46parameter       : object
47                | identifier = object
48
49parameters      : parameter parameters
50
51(define-log example-log
52  "A slightly silly example of a log definition"
53  (level foo bar)
54    -> (console) & (syslog "foo")
55  :
56  (level debug)
57    -> (prefix (srfi-19-date-format "[%d-%m-%Y/%H:%M:%S] " (current-date)))
58      -> (buffer size = 16384)
59        -> (file "foo.log" mode = truncate)
60  :
61  (level error)
62    -> (prefix timestamp " " level " " (? source " ") pid)
63      -> (syslog "foo" facility = user host = "syslog.example.com")
64  :
65  (level panic)
66    -> (smtp "mail.example.com" "foo@example.com") )
67
68; Log a message using the example
69(example-log "a message" #:level 'foo #:source "bar" #:indent 2)
70
71
72Channel
73-------
74
75All built-in log channels take log context & extendend lambda list.
76
77  ({channel-procedure} ctx [required ...] [#!optional ...] [#!rest rest] [#!key ...])
78
79All channel exceptions are caught & collected in a tree, which is then re-signaled
80at the top-level should the entire operation abort. The aborted branch exceptions can
81be "logged".
82
83  ((exn log) conditions ({condition} ...))
84   
85A log is a channel stream. Channels are divided into filters (interior node)
86& outputs (leaf node). Some filters perform flow control.
87
88
89Filters
90-------
91
92noop    ; passes everything
93
94alt  ; try each stream until success
95  stream ...
96
97seq  ; try each stream
98  stream ...
99
100neg  ; continue downstream on failure
101  stream       
102
103asynchronous  ; in own thread
104  stream      ;
105  [quantum]   ;
106  [error]     ; error procedure
107
108level   ; pass matching severity level(s)
109  op            ; < | > | <= | >= | <> | =
110  name ...      ; severity level name
111
112match  ; pass matching message (not the prefix!)
113    regexp  ; compiled patten or string
114    [ci]    ; case insensitive?
115    [si]    ; space insensitive?
116    [utf8]  ; UTF8 string?
117
118prefix  ; construct message prefix
119        ; downstream prefix is appended to existing prefix!
120  [constructor ...]   ; field-object
121                      | string
122                      | symbol {symbol string}
123                      | (field symbol) {a cataloged field name}
124                      | (? constructor ...) {(invoke ctor) != "" -> "ctor-result ..."}
125                      | (procedure [parameter ...])
126
127buffer  ; pend output until flush criteria met
128  [size]          ; string length to buffer before flush
129  [interval]      ; seconds between flush
130  [level-flush]   ; level change causes flush?
131
132call  ; (procedure message [parameter ...]) -> #f | string
133  procedure
134  [parameter ...]
135
136filter  ; raw filter definition
137  procedure
138  [parameter ...]
139
140
141Outputs
142-------
143
144null  ; writes nothing
145
146console ; /dev/console
147
148port  ; display message on specified port
149  output-port
150
151uri ; send message to uri
152  uri   ; uri object or string
153
154pipe  ; pipe message to process
155  command       ; string - command to execute
156
157file  ; filesystem
158  pathanme        ; pathname object or string
159  [mode]          ; append | truncate
160  [permissions]   ;
161  [jitter]        ; # of writes before reopen
162  [monitor]       ; # of seconds between checking file non-existence & reopen
163  [keep]          ; keep open
164
165socket  ;
166  [kind]        ; tcp | udp | unix | ssl
167  [name]        ; hostname | hostname:port | pathname
168  [port]        ; integer | service-name
169  [timeout]
170  [keep]        ; keep open
171
172syslog  ; syslog, syslogd, ... message
173  [facility]   ; default is user
174  [host]       ; hostname | hostname:port
175  [port]       
176
177smtp  ; e-mail message
178  host          ; hostname | hostname:port
179  to ...        ; one or more recipients
180  [domain]      ; default is local hostname
181  [user]        ; default is "uid#N"
182  [from]        ; default is "{user}@{source}:{domain}"
183  [subject]     ; default is "[LOGGER] log channel output on {domain}"
184  [port]
185  [timeout]
186
187output  ; raw output definition
188  open              ; (-> [parameter ...] port)
189  close             ; (-> port undefined)
190  display           ; (-> message port undefined)
191  [flush]           ; (-> port undefined) - default is (begin ({close} ...) ({open} ...))
192  [keep]            ; keep open
193  [parameter ...]   ; optional parameters for open
194
195
196Data Structures
197---------------
198
199- Context
200
201  levels      ; level domain
202  fields      ; field domain
203  level       ; symbol
204  source      ; string
205  prefix      ; list of thunk - indent is done by (lambda () (spaces indent))
206  message     ; string
207  channel     ; downstream
208  cached      ; actual message
209
210Cached message is built just before call of first leaf (output) channel & invalidated
211after last. The actions for this are built by the 'alt' & 'seq' compilers.
212The 'call' filter also builds the cached message.
213
214- Channel
215
216  name          ; symbol
217  description   ; string
218  action        ; procedure
219
220- Level
221
222  name          ; symbol
223  description   ; string
224  priority      ; integer
225
226- Field
227
228  name          ; symbol
229  description   ; string
230  action        ; procedure (-> [parameter ...] string)
231
232- Log
233
234  name          ; symbol
235  description   ; string
236  definition    ; string - string form of surface notation or #f
237  sources       ; source domain
238  levels        ; level domain
239  fields        ; field domain
240  stream        ; channel
241
242- Channel Catalog
243
244  name          ; symbol
245  description   ; string
246  channels      ; set of channel
247
248- Level Catalog
249
250  name          ; symbol
251  description   ; string
252  levels        ; set of level
253
254- Field Catalog
255
256  name          ; symbol
257  description   ; string
258  fields        ; set of level
259
260- Log Catalog
261
262  name          ; symbol
263  description   ; string
264  logs          ; set of log
265
266
267Internals
268---------
269
270- Use of Chicken namespace is provisional.
271
272- The syntax expanded example
273
274(define example-log
275  (##log#create
276    "A slightly silly example of a log definition"
277    (##log#alt
278      ((##log#level '= 'foo 'bar)
279        (##log#seq (##log#console) (##log#syslog "foo") ) )
280      ((##log#level '= 'debug)
281        ((##log#prefix (lambda () (srfi-19-date-format "[%d-%m-%Y/%H:%M:%S] " (current-date))))
282          ((##log#buffer #:size 16384)
283            (##log#file "foo.log" #:mode 'truncate) ) ) )
284      ((##log#level '= 'error)
285        ((##log#prefix (##log#field 'timestamp) " " (##log#field 'level) " " (##log#field-conditional (##log#field 'source) " ") (##log#field 'pid))
286          (##log#syslog "foo" #:facility 'user #:host "syslog.example.com") ) )
287      ((##log#level '= 'panic)
288        (##log#smtp "mail.example.com" "foo@example.com")) )
289    #:definition
290      "((level foo bar) -> (console) & (syslog \"foo\") : (level debug) -> (prefix (srfi-19-date-format \"[%d-%m-%Y/%H:%M:%S] \" (current-date))) -> (buffer size = 16384) -> (file \"foo.log\" mode = truncate) : (level error) -> (prefix timestamp \" \" level \" \" (? source \" \") pid) -> (syslog \"foo\" facility = user host = \"syslog.example.com\") : (level panic) -> (smtp \"mail.example.com\" \"foo@example.com\"))" ) )
291
292
293- Not
294
295((neg (match ...)) (output ...))
296
297  AND
298 
299~ (match ...) -> (output ...)
300
301  =>
302
303((##log#neg (##log#match ...)) (##log#output))
304
305-
306
307Each channel has syntax & semantic action. The syntax action transforms the
308surface notation into the semantic notation. The semantic action creates a
309channel procedure, providing any necessary flow control and side-effect
310operations.
311
312
313API (todo)
314---
315
316(log-levels LOG)
317(log-levels-set! LOG LEVEL-CATALOG | LEVEL ...)
318
319(log-fields LOG)
320(log-fields-set! LOG FIELD-CATALOG | FIELD ...)
321
322(log-sources LOG)
323(log-sources-set! LOG SOURCE-CATALOG | SOURCE ...)
324(log-restrict LOG SOURCE-CATALOG | SOURCE ...)
325
326(log-definition LOG)
327(log-definition-set! LOG STRING)
328
329(log-description LOG)
330(log-description-set! LOG STRING)
331
332(log-channel LOG)
333(log-channel-set! LOG CHANNEL)
334
335...
336
Note: See TracBrowser for help on using the repository browser.