Catchpoint Trace Node Agent

Contents

• Catchpoint Trace Node 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.

Important Environment variables

| Name | Type | Default Value | |:------------------------------------|:------:|:-------------------------------------------:| | CATCHPOINT_APIKEY | string | - | | CATCHPOINT_APPLICATION_NAME | string | - | | CATCHPOINT_APPLICATION_STAGE | string | - | | CATCHPOINT_TRACE_REQUEST_SKIP | bool | false | | CATCHPOINT_TRACE_RESPONSE_SKIP | bool | false |

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_EXPRESS_DISABLE | 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