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

Last change on this file since 13934 was 13934, checked in by Kon Lovett, 11 years ago

Updated.

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