feat(ddm): Update metric docs (#9639)

Author: iambriccardo

docs/product/metrics/index.mdx

@@ -6,52 +6,60 @@ description: "Sentry's Developer Metrics help you track and visualize the data p
 
 <Include name="feature-stage-beta-metrics.mdx" />
 
-Sentry metrics are numerical values that allow you to pinpoint and solve issues impacting user experience and app performance by measuring the data points that are important to you and your application. You can track things like latency, processing time, event size, user signups, and conversion rates, and see how they correlate back to tracing data. This gives you better observability, allowing you to gain a comprehensive understanding of the health of your systems and solve issues faster.
+Sentry metrics are numerical values that allow you to pinpoint and solve issues impacting user experience and app performance by measuring the data points that are important to you and your application. You can track things like latency, processing time, event size, user signups, and conversion rates, and see how they correlate back to tracing data. This gives you a comprehensive understanding of the health of your systems and helps solve issues faster.
 
 ![Metrics UI](./img/Index.png)
 
 ## Metric Types
 
 Metrics at Sentry come in different flavors, in order to help you track your data in the most efficient and cost-effective way. The metric types we currently support are:
 
-- **Counters** track a value that can only be incremented (for example, button clicks).
-- **Distributions** track a list of values that can be aggregated over time, like `max`, `min`, and `avg` (for example, page load times).
-- **Sets** track a set of values on which you can run aggregations over time, such as `count_unique` (for example, the number of unique users).
-- **Gauges** track a value that can go up or down (for example, available disk space and memory used).
-- **Timers** track the execution time for a specific block of code (for example, the time to load a user profile).
+- **Counters:** Tracks a value that can only be incremented (for example, button clicks)
+- **Distributions:** Tracks a list of values which can be aggregated over time like `max`, `min`, `avg` (for example, page load times)
+- **Gauges:** Tracks a value that can go up or down (for example, available disk space, memory used)
+- **Sets:** Tracks a set of values on which can be aggregations over time such as `count_unique` (for example, number of unique users)
 
 Each metric also needs to have a unit associated with it, so that you know what you're dealing with. Examples of units are seconds, milliseconds, bytes, or even potatoes if you like.
 
 ## Augmenting Metrics with Tags
 
-Metrics are powerful on their own, but you can enrich them further by adding dimensions in the form of Tags. Tags are key/value string pairs (for example, `cuisine:Italian`) that add contextual information to your metrics. They can also be used to filter and group metrics during analysis.
+Metrics are powerful on their own, but you can enrich them further by adding dimensions in the form of Tags. These are key/value string pairs (for example, `platform:ios`) that are associated with metrics to provide contextual information, and are often used to filter and group them during analysis.
 
-By default, Sentry adds some standard tags, such as `transaction`, `environment`, and `release`. You can also create custom tags to track attributes that help organize your data for your specific use case. For example, some useful custom tags are browser name, region, language, and platform.
+Sentry adds certain common tags by default such as, `transaction`, `environment`, and `release`, but you can also create your own custom tags to track attributes that help organize your data for your specific use case. Some common examples of useful tags are browser name, region, language, or customer.
 
 ## Limits and Restrictions
 
 ### Cardinality
 
-Cardinality, in the context of metrics, refers to how many unique time series your metrics create. The number of time series depends on the combinations of tags that are added to a metric.
+In metrics, "cardinality" refers to the number of unique time series generated by tags associated with a metric. The more tags combinations you create, the higher the cardinality.
 
-When dealing with tags, it's important to be wary of cardinality explosion. Here's an example to help you understand what this means.
+For instance, imagine you are tracking daily logins. You create a metric named `login` and add tags like `platform` (with values `ios`, `android`, `web`) to indicate where logins occur. Then you decide to add a new tag called `user_id`, which will have a different value for each user. In metrics, adding a `user_id` tag, which identifies the user logging in, can greatly increase cardinality as user IDs accumulate. Considering that each user might log in from various platforms, this multiplies the number of unique time series needed to analyze the data. For example, with 100,000 user IDs and 3 platform values, you would potentially require 300,000 time series.
 
-Suppose you're trying to make dinner plans and want your friends to vote on their preference. Each vote has two properties:
+To manage cardinality, use tags with fixed sets of values. Instead of `user_id`, consider using tags like `country` (with specific country names) to categorize login locations or `user_segment` (e.g.  `business`, `internal users`) to segment your login data based on user categories that are meaningful for your analysis. This approach helps limit cardinality and optimizes metric analysis.
 
-- Cuisine type: Type of restaurant (for example, Asian, Italian, German).
-- Price: Price range of the restaurant (for example, $, $$, $$).
+<Note>
 
-How would you count all the votes by type and price? The simple solution is to create multiple boxes that contain all the votes for each combination of type and price (Italian-$, German-$$). If you have 3 types and 3 prices, the resulting number of boxes you'd need would be 9, which is quite a lot.
+Sentry incorporates protection mechanisms that will drop metrics if their cardinality exceeds an internally defined limit.
 
-Now imagine if a friend comes and says, let's also vote on the day of the month, which has 31 values. Now all the combinations go from 3 × 3 = 9 to 3 × 3 × 31 = 279. As you can see, adding multiple properties can quickly become overwhelming. This is what's known as a cardinality explosion.
+</Note>
 
-To prevent such an explosion, you should use tags with a low number of distinct values. The end goal is to have a small product of possible tag values.
+### Supported Characters
 
-### Tags
+Sentry allows the use of specific characters for the components of a metric:
 
-Tag keys have a maximum length of 32 characters and can contain only letters (a-z, A-Z), numbers (0-9), underscores (\_), periods (.), colons (:), and dashes (-).
+- **Metric Name**: Supports all word characters including `_`, `-`, `.`. Any unsupported characters will be replaced by `_`.
 
-Tag values have a maximum length of 200 characters and cannot contain the newline (`\n`) character.
+- **Metric Tag Keys**: Supports all word characters including `_`, `-`, `.`, `/`. Any unsupported characters will be removed from the tag key.
+
+- **Metric Tag Values**: Supports all Unicode characters.
+
+More information about the normalization of unsupported characters can be found [here](https://develop.sentry.dev/sdk/metrics/#normalization).
+
+### Metric Tags Length
+
+Metric tags have a maximum length:
+- Tag Keys: 32 characters.
+- Tag Values: 200 characters.
 
 ### Retention