Docs » Track Organization DPM Usage with Access Tokens

Track Organization DPM Usage with Access Tokens

Note

This information on this page applies to you only if your organization’s subscription plan is based on the rate at which you are sending datapoints to SignalFx (DPM). If your organization’s usage is based on the number of hosts or metrics that SignalFx is monitoring for you, see Managing usage limits with access tokens.

Tokens Overview

Tokens are used to authenticate and track various types of usage in SignalFx. As an administrator, you can provide instructions or guidance to your users regarding which token to use for different use cases.

SignalFx supports two types of tokens – user API access tokens and organization-level access tokens.

User API access tokens

User API access tokens (sometimes called session tokens) are created by an authentication request from a specific user on their profile page, and expire automatically after 30 days. These tokens can be used to access most capabilities in the SignalFx API, but cannot be used to send ingest data (datapoints or custom events) to SignalFx. Administrators must use this type of token to perform the following tasks via the API:

  • Configure integrations
  • Create and manage access tokens
  • Override write permissions (Note that anyone can use their API access token to manage permissions on items for which they already have permissions.)
  • Create/delete teams, add/remove team members (Note that anyone can join or leave a team, but only admins can add/remove other users)
  • Manage users
  • Manage global data links
  • Add suggested search filters for use in the Metrics Sidebar
  • View certain organization-related information in the UI (Organization Overview, Billing and Usage) and download usage reports
  • Make changes to your organization’s subscription plan

When someone uses a User API access token to create or update UI objects such as dashboards, charts, and detectors, you can see who created or most recently updated a particular object. For example, to see that information for a dashboard, select Dashboard -> Info from the dashboard’s actions menu.

../_images/dashboard-info.png

If you want to track this information, tell your users to use their User API Access Token when working in the API. If their token expires, they can just generate another one on their profile page. If this information isn’t important to you, users can simply use an organization-level access token, described below, when using the API for tasks other than those listed above.

Access tokens

Access tokens (sometimes called org tokens) are long-lived organization-level tokens. By default, these tokens persist for 5 years, and thus are suitable for embedding into emitters that send data points over long periods of time, or for any long-running scripts that call the SignalFx API.

This type of token can be used for any API actions except those listed in User API access tokens above.

Access tokens can track usage for different groups of users. This feature can help you manage how your usage metrics are being utilized. For example, you may have users in the U.S. and Canada sending data to SignalFx. If each group of users uses a specific access token when sending data, you can compare the amount of data coming from each region.

Note

All access tokens are available to any user in your organization. That is, you cannot restrict who has access to which tokens. Use standard administrative processes in place in your organization to let people know which token you want them to use.

You can also create multiple access tokens to limit usage for a token; for more information, see Managing DPM limits with access tokens.

Working with access tokens

To view and manage access tokens, open the Settings menu at far right on the navigation bar, hover over Organization Settings, and then select Access Tokens. The following illustration shows the Access Tokens pane as well as options available on a token’s Actions menu.

../_images/tokens-tab-01.png

About the default access token

By default, every organization has one organization-level access tokens. If you don’t create any additional tokens, everyone in your organization sending data to SignalFx will use this access token.

View and copy an access token

To view and copy the access token, click the token name and then click Show Token. You do not need to be an administrator to view or copy a token.

../_images/show-token.png

Create an access token

To create access tokens to track usage in your organization, click New Token on the Access Tokens pane. You’ll be asked to provide a name for the new token. Token names must be unique; if you enter a name that is already being used (even for a disabled token), it will not be accepted.

../_images/new-token.png

Rename an access token

To rename a token, select Rename Token from the token’s Actions menu. Renaming a token has no effect on the value of the token.

Disable and enable access tokens

To disable a token, select Disable from the token’s Actions menu. (You cannot delete tokens.)

Disabled tokens are shown at the bottom of the tokens list, below the enabled tokens. To re-enable a disabled token, select Enable from the disabled token’s Actions menu.

Managing DPM limits with access tokens


Available in SignalFx Enterprise Edition


