Track usage for your subscription

7 minute read

Overview

Each API Builder integration that you create can report its own transaction usage to the platform without the need for an agent. Transactions are reported against Environments in your Organization, and you can review these transactions along with those from other Amplify products. For more information, see Subscription Usage Tracking.

What is counted as a transaction?

If your service receives inbound events which trigger business logic, then this is counted as a transaction. This includes the following:

• HTTP requests to endpoints, APIs, and web routes.
• Flow-triggers invoking a flow from an inbound event such as a Kafka or Solace message, or on a Cron or Timer interval.

A number of events will specifically not count as a transaction:

• Accessing API Swagger documentation or health-check.
• Bad requests due to invalid authentication or to non-existent endpoints before business logic can be executed.
• Outbound calls from a flow.
• A flow calling another flow.
• CORS preflight requests.

Prerequisites

Platform account

You need to have an account on https://platform.axway.com.

Network requirements

Each API Builder service will track its own transaction usage, and will communicate with the platform at a configurable interval to transmit the transaction counts. Only aggregated counts are transmitted as a JSON payload (no transaction details are sent). You will need to ensure that your API Builder services can reach https://gatekeeper.platform.axway.com on port 443. If you have the option of using a proxy for outbound connectivity, you can configure that proxy in API Builder to avoid configuring network access for each API Builder service.

Organization GUID

API Builder will need the Organization GUID of the organization for which you have an Amplify subscription. It is found on the Organization page in the platform. To obtain this, log on to the platform and then navigate to Organization from the landing page.

You can also navigate to Organization from your user menu.

You can use the clipboard to copy the Organization GUID.

Environment ID

Usage reporting on the platform is arranged by deployment Environments, which can also be found on the platform Organization management screen. Environments refer to where you deploy your API Builder services, which may be describe cloud or on-premise network segments, or describe separate development, test, and production environments. An environment is either marked as production or not, and each has a unique Environment ID. Your organization administrator can manage your environments and obtain IDs in your Organization page under Environments. You will need the Environment ID that corresponds to the deployment environment for the API Builder service you wish to provision.

If you have an existing production Environment that you wish to use for reporting transaction usage, you can copy the Environment ID from this screen. Otherwise, you will need to create a new production Environment by clicking the add Environment button.

Then fill out the form to create a production environment with “Customer Managed” governance and click Save:

Note that it is possible to create non-production environments and track usage against them, but they do not count towards your organization’s monthly quota.

Configuration

Since your API Builder service can be deployed in more than one environment (in particular, when it is moved between development, test, and production environments), you should configure your project to obtain usage tracking information from the environment in which it is running.

Usage tracking configuration is placed in the conf directory. In your project, create the file /conf/subscriptionUsageTracking.default.js with the following content:

// /conf/subscriptionUsageTracking.default.js

module.exports = {
  subscriptionUsageTracking: {
    enabled: process.env.AXWAY_USAGE_TRACKING_ENABLED !== 'false',
    environment: process.env.AXWAY_PLATFORM_ENVIRONMENT,
    org: process.env.AXWAY_PLATFORM_ORG
  }
};

To ensure that your local development or test environments do not accidentally report transaction usage, add the following line to your /conf/.env:

// /conf/.env

AXWAY_USAGE_TRACKING_ENABLED=false
AXWAY_PLATFORM_ENVIRONMENT=
AXWAY_PLATFORM_ORG=

This file is local only, and not deployed with your service when the production flag is used when building a container, and ensures that usage tracking is disabled (see Local environment file (conf/.env) for more information).

When you want to track transaction usage, in your target environment, you need to set AXWAY_PLATFORM_ENVIRONMENT to the Environment ID, the AXWAY_PLATFORM_ORG to the Organization GUID, and AXWAY_USAGE_TRACKING_ENABLED to true.

subscriptionUsageTracking

This configuration is used to configure API Builder. Certain keys are only applicable when using specific reporters. These are identified in the final column.

In order for you to ensure that you are billed correctly, you should ensure that the environment that your service is configured with is correct. Environments in the platform can be production or non-production, and the environment you use should reflect your own production or non-production deployment.

We recommend using an environment variable such as AXWAY_PLATFORM_ENVIRONMENT (defined in the template above) to specify the Environment ID, and not to hard code it in your service. When deploying to production, specify a production Environment ID, and when deploying to a non-production environment such as staging, specify a non-production Environment ID.

Usage reporters

API Builder comes with two reporters which can be used together or interchangeably (see subscriptionUsageTracking configuration above). The “platform” reporter is the primary used for subscription usage tracking. It will automatically send usage reports to the Amplify platform, and be counted against your quota depending on the configured environment. The “console” reporter is used to print transactions to the terminal and can be used for offline transaction usage reporting (e.g. using a log aggregator such as Splunk to calculate the transaction counts), but can also be useful for testing.

How to verify you have set everything up correctly

When configured correctly to report transaction usage to the Amplify platform, on start up, you should see the following in the log at INFO level:

[Subscription usage tracking: 32c9bc26-1833-46f1-b059-4ab1e469fb57] Reporting transactions every 3600s

After your service processes inbound requests, and after the configured interval (defaults to 5 minutes), your service should emit the following in the log at INFO level:

1628517801046 INFO  [platform-reporter: a52af8ae-f75e-49dc-831f-e1236c5007bc] Reported 1 transactions to Axway

Verify usage in non-production environments

To verify that your environment is tracking usage (you must have an Organization Administrator role to view this), in the Amplify platform homepage, select Organization, then Usage.

Notice that in this example, 6 transactions were tracked against the “Staging” environment, but they were not counted against this organization’s monthly quota. This is because only transactions in production environments will count towards the organization’s monthly quota.

Verify usage in production environments

Everything from the previous section stays the same, except this time you are using a production environment.

Notice that in this example, 23 transactions were tracked against the “Production” environment which resulted in a total of 8 tokens being counted against this organization’s monthly API Builder Transactions quota.