@thundra/core

Catchpoint Trace Node

Contents

• Catchpoint Trace Agent
  • Contents
  • Installation
  • Configuration
    • 1. Most Useful Environment variables
  • Usage
    • Integration Options for Containers and VMs
      • Express
      • Hapi
      • Koa
      • Google PubSub
  • Frameworks
  • Integrations
  • All Environment Variables
    • Module initialization parameters
  • How to build
  • How to test

Installation

npm ci @catchpoint/trace --save

Configuration

You can configure Catchpoint trace agent using environment variables or module initialization parameters.

Environment variables have higher precedence over initialization parameters.

Check out the configuration part of our docs for more detailed information.

1. Most Useful Environment variables

Name	Type	Default Value
CATCHPOINT_APIKEY	string	-
CATCHPOINT_APPLICATION_NAME	string	-
CATCHPOINT_APPLICATION_STAGE	string	-
CATCHPOINT_TRACE_DISABLE	bool	false
CATCHPOINT_TRACE_REQUEST_SKIP	bool	false
CATCHPOINT_TRACE_RESPONSE_SKIP	bool	false
CATCHPOINT_REPORT_REST_BASEURL	string	https://collector.tracing.catchpoint.com/v1

Usage

Integration Options for Containers and VMs

export CATCHPOINT_APIKEY=<YOUR-CATCHPOINT-TRACE-API-KEY>
export CATCHPOINT_APPLICATION_NAME=<YOUR-APP-NAME>

For Dockerfile, you just replace export with ENV.

For more information see the doc

Express

const catchpoint = require("@catchpoint/trace");
const express = require('express');

const app = express();

app.get('/', function (req,res) {
   res.send("Response")
});
app.listen(3000);

Hapi

const catchpoint = require("@catchpoint/trace");
const Hapi = require('@hapi/hapi');

catchpoint.init();

const startServer = async () => {
    const server = Hapi.server({
        ...
    });

    server.route([{
        method: 'GET',
        path: '/',
        handler: (request, h) => {
            return 'Response';
        }
    }]);
    
    await server.start();
}

startServer();

Koa

const catchpoint = require("@catchpoint/trace");
const Koa = require('koa');

catchpoint.init();
const app = new Koa();

app.use(async (ctx, next) => {
  await next();
  ctx.body = 'Hello Catchpoint!';
});
app.listen(3000)

Google Pubsub

Publish

const { PubSub } = require('@google-cloud/pubsub');

const projectId = 'your_google_cloud_project_id';
const topicName = 'your_google_cloud_pubsub_topic';

const pubsub = new PubSub({ projectId });

/* 
* if topic allready exists 
* const topic = await pubsub.topic(topicName)
**/
const topic = await pubsub.createTopic(topicName);

const date = new Date().toString();
const dataBuffer = Buffer.from(JSON.stringify({date}));

const result = await topic.publishMessage({ data: dataBuffer });

Subscription

Asynchronous Pull

const catchpoint = require("@catchpoint/trace");
catchpoint.init();

const { PubSub, Subscription } = require('@google-cloud/pubsub');

const projectId = 'your_google_cloud_project_id';
const topicName = 'your_google_cloud_pubsub_topic';
const subscriptionName = 'your_google_cloud_pubsup_subscription_name';

const pubsub = new PubSub({ projectId });

(async() => {
    
    /* 
    * if subscription allready exists 
    * const subscription = pubsub.subscription(subscriptionName);
    **/
    const [subscription] = await pubsub.topic(topicName).createSubscription(subscriptionName);
    
    const messageHandler = message => {
      try {
        ...
        message.ack();
      } catch (err) {
        ...
        message.nack();
      }
    };
    
    subscription.on(`message`, messageHandler);
})().catch(error => console.log(error));

Synchronous Pull

const { v1 } = require('@google-cloud/pubsub');

const subClient = new v1.SubscriberClient();

const projectId = 'your_google_cloud_project_id';
const subscriptionName = 'your_google_cloud_pubsup_subscription_name';

const formattedSubscription = subClient.subscriptionPath(
  projectId,
  subscriptionName
);

const request = {
  subscription: formattedSubscription,
  maxMessages: 10,
};

...

const result = await subClient.pull(request);
const [response] = result;

const ackIds = [];
for (const message of response.receivedMessages) {
  ...
  ackIds.push(message.ackId);
}

if (ackIds.length !== 0) {
  const ackRequest = {
    subscription: formattedSubscription,
    ackIds: ackIds,
  };

  await subClient.acknowledge(ackRequest);
}
...

Frameworks

The following frameworks are supported by Catchpoint trace agent:

Framework	Supported Version	Auto-tracing Supported
Express	>=3.0.0	- [x]
Hapi	>=16.0.0	- [✓]
Koa	>=2.0.0	- [✓]

Integrations

Catchpoint trace agent provides out-of-the-box instrumentation (tracing) for following libraries.

Library	Supported Version
logging	Fully supported
aws-sdk	>=2.0.0
elasticsearch	>=10.5.0
http	Fully supported
https	Fully supported
http2	Fully supported
ioredis	>=2.0.0
redis	>=2.6.0
mongodb	>=1.0.0
mysql	>=2.0.0
mysql2	>=1.5.0
pg	>=6.0.0
amqp 0.9.1	>=0.5.0
@google-cloud/pubsub	>=1.2
@google-cloud/bigquery	>=5.0

Mask Sensitive Data

You can specify the keys to be masked in the trace by passing the key names (separated by comma (,) if there are multiple) through the CATCHPOINT_REPORT_MASKED_KEYS environment variable. Here, key names can be string for exact match or regexp pattern.

For example,

CATCHPOINT_REPORT_MASKED_KEYS=password

masks all the keys/properties whose names exactly match to password.

As another example,

CATCHPOINT_REPORT_MASKED_KEYS=/.*password.*/

masks all the keys/properties whose names contain (partially match) password.

If there are multiple key names or patterns you want to specify, you can separate them by comma (,).

CATCHPOINT_REPORT_MASKED_KEYS=/.*password.*/,/.*secret.*/

By default, masked data is replaced with *****. But if you want to remove the masked data completely, you can set CATCHPOINT_REPORT_HIDE environment variable to true.

All Environment Variables