In addition to just tracking usage for different users, you can use access tokens to prevent plan overages by limiting usage for a token, and to send alerts when DPM for a token reaches a specified level. This feature can help you track down what might be causing sudden spikes in DPM being sent to SignalFx.

For example, you may be looking at your usage report (available in the Billing and Usage tab) and notice a recent spike in DPM sent in. If different groups are using different access tokens, you can use the information on the Access Tokens tab to identify which group is sending in more data than normal. You can then follow up to determine if the usage is justified or if something has changed that is sending more data than necessary. Upon investigation, you might find that a metric that was formerly sent every minute is now being sent every second. An analysis will help you decide how often to send this metric, and correct your code if necessary.

Access tokens can also let you know when your DPM might be approaching a limit that you don’t want to exceed. For example, your account might be set up to send 50,000 DPM and, if you significantly exceed this value, you may be asked to upgrade your account (which would increase your monthly bill). By monitoring DPM values across all tokens, you can keep an eye on your DPM totals and trends, and thus note whether your data plan is on track to meet your ongoing requirements.

Setting up limits and alerts for use with access tokens

For each access token, you can set a limit for how many DPM can be sent using it, and you can also create a detector to generate alerts and send notifications when DPM usage reaches a specified value. To do so, select Manage Token Limit from the token’s actions menu.

../_images/tokens-tab-01.png

The Manage Token Limits options are displayed.

../_images/token-set-threshold.png

Specify the limit (in DPM) for the token in the Token Limit field.

The token limit is also used to trigger an alert that notify one or more recipients when the DPM usage has been above 90% of the limit for 5 minutes. To specify the recipients, click Add Recipient, then select the recipient or notification method you want to use. (Specifying recipients is optional but highly recommended.) The severity for token alerts is always Critical.

Click Update.

What happens when a limit is exceeded?

When the limit has been exceeded, only datapoints associated with existing metric time series (MTS) will be stored and processed, and can be used in charts and detectors. In other words, if SignalFx has recently received datapoints for a given unique combination of a metric name and set of dimensions, then you will continue to see datapoints that match that combination, even while the token is being limited. However, datapoints for new MTS will not be processed and stored, and charts and detectors that would be expected to include those datapoints will not do so.

The following table describes four scenarios to illustrate this point.

Metric name Host Condition Token status Result
pages_served nginx_existing pages_served datapoints have recently been sent from nginx_existing Not limited Datapoints will continue to be processed and stored. Charts that display pages_served for host:nginx_existing will function normally, as will detectors that are monitoring the same MTS.
pages_served nginx_existing pages_served datapoints have recently been sent from nginx_existing Limited Datapoints will continue to be processed and stored. Charts that display pages_served for host:nginx_existing will function normally, as will detectors that are monitoring the same MTS.
pages_served nginx_new nginx_new is a newly provisioned host, and no pages_served datapoints have been sent Not limited Datapoints for nginx_new will be processed and stored as they arrive at SignalFx. Charts that display pages_served for host:nginx_new will function normally, as will detectors that are monitoring the same MTS.
pages_served nginx_new nginx_new is a newly provisioned host, and no pages_served datapoints have been sent Limited Datapoints for nginx_new will not be processed and stored as they arrive at SignalFx. Charts and detectors that would normally include metrics from pages_served for host:nginx_new will not do so while the account is limited.

Setting up custom alerts for use with access tokens

You can create a regular detector if you want to set up an alert for a token when its usage has reached a different level than 90%, or if you want alerts for tokens that don’t have a limit. The metric that tracks datapoints per token is a counter named sf.org.numDatapointsReceivedByToken. It can be filtered using the property tokenName for the token in question.

Managing DPM for a team

For teams that are sending data to SignalFx, you can manage DPM per team with access tokens.

  1. Create a token you want team members to use.
  2. Set DPM limits for the token.
  3. Tell team members to use the specified token when sending data to SignalFx.

Monitoring DPM usage for a token

To view activity related to a token, click the token name to display information about the token. If the token is being used to send data to SignalFx, a chart will show values for how much data has been coming in for the past seven days. Data is displayed at one-hour resolution. Note that the monitoring will operate whether you have set a limit for the token or not.

../_images/token-info-1.png