OpenTelemetry tracing
Tracing provides a detailed log of the activity that Prisma Client carries out, at an operation level, including the time taken to execute each query. It helps you analyze your application's performance and identify bottlenecks. Tracing is fully compliant with OpenTelemetry, so you can use it as part of your end-to-end application tracing system.
Tracing gives you a highly detailed, operation-level insight into your Prisma ORM project. If you want aggregated numerical reporting, such as query counts, connection counts, and total query execution times, see Metrics.
About tracing
When you enable tracing, Prisma Client outputs the following:
- One trace for each operation (e.g. findMany) that Prisma Client makes.
- In each trace, one or more spans. Each span represents the length of time that one stage of the operation takes, such as serialization, or a database query. Spans are represented in a tree structure, where child spans indicate that execution is happening within a larger parent span.
The number and type of spans in a trace depends on the type of operation the trace covers, but an example is as follows:
You can send tracing output to the console, or analyze it in any OpenTelemetry-compatible tracing system, such as Jaeger, Honeycomb and Datadog. On this page, we give an example of how to send tracing output to Jaeger, which you can run locally.
Trace output
For each trace, Prisma Client outputs a series of spans. The number and type of these spans depends on the Prisma Client operation. A typical Prisma trace has the following spans:
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.prisma:engine
: 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.
For example, given the following Prisma Client code:
prisma.user.findMany({
where: {
email: email,
},
include: {
posts: true,
},
})
The trace is structured as follows:
prisma:client:operation
prisma:client:serialize
prisma:engine
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
Considerations and prerequisites
If your application sends a large number of spans to a collector, this can have a significant performance impact. For information on how to minimize this impact, see Reducing performance impact.
To use tracing, you must do the following:
- Install the appropriate dependencies.
- Enable the
tracing
feature flag in your Prisma schema file. - Install OpenTelemetry packages.
Get started with tracing in Prisma ORM
This section explains how to install and register tracing in your application.