Name	Type	Default Value	Description
CATCHPOINT_APIKEY	string	-
CATCHPOINT_DISABLE	bool	false
CATCHPOINT_DEBUG_ENABLE	bool	false
CATCHPOINT_TRACE_DISABLE	bool	false
CATCHPOINT_REPORT_REST_BASEURL	string	https://collector.tracing.catchpoint.com/v1
CATCHPOINT_REPORT_REST_TRUSTALLCERTIFICATES	bool	false
CATCHPOINT_REPORT_REST_LOCAL	bool	false
CATCHPOINT_REPORT_SIZE_MAX	number	32 * 1024 (32 KB)
CATCHPOINT_REPORT_MASKED_KEYS	string	-	Comma (,) separated key names (can be string or regexp) to be masked in the trace
CATCHPOINT_REPORT_HIDE	bool	false	Hides masked keys instead of masking them
CATCHPOINT_TRACE_REQUEST_SKIP	bool	false
CATCHPOINT_TRACE_RESPONSE_SKIP	bool	false
CATCHPOINT_APPLICATION_ID	string	-
CATCHPOINT_APPLICATION_INSTANCEID	string	-
CATCHPOINT_APPLICATION_REGION	string	-
CATCHPOINT_APPLICATION_NAME	string	-
CATCHPOINT_APPLICATION_STAGE	string	-
CATCHPOINT_APPLICATION_DOMAINNAME	string	-
CATCHPOINT_APPLICATION_CLASSNAME	string	-
CATCHPOINT_APPLICATION_VERSION	string	-
CATCHPOINT_APPLICATION_TAG	any	-
CATCHPOINT_INVOCATION_SAMPLE_ONERROR	bool	false
CATCHPOINT_INVOCATION_REQUEST_TAGS	string	-
CATCHPOINT_INVOCATION_RESPONSE_TAGS	string	-
CATCHPOINT_TRACE_INSTRUMENT_DISABLE	bool	false
CATCHPOINT_TRACE_INSTRUMENT_TRACEABLECONFIG	string	-
CATCHPOINT_TRACE_INSTRUMENT_FILE_PREFIX	string	-
CATCHPOINT_TRACE_SPAN_LISTENERCONFIG	string	-
CATCHPOINT_TRACE_SPAN_COUNT_MAX	number	200
CATCHPOINT_SAMPLER_TIMEAWARE_TIMEFREQ	number	300000
CATCHPOINT_SAMPLER_COUNTAWARE_COUNTFREQ	number	100
CATCHPOINT_TRACE_INTEGRATIONS_DISABLE	bool	false
CATCHPOINT_TRACE_INTEGRATIONS_AWS_INSTRUMENT_ONLOAD	bool	false
CATCHPOINT_TRACE_INTEGRATIONS_AWS_SNS_MESSAGE_MASK	bool	false
CATCHPOINT_TRACE_INTEGRATIONS_AWS_SNS_TRACEINJECTION_DISABLE	bool	false
CATCHPOINT_TRACE_INTEGRATIONS_AWS_SQS_MESSAGE_MASK	bool	false
CATCHPOINT_TRACE_INTEGRATIONS_AWS_SQS_TRACEINJECTION_DISABLE	bool	false
CATCHPOINT_TRACE_INTEGRATIONS_AWS_LAMBDA_PAYLOAD_MASK	bool	false
CATCHPOINT_TRACE_INTEGRATIONS_AWS_LAMBDA_TRACEINJECTION_DISABLE	bool	false
CATCHPOINT_TRACE_INTEGRATIONS_AWS_DYNAMODB_STATEMENT_MASK	bool	false
CATCHPOINT_TRACE_INTEGRATIONS_AWS_DYNAMODB_RESULT_MASK	bool	false
CATCHPOINT_TRACE_INTEGRATIONS_AWS_DYNAMODB_TRACEINJECTION_ENABLE	bool	false
CATCHPOINT_TRACE_INTEGRATIONS_AWS_ATHENA_STATEMENT_MASK	bool	false
CATCHPOINT_TRACE_INTEGRATIONS_HTTP_BODY_MASK	bool	false
CATCHPOINT_TRACE_INTEGRATIONS_HTTP_BODY_SIZE_MAX	number	10 * 1024 (10 KB)
CATCHPOINT_TRACE_INTEGRATIONS_HTTP_HEADERS_MASK	bool	false
CATCHPOINT_TRACE_INTEGRATIONS_HTTP_RESPONSE_BODY_MASK	bool	true
CATCHPOINT_TRACE_INTEGRATIONS_HTTP_RESPONSE_BODY_SIZE_MAX	number	10 * 1024 (10 KB)
CATCHPOINT_TRACE_INTEGRATIONS_HTTP_RESPONSE_HEADERS_MASK	bool	false
CATCHPOINT_TRACE_INTEGRATIONS_HTTP_URL_DEPTH	number	1
CATCHPOINT_TRACE_INTEGRATIONS_HTTP_TRACEINJECTION_DISABLE	bool	false
CATCHPOINT_TRACE_INTEGRATIONS_HTTP_ERROR_ON4XX_DISABLE	bool	false
CATCHPOINT_TRACE_INTEGRATIONS_HTTP_ERROR_ON5XX_DISABLE	bool	false
CATCHPOINT_TRACE_INTEGRATIONS_REDIS_COMMAND_MASK	bool	false
CATCHPOINT_TRACE_INTEGRATIONS_RDB_STATEMENT_MASK	bool	false
CATCHPOINT_TRACE_INTEGRATIONS_RDB_RESULT_MASK	bool	false
CATCHPOINT_TRACE_INTEGRATIONS_ELASTICSEARCH_BODY_MASK	bool	false
CATCHPOINT_TRACE_INTEGRATIONS_ELASTICSEARCH_PATH_DEPTH	number	1
CATCHPOINT_TRACE_INTEGRATIONS_MONGODB_COMMAND_MASK	bool	false
CATCHPOINT_TRACE_INTEGRATIONS_AWS_EVENTBRIDGE_DETAIL_MASK	bool	false
CATCHPOINT_TRACE_INTEGRATIONS_AWS_SES_MAIL_MASK	bool	false
CATCHPOINT_TRACE_INTEGRATIONS_AWS_SES_MAIL_DESTINATION_MASK	bool	false
CATCHPOINT_TRACE_INTEGRATIONS_RABBITMQ_MESSAGE_MASK	bool	false
CATCHPOINT_TRACE_INTEGRATIONS_GOOGLE_PUBSUB_MESSAGE_MASK	bool	false
CATCHPOINT_TRACE_INTEGRATIONS_GOOGLE_BIGQUERY_RESPONSE_SIZE_MAX	number	1 * 1024 (1 KB)
CATCHPOINT_TRACE_INTEGRATIONS_GOOGLE_BIGQUERY_QUERY_MASK	bool	false
CATCHPOINT_TRACE_INTEGRATIONS_GOOGLE_BIGQUERY_RESPONSE_MASK	bool	false
CATCHPOINT_TRACE_INTEGRATIONS_HAPI_DISABLE	bool	false
CATCHPOINT_TRACE_INTEGRATIONS_KOA_DISABLE	bool	false
CATCHPOINT_TRACE_INTEGRATIONS_GOOGLE_PUBSUB_DISABLE	bool	false

How to build

Webpack is used as a module bundler.

To build the project,

npm ci
npm run build

How to test

Tests are written using Jest.

To run tests,

npm run test