README

logarithm

logarithm Is A Koa Middleware That Records Logs In ElasticSearch. The CLI binary also allows to execute commands on the ElasticSearch instance via the API, such as:

creating snapshots,
installing templates,
etc

yarn add logarithm

Table Of Contents
API
logarithm(options: !Config): !_goa.Middleware
- Config
- Hit
async ping(url: string, timeout: number): void
CLI
- List Templates, -T
- Statistics, -s
Copyright & License

API

The package is available by importing its default function and a named function:

import logarithm, { ping } from 'logarithm'

`logarithm(`_{options: !Config,}`): !_goa.Middleware`

Creates a middleware for logging requests in Koa/Goa web-server and returns it.

options* !Config: Options for the middleware.

Config: Options for the program.

Name	Type & Description	Default
app*	string	-

	The name of the website application.
url*	string	-

	ElasticSearch endpoint URL, e.g., `http://192.168.0.1:9200`.
timeout	number	`5000`

	Timeout for the connection after which an error is shown.
pipeline	string	`info`

	The pipeline in ElasticSearch, for example to parse GeoIP info and User-Agent.
index	string	-

	The name of the index. Defaults to the app name if not specified.
strategy	(index: string, date: !Date) => string

	How to construct the index name. By default, monthly strategy is used: `${index}-${yyyy}.${mm}`. `index` `string`: The general name of the index. `date` `!Date`: The date of the request.

/* yarn example/ */
import core from '@idio/idio'
import logarithm, { ping } from 'logarithm'

(async () => {
  await ping(process.env.ELASTIC)

  // setup for idio web-server
  const { url, app } = await core()

  app.use(logarithm({
    app: 'idio.cc',
    url: process.env.ELASTIC,
    index: 'clients',
  }))
  app.use(async (ctx) => {
    ctx.body = 'hello world'
  })
  console.log(url)
})()

The following data structure is sent to the server:

Hit: A record sent to ElasticSearch.

Name	Type	Description
app*	string	The application name from the config.
ip*	string	Client IP address.
path*	string	The decoded request path.
headers*	!Object	The request headers.
status*	number	The status code.
date*	!Date	The date of the request.
method*	string	The method of the request, e.g., `GET` or `POST`.
query	!Object	Possible query from the request.

`async ping(`_{url: string,
timeout: number,}`): void`

Check that a connection to the ElasticSearch server can be established. Will throw an error after timeout.

url* string: The ElasticSearch URL.
timeout* number: The timeout for the request in ms.

CLI

Logarithm also provides a CLI tool to be able to install index patterns and a pipeline for the use by the middleware API.

logarithm -h

ElasticSearch utility for creating a pipeline and index templates
for logging request using logarithm middleware.

  logarithm <url> [-TPS] [-p pipeline] [-d]

    url            	The ElasticSearch URL.
                    If protocol is not given, `http` is assumed.
    --stats, -s    	Display statistics by indices.
    --templates, -T	List all index templates.
    --delete, -d   	Delete an index, snapshot or pipeline.
                    Used with the relevant flag.
    --index, -i    	Select an index for operations.
    --pipeline, -p 	Create a pipeline with `User-Agent`
                    and `GeoIp` plugins.
    --pipelines, -P	Display installed pipelines.
    --snapshots, -S	List registered snapshot repositories.
    --help, -h     	Print the help information and exit.
    --version, -v  	Show the version's number and exit.

Snapshots: used to print info, create and restore snapshots.

  logarithm <url> [-r repo] [-s snapshot] [-s3 snapshot --bucket bucket] [--status|-d]

    --repository-s3, -s3	Create a new `s3` snapshot repo with this name.
    --bucket            	The bucket name for the `s3` snapshot repository.
    --repo, -r          	The name of the repo.
    --snapshot, -s      	The name of the snapshot.
    --restore           	Restore this snapshot.
    --status            	Fetch the status.

Templates: creates a template for an app.

  logarithm <url> -t {app-name} [-s shards] [-r replicas] [-d]

    --template, -t	Create an index template for storing
                    log data in the `{template}-*` index.
    --shards, -s  	The number of shards for index template.
                    Default: 1.
    --replicas, -r	The number of replicas for index template.

Methods: send data from JSON files.

  logarithm <url> [--post data.json] -p path

    --post    	Send POST request with data from the file.
    --path, -p	The path to send a request to.

📙 Read Wiki For More Documentation

List Templates, `-T`

To see what templates are installed.

logarithm 192.168.0.1:9200 -T

Name                           Patterns          Shards  Replicas
kibana_index_template:.kibana  .kibana           1
hits-logarithm.page            logarithm.page-*  1       0
hits-clients                   clients-*         1       0
hits-client2                   client2-*         1       0

Statistics, `-s`

The stats can be used to monitor created indices.

logarithm 192.168.0.1:9200 -s

Name                      Memory    Docs  Size
logarithm.page          11.6 KB   1     21.6 KB
logarithm.page-2018.12  60.4 KB   8859  3.3 MB
logarithm.page-2018.11  64.4 KB   116   179.5 KB
logarithm.page-2019.2   151.4 KB  63    279.1 KB
logarithm.page-2019.1   120.7 KB  5747  2.2 MB

Copyright & License

GNU Affero General Public License v3.0

	© Art Deco™ 2020

Usage no npm install needed!

README

logarithm

Table Of Contents

API

logarithm( options: !Config,): !_goa.Middleware

async ping( url: string, timeout: number,): void

CLI

List Templates, -T

Statistics, -s

Copyright & License

`logarithm(`_{options: !Config,}`): !_goa.Middleware`

`async ping(`_{url: string,
timeout: number,}`): void`

List Templates, `-T`

Statistics, `-s`