feat(python): Illustrate types of metrics (#15556)

Improve Python metrics documentation by:

- adding illustrative use cases to the introduction; and
- explaining the `before_send_metric()` callback; and
- adding individual examples for each metric type.

Author: alexander-alderman-webb

docs/platforms/python/metrics/index.mdx

@@ -11,7 +11,9 @@ This feature is currently in open beta. Please reach out on [GitHub](https://git
 
 </Alert>
 
-With Sentry Metrics, you can send counters, gauges and distributions from your applications to Sentry. Once in Sentry, these metrics can be viewed alongside relevant errors, and searched using their individual attributes.
+Sentry metrics help you pinpoint and solve issues that impact user experience and app performance by measuring the data points that are important to you. You can track things like processing time, event size, user signups, and conversion rates, then correlate them back to tracing data in order to get deeper insights and solve issues faster.
+
+Once in Sentry, these metrics can be viewed alongside relevant errors, and searched using their individual attributes.
 
 ## Requirements
 

platform-includes/metrics/options/python.mdx

@@ -1,17 +1,21 @@
 #### before_send_metric
 
-To filter metrics, or update them before they are sent to Sentry, you can use the `before_send_metric` option.
+To filter metrics, or update them before they are sent to Sentry, you can use the `before_send_metric` option. If the callback returns `None`, the metric is not emitted. Attributes can also be updated in the callback function.
 
 ```python
 import sentry_sdk
 from sentry_sdk.types import Metric, Hint
 from typing import Optional
 
-def before_metric(metric: Metric, _hint: Hint) -> Optional[Metric]:
-    # Filter out all failed checkouts on the acme tenant
-    if metric["name"] == "checkout.failed" and metric["attributes"].get("tenant") == "acme":
+def before_metric(metric: Metric, hint: Hint) -> Optional[Metric]:
+    if metric["name"] == "removed-metric":
         return None
 
+    metric["attributes"]["extra"] = "foo"
+
+    if "browser" in metric["attributes"]:
+        del metric["attributes"]["browser"]
+
     return metric
 
 sentry_sdk.init(

platform-includes/metrics/usage/python.mdx

@@ -2,26 +2,62 @@ Once the feature is enabled on the SDK and the SDK is initialized, you can send
 
 The `metrics` namespace exposes three methods that you can use to capture different types of metric information: `count`, `gauge`, and `distribution`.
 
+## Emit a Counter
+
+Counters are one of the more basic types of metrics and can be used to count certain event occurrences.
+
+To emit a counter, do the following:
+
 ```python
-from sentry_sdk import metrics
+import sentry_sdk
 
-metrics.count("checkout.failed", 1)
-metrics.gauge("queue.depth", 42)
-metrics.distribution("cart.amount_usd", 187.5)
+# Record five total button clicks
+sentry_sdk.metrics.count(
+	"button_click",
+	5,
+	attributes={
+		"browser": "Firefox",
+		"app_version": "1.0.0"
+	},
+)
 ```
 
-You can also pass additional attributes directly to `count`, `gauge`, and `distribution` via the `attributes` kwarg.
+## Emit a Distribution
+
+Distributions help you get the most insights from your data by allowing you to obtain aggregations such as `p90`, `min`, `max`, and `avg`.
+
+To emit a distribution, do the following:
 
 ```python
-from sentry_sdk import metrics
-
-metrics.count(
-    "checkout.failed",
-    1,
-    attributes={
-        "route": "/checkout",
-        "tenant": "acme",
-        "provider": "stripe",
-    },
+import sentry_sdk
+
+# Add '15.0' to a distribution used for tracking the loading times per page.
+sentry_sdk.metrics.distribution(
+	"page_load",
+	15.0,
+	unit="millisecond",
+	attributes={
+		"page": "/home"
+	},
+)
+```
+
+## Emit a Gauge
+
+Gauges let you obtain aggregates like `min`, `max`, `avg`, `sum`, and `count`. They can be represented in a more space-efficient way than distributions, but they can't be used to get percentiles. If percentiles aren't important to you, we recommend using gauges.
+
+To emit a gauge, do the following:
+
+```python
+import sentry_sdk
+
+# Add '15.0' to a gauge used for tracking the loading times for a page.
+sentry_sdk.metrics.gauge(
+	"page_load",
+	15.0,
+	unit="millisecond",
+	attributes={
+		"page": "/home"
+	},
 )
 ```