feat(metrics): add Datadog observability provider

.markdownlintignore

@@ -0,0 +1,2 @@
+docs/core/metrics/index.md
+includes/abbreviations.md

aws_lambda_powertools/metrics/functions.py

@@ -1,7 +1,6 @@
 from __future__ import annotations
 
-import re
-from typing import Any, Dict, List
+from typing import List
 
 from aws_lambda_powertools.metrics.provider.cloudwatch_emf.exceptions import (
     MetricResolutionError,
@@ -71,64 +70,3 @@ def extract_cloudwatch_metric_unit_value(metric_units: List, metric_valid_option
         unit = unit.value
 
     return unit
-
-
-def serialize_datadog_tags(metric_tags: Dict[str, Any], default_tags: Dict[str, Any]) -> List[str]:
-    """
-    Serialize metric tags into a list of formatted strings for Datadog integration.
-
-    This function takes a dictionary of metric-specific tags or default tags.
-    It parse these tags and converts them into a list of strings in the format "tag_key:tag_value".
-
-    Parameters
-    ----------
-    metric_tags: Dict[str, Any]
-        A dictionary containing metric-specific tags.
-    default_tags: Dict[str, Any]
-        A dictionary containing default tags applicable to all metrics.
-
-    Returns:
-    -------
-    List[str]
-        A list of formatted tag strings, each in the "tag_key:tag_value" format.
-
-    Example:
-        >>> metric_tags = {'environment': 'production', 'service': 'web'}
-        >>> serialize_datadog_tags(metric_tags, None)
-        ['environment:production', 'service:web']
-    """
-    tags = metric_tags or default_tags
-
-    return [f"{tag_key}:{tag_value}" for tag_key, tag_value in tags.items()]
-
-
-def validate_datadog_metric_name(metric_name: str) -> bool:
-    """
-    Validate a metric name according to specific requirements.
-
-    Metric names must start with a letter.
-    Metric names must only contain ASCII alphanumerics, underscores, and periods.
-    Other characters, including spaces, are converted to underscores.
-    Unicode is not supported.
-    Metric names must not exceed 200 characters. Fewer than 100 is preferred from a UI perspective.
-
-    More information here: https://docs.datadoghq.com/metrics/custom_metrics/#naming-custom-metrics
-
-    Parameters:
-    ----------
-    metric_name: str
-        The metric name to be validated.
-
-    Returns:
-    -------
-    bool
-        True if the metric name is valid, False otherwise.
-    """
-
-    # Check if the metric name starts with a letter
-    # Check if the metric name contains more than 200 characters
-    # Check if the resulting metric name only contains ASCII alphanumerics, underscores, and periods
-    if not metric_name[0].isalpha() or len(metric_name) > 200 or not re.match(r"^[a-zA-Z0-9_.]+$", metric_name):
-        return False
-
-    return True

aws_lambda_powertools/metrics/provider/datadog/datadog.py

@@ -4,17 +4,20 @@
 import logging
 import numbers
 import os
+import re
 import time
 import warnings
 from typing import Any, Callable, Dict, List, Optional
 
 from aws_lambda_powertools.metrics.exceptions import MetricValueError, SchemaValidationError
-from aws_lambda_powertools.metrics.functions import serialize_datadog_tags, validate_datadog_metric_name
 from aws_lambda_powertools.metrics.provider import BaseProvider
+from aws_lambda_powertools.metrics.provider.datadog.warnings import DatadogDataValidationWarning
 from aws_lambda_powertools.shared import constants
 from aws_lambda_powertools.shared.functions import resolve_env_var_choice
 from aws_lambda_powertools.utilities.typing import LambdaContext
 
+METRIC_NAME_REGEX = re.compile(r"^[a-zA-Z0-9_.]+$")
+
 logger = logging.getLogger(__name__)
 
 # Check if using datadog layer
@@ -99,13 +102,16 @@ def add_metric(
         """
 
         # validating metric name
-        if not validate_datadog_metric_name(name):
+        if not self._validate_datadog_metric_name(name):
             docs = "https://docs.datadoghq.com/metrics/custom_metrics/#naming-custom-metrics"
             raise SchemaValidationError(
                 f"Invalid metric name. Please ensure the metric {name} follows the requirements. \n"
                 f"See Datadog documentation here: \n {docs}",
             )
 
+        # validating metric tag
+        self._validate_datadog_tags_name(**tags)
+
         if not isinstance(value, numbers.Real):
             raise MetricValueError(f"{value} is not a valid number")
 
@@ -158,7 +164,7 @@ def serialize_metric_set(self, metrics: List | None = None) -> List:
                     "m": metric_name,
                     "v": single_metric["v"],
                     "e": single_metric["e"],
-                    "t": serialize_datadog_tags(metric_tags=single_metric["t"], default_tags=self.default_tags),
+                    "t": self._serialize_datadog_tags(metric_tags=single_metric["t"], default_tags=self.default_tags),
                 },
             )
 
@@ -233,7 +239,8 @@ def log_metrics(
         -------
         **Lambda function using tracer and metrics decorators**
 
-            from aws_lambda_powertools import DatadogMetrics, Tracer
+            from aws_lambda_powertools import Tracer
+            from aws_lambda_powertools.metrics.provider.datadog import DatadogMetrics
 
             metrics = DatadogMetrics(namespace="powertools")
             tracer = Tracer(service="payment")
@@ -292,4 +299,93 @@ def set_default_tags(self, **tags) -> None:
             def lambda_handler():
                 return True
         """
+        self._validate_datadog_tags_name(**tags)
         self.default_tags.update(**tags)
+
+    @staticmethod
+    def _serialize_datadog_tags(metric_tags: Dict[str, Any], default_tags: Dict[str, Any]) -> List[str]:
+        """
+        Serialize metric tags into a list of formatted strings for Datadog integration.
+
+        This function takes a dictionary of metric-specific tags or default tags.
+        It parse these tags and converts them into a list of strings in the format "tag_key:tag_value".
+
+        Parameters
+        ----------
+        metric_tags: Dict[str, Any]
+            A dictionary containing metric-specific tags.
+        default_tags: Dict[str, Any]
+            A dictionary containing default tags applicable to all metrics.
+
+        Returns:
+        -------
+        List[str]
+            A list of formatted tag strings, each in the "tag_key:tag_value" format.
+
+        Example:
+            >>> metric_tags = {'environment': 'production', 'service': 'web'}
+            >>> serialize_datadog_tags(metric_tags, None)
+            ['environment:production', 'service:web']
+        """
+        tags = metric_tags or default_tags
+
+        return [f"{tag_key}:{tag_value}" for tag_key, tag_value in tags.items()]
+
+    @staticmethod
+    def _validate_datadog_tags_name(**tags):
+        """
+        Validate a metric tag according to specific requirements.
+
+        Metric tags must start with a letter.
+        Metric tags must not exceed 200 characters. Fewer than 100 is preferred from a UI perspective.
+
+        More information here: https://docs.datadoghq.com/getting_started/tagging/#define-tags
+
+        Parameters:
+        ----------
+        tags: Dict
+            The metric tags to be validated.
+        """
+        for tag_key, tag_value in tags.items():
+            tag = f"{tag_key}:{tag_value}"
+            if not tag[0].isalpha() or len(tag) > 200:
+                docs = "https://docs.datadoghq.com/getting_started/tagging/#define-tags"
+                warnings.warn(
+                    f"Invalid tag value. Please ensure the specific tag {tag} follows the requirements. \n"
+                    f"May incur data loss for metrics. \n"
+                    f"See Datadog documentation here: \n {docs}",
+                    DatadogDataValidationWarning,
+                    stacklevel=2,
+                )
+
+    @staticmethod
+    def _validate_datadog_metric_name(metric_name: str) -> bool:
+        """
+        Validate a metric name according to specific requirements.
+
+        Metric names must start with a letter.
+        Metric names must only contain ASCII alphanumerics, underscores, and periods.
+        Other characters, including spaces, are converted to underscores.
+        Unicode is not supported.
+        Metric names must not exceed 200 characters. Fewer than 100 is preferred from a UI perspective.
+
+        More information here: https://docs.datadoghq.com/metrics/custom_metrics/#naming-custom-metrics
+
+        Parameters:
+        ----------
+        metric_name: str
+            The metric name to be validated.
+
+        Returns:
+        -------
+        bool
+            True if the metric name is valid, False otherwise.
+        """
+
+        # Check if the metric name starts with a letter
+        # Check if the metric name contains more than 200 characters
+        # Check if the resulting metric name only contains ASCII alphanumerics, underscores, and periods
+        if not metric_name[0].isalpha() or len(metric_name) > 200 or not METRIC_NAME_REGEX.match(metric_name):
+            return False
+
+        return True

aws_lambda_powertools/metrics/provider/datadog/metrics.py

@@ -16,7 +16,7 @@ class DatadogMetrics:
     -------
     **Creates a few metrics and publish at the end of a function execution**
 
-        from aws_lambda_powertools import DatadogMetrics
+        from aws_lambda_powertools.metrics.provider.datadog import DatadogMetrics
 
         metrics = DatadogMetrics(namespace="ServerlessAirline")
 
@@ -33,7 +33,7 @@ def lambda_handler():
     Parameters
     ----------
     flush_to_log : bool, optional
-        Used when using export instead of extension
+        Used when using export instead of Lambda Extension
     namespace : str, optional
         Namespace for metrics
     provider: DatadogProvider, optional

aws_lambda_powertools/metrics/provider/datadog/warnings.py

@@ -0,0 +1,8 @@
+class DatadogDataValidationWarning(Warning):
+    message: str
+
+    def __init__(self, message: str):
+        self.message = message
+
+    def __str__(self) -> str:
+        return self.message

docs/core/metrics.md

@@ -1,5 +1,5 @@
 ---
-title: CloudWatch EMF
+title: Amazon CloudWatch EMF Metrics
 description: Core utility
 ---
 
@@ -16,7 +16,7 @@ These metrics can be visualized through [Amazon CloudWatch Console](https://cons
 
 ## Terminologies
 
-If you're new to Amazon CloudWatch, there are two terminologies you must be aware of before using this utility:
+If you're new to Amazon CloudWatch, there are five terminologies you must be aware of before using this utility:
 
 * **Namespace**. It's the highest level container that will group multiple metrics from multiple services for a given application, for example `ServerlessEcommerce`.
 * **Dimensions**. Metrics metadata in key-value format. They help you slice and dice metrics visualization, for example `ColdStart` metric by Payment `service`.
@@ -197,9 +197,9 @@ This has the advantage of keeping cold start metric separate from your applicati
 
 The following environment variable is available to configure Metrics at a global scope:
 
-| Setting            | Description                                                                  | Environment variable                    | Default |
-|--------------------|------------------------------------------------------------------------------|-----------------------------------------|---------|
-| **Namespace Name** | Sets namespace used for metrics.                                             | `POWERTOOLS_METRICS_NAMESPACE`          | `None`  |
+| Setting            | Description                      | Environment variable           | Default |
+| ------------------ | -------------------------------- | ------------------------------ | ------- |
+| **Namespace Name** | Sets namespace used for metrics. | `POWERTOOLS_METRICS_NAMESPACE` | `None`  |
 
 `POWERTOOLS_METRICS_NAMESPACE` is also available on a per-instance basis with the `namespace` parameter, which will consequently override the environment variable value.
 
@@ -286,9 +286,9 @@ You can use `EphemeralMetrics` class when looking to isolate multiple instances
 
 `EphemeralMetrics` has only one difference while keeping nearly the exact same set of features:
 
-| Feature                                                                                                     | Metrics | EphemeralMetrics |
-| ----------------------------------------------------------------------------------------------------------- | ------- | ---------------- |
-| **Share data across instances** (metrics, dimensions, metadata, etc.)                                       | Yes     | -                |
+| Feature                                                               | Metrics | EphemeralMetrics |
+| --------------------------------------------------------------------- | ------- | ---------------- |
+| **Share data across instances** (metrics, dimensions, metadata, etc.) | Yes     | -                |
 
 !!! question "Why not changing the default `Metrics` behaviour to not share data across instances?"
 
@@ -327,6 +327,20 @@ These issues are exacerbated when you create **(A)** metric dimensions condition
 
 That is why `Metrics` shares data across instances by default, as that covers 80% of use cases and different personas using Powertools. This allows them to instantiate `Metrics` in multiple places throughout their code - be a separate file, a middleware, or an abstraction that sets default dimensions.
 
+### Observability providers
+
+> An observability provider is an [AWS Lambda Partner](https://docs.aws.amazon.com/lambda/latest/dg/extensions-api-partners.html){target="_blank" rel="nofollow"} offering a platform for logging, metrics, traces, etc.
+
+We provide a thin-wrapper on top of the most requested observability providers. We strive to keep a similar UX as close as possible while keeping our value add features.
+
+!!! tip "Missing your preferred provider? Please create a [feature request](https://github.com/aws-powertools/powertools-lambda-python/issues/new?assignees=&labels=feature-request%2Ctriage&projects=&template=feature_request.yml&title=Feature+request%3A+TITLE){target="_blank"}."
+
+Current providers:
+
+| Provider                              | Notes                                                    |
+| ------------------------------------- | -------------------------------------------------------- |
+| [Datadog](./datadog){target="_blank"} | Uses Datadog SDK and Datadog Lambda Extension by default |
+
 ## Testing your code
 
 ### Setting environment variables