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',
socketOptions: {heartbeat: 5, channelMax: 100}, // optional, overrides url params; heartbeat defaults to 5, channelMax to the broker's limit; other keys (e.g. TLS ca/cert) are passed to the socket
reconnectTimeInSeconds: 5, // optional, values <= 0 fall back to the default
publishTimeout: 5000 // optional, ms, default for the per-publish `timeout` option; a timed out message is dropped if not yet sent, but may still be delivered if it was already awaiting the broker's confirm
}, // queue provider config
error: {name: 'sentry', url: "https://dd..ba:[email protected]/24343"} // error reporter config
});
/** 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'}});
// handlers always get the message body and the event
microkit.queue.subscribe({key: 'value'}, (data, event) => {
console.log("message", data);
console.log("headers", event.headers); // {key: 'value'}
console.log("routing key", event.routingKey); // '' for headers messages
console.log("id", event.id); // headers if any, otherwise the routing 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
// 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 withexcludeRoutesandignoredOutgoingHosts(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