Loading...
Searching...
No Matches
logger.h File Reference
Loggers » Logger API

Modular Janus loggers (headers). More...

`#include <stdlib.h>`
`#include <stdint.h>`
`#include <stdio.h>`
`#include <string.h>`
`#include <ctype.h>`
`#include <unistd.h>`
`#include <inttypes.h>`
`#include <glib.h>`
`#include <jansson.h>`
`#include "../utils.h"`
Include dependency graph for logger.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

## Data Structures

struct | janus_logger
| The logger plugin session and callbacks interface. More...

## Macros

#define | JANUS_LOGGER_API_VERSION 3
| Version of the API, to match the one logger plugins were compiled against.
#define | JANUS_LOGGER_INIT(...)
| Initialization of all logger plugin properties to NULL.

## Typedefs

typedef struct janus_logger | janus_logger
| The logger plugin session and callbacks interface.
typedef janus_logger * | create_l(void)
| The hook that logger plugins need to implement to be created from the Janus core.

## Detailed Description

Modular Janus loggers (headers).

Author
  Lorenzo Miniero loren.nosp@m.zo@m.nosp@m.eetec.nosp@m.ho.c.nosp@m.om

Copyright
  GNU General Public License v3

This header contains the definition of the callbacks all the custom loggers need to implement to interact with the Janus core. In fact, a custom logger is basically a module that receives log lines from the Janus core and plugins, so that they can be handled somehow (e.g., aggregated or forwarded elsewhere).

An logger plugin that wants to register at the Janus core needs to implement the `janus_logger` interface. This includes callbacks the Janus core can use to receive log lines to process. Besides, as a logger plugin is a shared object, and as such external to the core itself, in order to be dynamically loaded at startup it needs to implement the `create_l()` hook as well, that should return a pointer to the plugin instance. This is an example of such a step:

    static janus_logger mylogger = {
            [..]
    };

    janus_logger *create(void) {
            JANUS_LOG(LOG_VERB, , "%s created!\n", MY_LOGGER_NAME);
            return &mylogger;
    }

This will make sure that your logger plugin is loaded at startup by the Janus core, if it is deployed in the proper folder.

As anticipated and described in the above example, a logger plugin must basically be an instance of the `janus_logger` type. As such, it must implement the following methods and callbacks for the core:

- `init()`: this is called by the Janus core as soon as your logger plugin is started; this is where you should setup your logger plugin (e.g., static stuff and reading the configuration file);
- `destroy()`: on the other hand, this is called by the core when it is shutting down, and your logger plugin should too;
- `get_api_compatibility()`: this method MUST return JANUS_LOGGER_API_VERSION;
- `get_version()`: this method should return a numeric version identifier (e.g., 3);
- `get_version_string()`: this method should return a verbose version identifier (e.g., "v1.0.1");
- `get_description()`: this method should return a verbose description of your logger plugin (e.g., "This is a logger that saves log lines on a database");
- `get_name()`: this method should return a short display name for your logger plugin (e.g., "My Amazing Logger");
- `get_package()`: this method should return a unique package identifier for your logger plugin (e.g., "janus.logger.mylogger");
- `incoming_logline()`: this callack informs the logger that a log line is available for consumption.

All the above methods and callbacks are mandatory: the Janus core will reject al logger plugin that doesn't implement any of the mandatory callbacks.

Unlike other kind of modules (transports, plugins), the `init()` method here only passes the path to the configurations files folder, as loggers never need to contact the Janus core themselves. This path can be used to read and parse a configuration file for the logger plugin: the logger plugins we made available out of the box use the package name as a name for the file (e.g., `janus.logger.json.jcfg` for the sample logger plugin), but you're free to use a different one, as long as it doesn't collide with existing ones. Besides, the existing logger plugins use the same libconfig format for configuration files the core uses (relying on the `janus_config` helpers for the purpose) but again, if you prefer a different format (XML, JSON, etc.) that's up to you.

Logger API

## Macro Definition Documentation

## JANUS_LOGGER_API_VERSION

#define JANUS_LOGGER_API_VERSION 3

Version of the API, to match the one logger plugins were compiled against.

## JANUS_LOGGER_INIT

#define JANUS_LOGGER_INIT | ( |  | ... | ) |

Value:
{ \
.init = NULL, \
.destroy = NULL, \
.get_api_compatibility = NULL, \
.get_version = NULL, \
.get_version_string = NULL, \
.get_description = NULL, \
.get_name = NULL, \
.get_author = NULL, \
.get_package = NULL, \
.incoming_logline = NULL, \
## __VA_ARGS__ }

Initialization of all logger plugin properties to NULL.

Note
  All logger plugins MUST add this as the FIRST line when initializing their logger plugin structure, e.g.:

    static janus_logger janus_fake_logger_plugin =
            {
                    JANUS_LOGGER_INIT,

                    .init = janus_fake_init,
                    [..]

## Typedef Documentation

## create_l

typedef janus_logger * create_l(void)

The hook that logger plugins need to implement to be created from the Janus core.

## janus_logger

typedef struct janus_logger janus_logger

The logger plugin session and callbacks interface.