← Back to branch summary

~ubuntu-branches/ubuntu/quantal/enigmail/quantal-security

« back to all changes in this revision

Viewing changes to mozilla/python/mozbuild/README.rst

  • Committer: Package Import Robot
  • Author(s): Chris Coulson
  • Date: 2013-09-13 16:02:15 UTC
  • mfrom: (0.12.16)
  • Revision ID: package-import@ubuntu.com-20130913160215-u3g8nmwa0pdwagwc
Tags: 2:1.5.2-0ubuntu0.12.10.1
* New upstream release v1.5.2 for Thunderbird 24

* Build enigmail using a stripped down Thunderbird 17 build system, as it's
  now quite difficult to build the way we were doing previously, with the
  latest Firefox build system
* Add debian/patches/no_libxpcom.patch - Don't link against libxpcom, as it
  doesn't exist anymore (but exists in the build system)
* Add debian/patches/use_sdk.patch - Use the SDK version of xpt.py and
  friends
* Drop debian/patches/ipc-pipe_rename.diff (not needed anymore)
* Drop debian/patches/makefile_depth.diff (not needed anymore)

Show diffs side-by-side

added added

removed removed

Lines of Context:
mozilla/python/mozbuild/README.rst
 
1
========
 
2
mozbuild
 
3
========
 
4
 
 
5
mozbuild is a Python package providing functionality used by Mozilla's
 
6
build system.
 
7
 
 
8
Modules Overview
 
9
================
 
10
 
 
11
* mozbuild.compilation -- Functionality related to compiling. This
 
12
  includes managing compiler warnings.
 
13
* mozbuild.logging -- Defines mozbuild's logging infrastructure.
 
14
  mozbuild uses a structured logging backend.
 
15
 
 
16
Structured Logging
 
17
==================
 
18
 
 
19
One of the features of mozbuild is structured logging. Instead of
 
20
conventional logging where simple strings are logged, the internal
 
21
logging mechanism logs all events with the following pieces of
 
22
information:
 
23
 
 
24
* A string *action*
 
25
* A dict of log message fields
 
26
* A formatting string
 
27
 
 
28
Essentially, instead of assembling a human-readable string at
 
29
logging-time, you create an object holding all the pieces of data that
 
30
will constitute your logged event. For each unique type of logged event,
 
31
you assign an *action* name.
 
32
 
 
33
Depending on how logging is configured, your logged event could get
 
34
written a couple of different ways.
 
35
 
 
36
JSON Logging
 
37
------------
 
38
 
 
39
Where machines are the intended target of the logging data, a JSON
 
40
logger is configured. The JSON logger assembles an array consisting of
 
41
the following elements:
 
42
 
 
43
* Decimal wall clock time in seconds since UNIX epoch
 
44
* String *action* of message
 
45
* Object with structured message data
 
46
 
 
47
The JSON-serialized array is written to a configured file handle.
 
48
Consumers of this logging stream can just perform a readline() then feed
 
49
that into a JSON deserializer to reconstruct the original logged
 
50
message. They can key off the *action* element to determine how to
 
51
process individual events. There is no need to invent a parser.
 
52
Convenient, isn't it?
 
53
 
 
54
Logging for Humans
 
55
------------------
 
56
 
 
57
Where humans are the intended consumer of a log message, the structured
 
58
log message are converted to more human-friendly form. This is done by
 
59
utilizing the *formatting* string provided at log time. The logger
 
60
simply calls the *format* method of the formatting string, passing the
 
61
dict containing the message's fields.
 
62
 
 
63
When *mach* is used in a terminal that supports it, the logging facility
 
64
also supports terminal features such as colorization. This is done
 
65
automatically in the logging layer - there is no need to control this at
 
66
logging time.
 
67
 
 
68
In addition, messages intended for humans typically prepends every line
 
69
with the time passed since the application started.
 
70
 
 
71
Logging HOWTO
 
72
-------------
 
73
 
 
74
Structured logging piggybacks on top of Python's built-in logging
 
75
infrastructure provided by the *logging* package. We accomplish this by
 
76
taking advantage of *logging.Logger.log()*'s *extra* argument. To this
 
77
argument, we pass a dict with the fields *action* and *params*. These
 
78
are the string *action* and dict of message fields, respectively. The
 
79
formatting string is passed as the *msg* argument, like normal.
 
80
 
 
81
If you were logging to a logger directly, you would do something like:
 
82
 
 
83
    logger.log(logging.INFO, 'My name is {name}',
 
84
        extra={'action': 'my_name', 'params': {'name': 'Gregory'}})
 
85
 
 
86
The JSON logging would produce something like:
 
87
 
 
88
    [1339985554.306338, "my_name", {"name": "Gregory"}]
 
89
 
 
90
Human logging would produce something like:
 
91
 
 
92
     0.52 My name is Gregory
 
93
 
 
94
Since there is a lot of complexity using logger.log directly, it is
 
95
recommended to go through a wrapping layer that hides part of the
 
96
complexity for you. e.g.
 
97
 
 
98
    def log(self, level, action, params, format_str):
 
99
        self.logger.log(level, format_str,
 
100
            extra={'action': action, 'params': params)
 
101