Treblle Express Integration Docs

Introduction

Thank you for choosing Treblle Express for monitoring API best practices and inspecting request and response bodies in your Express.js application. This documentation will guide you through the process of integrating Treblle Express into your project.

Requirements

• Node.js and npm installed on your machine.
• An existing Express.js application.

Installation

Install Treblle Express using pnpm:

pnpm install @trythis/treblle-express

Integration Steps

1. Import Dependencies

Ensure you have the required dependencies installed:

import express from 'express';
import bodyParser from 'body-parser';
import cookieParser from 'cookie-parser';
import cors from 'cors';
import { TreblleExpress } from '@trythis/treblle-express';

2. Create Express App

Initialize your Express application:

const app = express();

3. Configure Middleware

Set up necessary middleware for your Express app:

app.use(cors());
app.options('*', cors());
app.use(express.json());
app.use(bodyParser.urlencoded({ extended: false }));
app.use(cookieParser());

4. Using Express Router

Include your application routes. Adjust the path accordingly:

import express from 'express';
const router = express.Router();
 
const treblle = new TreblleExpress(router, {
  apiKey: process.env.TREBLLE_API_KEY,
  projectId: process.env.TREBLLE_PROJECT_ID,
})
  .config({
    environment: 'development', // Possible values: "production", "development", "testing"
    // debugEndpoints: ['https://webhook.site/your-webhook-id'],
    maskValues: ['email', 'name'],
    logError: true,
  })
  .listen();

5. Using Express app

5.1 Create a .env file add the following:

The TREBLLE_API_KEY and TREBLLE_PROJECT_ID are required and an error will be thrown if unspecified

TREBLLE_API_KEY=
TREBLLE_PROJECT_ID=

Create an instance of TreblleExpress, passing your Express app object and configuration options:

import express from 'express';
const app = express();
 
const treblle = new TreblleExpress(app, {
  apiKey: process.env.TREBLLE_API_KEY,
  projectId: process.env.TREBLLE_PROJECT_ID,
})
  .config({
    environment: 'development', // Possible values: "production", "development", "testing"
    // debugEndpoints: ['https://webhook.site/your-webhook-id'],
    maskValues: ['email', 'name'],
    logError: true,
  })
  .listen();

Note: All values in the configuration are optional, and default values will be used if not provided.

• environment: The environment in which your application is running ("production", "development", "testing"). Default is "testing," where Treblle Express won't log requests to the production Treblle API.
• debugEndpoints: An array of endpoints to inspect the payloads sent by Treblle Express. Useful for debugging.
• maskValues: An array of sensitive values (e.g., passwords, emails) to be masked in logs.
• logError: Set to true to log errors.

Note: The listen method must be called to start monitoring. Ensure that you include this method in your integration as shown in the example:

Note: Calling the listen, config methods multiple times will not affect the logging.

6. Error Handling

Treblle Express provides a built-in async error handler that you can use to capture errors in your Express application. This handler is especially useful for capturing unhandled exceptions and logging relevant information. Here's how you can integrate it into your project:

6.1. Add the Error Handler Middleware

Insert the error handler middleware into your Express application, typically after other middleware and route definitions:

// Add other middleware and route definitions here
 
// Use the Treblle Express error handler
app.get(
  '/',
  treblle.errorHandler(async (req: Request, res: Response) => {
    // route handling here
    res.send({ status: 'This is the base endpoint', password: 'sammy' });
  }),
);

The errorHandler function takes a async fn(req, res, next) => {} as a parameter, which should handle errors and return a closure which executes your request handler.

The error handler logs relevant information, including the source file, error type, message, file, and line number on the Treblle dashboard. This information is valuable for debugging and troubleshooting.

Now, your Express application is equipped with a robust error handling mechanism provided by Treblle Express.

For more details and advanced configurations, refer to the Treblle Express documentation (opens in a new tab).

7. Known Issues

While using Treblle Express, be aware of the following known issues:

• Issue 1: Multiple instances of TreblleExpress is not recommended, as requests will most likely not be captured. Declare the TreblleExpress instance at the top most level of your express server.

Support

If you encounter any issues or have questions, feel free to reach out to our support team (opens in a new tab). We're here to help!

Happy coding! 🚀