372 lines
16 KiB
YAML
372 lines
16 KiB
YAML
groups:
|
|
- id: registry.db
|
|
type: attribute_group
|
|
display_name: General Database Attributes
|
|
brief: >
|
|
This group defines the attributes used to describe telemetry in the context of databases.
|
|
attributes:
|
|
- id: db.collection.name
|
|
type: string
|
|
stability: release_candidate
|
|
brief: The name of a collection (table, container) within the database.
|
|
note: |
|
|
It is RECOMMENDED to capture the value as provided by the application
|
|
without attempting to do any case normalization.
|
|
|
|
The collection name SHOULD NOT be extracted from `db.query.text`,
|
|
when the database system supports query text with multiple collections
|
|
in non-batch operations.
|
|
|
|
For batch operations, if the individual operations are known to have the same
|
|
collection name then that collection name SHOULD be used.
|
|
examples: ["public.users", "customers"]
|
|
- id: db.namespace
|
|
type: string
|
|
stability: release_candidate
|
|
brief: >
|
|
The name of the database, fully qualified within the server address and port.
|
|
note: >
|
|
If a database system has multiple namespace components, they SHOULD be concatenated
|
|
from the most general to the most specific namespace component,
|
|
using `|` as a separator between the components.
|
|
Any missing components (and their associated separators) SHOULD be omitted.
|
|
|
|
Semantic conventions for individual database systems SHOULD document what `db.namespace`
|
|
means in the context of that system.
|
|
|
|
It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization.
|
|
examples: ["customers", "test.users"]
|
|
- id: db.operation.name
|
|
type: string
|
|
stability: release_candidate
|
|
brief: >
|
|
The name of the operation or command being executed.
|
|
note: |
|
|
It is RECOMMENDED to capture the value as provided by the application
|
|
without attempting to do any case normalization.
|
|
|
|
The operation name SHOULD NOT be extracted from `db.query.text`,
|
|
when the database system supports query text with multiple operations
|
|
in non-batch operations.
|
|
|
|
If spaces can occur in the operation name, multiple consecutive spaces
|
|
SHOULD be normalized to a single space.
|
|
|
|
For batch operations, if the individual operations are known to have the same operation name
|
|
then that operation name SHOULD be used prepended by `BATCH `,
|
|
otherwise `db.operation.name` SHOULD be `BATCH` or some other database
|
|
system specific term if more applicable.
|
|
examples: ["findAndModify", "HMSET", "SELECT"]
|
|
- id: db.query.text
|
|
type: string
|
|
stability: release_candidate
|
|
brief: >
|
|
The database query being executed.
|
|
note: >
|
|
For sanitization see [Sanitization of `db.query.text`](/docs/database/database-spans.md#sanitization-of-dbquerytext).
|
|
|
|
For batch operations, if the individual operations are known to have the same query text
|
|
then that query text SHOULD be used, otherwise all of the individual query texts SHOULD be concatenated
|
|
with separator `; ` or some other database system specific separator if more applicable.
|
|
|
|
Parameterized query text SHOULD NOT be sanitized.
|
|
Even though parameterized query text can potentially have sensitive data, by using a parameterized query
|
|
the user is giving a strong signal that any sensitive data will be passed as parameter values, and the benefit
|
|
to observability of capturing the static part of the query text by default outweighs the risk.
|
|
examples:
|
|
[
|
|
"SELECT * FROM wuser_table where username = ?",
|
|
'SET mykey ?',
|
|
]
|
|
- id: db.query.parameter
|
|
type: template[string]
|
|
stability: development
|
|
brief: >
|
|
A database query parameter, with `<key>` being the parameter name,
|
|
and the attribute value being a string representation of the parameter value.
|
|
note: |
|
|
If a query parameter has no name and instead is referenced only by index,
|
|
then `<key>` SHOULD be the 0-based index.
|
|
|
|
`db.query.parameter.<key>` SHOULD match
|
|
up with the parameterized placeholders present in `db.query.text`.
|
|
|
|
`db.query.parameter.<key>` SHOULD NOT be captured on batch operations.
|
|
|
|
Examples:
|
|
|
|
- For a query `SELECT * FROM users where username = %s` with the parameter `"jdoe"`,
|
|
the attribute `db.query.parameter.0` SHOULD be set to `"jdoe"`.
|
|
|
|
- For a query `"SELECT * FROM users WHERE username = %(username)s;` with parameter
|
|
`username = "jdoe"`, the attribute `db.query.parameter.username` SHOULD be set to `"jdoe"`.
|
|
|
|
examples: ["someval", "55"]
|
|
- id: db.query.summary
|
|
type: string
|
|
stability: release_candidate
|
|
brief: >
|
|
Low cardinality summary of a database query.
|
|
note: |
|
|
The query summary describes a class of database queries and is useful
|
|
as a grouping key, especially when analyzing telemetry for database
|
|
calls involving complex queries.
|
|
|
|
Summary may be available to the instrumentation through
|
|
instrumentation hooks or other means. If it is not available, instrumentations
|
|
that support query parsing SHOULD generate a summary following
|
|
[Generating query summary](/docs/database/database-spans.md#generating-a-summary-of-the-query)
|
|
section.
|
|
examples:
|
|
[
|
|
'SELECT wuser_table',
|
|
'INSERT shipping_details SELECT orders',
|
|
'get user by id',
|
|
]
|
|
- id: db.stored_procedure.name
|
|
type: string
|
|
stability: release_candidate
|
|
brief: The name of a stored procedure within the database.
|
|
note: |
|
|
It is RECOMMENDED to capture the value as provided by the application
|
|
without attempting to do any case normalization.
|
|
|
|
For batch operations, if the individual operations are known to have the same
|
|
stored procedure name then that stored procedure name SHOULD be used.
|
|
examples: ["GetCustomer"]
|
|
- id: db.operation.parameter
|
|
type: template[string]
|
|
stability: development
|
|
brief: >
|
|
A database operation parameter, with `<key>` being the parameter name,
|
|
and the attribute value being a string representation of the parameter value.
|
|
note: |
|
|
For example, a client-side maximum number of rows to read from the database
|
|
MAY be recorded as the `db.operation.parameter.max_rows` attribute.
|
|
|
|
`db.query.text` parameters SHOULD be captured using `db.query.parameter.<key>`
|
|
instead of `db.operation.parameter.<key>`.
|
|
examples: ["someval", "55"]
|
|
- id: db.operation.batch.size
|
|
type: int
|
|
stability: release_candidate
|
|
brief: The number of queries included in a batch operation.
|
|
note: >
|
|
Operations are only considered batches when they contain two or more operations,
|
|
and so `db.operation.batch.size` SHOULD never be `1`.
|
|
examples: [2, 3, 4]
|
|
- id: db.response.status_code
|
|
type: string
|
|
stability: release_candidate
|
|
brief: Database response status code.
|
|
note: >
|
|
The status code returned by the database. Usually it represents an error code,
|
|
but may also represent partial success, warning, or differentiate
|
|
between various types of successful outcomes.
|
|
|
|
Semantic conventions for individual database systems SHOULD document what
|
|
`db.response.status_code` means in the context of that system.
|
|
examples: ["102", "ORA-17002", "08P01", "404"]
|
|
- id: db.response.returned_rows
|
|
type: int
|
|
stability: development
|
|
brief: Number of rows returned by the operation.
|
|
examples: [10, 30, 1000]
|
|
- id: db.system.name
|
|
brief: The database management system (DBMS) product as identified by the client instrumentation.
|
|
note: >
|
|
The actual DBMS may differ from the one identified by the client.
|
|
For example, when using PostgreSQL client libraries to connect to a CockroachDB, the `db.system.name`
|
|
is set to `postgresql` based on the instrumentation's best knowledge.
|
|
type:
|
|
members:
|
|
- id: other_sql
|
|
value: "other_sql"
|
|
brief: "Some other SQL database. Fallback only."
|
|
stability: development
|
|
- id: softwareag.adabas
|
|
value: "softwareag.adabas"
|
|
brief: "[Adabas (Adaptable Database System)](https://documentation.softwareag.com/?pf=adabas)"
|
|
stability: development
|
|
- id: actian.ingres
|
|
value: "actian.ingres"
|
|
brief: "[Actian Ingres](https://www.actian.com/databases/ingres/)"
|
|
stability: development
|
|
- id: aws.dynamodb
|
|
value: "aws.dynamodb"
|
|
brief: "[Amazon DynamoDB](https://aws.amazon.com/pm/dynamodb/)"
|
|
stability: development
|
|
- id: aws.redshift
|
|
value: "aws.redshift"
|
|
brief: "[Amazon Redshift](https://aws.amazon.com/redshift/)"
|
|
stability: development
|
|
- id: azure.cosmosdb
|
|
value: "azure.cosmosdb"
|
|
brief: "[Azure Cosmos DB](https://learn.microsoft.com/azure/cosmos-db)"
|
|
stability: development
|
|
- id: intersystems.cache
|
|
value: "intersystems.cache"
|
|
brief: "[InterSystems Caché](https://www.intersystems.com/products/cache/)"
|
|
stability: development
|
|
- id: cassandra
|
|
value: "cassandra"
|
|
brief: "[Apache Cassandra](https://cassandra.apache.org/)"
|
|
stability: development
|
|
- id: clickhouse
|
|
value: "clickhouse"
|
|
brief: "[ClickHouse](https://clickhouse.com/)"
|
|
stability: development
|
|
- id: cockroachdb
|
|
value: "cockroachdb"
|
|
brief: "[CockroachDB](https://www.cockroachlabs.com/)"
|
|
stability: development
|
|
- id: couchbase
|
|
value: "couchbase"
|
|
brief: "[Couchbase](https://www.couchbase.com/)"
|
|
stability: development
|
|
- id: couchdb
|
|
value: "couchdb"
|
|
brief: "[Apache CouchDB](https://couchdb.apache.org/)"
|
|
stability: development
|
|
- id: derby
|
|
value: "derby"
|
|
brief: "[Apache Derby](https://db.apache.org/derby/)"
|
|
stability: development
|
|
- id: elasticsearch
|
|
value: "elasticsearch"
|
|
brief: "[Elasticsearch](https://www.elastic.co/elasticsearch)"
|
|
stability: development
|
|
- id: firebirdsql
|
|
value: "firebirdsql"
|
|
brief: "[Firebird](https://www.firebirdsql.org/)"
|
|
stability: development
|
|
- id: gcp.spanner
|
|
value: "gcp.spanner"
|
|
brief: "[Google Cloud Spanner](https://cloud.google.com/spanner)"
|
|
stability: development
|
|
- id: geode
|
|
value: "geode"
|
|
brief: "[Apache Geode](https://geode.apache.org/)"
|
|
stability: development
|
|
- id: h2database
|
|
value: "h2database"
|
|
brief: "[H2 Database](https://h2database.com/)"
|
|
stability: development
|
|
- id: hbase
|
|
value: "hbase"
|
|
brief: "[Apache HBase](https://hbase.apache.org/)"
|
|
stability: development
|
|
- id: hive
|
|
value: "hive"
|
|
brief: "[Apache Hive](https://hive.apache.org/)"
|
|
stability: development
|
|
- id: hsqldb
|
|
value: "hsqldb"
|
|
brief: "[HyperSQL Database](https://hsqldb.org/)"
|
|
stability: development
|
|
- id: ibm.db2
|
|
value: "ibm.db2"
|
|
brief: "[IBM Db2](https://www.ibm.com/db2)"
|
|
stability: development
|
|
- id: ibm.informix
|
|
value: "ibm.informix"
|
|
brief: "[IBM Informix](https://www.ibm.com/products/informix)"
|
|
stability: development
|
|
- id: ibm.netezza
|
|
value: "ibm.netezza"
|
|
brief: "[IBM Netezza](https://www.ibm.com/products/netezza)"
|
|
stability: development
|
|
- id: influxdb
|
|
value: "influxdb"
|
|
brief: "[InfluxDB](https://www.influxdata.com/)"
|
|
stability: development
|
|
- id: instantdb
|
|
value: "instantdb"
|
|
brief: "[Instant](https://www.instantdb.com/)"
|
|
stability: development
|
|
- id: mariadb
|
|
value: "mariadb"
|
|
brief: "[MariaDB](https://mariadb.org/)"
|
|
stability: release_candidate
|
|
- id: memcached
|
|
value: "memcached"
|
|
brief: "[Memcached](https://memcached.org/)"
|
|
stability: development
|
|
- id: mongodb
|
|
value: "mongodb"
|
|
brief: "[MongoDB](https://www.mongodb.com/)"
|
|
stability: development
|
|
- id: microsoft.sql_server
|
|
value: "microsoft.sql_server"
|
|
brief: "[Microsoft SQL Server](https://www.microsoft.com/sql-server)"
|
|
stability: release_candidate
|
|
- id: mysql
|
|
value: "mysql"
|
|
brief: "[MySQL](https://www.mysql.com/)"
|
|
stability: release_candidate
|
|
- id: neo4j
|
|
value: "neo4j"
|
|
brief: "[Neo4j](https://neo4j.com/)"
|
|
stability: development
|
|
- id: opensearch
|
|
value: "opensearch"
|
|
brief: "[OpenSearch](https://opensearch.org/)"
|
|
stability: development
|
|
- id: oracle.db
|
|
value: "oracle.db"
|
|
brief: "[Oracle Database](https://www.oracle.com/database/)"
|
|
stability: development
|
|
- id: postgresql
|
|
value: "postgresql"
|
|
brief: "[PostgreSQL](https://www.postgresql.org/)"
|
|
stability: release_candidate
|
|
- id: redis
|
|
value: "redis"
|
|
brief: "[Redis](https://redis.io/)"
|
|
stability: development
|
|
- id: sap.hana
|
|
value: "sap.hana"
|
|
brief: "[SAP HANA](https://www.sap.com/products/technology-platform/hana/what-is-sap-hana.html)"
|
|
stability: development
|
|
- id: sap.maxdb
|
|
value: "sap.maxdb"
|
|
brief: "[SAP MaxDB](https://maxdb.sap.com/)"
|
|
stability: development
|
|
- id: sqlite
|
|
value: "sqlite"
|
|
brief: "[SQLite](https://www.sqlite.org/)"
|
|
stability: development
|
|
- id: teradata
|
|
value: "teradata"
|
|
brief: "[Teradata](https://www.teradata.com/)"
|
|
stability: development
|
|
- id: trino
|
|
value: "trino"
|
|
brief: "[Trino](https://trino.io/)"
|
|
stability: development
|
|
stability: release_candidate
|
|
- id: db.client.connection.state
|
|
stability: development
|
|
type:
|
|
members:
|
|
- id: idle
|
|
value: "idle"
|
|
stability: development
|
|
- id: used
|
|
value: "used"
|
|
stability: development
|
|
brief: "The state of a connection in the pool"
|
|
examples: ["idle"]
|
|
- id: db.client.connection.pool.name
|
|
type: string
|
|
stability: development
|
|
brief: >
|
|
The name of the connection pool; unique within the instrumented application.
|
|
In case the connection pool implementation doesn't provide a name,
|
|
instrumentation SHOULD use a combination of parameters that would make the name
|
|
unique, for example, combining attributes `server.address`, `server.port`,
|
|
and `db.namespace`, formatted as `server.address:server.port/db.namespace`.
|
|
Instrumentations that generate connection pool name following different patterns
|
|
SHOULD document it.
|
|
examples: ["myDataSource"]
|