chore: Add Custom OpenTelemetry Exporter in for Service Metrics (#1273)

* chore: Add Custom OpenTelemetry Exporter in for Service Metrics

* Updated copyright dates to 2025

---------

Co-authored-by: rahul2393 <[email protected]>

Author: lszinv

google/cloud/spanner_v1/metrics/README.md

@@ -0,0 +1,19 @@
+# Custom Metric Exporter
+The custom metric exporter, as defined in [metrics_exporter.py](./metrics_exporter.py), is designed to work in conjunction with OpenTelemetry and the Spanner client. It converts data into its protobuf equivalent and sends it to Google Cloud Monitoring.
+
+## Filtering Criteria
+The exporter filters metrics based on the following conditions, utilizing values defined in [constants.py](./constants.py):
+
+* Metrics with a scope set to `gax-python`.
+* Metrics with one of the following predefined names:
+  * `attempt_latencies`
+  * `attempt_count`
+  * `operation_latencies`
+  * `operation_count`
+  * `gfe_latency`
+  * `gfe_missing_header_count`
+
+## Service Endpoint
+The exporter sends metrics to the Google Cloud Monitoring [service endpoint](https://cloud.google.com/python/docs/reference/monitoring/latest/google.cloud.monitoring_v3.services.metric_service.MetricServiceClient#google_cloud_monitoring_v3_services_metric_service_MetricServiceClient_create_service_time_series), distinct from the regular client endpoint. This service endpoint operates under a different quota limit than the user endpoint and features an additional server-side filter that only permits a predefined set of metrics to pass through.
+
+When introducing new service metrics, it is essential to ensure they are allowed through by the server-side filter as well.

google/cloud/spanner_v1/metrics/constants.py

@@ -0,0 +1,63 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+BUILT_IN_METRICS_METER_NAME = "gax-python"
+NATIVE_METRICS_PREFIX = "spanner.googleapis.com/internal/client"
+SPANNER_RESOURCE_TYPE = "spanner_instance_client"
+
+# Monitored resource labels
+MONITORED_RES_LABEL_KEY_PROJECT = "project_id"
+MONITORED_RES_LABEL_KEY_INSTANCE = "instance_id"
+MONITORED_RES_LABEL_KEY_INSTANCE_CONFIG = "instance_config"
+MONITORED_RES_LABEL_KEY_LOCATION = "location"
+MONITORED_RES_LABEL_KEY_CLIENT_HASH = "client_hash"
+MONITORED_RESOURCE_LABELS = [
+    MONITORED_RES_LABEL_KEY_PROJECT,
+    MONITORED_RES_LABEL_KEY_INSTANCE,
+    MONITORED_RES_LABEL_KEY_INSTANCE_CONFIG,
+    MONITORED_RES_LABEL_KEY_LOCATION,
+    MONITORED_RES_LABEL_KEY_CLIENT_HASH,
+]
+
+# Metric labels
+METRIC_LABEL_KEY_CLIENT_UID = "client_uid"
+METRIC_LABEL_KEY_CLIENT_NAME = "client_name"
+METRIC_LABEL_KEY_DATABASE = "database"
+METRIC_LABEL_KEY_METHOD = "method"
+METRIC_LABEL_KEY_STATUS = "status"
+METRIC_LABEL_KEY_DIRECT_PATH_ENABLED = "directpath_enabled"
+METRIC_LABEL_KEY_DIRECT_PATH_USED = "directpath_used"
+METRIC_LABELS = [
+    METRIC_LABEL_KEY_CLIENT_UID,
+    METRIC_LABEL_KEY_CLIENT_NAME,
+    METRIC_LABEL_KEY_DATABASE,
+    METRIC_LABEL_KEY_METHOD,
+    METRIC_LABEL_KEY_STATUS,
+    METRIC_LABEL_KEY_DIRECT_PATH_ENABLED,
+    METRIC_LABEL_KEY_DIRECT_PATH_USED,
+]
+
+# Metric names
+METRIC_NAME_OPERATION_LATENCIES = "operation_latencies"
+METRIC_NAME_ATTEMPT_LATENCIES = "attempt_latencies"
+METRIC_NAME_OPERATION_COUNT = "operation_count"
+METRIC_NAME_ATTEMPT_COUNT = "attempt_count"
+METRIC_NAME_GFE_LATENCY = "gfe_latency"
+METRIC_NAME_GFE_MISSING_HEADER_COUNT = "gfe_missing_header_count"
+METRIC_NAMES = [
+    METRIC_NAME_OPERATION_LATENCIES,
+    METRIC_NAME_ATTEMPT_LATENCIES,
+    METRIC_NAME_OPERATION_COUNT,
+    METRIC_NAME_ATTEMPT_COUNT,
+]