https://github.com/jkrenge/log-to-database
Logs events of specific types to a database.
https://github.com/jkrenge/log-to-database
Last synced: 3 months ago
JSON representation
Logs events of specific types to a database.
- Host: GitHub
- URL: https://github.com/jkrenge/log-to-database
- Owner: jkrenge
- License: mit
- Created: 2016-01-01T18:43:49.000Z (over 9 years ago)
- Default Branch: master
- Last Pushed: 2016-01-02T17:49:43.000Z (over 9 years ago)
- Last Synced: 2025-02-25T10:50:02.695Z (3 months ago)
- Language: JavaScript
- Size: 10.7 KB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
> Persistent write-only logging of requests, events, cycles, and loads to a database, it's basically written in stone.
TOC: [Overview](#overview), [Setup](#setup), [Quick start](#event-types-to-log), [Advanced](#advanced-usage), [Contribute](#contribute)
# Overview
Supports two engines: `MongoDB` (default and recommended), and `MySQL` (alpha, limited functionality).
# Setup
Install via [npm](https://www.npmjs.com/package/written-in-stone):
```
npm install written-in-stone --save
```
Then, as listed in `samples/log.js` init the logger:
```
const WrittenInStone = require('written-in-stone');
const stonePlate = new WrittenInStone('mongodb', {
path: 'mongodb://localhost/test'
});
```
# Event types to log
Then you can log an `event` with certain fixed attributes per type, and a `payload`. Following `event` types exist:
Type | Fixed attributes | Usage
:-------------------- | :--------------------------- | :--------------------------------------------------------
[Activity](#activity) | `activity` | Atomic events like *email sent*
[Status](#status) | `key`, `value` | Values that change over time like *load of queue*
[Request](#request) | `requester`, `requested` | Requests of resources like *requested endpoint*
[Cycle](#cycle) | `type`, `identifier`, `step` | Incremental monitoring like *endqueued*, then *processed*
## Activity
An `activity` logs the firing of some atomic function.
The `activity` acts as a category, additional information can be logged in the `payload`, e.g. if an email is sent.
```
const activity = 'email-sent';
var payload = {
to: '[email protected]',
from: '[email protected]'
};
stonePlate.engraveActivity(activity, payload);
```
## Status
A `status` reflects the current state of the application.
The `key` is the variable of which the snapshot should be made, the `value` represents the snapshot itself, i.e. its current status. With the `payload`, any additional information can be logged. This makes sense to e.g. log the current waiting jobs in a queue (redis).
```
const key = 'queue-waiting-jobs';
var value = getNumberOfJobsInQueue();
var payload = {
env: process.env.NODE_ENV
};
stonePlate.engraveStatus(key, value, payload);
```
## Request
A `request` logs, as the name suggests, a request of a resource.
The `requester` is the requesting entity, e.g. the users IP address in an Express.js service. `requested` represents the requested resource, e.g. a fixed name for a certain service. Within the `payload` additional information can be stored.
**Note:** So far, only the `event` type `request` is supported with MySQL as persistence.
```
const requested = 'name-of-this-resource';
var requester = req.headers['x-forwarded-for'] || req.connection.remoteAddress;
var payload = {
query: req.query
};
stoneLog.request(requester, requested, payload);
```
## Cycle
A `cycle` event is one step in the processing of a certain object. E.g. if a document from the database is processed in several steps, each `step` can be enumerated.
The `type` described the kind of cycle. The `identifier` is unique for the cycle. The `step` represents the current progress. The combination of `identifier` and `step` is required to be unique.
```
// after enqueueing a job
const type = 'render-images';
var identifier = job.id;
var step = 0;
var payload = {
imageSource: 'user-upload'
}
stonePlate.engraveCycle(type, identifier, step, payload);
```
Then, in a later step:
```
// in the queue worker after processing is done
const type = 'render-images';
var identifier = job.id;
var step = 1;
stonePlate.engraveCycle(type, identifier, step, null);
```
# Advanced usage
## Instances
To segregate your logs, you can also pass an `instance` (which is a `Number`) to every `.engraveX()` as optional first parameter.
```
stonePlate.engraveActivity(0, 'something-happened, null');
```
## Callbacks
Every `.engraveX()` has a `callback` as optional last parameter.
```
stonePlate.engraveActivity('something-happened', null, function (err) {
console.log(err);
});
```
# Contribute
This is all dirty. ✋ If you want to help, please do.
Licensed as [MIT](http://opensource.org/licenses/MIT), uses
[async](https://github.com/caolan/async),
[mongoose](http://mongoosejs.com/),
[node-mysql](https://github.com/felixge/node-mysql),
[underscore](http://underscorejs.org/).