Queries Module

The SDK should auto-instrument all database queries, and each query to the database should result in a span. This includes queries made manually, or via ORM. The Queries module supports SQL databases like PostgreSQL and MySQL, as well as MongoDB. It does not support other databases like Neo4j or ClickHouse. Regardless of that, the SDK should instrument database queries as fully and correctly as possible to ensure correct behavior and future compatibility.

AttributeDescriptionNotes
opPrefixed with "db" (e.g., "db", "db.query", "db.sql.query") 1Required
descriptionThe full scrubbed query (e.g., SELECT * FROM users where id = ?)Required, see Query Scrubbing for details
dataA key-value mapping of span attributes. (e.g., {"db.system": "postgresql", "db.name": "prod-2"})Required for full experience. See Span Data for details

The query description should be scrubbed of any user-supplied values.

e.g., the query

Copied
SELECT * FROM users WHERE id = 17;

should be scrubbed to:

Copied
SELECT * FROM users WHERE id = ?;

The ? parameter is a placeholder in the query. The SDK must scrub out all values and replace them with a placeholder. Supported placeholder values are %s, ?, :c0 (e.g., :c0, :c1) and $1 (e.g., $1, $2).

For MongoDB, the description should contain valid JSON. If replacing values with a placeholder, the string "?" should be used.

Copied
{ "find": "documents", "filter": { "wordCount": { "$gte": "?" } } }

For full support, each database span should have a data attribute. data is itself a key-value lookup of attributes. Refer to Database Span Data Conventions for a full list of attributes that database spans should have. We recommend that the SDK provide all of those attributes for every span. However, the minimal requirement is that the SDK provides the db.system attribute.

MongoDB support requires a few extra data attributes. In addition to a db.system value of "mongodb", the db.operation and db.collection.name attributes are also required to contain the command and collection name respectively.

Consider a hypothetical Python ORM:

Copied
from magicORM import ORM
from .models import User, Product

ORM.connect_postgres(host="127.0.0.1", port="7777", database="production")
return User.find(17).find_related(Product)

Assume it makes this SQL query:

Copied
SELECT * FROM projects
WHERE projects_user = 17;

This should result in the following span:

Copied
{
  "description": "SELECT * FROM projects WHERE projects_user = 17",
  "op": "db",
  "data": {
    "db.system": "postgresql",
    "db.operation": "SELECT",
    "db.name": "production",
    "server.address": "127.0.0.1",
    "server.port": "7777"
  }
}

  1. Some operations are accepted by Sentry, but not indexed by the Queries module. This includes db.sql.room, db.redis, and some others. Do not attempt to trick the system by providing an incorrect span operation! ↩

Help improve this content
Our documentation is open source and available on GitHub. Your contributions are welcome, whether fixing a typo (drat!) or suggesting an update ("yeah, this would be better").