moesif-cloudflare v2.0.2

Moesif Cloudflare SDK Documentation

by Moesif, the API analytics and API monetization platform.

If you're new to Moesif, see our Getting Started resources to quickly get up and running.

Overview

This SDK allows you to integrate Moesif with Cloudflare Workers using the new ECMAScript modules (ES modules).

This NPM package only supports Node.js version 18 and 20.

Important Note about Legacy Service Worker Model

If you are using Cloudflare's Service Workers API instead of the new ES modules, please follow the legacy instructions.

Prerequisites

Before using this SDK, make sure you have the following:

• An active Moesif account
• A Moesif Application ID

Get Your Moesif Application ID

After you log into Moesif Portal, you can get your Moesif Application ID during the onboarding steps. You can always access the Application ID any time by following these steps from Moesif Portal after logging in:

1. Select the account icon to bring up the settings menu.
2. Select Installation or API Keys.
3. Copy your Moesif Application ID from the Collector Application ID field.

Install the SDK

In the directory of your Worker project created with Wranger, install the SDK:

npm install moesif-cloudflare

Configure the SDK

See the available configuration options to learn how to configure the SDK for your use case.

How to Use

Using the SDK involves three simple steps:

1. Import the moesifMiddleware function.
2. Specify your Moesif Application ID in the Moesif options object.
3. Wrap your handler with moesifMiddleware.

For example:

import moesifMiddleware from 'moesif-cloudflare';

const options = {
  applicationId: 'YOUR MOESIF Application ID',
};

// your original fetch handler.
async function originalFetchHandler(request, _env, context) {
  // your code.
}

// this create a new fetch that is wrapped by moesifMiddleware
const wrappedFetchHandler = moesifMiddleware(originalFetch, options);

// export the fetch handler.
export default {
  fetch: wrappedFetchHandler
};

Troubleshoot

For a general troubleshooting guide that can help you solve common problems, see Server Troubleshooting Guide.

Other troubleshooting supports:

• FAQ
• Moesif support email

Repository Structure

.
├── esm/
├── example-project/
├── images/
├── legacy/
├── LICENSE
└── README.md

Configuration Options

The following sections describe the available configuration options for this SDK. You can set these options in the Moesif initialization options object. See the example Worker project code for an example.

You can see the full list of options in the prepareOptions.mjs file.

identifyUser

Parameters:

• req: a Request object.
• res: a Response object.
• env: an env object representing the bindings available to the Worker.
• ctx: a Context API object.

The function returns a user ID string. This allows Moesif to attribute API requests to individual unique users so you can understand who is calling your API. You can use this simultaneously with identifyCompany to track both individual customers and the companies they are a part of.

See the example project's identifyUser function for an example.

identifyCompany

Parameters:

• req: a Request object.
• res: a Response object.
• env: an env object representing the bindings available to the Worker.
• ctx: a Context API object.

This function returns a company ID string. If you have a B2B business, this allows Moesif to attribute API requests to specific companies or organizations so you can understand which accounts are calling your API. You can use this simultaneously with identifyUser to track both individual customers and the companies they are a part of.

See the example project's identifyCompany function for an example.

getSessionToken

Parameters

• req: a Request object.
• res: a Response object.
• env: an env object representing the bindings available to the Worker.
• ctx: a Context API object.

This function returns a session token such as an API key.

For example:

var options = {
  getSessionToken: function (req, res, env, ctx) {
    // your code here must return a string. Example Below
    return req.headers.get['Authorization'];
  }
}

getApiVersion

Parameters

• req: a Request object.
• res: a Response object.
• env: an env object representing the bindings available to the Worker.
• ctx: a Context API object.

This function returns a string to tag requests with a specific version of your API.

For example:

var options = {
  getApiVersion: function (req, res, env, ctx) {
    // your code here must return a string. Example Below
    return req.headers.get['X-Api-Version']
  }
}

maskContent

A function that takes the final Moesif event model as an argument before sending the event model object to Moesif.

