2steps-jslogger

2steps-jslogger

npm package for Twosteps Node.js apps. Install in any project — logs go to OTEL Collector → Elasticsearch → Kibana.

your-app  →  OTEL Collector  →  Elasticsearch  →  Kibana

Node.js 18+

---

Quick start

1. Install

npm install 2steps-jslogger dotenv

2. Create .env (project root)

OTEL_EXPORTER_OTLP_ENDPOINT=https://otel.your-host.example.com
OTEL_EXPORTER_OTLP_HEADERS="Authorization=Basic <your-token>"
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf

OTEL_SERVICE_NAME=service-my-app
LOGGER_PROJECT_NAME=Project-my-app
LOGGER_ENVIRONMENT=development

OTEL_RESOURCE_ATTRIBUTES="environment=mac,host.name=my-host,elasticsearch.index=my-app-logs-v1"
OTEL_ELASTIC_MAPPING_MODE=bodymap

3. Create logger.js

require('dotenv').config();
const { CustomLogger } = require('2steps-jslogger');

const logger = new CustomLogger();

module.exports = { logger };

Service, project, environment, and index come from .env — no options needed in code.

4. Use in your app

const { logger } = require('./logger');

logger.info('Server started');
logger.info('User action', { user_id: 789, action: 'login' });
logger.warning('Slow API', { latency_ms: 420 });
logger.debug('Debug info', { step: 1 });
logger.error('Failed', { error_code: 'ERR_001' }, new Error('details'));

await logger.flush();
await logger.close();

Note: logger.info() and similar calls do not throw if OTLP export fails. Errors appear when you call flush() or close(). Always call both before process exit (scripts, tests, graceful shutdown).

---

Testing

A. This repo — OTEL logs to Kibana (examples/test-logger.js)

Uses require('2steps-jslogger') like real apps. One-time setup:

cd nodejs-logger
cp examples/.env.example examples/.env
# Edit examples/.env — token, elasticsearch.index, service name

Each test run:

npm run build
npm link
npm link 2steps-jslogger
node examples/test-logger.js

Or one command (build + link + run):

npm run test:logger

Env file: examples/.env
Kibana: data view {your-index}* from elasticsearch.index (e.g. jslogger-otel-v4*), time field @timestamp, last 15 minutes.

B. This repo — production env file (.env.production)

No 2steps-jslogger link; uses local dist/:

npm run dev:test:prod

Env file: .env.production (repo root)

C. Unit tests (no logs sent)

npm test

D. Your app (after npm install 2steps-jslogger)

npm install 2steps-jslogger dotenv
cp node_modules/2steps-jslogger/examples/test-logger.js scripts/test-logger.js
cp node_modules/2steps-jslogger/examples/.env.example scripts/.env
# Edit scripts/.env
node scripts/test-logger.js

---

Express example

const express = require('express');
const { logger } = require('./logger');

const app = express();

app.get('/health', (req, res) => {
  logger.info('Health check');
  res.json({ ok: true });
});

const server = app.listen(3000, () => logger.info('Listening on 3000'));

async function shutdown() {
  await logger.flush();
  await logger.close();
  server.close(() => process.exit(0));
}

process.on('SIGINT', shutdown);
process.on('SIGTERM', shutdown);

---

Log levels

Override: LOGGER_LEVEL=DEBUG or LOGGER_LEVEL=INFO

---

Extra fields

logger.info('Request', {
  request_id: 'abc',
  method: 'POST',
  endpoint: '/api/orders',
  duration_ms: 120,
});

logger.info('Login', {
  user_id: '123',
  email: 'user@example.com',
});

In Kibana: custom_fields.*, auth.*, request_context.*

---

Example .env

OTEL_EXPORTER_OTLP_ENDPOINT=https://otel.your-host.example.com
OTEL_EXPORTER_OTLP_HEADERS="Authorization=Basic <token>"
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf

OTEL_SERVICE_NAME=service-my-app
LOGGER_PROJECT_NAME=Project-my-app
LOGGER_ENVIRONMENT=development

OTEL_RESOURCE_ATTRIBUTES="environment=mac,host.name=my-host,elasticsearch.index=my-app-logs-v1"
OTEL_ELASTIC_MAPPING_MODE=bodymap

---

TypeScript

import { CustomLogger } from '2steps-jslogger';

export const logger = new CustomLogger();

---

Troubleshooting

---

Versioning & release (bumpit)

This repo uses @twostepsai/bumpit for semver and changelog.

Contributor workflow (before merge)

After your code changes, record release intent:

npx @twostepsai/bumpit add

Or non-interactive (CI / scripts):

npx @twostepsai/bumpit add --level patch --message "Fix OTLP header parsing"

Commit the generated .bumpit/*.md change file with your PR.

Check pending changes:

npm run version:status

Maintainer — publish via GitHub Actions

1. Merge all PRs to main.
2. GitHub → Actions → Release → Run workflow.
3. Choose bump type: patch | minor | major.
4. Workflow runs: test → bumpit bump → build → npm publish → git tag → GitHub Release.

Required secret: NPM_TOKEN (npm automation token with publish access).

Maintainer — publish locally (optional)

npm run version:bump    # bumps package.json + CHANGELOG.md
npm run build
npm publish --access public
git push origin HEAD --follow-tags

---

License

MIT