Skip to content

Commit

Permalink
Updating tracing docs for GA (#6523)
Browse files Browse the repository at this point in the history 
* first pass at updating tracing docs for GA

* fix anchors

* update prisma:engine to prisma:engine:query

* add notes about opentelemetry peer dep

* Update content/200-orm/200-prisma-client/600-observability-and-logging/250-opentelemetry-tracing.mdx

Co-authored-by: Alexey Orlenko <[email protected]>

* PR edits

* correct spans and document re-exported registerInstrumentations

---------

Co-authored-by: Alexey Orlenko <[email protected]>
  • Loading branch information
@jharrell @aqrln
jharrell and aqrln authored Dec 17, 2024
1 parent 60204fb commit cf22b49
Show file tree
Hide file tree
Showing 5 changed files with 39 additions and 40 deletions.
2 changes: 1 addition & 1 deletion content/200-orm/200-prisma-client/100-queries/058-transactions.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -202,7 +202,7 @@ Sometimes you need more control over what queries execute within a transaction.

Interactive transactions have been generally available from version 4.7.0.

If you use interactive transactions in preview from version 2.29.0 to 4.6.1 (included), you need to add the `interactiveTransactions` preview feature to the generator block of your Prisma schema.
If you use interactive transactions in preview from version 2.29.0 to 4.6.1 (inclusive), you need to add the `interactiveTransactions` preview feature to the generator block of your Prisma schema.

</Admonition>

Expand Down
43 changes: 22 additions & 21 deletions ...m/200-prisma-client/600-observability-and-logging/250-opentelemetry-tracing.mdx
View file
Original file line number Diff line number Diff line change
@@ -1,9 +1,7 @@
---
title: 'OpenTelemetry tracing'
metaTitle: 'OpenTelemetry tracing (Preview)'
metaTitle: 'OpenTelemetry tracing'
metaDescription: 'Diagnose application performance with detailed traces of each query.'
sidebar_class_name: preview-badge
toc_max_heading_level: 4
---


Expand Down Expand Up @@ -36,10 +34,11 @@ For each trace, Prisma Client outputs a series of spans. The number and type of
- `prisma:client:operation`: Represents the entire Prisma Client operation, from Prisma Client to the database and back. It contains details such as the model and method called by Prisma Client. Depending on the Prisma operation, it contains one or more of the following spans:
- `prisma:client:connect`: Represents how long it takes for Prisma Client to connect to the database.
- `prisma:client:serialize`: Represents how long it takes to validate and transform a Prisma Client operation into a query for the [query engine](/orm/more/under-the-hood/engines).
- `prisma:engine`: Represents how long a query takes in the query engine.
- `prisma:engine:query`: Represents how long a query takes in the query engine.
- `prisma:engine:connection`: Represents how long it takes for Prisma Client to get a database connection.
- `prisma:engine:db_query`: Represents the database query that was executed against the database. It includes the query in the tags, and how long the query took to run.
- `prisma:engine:serialize`: Represents how long it takes to transform a database query result into a Prisma Client result.
- `prisma:engine:serialize`: Represents how long it takes to transform a raw response from the database into a typed result.
- `prisma:engine:response_json_serialization`: Represents how long it takes to serialize the database query result into a JSON response to the Prisma Client.

For example, given the following Prisma Client code:

Expand All @@ -58,11 +57,12 @@ The trace is structured as follows:

- `prisma:client:operation`
- `prisma:client:serialize`
- `prisma:engine`
- `prisma:engine:query`
- `prisma:engine:connection`
- `prisma:engine:db_query`: details of the first SQL query or command...
- `prisma:engine:db_query`: ...details of the next SQL query or command...
- `prisma:engine:serialize`
- `prisma:engine:response_json_serialization`

## Considerations and prerequisites

Expand All @@ -71,26 +71,28 @@ If your application sends a large number of spans to a [collector](https://opent
To use tracing, you must do the following:

1. [Install the appropriate dependencies](#step-1-install-up-to-date-prisma-orm-dependencies).
1. [Enable the `tracing` feature flag in your Prisma schema file](#step-2-enable-the-feature-flag-in-your-prisma-schema-file).
1. [Install OpenTelemetry packages](#step-3-install-opentelemetry-packages).
1. [Install OpenTelemetry packages](#step-2-install-opentelemetry-packages).
1. [Register tracing in your application](#step-3-register-tracing-in-your-application).

## Get started with tracing in Prisma ORM

This section explains how to install and register tracing in your application.

### Step 1. Install up-to-date Prisma ORM dependencies

Use version `4.2.0` or later of the `prisma`, `@prisma/client`, and `@prisma/instrumentation` npm packages.
Use version `6.1.0` or later of the `prisma`, `@prisma/client`, and `@prisma/instrumentation` npm packages. You will also need to install the `@opentelemetry/api` package as it's a peer dependency.

```terminal
npm install prisma@latest --save-dev
npm install @prisma/client@latest --save
npm install @prisma/instrumentation@latest --save
npm install @opentelemetry/api@latest --save
```

### Step 2: Enable the feature flag in your Prisma schema file
<details>
<summary>Tracing on previous versions of Prisma ORM</summary>

In the `generator` block of your `schema.prisma` file, enable the `tracing` feature flag:
Tracing was added in version `4.2.0` of Prisma ORM as a Preview feature. For versions of Prisma ORM between `4.2.0` and `6.1.0`, you need to enable the `tracing` Preview feature in your Prisma schema file.

```prisma
generator client {
Expand All @@ -99,15 +101,17 @@ generator client {
}
```

### Step 3: Install OpenTelemetry packages
</details>

Finally, install the appropriate OpenTelemetry packages, as follows:
### Step 2: Install OpenTelemetry packages

Now install the appropriate OpenTelemetry packages, as follows:

```console
npm install @opentelemetry/semantic-conventions @opentelemetry/exporter-trace-otlp-http @opentelemetry/instrumentation @opentelemetry/sdk-trace-base @opentelemetry/sdk-trace-node @opentelemetry/resources
npm install @opentelemetry/semantic-conventions @opentelemetry/exporter-trace-otlp-http @opentelemetry/sdk-trace-base @opentelemetry/sdk-trace-node @opentelemetry/resources
```

### Register tracing in your application
### Step 3: Register tracing in your application

The following code provides two examples of configuring OpenTelemetry tracing in Prisma:

Expand All @@ -122,12 +126,11 @@ This setup gives you fine-grained control over instrumentation and tracing. You

```ts
// Imports
import { SEMRESATTRS_SERVICE_NAME, SEMRESATTRS_SERVICE_VERSION } from '@opentelemetry/semantic-conventions'
import { ATTR_SERVICE_NAME, ATTR_SERVICE_VERSION } from '@opentelemetry/semantic-conventions'
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http'
import { registerInstrumentations } from '@opentelemetry/instrumentation'
import { SimpleSpanProcessor } from '@opentelemetry/sdk-trace-base'
import { NodeTracerProvider } from '@opentelemetry/sdk-trace-node'
import { PrismaInstrumentation } from '@prisma/instrumentation'
import { PrismaInstrumentation, registerInstrumentations } from '@prisma/instrumentation'
import { Resource } from '@opentelemetry/resources'

// Configure the trace provider
Expand Down Expand Up @@ -238,15 +241,14 @@ The following example sends output tracing to the console with `ConsoleSpanExpor
```ts
// Imports
import { SemanticResourceAttributes } from '@opentelemetry/semantic-conventions'
import { registerInstrumentations } from '@opentelemetry/instrumentation'
import {
BasicTracerProvider,
ConsoleSpanExporter,
SimpleSpanProcessor,
} from '@opentelemetry/sdk-trace-base'
import { AsyncHooksContextManager } from '@opentelemetry/context-async-hooks'
import * as api from '@opentelemetry/api'
import { PrismaInstrumentation } from '@prisma/instrumentation'
import { PrismaInstrumentation, registerInstrumentations } from '@prisma/instrumentation'
import { Resource } from '@opentelemetry/resources'

// Export the tracing
Expand Down Expand Up @@ -308,7 +310,6 @@ As an example, take the following Prisma schema:
```prisma file=schema.prisma showLineNumbers
generator client {
provider = "prisma-client-js"
previewFeatures = ["tracing", "interactiveTransactions"]
}
datasource db {
Expand Down
1 change: 1 addition & 0 deletions content/200-orm/500-reference/500-preview-features/050-client-preview-features.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -66,6 +66,7 @@ In the list below, you can find a history of Prisma Client and Prisma schema fea
| [`fieldReference`](/orm/reference/prisma-client-reference#compare-columns-in-the-same-table) | [4.3.0](https://github.com/prisma/prisma/releases/tag/4.3.0) | [5.0.0](https://github.com/prisma/prisma/releases/tag/5.0.0) |
| [`clientExtensions`](/orm/prisma-client/client-extensions) | [4.7.0](https://github.com/prisma/prisma/releases/tag/4.7.0) | [4.16.0](https://github.com/prisma/prisma/releases/tag/4.16.0) |
| [`filteredRelationCount`](/orm/prisma-client/queries/aggregation-grouping-summarizing#filter-the-relation-count) | [4.3.0](https://github.com/prisma/prisma/releases/tag/4.3.0) | [4.16.0](https://github.com/prisma/prisma/releases/tag/4.16.0) |
| [`tracing`](/orm/prisma-client/observability-and-logging/opentelemetry-tracing) | [4.2.0](https://github.com/prisma/prisma/releases/tag/4.2.0) | [6.1.0](https://github.com/prisma/prisma/releases/tag/6.1.0)
| [`orderByNulls`](/orm/prisma-client/queries/filtering-and-sorting#sort-with-null-records-first-or-last) | [4.1.0](https://github.com/prisma/prisma/releases/tag/4.1.0) | [4.16.0](https://github.com/prisma/prisma/releases/tag/4.16.0) |
| [`referentialIntegrity`](/orm/prisma-schema/data-model/relations/relation-mode) | [3.1.1](https://github.com/prisma/prisma/releases/tag/3.1.1) | [4.7.0](https://github.com/prisma/prisma/releases/tag/4.7.0) |
| [`interactiveTransactions`](/orm/prisma-client/queries/transactions#interactive-transactions) | [2.29.0](https://github.com/prisma/prisma/releases/tag/2.29.0) | <ul><li> [4.7.0](https://github.com/prisma/prisma/releases/tag/4.7.0)</li><li>with Prisma Accelerate [5.1.1](https://github.com/prisma/prisma/releases/tag/5.1.1)</li></ul> |
Expand Down
2 changes: 1 addition & 1 deletion content/500-platform/10-about.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -65,7 +65,7 @@ To obtain the Optimize API key:
4. Select **Settings**.
5. Click **Create API key**.
6. Enter a name for the API key in the **Name** field, then click **Create**.
7. Copy the API key and store it securely. This will be used in your project's [`.env` file](/optimize/getting-started#23-add-the-optimize-api-key-to-your-env-file) via the `"OPTIMIZE_API_KEY"`. Finally, click the **"I've stored it securely"** button.
7. Copy the API key and store it securely. This will be used in your project's [`.env` file](/optimize/getting-started#22-add-the-optimize-api-key-to-your-env-file) via the `"OPTIMIZE_API_KEY"`. Finally, click the **"I've stored it securely"** button.

You now have your Optimize API key.

Expand Down
31 changes: 14 additions & 17 deletions content/700-optimize/200-getting-started.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -27,9 +27,18 @@ Prisma Optimize is intended for use in local environments. Learn more in the [FA

## 2. Add Optimize to your application

### 2.1. Update Your `schema.prisma` file
### 2.1. Install the Optimize Prisma Client extension

In the `generator` block of your Prisma schema, add the `tracing` preview feature:
Install Prisma Client and the Optimize extension:

```bash
npm install @prisma/client@latest @prisma/extension-optimize
```

<details>
<summary>Enabling tracing in older versions of Prisma ORM</summary>

For versions of Prisma ORM between `4.2.0` and `6.1.0`, you need to enable the `tracing` preview feature in your Prisma schema file.

```prisma
generator client {
Expand All @@ -38,29 +47,17 @@ generator client {
}
```

Then, generate the Prisma Client:

```bash
npx prisma generate
```

### 2.2. Install the Optimize Prisma Client extension

Install the latest versions of Prisma Client and the Optimize extension:

```bash
npm install @prisma/client@latest @prisma/extension-optimize
```
</details>

### 2.3. Add the Optimize API Key to your `.env` file
### 2.2. Add the Optimize API Key to your `.env` file

<a href="/docs/platform/about#generating-an-optimize-api-key" target="_blank">Generate a Prisma Optimize API key</a> and add it to your `.env` file:

```bash
OPTIMIZE_API_KEY="YOUR_OPTIMIZE_API_KEY"
```

### 2.4. Extend your Prisma Client instance
### 2.3. Extend your Prisma Client instance

Extend your existing Prisma Client instance with the Optimize extension:

Expand Down

0 comments on commit cf22b49

Please sign in to comment.