Docs » Admin Guide » Track Organization DPM Usage with Access Tokens

Track Organization DPM Usage with Access Tokens

Admin users in your SignalFx organization can use tokens to manage and monitor SignalFx data ingest (DPM counts) across your organization.

About tokens

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. You can also limit the rate at which datapoints can be sent using particular tokens.

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

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 call except those that invite or delete users; those APIs require a User API access token associated with an administrator.

User API access tokens

User API access tokens (sometimes called session tokens) can be thought of as a subset type of access token. These tokens are created by an authentication request from a specific user on their profile page, and expire automatically after 30 days. Session 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.

When a user uses a session 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 -> Get Info from the dashboard’s actions menu.

../_images/token-info-in-ui.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 above, when using the API. You can use the information in the rest of this section to determine which access token you want each user to use.

Why use multiple access tokens?

Access tokens can track DPM for different groups of users, can be used to limit the rate at which datapoints can be sent, and can 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.

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.

Managing access tokens

To view and manage access tokens, click Organization on the global navigation bar, then click Access Tokens in the sidebar. The following illustration shows the Access Tokens tab 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 access token. 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.

../_images/show-token.png

Create an access token

To create a token, click New Token on the Access Tokens tab. 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.)

To view disabled tokens, click Show disabled tokens at the bottom of the tokens list. To re-enable a disabled token, select Enable from the disabled token’s actions menu.

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 notifications when DPM usage reaches a specified value. To do so, select Manage Token Limit from the token’s actions menu.

Specify the limit (in DPM) for the token in the Token Limit field. 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.

Note: 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.

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

Setting up alerts for use with access tokens without limits

If you want to set up an alert for a token when its usage has reached a certain level, but you do not want to set limits on it, you can create a regular detector. The metric that tracks datapoints per token is a counter named sf.org.numDatapointsReceivedByToken and can be filtered using the property tokenName for the token in question.

Monitoring DPM usage with access tokens

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 irrespective of whether you have set a limit for the token.

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