feat(client): add support for metrics (#831)

## Change Summary

closes #434

TODO:
- [x] support globalLabels
- [x] check if int / float is right
- [x] test multiple client instances
- [x] document

## Checklist

- [ ] Unit tests for the changes exist
- [ ] Tests pass without significant drop in coverage
- [ ] Documentation reflects changes where applicable
- [ ] Test snapshots have been
[updated](https://prisma-client-py.readthedocs.io/en/latest/contributing/contributing/#snapshot-tests)
if applicable

## Agreement

By submitting this pull request, I confirm that you can use, modify,
copy and redistribute this contribution, under the terms of your choice.

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

Author: RobertCraigie

databases/sync_tests/test_metrics.py

@@ -0,0 +1,55 @@
+from prisma import Prisma
+from prisma._compat import model_json
+
+
+def test_prometheus(client: Prisma) -> None:
+    """Metrics can be returned in Prometheus format"""
+    client.user.create(data={'name': 'Robert'})
+
+    metrics = client.get_metrics(format='prometheus')
+
+    assert 'prisma_client_queries_total' in metrics
+    assert 'prisma_datasource_queries_total' in metrics
+    assert 'prisma_client_queries_active' in metrics
+    assert 'prisma_client_queries_duration_histogram_ms_bucket' in metrics
+
+
+def test_json_string(client: Prisma) -> None:
+    """Metrics can be serlialized to JSON"""
+    client.user.create(data={'name': 'Robert'})
+
+    metrics = client.get_metrics()
+    assert isinstance(model_json(metrics), str)
+
+
+def test_json(client: Prisma) -> None:
+    """Metrics returned in the JSON format"""
+    client.user.create(data={'name': 'Robert'})
+
+    metrics = client.get_metrics(format='json')
+
+    assert len(metrics.counters) > 0
+    assert metrics.counters[0].value > 0
+
+    assert len(metrics.gauges) > 0
+    gauge = next(
+        filter(
+            lambda g: g.key == 'prisma_pool_connections_open', metrics.gauges
+        )
+    )
+    assert gauge.value > 0
+
+    assert len(metrics.histograms) > 0
+    assert metrics.histograms[0].value.sum > 0
+    assert metrics.histograms[0].value.count > 0
+
+    assert len(metrics.histograms[0].value.buckets) > 0
+
+    for bucket in metrics.histograms[0].value.buckets:
+        assert bucket.max_value >= 0
+        assert bucket.total_count >= 0
+
+
+def test_global_labels(client: Prisma) -> None:
+    metrics = client.get_metrics(global_labels={'foo': 'bar'})
+    assert metrics.counters[0].labels == {'foo': 'bar'}

databases/templates/schema.prisma.jinja2

@@ -39,20 +39,20 @@ model Profile {
 }
 
 model Post {
-  id          String   @id @default(uuid())
-  created_at  DateTime @default(now())
-  updated_at  DateTime @updatedAt
+  id          String     @id @default(uuid())
+  created_at  DateTime   @default(now())
+  updated_at  DateTime   @updatedAt
   title       String
   description String?
-  published   Boolean  @default(false)
-  views       Int      @default(0)
-  author      User?    @relation(fields: [author_id], references: [id])
+  published   Boolean    @default(false)
+  views       Int        @default(0)
+  author      User?      @relation(fields: [author_id], references: [id])
   author_id   String?
-  categories Category[]
+  categories  Category[]
 }
 
 model Category {
-  id          String   @id @default(uuid())
+  id    String @id @default(uuid())
   posts Post[]
   name  String
 }
@@ -80,10 +80,10 @@ model Types {
 
   // TODO: optional for these too
   {% if config.supports_feature('enum') %}
-  enum     Role   @default(USER)
+  enum     Role  @default(USER)
   {% endif %}
   {% if config.supports_feature('json') %}
-  json_obj Json?  @default("{}")
+  json_obj Json? @default("{}")
   {% endif %}
 }
 
@@ -123,6 +123,7 @@ model ListsDefaults {
   roles        Role[]     @default([USER])
   {% endif %}
 }
+
 {% endif %}
 
 // these models are here for testing different combinations of unique constraints
@@ -173,6 +174,7 @@ model Unique6 {
 
   @@unique([name, role])
 }
+
 {% endif %}
 
 model Id1 {
@@ -211,6 +213,7 @@ model Id5 {
 
   @@unique([name, role])
 }
+
 {% endif %}
 
 {% if config.supports_feature('enum') %}
@@ -219,4 +222,5 @@ enum Role {
   ADMIN
   EDITOR
 }
+
 {% endif %}

databases/tests/test_metrics.py

@@ -0,0 +1,61 @@
+import pytest
+
+from prisma import Prisma
+from prisma._compat import model_json
+
+
+@pytest.mark.asyncio
+async def test_prometheus(client: Prisma) -> None:
+    """Metrics can be returned in Prometheus format"""
+    await client.user.create(data={'name': 'Robert'})
+
+    metrics = await client.get_metrics(format='prometheus')
+
+    assert 'prisma_client_queries_total' in metrics
+    assert 'prisma_datasource_queries_total' in metrics
+    assert 'prisma_client_queries_active' in metrics
+    assert 'prisma_client_queries_duration_histogram_ms_bucket' in metrics
+
+
+@pytest.mark.asyncio
+async def test_json_string(client: Prisma) -> None:
+    """Metrics can be serlialized to JSON"""
+    await client.user.create(data={'name': 'Robert'})
+
+    metrics = await client.get_metrics()
+    assert isinstance(model_json(metrics), str)
+
+
+@pytest.mark.asyncio
+async def test_json(client: Prisma) -> None:
+    """Metrics returned in the JSON format"""
+    await client.user.create(data={'name': 'Robert'})
+
+    metrics = await client.get_metrics(format='json')
+
+    assert len(metrics.counters) > 0
+    assert metrics.counters[0].value > 0
+
+    assert len(metrics.gauges) > 0
+    gauge = next(
+        filter(
+            lambda g: g.key == 'prisma_pool_connections_open', metrics.gauges
+        )
+    )
+    assert gauge.value > 0
+
+    assert len(metrics.histograms) > 0
+    assert metrics.histograms[0].value.sum > 0
+    assert metrics.histograms[0].value.count > 0
+
+    assert len(metrics.histograms[0].value.buckets) > 0
+
+    for bucket in metrics.histograms[0].value.buckets:
+        assert bucket.max_value >= 0
+        assert bucket.total_count >= 0
+
+
+@pytest.mark.asyncio
+async def test_global_labels(client: Prisma) -> None:
+    metrics = await client.get_metrics(global_labels={'foo': 'bar'})
+    assert metrics.counters[0].labels == {'foo': 'bar'}

docs/reference/metrics.md

@@ -0,0 +1,38 @@
+# Metrics
+
+Prisma Metrics gives you detailed insight into how Prisma is interactting with your Database. For more detailed information see the [Prisma Documentation](https://www.prisma.io/docs/concepts/components/prisma-client/metrics).
+
+To access metrics in the Python client
+
+Metrics can be accessed in the Python client through the `Prisma.get_metrics()` method. Two different formats are available, `json` and `prometheus`.
+
+## JSON Format
+
+The default format is `json` which returns a `prisma.Metrics` instance:
+
+```py
+from prisma import Prisma
+
+client = Prisma()
+
+metrics = client.get_metrics()
+print(metrics.counters[0])
+```
+
+See the [Prisma Documentation](https://www.prisma.io/docs/concepts/components/prisma-client/metrics#retrieve-metrics-in-json-format) for more details on the structure of the metrics object.
+
+## Prometheus Format
+
+The `prometheus` format returns a `str` which is a valid [Prometheus data](https://prometheus.io/).
+
+
+```py
+from prisma import Prisma
+
+client = Prisma()
+
+metrics = client.get_metrics(format='prometheus')
+print(metrics)
+```
+
+See the [Prisma Documentation](https://www.prisma.io/docs/concepts/components/prisma-client/metrics#retrieve-metrics-in-prometheus-format) for more details on the structure of the data.

mkdocs.yml

@@ -74,6 +74,7 @@ nav:
       - Custom Generators: reference/custom-generators.md
       - Logging: reference/logging.md
       - Binaries: reference/binaries.md
+      - Metrics: reference/metrics.md
   - Contributing:
       - How to Contribute: contributing/contributing.md
       - Architecture: contributing/architecture.md

src/prisma/__init__.py

@@ -13,6 +13,11 @@
 from . import errors as errors
 from .validator import *
 from ._types import PrismaMethod as PrismaMethod
+from ._metrics import (
+    Metric as Metric,
+    Metrics as Metrics,
+    MetricHistogram as MetricHistogram,
+)
 
 
 try:

src/prisma/_metrics.py

@@ -0,0 +1,50 @@
+# copied from https://github.com/prisma/prisma/blob/23d5ef0672372035a84552b6b457197ca19f486d/packages/client/src/runtime/core/engines/common/types/Metrics.ts
+from __future__ import annotations
+
+from typing import Generic, List, TypeVar, Dict, NamedTuple
+
+from pydantic import BaseModel
+
+from ._compat import GenericModel, model_rebuild
+
+
+__all__ = (
+    'Metrics',
+    'Metric',
+    'MetricHistogram',
+)
+
+
+_T = TypeVar('_T')
+
+
+# TODO: check if int / float is right
+
+
+class Metrics(BaseModel):
+    counters: List[Metric[int]]
+    gauges: List[Metric[float]]
+    histograms: List[Metric[MetricHistogram]]
+
+
+class Metric(GenericModel, Generic[_T]):
+    key: str
+    value: _T
+    labels: Dict[str, str]
+    description: str
+
+
+class MetricHistogram(BaseModel):
+    sum: float
+    count: int
+    buckets: List[HistogramBucket]
+
+
+class HistogramBucket(NamedTuple):
+    max_value: float
+    total_count: int
+
+
+model_rebuild(Metric)
+model_rebuild(Metrics)
+model_rebuild(MetricHistogram)

src/prisma/generator/models.py

@@ -480,6 +480,9 @@ def warn_binary_targets(
 
         return targets
 
+    def has_preview_feature(self, feature: str) -> bool:
+        return feature in self.preview_features
+
 
 class ValueFromEnvVar(BaseModel):
     value: str

src/prisma/generator/templates/client.py.jinja

@@ -11,7 +11,7 @@ from types import TracebackType
 from pydantic import BaseModel
 
 from . import types, models, errors, actions
-from .types import DatasourceOverride, HttpConfig
+from .types import DatasourceOverride, HttpConfig, MetricsFormat
 from ._types import BaseModelT, PrismaMethod
 from .bases import _PrismaModel
 from .engine import AbstractEngine, QueryEngine, TransactionId
@@ -20,6 +20,7 @@ from .generator.models import EngineType, OptionalValueFromEnvVar, BinaryPaths
 from ._compat import removeprefix, model_parse
 from ._constants import DEFAULT_CONNECT_TIMEOUT, DEFAULT_TX_MAX_WAIT, DEFAULT_TX_TIMEOUT
 from ._raw_query import deserialize_raw_results
+from ._metrics import Metrics
 
 __all__ = (
     'ENGINE_TYPE',
@@ -423,6 +424,44 @@ class Prisma:
         """Returns True if the client is wrapped within a transaction"""
         return self._tx_id is not None
 
+    @overload
+    {{ maybe_async_def }}get_metrics(
+        self,
+        format: Literal['json'] = 'json',
+        *,
+        global_labels: dict[str, str] | None = None,
+    ) -> Metrics:
+        ...
+
+    @overload
+    {{ maybe_async_def }}get_metrics(
+        self,
+        format: Literal['prometheus'],
+        *,
+        global_labels: dict[str, str] | None = None,
+    ) -> str:
+        ...
+
+    {{ maybe_async_def }}get_metrics(
+        self,
+        format: MetricsFormat = 'json',
+        *,
+        global_labels: dict[str, str] | None = None,
+    ) -> str | Metrics:
+        """Metrics give you a detailed insight into how the Prisma Client interacts with your database.
+
+        You can retrieve metrics in either JSON or Prometheus formats.
+
+        For more details see https://www.prisma.io/docs/concepts/components/prisma-client/metrics.
+        """
+        response = {{ maybe_await }}self._engine.metrics(format=format, global_labels=global_labels)
+        if format == 'prometheus':
+            # For the prometheus format we return the response as-is
+            assert isinstance(response, str)
+            return response
+
+        return model_parse(Metrics, response)
+
     # TODO: don't return Any
     {{ maybe_async_def }}_execute(
         self,