Skip to content

Latest commit

 

History

History
658 lines (570 loc) · 18.8 KB

README.md

File metadata and controls

658 lines (570 loc) · 18.8 KB
Raw

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:

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.

Accessing the settings menu in Moesif Portal

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:

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:

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:

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

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

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

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

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: