microkit

Node.js microservice toolkit

Abstraction toolkit for microservices, to make nodejs developers happy again.

Installation

$ npm install --save @gatehub/microkit

Usage

var MicroKit = require('microkit');

// Instantiate MicroKit
var microkit = new MicroKit({
  name: 'myAwesomeService',
  environment: 'production',
  logLevel: 'info',
  catchGlobal: true, // catch global errors
  queue: {
    name: 'amqp',
    url: "amqp://localhost",
    queue: 'myAwesomeService'
  }, // queue provider config
  error: {name: 'sentry', url: "https://dd..ba:[email protected]/24343"}, // error reporter config
  stats: {name: 'statsd', host: "statsd.example.com"}, // stats reporter config
  api: {
    name: 'swagger',
    services: {
      serviceA: {url: 'http://api.domain.com/swagger.yaml'},
    }
  }
});

/** or for development it will log on stdout
 *  var microkit = new MicroKit({name: 'myAwesomeService'});
 **/

// Logging
microkit.logger.debug('message', {key: 'value'});
microkit.logger.info('message', {key: 'value'});
microkit.logger.warn('message', {key: 'value'});
microkit.logger.fatal(new Error("some error"));
microkit.logger.error('message', {key: 'value', err: new Error("some error")});

var logger = microkit.logger.create('componentName', {some: 'context'});
logger.info('message', {key: 'value'});

// Queue
microkit.queue.publish({key: 'value'}, {some: 'data'});
microkit.queue.publish({key: {key: 'value'}, message: {key: 'value'}});
microkit.queue.subscribe({key: 'value'}, (msg, info) => {
  console.log("message", msg);
  console.log("key", info.key);
});

// Error reporting
microkit.error.capture(new Error('some error'));

// Metrics
microkit.metrics.send('some.metric', 10, {tag1: 'value', tag2: 'value2'});

// Exit handling
microkit.onExit(() => server.close());

// Express integration (logging, error reporting)
app.use(microkit.express.preHandler); // before all middlewares
app.use(microkit.express.postHandler); // after middlewares

// API calling
microkit.api.call('serviceA', 'getUser', {id: '123-456'});

// config
microkit.config.get('key.value');

// common errors
const MyConnectionError = microkit.errors.ConnectionError.extend({
  name: 'MyConnectionError'
});
throw new MyConnectionError({code: 'database_error', error: err});

Tracing

To enable tracing, it needs to be included in the start script for it to be loaded before everything else:

    "start": "node --require @gatehub/microkit/lib/telemetry.js dist/server.js",

Configuration

The configuration parameters will be acquired from the environment variables. The following environment variables are required:

# The destination to send traces to
  OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://localhost:4318/v1/traces
# Your service name - it will be listed as such in the traces
  OTEL_SERVICE_NAME=my-service-name
# Log level - info is fine unless debugging
  OTEL_LOG_LEVEL=info
# Enable tracing database requests
  TRACING_SQL_ENABLE=true

For local and service specific configuration two configuration files are required:

• .tracing.json : Runtime configuration with excludeRoutes and ignoredOutgoingHosts (other parameters should be set-up as env vars)
• dev.tracing.json: Local configuration (all parameters)

Any configuration variables that are acquired from the environment will take priority over the configuration file.

Example:

{
  "otlpEndpoint": "http://localhost:4318/v1/traces", // optional, dev 
  "otelServiceName": "service-name", // optional, dev
  "otelLogLevel": "info", // optional, dev
  "otelSqlTracingEnabled": true, // optional, dev, default false
  "otelAmqpTraceContentEnabled": true, // optional, dev, default false
  "excludeRoutes": [
    "/healthz/liveness",
    "/metricz"
  ],
  "ignoredOutgoingHosts": [
  ]
}

Usage

Any function can be annotated with TraceSpan to add it to the trace. getActiveSpan() can be used to get the current active span. spanObjectStringify() can be used to stringify any object into an appropriate format.

    @microkit.tracing.TraceSpan()
    public async someFunction(payload: Payload) {
        const span = microkit.tracing.getActiveSpan()
        span?.setAttribute(
            'some-attribute-name-payload',
            microkit.tracing.spanObjectStringify(payload),
        );

        ... function body
    }

License

MIT © GateHubNet