https://github.com/artdecocode/logarithm
A Koa Middleware For Web-Server To Record Hits In ElasticSearch.
https://github.com/artdecocode/logarithm
Last synced: about 2 months ago
JSON representation
A Koa Middleware For Web-Server To Record Hits In ElasticSearch.
- Host: GitHub
- URL: https://github.com/artdecocode/logarithm
- Owner: artdecocode
- License: mit
- Created: 2018-11-18T05:16:08.000Z (about 7 years ago)
- Default Branch: master
- Last Pushed: 2020-03-10T01:04:14.000Z (almost 6 years ago)
- Last Synced: 2025-09-07T02:34:55.527Z (4 months ago)
- Language: JavaScript
- Homepage: https://www.artd.eco
- Size: 209 KB
- Stars: 2
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# logarithm
[](https://www.npmjs.com/package/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_
```sh
yarn add logarithm
```
## Table Of Contents
- [Table Of Contents](#table-of-contents)
- [API](#api)
- [`logarithm(options: !Config): !_goa.Middleware`](#logarithmoptions-config-_goamiddleware)
* [`Config`](#type-config)
* [`Hit`](#type-hit)
- [`async ping(url: string, timeout: number): void`](#async-pingurl-stringtimeout-number-void)
- [CLI](#cli)
* [List Templates, `-T`](#list-templates--t)
* [Statistics, `-s`](#statistics--s)
- [Copyright & License](#copyright--license)
## API
The package is available by importing its default function and a named function:
```js
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.
```js
/* 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.
```js
logarithm -h
```
```Dockerfile
ElasticSearch utility for creating a pipeline and index templates
for logging request using logarithm middleware.
logarithm [-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 [-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 -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 [--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](../../wiki) For More Documentation
### List Templates, `-T`
To see what templates are installed.
```sh
logarithm 192.168.0.1:9200 -T
```
```fs
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.
```sh
logarithm 192.168.0.1:9200 -s
```
```sh
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
