npm package: 2steps-jslogger
Description: Node.js logger for Elasticsearch with ECS format. Filter logs by index name, date, month.
Author: Twosteps
Latest version: 1.0.3

# Elastic Logger (Node.js)

Node.js logger library that sends logs to Elasticsearch in ECS-style format.
It supports:

- project-based index naming
- monthly indices (`project-03-26`) and daily indices (`project-2026.03.12`)
- querying logs by index/date/month/severity
- listing indices for UI filters

## Why `npm install 2steps-jslogger`?

This command is for **other projects/apps** that want to use this logger as a package.

- If package is published: install via npm registry.
- In this repository (local development): use local code by building and running demo scripts.

## Requirements

- Node.js 18+
- Elasticsearch running on `localhost:9200`

## Configure Elasticsearch via ENV

You can configure the Elasticsearch connection using environment variables (useful for local vs production):

```bash
# Local development
export ELASTIC_HOST=localhost
export ELASTIC_PORT=9200
export ELASTIC_SCHEME=http

# Production
export ELASTIC_HOST=elastic.shayb-vps.cloud
export ELASTIC_PORT=443
export ELASTIC_SCHEME=https
export ELASTIC_USERNAME=elastic
export ELASTIC_PASSWORD='***'
```

Supported variables:

- `ELASTIC_HOST`
- `ELASTIC_PORT`
- `ELASTIC_SCHEME` (`http` / `https`)
- `ELASTIC_USERNAME`
- `ELASTIC_PASSWORD`
- `ELASTIC_API_KEY`
- `ELASTIC_CLOUD_ID`

## Setup (local development)

```bash
cd /home/saud/ESS/github/twosteps/logger/nodejs-logger
npm install
```

## Create Elasticsearch template (like Python version)

Create template first for your project prefix:

```bash
# demo project
npm run template:create -- --prefix demo-api

# benchmark project
npm run template:create -- --prefix benchmark

# custom project
npm run template:create -- --prefix test-demo
```

If template pattern conflicts (e.g. `benchmark-*` and `benchmark-demo-*`), set higher priority:

```bash
npm run template:create -- --prefix benchmark-demo --priority 10
```

## Use logger in Node.js app

```javascript
const { CustomLogger } = require('2steps-jslogger');

const logger = new CustomLogger({
  name: 'test-demo',
  indexPattern: 'test-demo-{month}', // test-demo-03-26
  serviceName: 'test-demo',
  projectName: 'test-demo',
  environment: 'development',
  level: 10, // DEBUG
});

logger.info('Application started');
logger.debug('Debug trace', { step: 1 });
logger.error('Operation failed', { error_code: 'ERR_001' }, new Error('Details'));
```

## Query logs (index/date/month)

```javascript
const { queryLogs, listIndices } = require('2steps-jslogger');

const result = await queryLogs({
  indexPattern: 'test-demo*',
  year: 2026,
  month: 3,
  severity: 'ERROR',
  size: 100,
  from: 0,
});

console.log(result.total, result.hits);

const indices = await listIndices('test-demo*');
console.log(indices);
```

## Run demo

```bash
npm run demo
```

Demo server:

- `GET /`
- `GET /health`
- `GET /users/:userId`
- `POST /items`
- `GET /error`
- `GET /logs?index_pattern=demo-api*&year=2026&month=3`
- `GET /logs/indices?pattern=demo-api*`
- `GET /logs/project/demo-api?year=2026&month=3`

## Python-like quick test (new-test)

Add test file here:

- `nodejs-logger/new-test-node.js`

Commands (exact order):

```bash
cd /home/saud/ESS/github/twosteps/logger/nodejs-logger
npm install

# 1) Make sure Elasticsearch is running
curl http://localhost:9200

# 2) Create template for prefix
npm run template:create -- --prefix new-test

# 3) Send logs (includes DEBUG)
npm run test:new

# 4) Verify in Elasticsearch
curl "http://localhost:9200/_cat/indices/new-test*?v"
curl "http://localhost:9200/new-test-03-26/_search?pretty"
```

Kibana:

- Create/select Data View: `new-test*`
- Time field: `@timestamp`
- Time range: Last 15 minutes / Last 24 hours

## Kibana

Create data view for your project prefix:

- `demo-api*`
- `benchmark*`
- `test-demo*`

Use `@timestamp` as time field.

## GitHub Actions (CI/CD)

This repo now includes:

- `.github/workflows/ci.yml` (build checks on push/PR)
- `.github/workflows/publish.yml` (publishes package to npmjs on tag push like `v1.0.1`)

To publish:

1. Update version in `package.json`
2. Commit + push changes
3. Create and push tag:

```bash
git tag v1.0.1
git push origin v1.0.1
```

`publish.yml` will publish `2steps-jslogger` to npmjs.

### Required GitHub secret

Add repository secret:

- `NPM_TOKEN`: an npm access token with publish permissions.

## Notes

- `{month}` format = `MM-YY` (e.g. `03-26`)
- `{date}` format = `YYYY.MM.DD` (e.g. `2026.03.12`)
- Default logger level is INFO. For debug logs, set `level: 10`.