README.rst

   1 pg_logfebe
   2 ----------
   3
   4 ``pg_logfebe`` produces detailed Postgres logs framed in the general
   5 style of PostgreSQL's FEBE, the basis of the PostgreSQL wire protocol.
   6
   7 ``pg_logfebe`` is implemented with a C extension that is to be loaded
   8 via PostgreSQL's ``shared_preload_libraries`` configuration and hooks
   9 into the logging system to provide sending detailed, structured log
  10 output from PostgreSQL to another process via connecting to a unix
  11 socket specified in ``postgresql.conf``.
  12
  13 This is useful to allow for rapid analysis, filtering, and forwarding
  14 of large volumes of logs in another process that may be upgraded or
  15 changed without too much difficulty or impact.
  16
  17 Configuration
  18 =============
  19
  20 In ``postgresql.conf``::
  21
  22    shared_preload_libraries = 'pg_logfebe'
  23
  24    logfebe.unix_socket = '/wherever/log.sock'
  25
  26    # The identity string is forwarded during connection start-up so
  27    # the receiver of logs can know what Postgres the log records are
  28    # coming from.
  29    logfebe.identity = 'a name of your choice'
  30
  31
  32 Reporting Bugs
  33 ==============
  34
  35 Please contact daniel@fdr.io, daniel@heroku.com, and/or
  36 security@heroku.com if you find a security-sensitive bug, such as (but
  37 not limited to) denial of service, information disclosure, or remote
  38 code execution.
  39
  40 Otherwise, please file an issue on the `project page on Github`__.
  41
  42 __ https://github.com/fdr/pg_logfebe/issues
  43
  44
  45 List of Structured Fields Provided
  46 ==================================
  47
  48 The existing PostgreSQL CSV output code was used to populate this
  49 list, and the meanings of the fields are the same and `can be
  50 referenced in the PostgreSQL manual`__.  A sample parser and
  51 human-readable renderer is seen (in the language "Go" in
  52 ``pg_logfebe_prototext.go``).  It can be useful for debugging.
  53
  54 __ http://www.postgresql.org/docs/current/static/runtime-config-logging.html#RUNTIME-CONFIG-LOGGING-CSVLOG
  55
  56 * LogTime
  57 * UserName
  58 * DatabaseName
  59 * Pid
  60 * ClientAddr
  61 * SessionId
  62 * SeqNum
  63 * PsDisplay
  64 * SessionStart
  65 * Vxid
  66 * Txid
  67 * ELevel
  68 * SQLState
  69 * ErrMessage
  70 * ErrDetail
  71 * ErrHint
  72 * InternalQuery
  73 * InternalQueryPos
  74 * ErrContext
  75 * UserQuery
  76 * UserQueryPos
  77 * FileErrPos
  78 * ApplicationName
  79
  80 What is FEBE Framing
  81 ====================
  82
  83 FEBE (sometimes rendered FE/BE) is the "Front-end/Back-end" protocol
  84 that is the basis of virtually all PostgreSQL wire protocol
  85 communications.
  86
  87 Each frame in this scheme is called a "Message".
  88
  89 The format looks like this::
  90
  91     Message Type.  One 8-bit clean mnemonic ASCII character by
  92     convention, but could be any byte in principle.
  93     |
  94     |
  95     |  Message Length, 4 bytes, including the frame length (but not
  96     |  the type).  Network byte order integer.
  97     |  |
  98     |  |
  99     |  |     Message payload, (length - 4) bytes long.
 100     |  |     |
 101     |  |     |
 102     |  |     |
 103     v  v     v
 104    [-][----][...........]
 105     0  1234  5+
 106
 107 A simple de-framer can be seen in ``pg_logfebe_prototext.go`` in the
 108 procedure ``readMessage``.
 109
 110 Protocol
 111 ========
 112
 113 ``pg_logfebe`` is half-duplex: no response from the software receiving
 114 ``pg_logfebe`` traffic is required.  At connection startup, two
 115 special messages are sent, followed by an infinite series of log
 116 records.
 117
 118 A concrete implementation can be seen in ``pg_logfebe_prototext.go``,
 119 in ``handleConnection``.
 120
 121 The protocol is versioned in its startup sequence to allow for gradual
 122 change.
 123
 124 A server receiving ``pg_logfebe`` will receive a stream of messages
 125 that will occur in this order::
 126
 127    (T)ype              Payload
 128    ---------------------------
 129
 130    (V)ersion           "PG-9.2.4/logfebe-1"
 131
 132    (I)dentification    "Any-string-set-via-logfebe.identity"
 133
 134    (L)og Record        [many structured fields]
 135    (L)og Record
 136    ...[Log Records ad-infinitum]...
 137
 138 Message Format Reference
 139 ========================
 140
 141 Reference guide:
 142
 143 * Fields are listed in order.
 144
 145 * All numerical types are network byte order.
 146
 147 * "CStrings" are NUL-terminated strings.
 148
 149 * "\*CStrings" are nullable-CStrings.  These are formatted like
 150   CStrings that always start with one byte: ``N``\(ull) or
 151   ``P``\(resent).  This is to disambiguate empty strings from C-`NULL`
 152   pointers in the PostgreSQL backend.
 153
 154 =======
 155 Version
 156 =======
 157
 158 ::
 159
 160    (V)ersion
 161            Version CString
 162
 163 The version is of the format "PG-9.2.4/logfebe-1", where the former
 164 part is the Postgres version emitting the logs (as different versions
 165 of Postgres may have slightly different ``LogRecord`` fields available
 166 at some future time), and the latter part after the ``/`` is the
 167 ``pg_logfebe`` protocol version, which is to be incremented if the
 168 protocol mechanics unrelated to the Postgres version are changed.
 169
 170 ==============
 171 Identification
 172 ==============
 173
 174 ::
 175
 176    (I)dentification
 177            Ident CString
 178
 179 ==========
 180 Log Record
 181 ==========
 182
 183 ::
 184
 185    (L)og Record
 186            LogTime          CString
 187            UserName         *CString
 188            DatabaseName     *CString
 189            Pid              int32
 190            ClientAddr       *CString
 191            SessionId        CString
 192            SeqNum           int64
 193            PsDisplay        *CString
 194            SessionStart     CString
 195            Vxid             *CString
 196            Txid             uint64
 197            ELevel           int32
 198            SQLState         *CString
 199            ErrMessage       *CString
 200            ErrDetail        *CString
 201            ErrHint          *CString
 202            InternalQuery    *CString
 203            InternalQueryPos int32
 204            ErrContext       *CString
 205            UserQuery        *CString
 206            UserQueryPos     int32
 207            FileErrPos       *CString
 208            ApplicationName  *CString