Traceo SDK for Node.js

Library for integration with the Traceo Platform.

Installation

To install this SDK add this package to your package.json like below:

yarn add @traceo-sdk/node

or

npm install @traceo-sdk/node

Usage

First what you need is to initialize TraceoClient in your application.

import { TraceoClient } from "@traceo-sdk/node";

new TraceoClient(<project_api_key>, {
    host: <traceo_host>
});

TraceoClient constructor required two attribtues. First one in api key which you can generate in project settings. Second is an object contains required attribute host which specifies the address where your Traceo Platform instance is located. Address should be passed in the format <protocol>://<domain>:<port>, eq. http://localhost:3000.

Incidents handling

Incidents are all the exceptions and other problems that occur in your application. After each exception occurs, the Traceo SDK catches the exception and sends it to the Traceo Platform. This package provide the two main ways to catch exceptions in your application - Handlers and Middlewares.

Handlers

The easiest way is to use ExceptionsHandlers.catchException() in try-catch clause like below:

import { ExceptionHandlers } from "@traceo-sdk/node";

try {
    //your code
} catch (error) {
    ExceptionHandlers.catchException(error);
}

If you use NestJS framework then you can also create Interceptor to catch exceptions like below:

traceo.interceptor.ts

import { ExceptionHandlers } from "@traceo-sdk/node";
//other imports

@Injectable()
export class TraceoInterceptor implements NestInterceptor {
  intercept(context: ExecutionContext, next: CallHandler): Observable<any> {
    return next.handle().pipe(
      tap(null, (exception) => {
        ExceptionHandlers.catchException(exception);
      }),
    );
  }
}

main.ts

  app.useGlobalInterceptors(new TraceoInterceptor());

Middleware

Another approach is to use ExceptionMiddlewares.errorMiddleware(). If you use the Express.js framework, you can use our middleware like below:

Javascript:

import { ExceptionMiddlewares } from "@traceo-sdk/node";

app.use(ExceptionMiddlewares.errorMiddleware());

Typescript:

const { ExceptionMiddlewares } from "@traceo-sdk/node";

app.use(ExceptionMiddlewares.errorMiddleware() as express.ErrorRequestHandler);

Remember that ExceptionMiddlwares.errorMiddleware() should be before any other error middlewares and after all routes/controllers.

Middleware options

| Parameter | Description | Default | | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | | allowLocalhost | If false then middleware doesn't catch exceptions from requests coming from localhost | true | | allowHttp | If false then middleware doesn't catch exceptions received from requests where req.protocol = http and catch only exception received with https | true |

Logger

The Traceo SDK can be used also as a logger. Each log is saved on the Traceo Platform, thanks to which it is possible to later easily access the recorded information. Logs are sent to Traceo in every 60 seconds. To change this behavior, set a custom value (measured in seconds) in the scrapLogsInterval field inside traceo client properties like below:

import { TraceoClient } from "@traceo-sdk/node";

new TraceoClient(<project_api_key>, {
    host: <traceo_host>,
    scrapLogsInterval: 120 //in seconds
});

Example of using logger:

import { Logger } from "@traceo-sdk/node";

const traceo = new TraceoClient({...});

traceo.logger.log("Traceo");

The logger can use 5 different types of log: log, info, debug, warn, error. Each function responsible for logging the appropriate log type accepts a list of arguments in the parameter.

traceo.logger.log("Traceo", "Example", "Log");
// [TraceoLogger][LOG] - 31.10.2022, 13:55:45 - Traceo Example Log

traceo.logger.debug("Traceo", {
    hello: "World"
});
// [TraceoLogger][DEBUG] - 31.10.2022, 13:58:00 - Traceo { hello: 'World' }

Metrics

To activate the collection of metrics from your application, set the parameter collectMetrics in your TraceoClient to true:

new TraceoClient({ collectMetrics: true });

Metrics are collected from the application every 30 seconds. If you want to collect metrics at a different time interval then you can use the scrapMetricsInterval parameter.

new TraceoClient({ scrapMetricsInterval: <interval_in_seconds> });

Remember that provided scrapMetricsInterval can't be less than 15 seconds.

Support

Feel free to create Issues, Pull Request and Discussion. If you want to contact with the developer working on this package click here.