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

• 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