## Documentation Index

Fetch the complete documentation index at: [/llms.txt](https://docs.m3ter.com/llms.txt)

Use this file to discover all available pages before exploring further.

---

You can set up _Meters_ to collect usage data on your end customer activity when they consume your products and services. For example:

- Number of logins.
- Duration of session.
- Amount of data downloaded.

Meters offer you wide-ranging flexibility when configuring the types of data you need to collect to support the usage-based pricing models you want to apply to your products and services.

This topic explains the difference between Product and Global Meters and the configuration options available for Meters:

- [Product Meters vs. Global Meters](https://docs.m3ter.com/guides/usage-data-meters/reviewing-meter-options#product-meters-vs-global-meters)
- [Configuring Meter Fields](https://docs.m3ter.com/guides/usage-data-meters/reviewing-meter-options#configuring-meter-fields)
- [Data Field Options](https://docs.m3ter.com/guides/usage-data-meters/reviewing-meter-options#data-field-options)
- [Derived Fields](https://docs.m3ter.com/guides/usage-data-meters/reviewing-meter-options#derived-fields)
- [Units for Meter Fields - Examples](https://docs.m3ter.com/guides/usage-data-meters/reviewing-meter-options#units-for-meter-fields-examples)
- [Custom Fields](https://docs.m3ter.com/guides/usage-data-meters/reviewing-meter-options#custom-fields)

## Product Meters vs. Global Meters

You can create Meters that belong to a specific Product or create Global Meters. **Usage data Meters collect**:

- You can use Product-specific Meters to charge for usage data the Meter collects _for the Product_.
- You can use Global Meters when you want to charge for the usage data the Meter collects _across multiple different Products_.

**Aggregations targeting Meters**:

- Any Aggregations that target a Product-specific Meter also becomes Product-specific and can only be used to Price Plans _for that Product_.
- Any Aggregations that target a Global Meter are also Global, meaning they are not tied to a specific Product and can be used to price Plans _belonging to different Products_.

**Switching Meters between Product-specific and Global**:

- _You can_ switch a Product-specific Meter to Global, but you cannot switch it back to make it a Product-specific Meter again.
- If you have already created any Aggregations that target a Product-specific Meter and you then switch the Product-specific Meter to be Global, then the Aggregations then become Global.
- _You cannot_ switch a Product-specific Meter to another Product.
- _You cannot_ switch a Global Meter to Product-specific.

## Configuring Meter Fields

When you create and set up a Meter, the key configuration is adding fields to collect data:

- **Data Fields.** Baseline fields for collecting raw usage data.
- **Derived Fields.** Fields whose values are the result of a calculation/function performed on Meter Data Fields, Custom Fields, or Timestamp Fields.
- **Custom Fields.** Allow you to attach custom data to the Meter as name/value pairs.

## Data Field Options

You can add _Data Fields_ to a Meter to collect:

- Usage data on which you want to base your measurements for pricing.
- Any associated data required for other business needs, such as for analytics purposes.

Each Meter can have up to a maximum of fifteen Data Fields. For each field, you can define the type of data you want the field to collect using the **Category** attribute. There are eight options:

- **Who**. String. Use to collect usage data about an individual or organization.
- **What**. String. Use to collect usage data about some object or thing.
- **Where**. String. Use to collect usage data about a location.
- **Measure**. Numeric. Use in a general way to collect quantitative usage data.
- **Metadata**. String. _(Max. 256 characters)._ Use for high-cardinality fields.
- **Income**. Numeric. Use to collect usage data associated with income.
- **Cost**. Numeric. Use to collect usage data associated with costs.
- **Other.** String. Use to collect textual usage not applicable to **Who**, **What**, or **Where** events.

**Important: When setting up Measures on Meters, consider how you want to aggregate your usage data!** The options for Aggregating usage data collected by a Meter are constrained by the Categories you select for a Meter’s Data Fields.

## Derived Fields

Each Meter can have up to a maximum of fifteen _Derived Fields_.  The values of a Derived Field are always the result of a calculation or function performed on Meter Data Fields. Derived Fields add a powerful extra dimension of flexibility for setting up the data on which your usage-based pricing plans will be based.

**Tip: Examples?** The [Derived Fields for Meters - Examples and Supported Syntax](https://docs.m3ter.com/guides/usage-data-meters/derived-fields-for-meters-examples-and-supported-syntax) topic offers examples of how to set up Derived Fields on your Meters.

## Units for Meter Fields - Examples

For numeric Meter Data and Derived Fields - Measure, Income, or Cost - we recommend conforming to the [_The Unified Code for Units of Measure (UCUM)_](https://ucum.org/ucum).

### Measures of Data Storage
For example, services that want to price on sum of storage used:
- Kilobyte: **KiBy**
- Gigabyte: **GiBy**
- Megabyte: **MiBy**
- Terabytes: **TiBy**

### Measures of Rates of Consumption
For example, services that want to price on maximum rates of consumption:
- Gigabytes per second: **GiBy/s**
- Megabytes per hour: **MiBy/h**

### Measures of Computing Resource
For example, services that want to price on sum of memory allocation over time:
- Gigabyte-seconds: **GiBy.s**
- Megabyte-hours: **MiBy.h**

### Non-Units of Measure - Counts
Counts aren’t strictly units of measure, but within UCUM, curly braces can be used to represent them. For example, a service that wants to price on the basis of number of API calls:
- A count of number of API calls: `{API_calls}`
- A count of the number of API calls per second: `{API_calls/s}`

**Tip: Other Resources?** You might also like to consult the Wikipedia article on the [Unified Code for Units of Measure](https://en.wikipedia.org/wiki/Unified_Code_for_Units_of_Measure).

## Custom Fields

You can define **Custom Fields** when creating a Meter or edit the Meter at a later date. Custom Fields you create for an individual Meter override those created at the Organizational level. We recommend reviewing [Working with Custom Fields](https://docs.m3ter.com/guides/creating-and-managing-products/working-with-custom-fields) before you create and use Custom Fields.