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

Data type	Parameters	Return type
Function	(req, res, env, ctx)	String

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

Data type	Parameters	Return type
Function	(req, res, env, ctx)	String

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

Data type	Parameters	Return type
Function	(req, res, env, ctx)	String

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

Data type	Parameters	Return type
Function	(req, res, env, ctx)	String

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

Data type	Parameters	Return type
Function	(MoesifEventModel)	MoesifEventModel

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.

Name	Required	Description
request	Yes	The object that specifies the API request.
request.time	Yes	Timestamp for the request in ISO 8601 format.
request.uri	Yes	Full URI such as https://api.com/?query=string including host, query string, and so on.
request.verb	Yes	The HTTP method—for example, GET and POST.
request.api_version	No	API Version you want to tag this request with such as 1.0.0.
request.ip_address	No	IP address of the client. If not set, Moesif uses the IP address of your logging API calls.
request.headers	Yes	Headers of the request as a Map<string, string> object. Multiple headers with the same key name should be combined together such that the values are joined by a comma. For more information, see HTTP Header Protocol on w3.org
request.body	No	Body of the request in JSON format or base64 encoded binary data. To specify the transfer encoding, use request.transfer_encoding.
request.transfer_encoding	No	A string that specifies the transfer encoding of the request body sent to Moesif. If not specified, Moesif assumes the request body assumed to be JSON or text. Only supported value is base64 for sending binary data like protocol buffers.
response	No	The object that specifies the response message. If not set, it implies a null response such as a timeout.
response.time	Yes	Timestamp for the response in ISO 8601 format.
response.status	Yes	HTTP response status code number such as 200 OK or 500 Internal Server Error.
response.ip_address	No	IP address of the responding server.
response.headers	Yes	Headers of the response as a Map<string, string> object. Multiple headers with the same key name should be combined together such that the values are joined by a comma. For more information, see HTTP Header Protocol on w3.org
response.body	No	Body of the response in JSON format or base64 encoded binary data. To specify the transfer encoding, use response.transfer_encoding
response.transfer_encoding	No	A string that specifies the transfer encoding of the request body sent to Moesif. If not specified, Moesif assumes the body to be JSON or text. Only supported value is base64 for sending binary data like protocol buffers.
session_token	Recommended	The end user session token such as a JWT or API key, which may or may not be temporary. Moesif automatically detects the session token if not set.
user_id	Recommended	Identifies this API call to a permanent user ID.
metadata	No	A JSON Object consisting of any custom metadata to be stored with this event.

getMetadata

Data type	Parameters	Return type
Function	(req, res, env, ctx)	Object

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

Data type	Parameters	Return type
Function	(req, res, env, ctx)	Boolean

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

Data type	Default
Boolean	true

Whether to log request and response body to Moesif.

hideCreditCards

Data type	Default
Boolean	true

This masks any credit cards using the Luhn algorithm.

disableTransactionId

Data type	Default
Boolean	false

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

Data type	Default
Boolean	false

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

fetchTimeoutMS

Data type	Default
Number	120000 milliseconds

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

requestMaxBodySize

Data type	Default
Number	100000

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

responseMaxBodySize

Data type	Default
Number	100000

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