include/anna/core/tracing/Logger.hpp

   1 // ANNA - Anna is Not 'N' Anymore
   2 //
   3 // (c) Copyright 2005-2014 Eduardo Ramos Testillano & Francisco Ruiz Rayo
   4 //
   5 // https://bitbucket.org/testillano/anna
   6 //
   7 // Redistribution and use in source and binary forms, with or without
   8 // modification, are permitted provided that the following conditions
   9 // are met:
  10 //
  11 //     * Redistributions of source code must retain the above copyright
  12 // notice, this list of conditions and the following disclaimer.
  13 //     * Redistributions in binary form must reproduce the above
  14 // copyright notice, this list of conditions and the following disclaimer
  15 // in the documentation and/or other materials provided with the
  16 // distribution.
  17 //     * Neither the name of Google Inc. nor the names of its
  18 // contributors may be used to endorse or promote products derived from
  19 // this software without specific prior written permission.
  20 //
  21 // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  22 // "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  23 // LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  24 // A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  25 // OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  26 // SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  27 // LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  28 // DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  29 // THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  30 // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  31 // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  32 //
  33 // Authors: eduardo.ramos.testillano@gmail.com
  34 //          cisco.tierra@gmail.com
  35
  36
  37 #ifndef anna_core_tracing_Logger_hpp
  38 #define anna_core_tracing_Logger_hpp
  39
  40 #include <syslog.h>
  41
  42 #ifdef _MT
  43 #include <pthread.h>
  44 #endif
  45
  46 #include <anna/core/mt/NRMutex.hpp>
  47 #include <anna/core/mt/Guard.hpp>
  48
  49 namespace anna {
  50
  51 class DataBlock;
  52
  53 /**
  54    Facilidad para la realizacion de archivos de historico (logs) de nuestra aplicacion.
  55
  56    @see Patron proxy  http://maniaco/anna/docs/html/DesingPatterns//pat4gfso.htm
  57 */
  58 class Logger {
  59 public:
  60   /**
  61      Nivel de las trazas de historico.
  62
  63      Para mas informacion ver los niveles de emergencia listados en: man syslog.conf
  64
  65      @see Logger
  66   */
  67   enum Level {
  68     Emergency = LOG_EMERG,
  69     Alert = LOG_ALERT, Critical = LOG_CRIT, Error = LOG_ERR, Warning = LOG_WARNING,
  70     Notice = LOG_NOTICE, Information = LOG_INFO, Debug = LOG_DEBUG,
  71     Local0 = LOG_LOCAL0, Local1 = LOG_LOCAL1, Local2 = LOG_LOCAL2, Local3 = LOG_LOCAL3,
  72     Local4 = LOG_LOCAL4, Local5 = LOG_LOCAL5, Local6 = LOG_LOCAL6, Local7 = LOG_LOCAL7
  73   };
  74
  75   /**
  76      Clase virtual que debemos asociar al Logger para transferir las trazas al medio
  77      deseado.
  78
  79      @see DefaultWriter
  80   */
  81   class Writer {
  82   public:
  83     /**
  84        Destructor.
  85     */
  86     virtual ~Writer();
  87
  88     /**
  89        Metodo virtual que debe inicializar el funcionamiento del Writer particular.
  90
  91        @param id Identificador logico. Usado en el  DefaultWriter para inicializar el sistema
  92        del log (metodo syslog).
  93     */
  94     virtual void initialize(const char* id) throw() = 0;
  95
  96     /**
  97        Transfiere el mensaje de trazas al log del sistema. El metodo implementado debe ser
  98        MT-Safe.
  99        No es necesario realizar ningun control del nivel de trazas establecido ya que si la
 100        clase  Logger ha decidido llamar a este metodo es porque el nivel indicado esta
 101        activo.
 102
 103        @param level Nivel de las trazas que vamos a sacar.
 104        @param text Especificacion de formato del mensaje. Similar al usado en el comando sprintf.
 105     */
 106     virtual void do_write(int level, const char* text, ...) throw() = 0;
 107
 108   protected:
 109     /**
 110        Constructor.
 111
 112        @param bufferSize Numero de bytes reservado para la linea de trazas.
 113     */
 114     Writer(const int bufferSize);
 115
 116     /**
 117        Constructor.
 118     */
 119     Writer();
 120
 121     /**
 122        @return La instancia del bloque de datos con memoria reservada para poder interpretar los
 123        parametros.
 124     */
 125     DataBlock& getDataBlock() throw() { return *a_dataBlock; }
 126
 127   private:
 128     DataBlock* a_dataBlock;
 129   };
 130
 131   /**
 132      Inicializa el sistema de historico de nuestra aplicacion. Solo debe invocarse una unica vez
 133      al comienzo de la aplicacion.
 134
 135      Al no indicar ninguna clase encargada de transferir los datos de la aplicacion al
 136      sistema de historico se establece el  Writer por defecto.
 137
 138      Este metodo no es MT-safe por lo que tenemos que estar seguros que no se puede invocar desde
 139      varios thread simultaneamente. Lo mas aconsejable es invocarlo desde el comienzo de la
 140      aplicacion.
 141
 142      @param ident Identifica las trazas de nuestra aplicacion que apareceran  en el archivo de historico.
 143      Deberia ser un texto con entre 4 y 16 caracteres.
 144
 145      @see DefaultWriter.
 146   */
 147   static void initialize(const char* ident) throw();
 148
 149   /**
 150      Inicializa el sistema de historico de nuestra aplicacion. Solo debe invocarse una unica vez
 151      al comienzo de la aplicacion.
 152
 153      Este metodo no es MT-safe por lo que tenemos que estar seguros que no se puede invocar desde
 154      varios thread simultaneamente. Lo mas aconsejable es invocarlo desde el comienzo de la
 155      aplicacion.
 156
 157      @param ident Identifica las trazas de nuestra aplicacion que apareceran  en el archivo de historico.
 158      Deberia ser un texto con entre 4 y 16 caracteres.
 159      @param writer Establece el objeto encargado de transferir los datos de la aplicacion
 160      al sistema de historico. La instancia pasada como parametro debera estar disponible mientras
 161      no termine la ejecucion de nuestra aplicacion. Podemos indicar NULL para desactivar
 162      completamente cualquier sistema de trazas.
 163
 164      @see DefaultWriter.
 165   */
 166   static void initialize(const char* ident, Writer* writer) throw();
 167
 168   /**
 169      @return El nivel de trazado de nuestra aplicacion.
 170   */
 171   static Level getLevel() throw() { return st_level; }
 172
 173   /**
 174      Establece el nivel de trazado de nuestra aplicacion. El nivel de trazado por defecto
 175      de nuestra aplicacion dependera del modo de compilacion, en modo depuracion el nivel
 176      de trazado por defecto sera  Debug, en otro caso sera  Warning.
 177
 178      Solo apareceran en el historico las trazas que lleven un nivel menor que el establecido
 179      en este metodo.
 180
 181      @param level Nivel de trazado que deseamos establecer.
 182   */
 183   static void setLevel(const Level level)
 184   throw(RuntimeException) {
 185     Guard guard(st_mutex, "Logger::setLevel");
 186     st_level = (level <= Error) ? Error : level;
 187   }
 188
 189   /**
 190      Comprueba si el nivel de trazado recibido como parametro esta activo en nuestra aplicacion.
 191
 192      @param level Nivel de trazado que deseamos comprobar.
 193
 194      @return @em true Si el nivel de trazado de nuestra aplicacion es mayor que el recibido como
 195      parametro o @em false en otro caso.
 196   */
 197   static bool isActive(const Level level) throw() {
 198     return (st_writer != NULL && level <= Error) ? true : (st_enabled && level <= st_level && st_writer != NULL);
 199   }
 200
 201   /**
 202      Desactiva el sistema de trazado.
 203   */
 204   static void disable() throw(RuntimeException);
 205
 206   /**
 207      Activa el sistema de trazado y establece el nivel de trazado existente antes
 208      de la desactivacion (Ver  #disable).
 209   */
 210   static void enable() throw(RuntimeException);
 211
 212   /**
 213    * Establece el valor del indicador que hace que se vuelque el PID del proceso en la linea de trazas.
 214    *
 215    * Puede ser util cuando el programa principal cree procesos hijos mediante a la invocacion al metodo \em fork.
 216    *
 217    * \param showPID Valor del indicador.
 218    */
 219   static void showPID(const bool show) throw();
 220
 221   /**
 222      Traza el texto recibido en el historico con el nivel indicado.
 223
 224      La traza solo sera registrada en el historico si el nivel de trazado recibido como
 225      parametro esta habilitado.
 226
 227      @param level Nivel de la traza que deseamos registrar.
 228      @param text Texto de la traza.
 229      @param fromFile Nombre del archivo donde se genera la traza.
 230      @param fromLine Numero de linea del archivo donde se genera la traza.
 231   */
 232   static void write(const Level level, const char* text, const char* fromFile, const int fromLine) throw();
 233
 234   /**
 235      Traza el texto recibido en el historico con el nivel indicado.
 236
 237      La traza solo sera registrada en el historico si el nivel de trazado recibido como
 238      parametro esta habilitado.
 239
 240      @param level Nivel de la traza que deseamos registrar.
 241      @param text Texto de la traza.
 242      @param fromFile Nombre del archivo donde se genera la traza.
 243      @param fromLine Numero de linea del archivo donde se genera la traza.
 244   */
 245   static void write(const Level level, const std::string& text, const char* fromFile, const int fromLine) throw() {
 246     write(level, text.c_str(), fromFile, fromLine);
 247   }
 248
 249   /**
 250      Traza el texto recibido en el historico con el nivel indicado.
 251
 252      La traza solo sera registrada en el historico si el nivel de trazado recibido como
 253      parametro esta habilitado.
 254
 255      @param level Nivel de la traza que deseamos registrar.
 256      @param text Texto de la traza.
 257      @param value Contenido de una cadena.
 258      @param fromFile Nombre del archivo donde se genera la traza.
 259      @param fromLine Numero de linea del archivo donde se genera la traza.
 260   */
 261   static void write(const Level level, const char* text, const char* value, const char* fromFile, const int fromLine) throw();
 262
 263   /**
 264      Traza el texto recibido en el historico con el nivel indicado.
 265
 266      La traza solo sera registrada en el historico si el nivel de trazado recibido como
 267      parametro esta habilitado.
 268
 269      @param level Nivel de la traza que deseamos registrar.
 270      @param text Texto de la traza.
 271      @param value Contenido de una cadena.
 272      @param fromFile Nombre del archivo donde se genera la traza.
 273      @param fromLine Numero de linea del archivo donde se genera la traza.
 274   */
 275   static void write(const Level level, const char* text, const std::string& value, const char* fromFile, const int fromLine)
 276   throw() {
 277     write(level, text, value.c_str(), fromFile, fromLine);
 278   }
 279
 280   /**
 281      Traza el texto recibido en el historico con el nivel indicado.
 282
 283      La traza solo sera registrada en el historico si el nivel de trazado recibido como
 284      parametro esta habilitado.
 285
 286      @param level Nivel de la traza que deseamos registrar.
 287      @param text Texto de la traza.
 288      @param value Contenido de una cadena.
 289      @param fromFile Nombre del archivo donde se genera la traza.
 290      @param fromLine Numero de linea del archivo donde se genera la traza.
 291   */
 292   static void write(const Level level, const std::string& text, const std::string& value, const char* fromFile, const int fromLine)
 293   throw() {
 294     write(level, text.c_str(), value.c_str(), fromFile, fromLine);
 295   }
 296
 297   /**
 298      Traza el texto recibido en el historico con el nivel indicado.
 299
 300      La traza solo sera registrada en el historico si el nivel de trazado recibido como
 301      parametro esta habilitado.
 302
 303      @param level Nivel de la traza que deseamos registrar.
 304      @param text Texto de la traza.
 305      @param value Valor numerico.
 306      @param fromFile Nombre del archivo donde se genera la traza.
 307      @param fromLine Numero de linea del archivo donde se genera la traza.
 308   */
 309   static void write(const Level level, const char* text, const int value, const char* fromFile, const int fromLine)
 310   throw();
 311
 312   /**
 313      Traza el texto recibido en el historico con el nivel indicado.
 314
 315      La traza solo sera registrada en el historico si el nivel de trazado recibido como
 316      parametro esta habilitado.
 317
 318      @param level Nivel de la traza que deseamos registrar.
 319      @param text Texto de la traza.
 320      @param value Bloque de datos a transferir al log del sistema.
 321      @param fromFile Nombre del archivo donde se genera la traza.
 322      @param fromLine Numero de linea del archivo donde se genera la traza.
 323   */
 324   static void write(const Level level, const char* text, const DataBlock& value, const char* fromFile, const int fromLine)
 325   throw();
 326
 327   /**
 328      Si el nivel \em Debug esta activado traza el texto recibido en el historico.
 329      @param text Texto de la traza.
 330      @param fromFile Nombre del archivo donde se genera la traza.
 331      @param fromLine Numero de linea del archivo donde se genera la traza.
 332   */
 333   static void debug(const std::string& text, const char* fromFile, const int fromLine)
 334   throw() {
 335     write(Logger::Debug, text, fromFile, fromLine);
 336   }
 337
 338   /**
 339      Si el nivel \em Information esta activado traza el texto recibido en el historico.
 340      @param text Texto de la traza.
 341      @param fromFile Nombre del archivo donde se genera la traza.
 342      @param fromLine Numero de linea del archivo donde se genera la traza.
 343   */
 344   static void information(const std::string& text, const char* fromFile, const int fromLine)
 345   throw() {
 346     write(Logger::Information, text, fromFile, fromLine);
 347   }
 348
 349   /**
 350      Si el nivel \em Notice esta activado traza el texto recibido en el historico.
 351      @param text Texto de la traza.
 352      @param fromFile Nombre del archivo donde se genera la traza.
 353      @param fromLine Numero de linea del archivo donde se genera la traza.
 354   */
 355   static void notice(const std::string& text, const char* fromFile, const int fromLine)
 356   throw() {
 357     write(Logger::Notice, text, fromFile, fromLine);
 358   }
 359
 360   /**
 361       Si el nivel \em Warning esta activado traza el texto recibido en el historico.
 362       @param text Texto de la traza.
 363       @param fromFile Nombre del archivo donde se genera la traza.
 364       @param fromLine Numero de linea del archivo donde se genera la traza.
 365    */
 366   static void warning(const std::string& text, const char* fromFile, const int fromLine)
 367   throw() {
 368     write(Logger::Warning, text, fromFile, fromLine);
 369   }
 370
 371   /**
 372       Si el nivel \em Error esta activado traza el texto recibido en el historico.
 373       @param text Texto de la traza.
 374       @param fromFile Nombre del archivo donde se genera la traza.
 375       @param fromLine Numero de linea del archivo donde se genera la traza.
 376    */
 377   static void error(const std::string& text, const char* fromFile, const int fromLine)
 378   throw() {
 379     write(Logger::Error, text, fromFile, fromLine);
 380   }
 381
 382   /**
 383       Si el nivel \em Critical esta activado traza el texto recibido en el historico.
 384       @param text Texto de la traza.
 385       @param fromFile Nombre del archivo donde se genera la traza.
 386       @param fromLine Numero de linea del archivo donde se genera la traza.
 387    */
 388   static void critical(const std::string& text, const char* fromFile, const int fromLine)
 389   throw() {
 390     write(Logger::Critical, text, fromFile, fromLine);
 391   }
 392
 393   /**
 394       Si el nivel \em Alert esta activado traza el texto recibido en el historico.
 395       @param text Texto de la traza.
 396       @param fromFile Nombre del archivo donde se genera la traza.
 397       @param fromLine Numero de linea del archivo donde se genera la traza.
 398    */
 399   static void alert(const std::string& text, const char* fromFile, const int fromLine)
 400   throw() {
 401     write(Logger::Alert, text, fromFile, fromLine);
 402   }
 403
 404   /**
 405       Si el nivel \em Emergency esta activado traza el texto recibido en el historico.
 406       @param text Texto de la traza.
 407       @param fromFile Nombre del archivo donde se genera la traza.
 408       @param fromLine Numero de linea del archivo donde se genera la traza.
 409    */
 410   static void emergency(const std::string& text, const char* fromFile, const int fromLine)
 411   throw() {
 412     write(Logger::Emergency, text, fromFile, fromLine);
 413   }
 414
 415   /**
 416      @return La cadena que identifica al nivel recibido como parametro.
 417
 418   */
 419   static const char* asString(const Level level) throw();
 420
 421   /**
 422      Traduce la cadena recibida al nivel correspondiente.
 423
 424      @param level Cadena que deberia contener un nombre de nivel (emerg, alert, crit, err, warning, notice, info, debug).
 425
 426      \warning Debe de ser alguno de los siguiente literales: emerg, alert, crit, err, warning, notice, info, debug
 427   */
 428   static Level asLevel(const char* level) throw(RuntimeException);
 429
 430 private:
 431   static NRMutex st_mutex;
 432   static Level st_level;
 433   static bool st_enabled;
 434   static Writer* st_writer;
 435
 436 #ifndef _MT
 437   static pid_t st_pid;
 438 #endif
 439
 440   Logger();
 441
 442   friend class Logger::Writer;
 443 };
 444
 445 } //namespace anna
 446
 447 #endif
 448
 449