With maskContent, you can make modifications to headers or body such as removing certain header or body fields.

import _ from 'lodash';

var options = {
  maskContent: function(event) {
    // remove any field that you don't want to be sent to Moesif.
    const newEvent = _.omit(event, ['request.headers.Authorization', 'event.response.body.sensitive_field'])
    return newEvent;
  }
};

Moesif's event model format looks like this:

{
  "request": {
    "time": "2022-08-08T04:45:42.914",
    "uri": "https://api.acmeinc.com/items/83738/reviews/",
    "verb": "POST",
    "api_version": "1.1.0",
    "ip_address": "61.48.220.123",
    "headers": {
      "Host": "api.acmeinc.com",
      "Accept": "*/*",
      "Connection": "Keep-Alive",
      "Content-Type": "application/json",
      "Content-Length": "126",
      "Accept-Encoding": "gzip"
    },
    "body": {
      "items": [
        {
          "direction_type": 1,
          "item_id": "fwdsfrf",
          "liked": false
        },
        {
          "direction_type": 2,
          "item_id": "d43d3f",
          "liked": true
        }
      ]
    }
  },
  "response": {
    "time": "2022-08-08T04:45:42.924",
    "status": 500,
    "headers": {
      "Vary": "Accept-Encoding",
      "Pragma": "no-cache",
      "Expires": "-1",
      "Content-Type": "application/json; charset=utf-8",
      "Cache-Control": "no-cache"
    },
    "body": {
      "Error": "InvalidArgumentException",
      "Message": "Missing field location"
    }
  },
  "user_id": "my_user_id",
  "company_id": "my_company_id",
  "session_token":"end_user_session_token",
  "tags": "tag1, tag2"
}

For more information about the different fields of Moesif's event model, see the following table or the Moesif Node.js API documentation.

getMetadata

Parameters

• req: a Request object.
• res: a Response object.
• env: an env object representing the bindings available to the Worker.
• ctx: a Context API object.

This function returns an object containing custom metadata that Moesif can associate with the request. The metadata must be a simple JavaScript object that can be converted to JSON.

For example, you may want to save a virtual machine instance ID, a trace ID, or a tenant ID with the request.

var options = {
  getMetadata: function (req, res, env, ctx) {
    // your code here:
    return {
      foo: 'custom data',
      bar: 'another custom data'
    };
  }
}

skip

Parameters

• req: a Request object.
• res: a Response object.
• env: an env object representing the bindings available to the Worker.
• ctx: a Context API object.

This function returns true if you want to skip the event. Skipping an event means Moesif doesn't log the event.

The following example skips requests to the root path / and the /health path:

var options = {
  skip: function (req, res, env, ctx) {
    const url = new URL(req.url)
    // your code here must return a boolean. Example Below
    if (url.pathname === '/' || url.pathname === '/health') {
      // Skip logging traffic to root path or health probe.
      return true;
    }
    return false
  }
}

logBody

hideCreditCards

This masks any credit cards using the Luhn algorithm.

disableTransactionId

X-Moesif-Transaction-Id helps identify transactions in Moesif. Set this option to true to prevent insertion of X-Moesif-Transaction-Id response header.

debug

Set to true to print debug logs. This may help you troubleshoot if you're having integration issues.

fetchTimeoutMS

The fetch timeout in milliseconds so that Moesif can log the call even if origin server doesnt respond.

requestMaxBodySize

The maximum request body size in bytes to log when sending the data to Moesif.

responseMaxBodySize

The maximum response body size in bytes to log when sending the data to Moesif.

Example

See the example-project folder for an example. The example is generated using C3 (create-cloudflare-cli) and follows the Cloudflare get started guide.

How to Get Help

If you face any issues using this SDK, try the troubheshooting guidelines. For further assistance, reach out to our support team.

Explore Other Integrations

Explore other integration options from Moesif:

• Server integration options documentation
• Client integration options documentation