Learn about our RFC process, Open RFC meetings & more.Join in the discussion! »

logarithm

2.4.0 • Public • Published

logarithm

npm version

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

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 © Art Deco™ 2020

Install

npm i logarithm

DownloadsWeekly Downloads

5

Version

2.4.0

License

AGPL-3.0

Unpacked Size

102 kB

Total Files

40

Homepage

www.idio.cc/

Last publish

Collaborators

  • avatar