Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add yaml semantic conventions for Database #928

Merged
merged 2 commits into from
Sep 11, 2020
Merged

Add yaml semantic conventions for Database #928

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
d36c45b
Add yaml semantic conventions for Database
thisthat Sep 7, 2020
5efc3c2
Address feedback
thisthat Sep 11, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
303 changes: 303 additions & 0 deletions semantic_conventions/trace/database.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,303 @@
groups:
- id: db
prefix: db
brief: >
This document defines the attributes used to perform database client calls.
span_kind: client
attributes:
- id: system
tag: connection-level
brief: An identifier for the database management system (DBMS) product being used. See below for a list of well-known identifiers.
required: always
type:
allow_custom_values: true
members:
- id: other_sql
value: 'other_sql'
brief: 'Some other SQL database. Fallback only. See notes.'
- id: mssql
value: 'mssql'
brief: 'Microsoft SQL Server'
- id: mysql
value: 'mysql'
brief: 'MySQL'
- id: oracle
value: 'oracle'
brief: 'Oracle Database'
- id: db2
value: 'db2'
brief: 'IBM Db2'
- id: postgresql
value: 'postgresql'
brief: 'PostgreSQL'
- id: redshift
value: 'redshift'
brief: 'Amazon Redshift'
- id: hive
value: 'hive'
brief: 'Apache Hive'
- id: cloudscape
value: 'cloudscape'
brief: 'Cloudscape'
- id: hsqlsb
value: 'hsqlsb'
brief: 'HyperSQL DataBase'
- id: progress
value: 'progress'
brief: 'Progress Database'
- id: maxdb
value: 'maxdb'
brief: 'SAP MaxDB'
- id: hanadb
value: 'hanadb'
brief: 'SAP HANA'
- id: ingres
value: 'ingres'
brief: 'Ingres'
- id: firstsql
value: 'firstsql'
brief: 'FirstSQL'
- id: edb
value: 'edb'
brief: 'EnterpriseDB'
- id: cache
value: 'cache'
brief: 'InterSystems Caché'
- id: adabas
value: 'adabas'
brief: 'Adabas (Adaptable Database System)'
- id: firebird
value: 'firebird'
brief: 'Firebird'
- id: derby
value: 'derby'
brief: 'Apache Derby'
- id: filemaker
value: 'filemaker'
brief: 'FileMaker'
- id: informix
value: 'informix'
brief: 'Informix'
- id: instantdb
value: 'instantdb'
brief: 'InstantDB'
- id: interbase
value: 'interbase'
brief: 'InterBase'
- id: mariadb
value: 'mariadb'
brief: 'MariaDB'
- id: netezza
value: 'netezza'
brief: 'Netezza'
- id: pervasive
value: 'pervasive'
brief: 'Pervasive PSQL'
- id: pointbase
value: 'pointbase'
brief: 'PointBase'
- id: sqlite
value: 'sqlite'
brief: 'SQLite'
- id: sybase
value: 'sybase'
brief: 'Sybase'
- id: teradata
value: 'teradata'
brief: 'Teradata'
- id: vertica
value: 'vertica'
brief: 'Vertica'
- id: h2
value: 'h2'
brief: 'H2'
- id: coldfusion
value: 'coldfusion'
brief: 'ColdFusion IMQ'
- id: cassandra
value: 'cassandra'
brief: 'Apache Cassandra'
- id: hbase
value: 'hbase'
brief: 'Apache HBase'
- id: mongodb
value: 'mongodb'
brief: 'MongoDB'
- id: redis
value: 'redis'
brief: 'Redis'
- id: couchbase
value: 'couchbase'
brief: 'Couchbase'
- id: couchdb
value: 'couchdb'
brief: 'CouchDB'
- id: cosmosdb
value: 'cosmosdb'
brief: 'Microsoft Azure Cosmos DB'
- id: dynamodb
value: 'dynamodb'
brief: 'Amazon DynamoDB'
- id: neo4j
value: 'neo4j'
brief: 'Neo4j'
- id: connection_string
tag: connection-level
type: string
brief: >
The connection string used to connect to the database.
note: It is recommended to remove embedded credentials.
thisthat marked this conversation as resolved.
Show resolved Hide resolved
examples: 'Server=(localdb)\v11.0;Integrated Security=true;'
- id: user
tag: connection-level
type: string
brief: >
Username for accessing the database.
examples: ['readonly_user', 'reporting_user']
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It is not completely obvious in the resulting markdown that these are 2 distinct examples. It was clear in the original markdown. Perhaps remove one of the examples to avoid confusion.

- id: jdbc.driver_classname
tag: connection-level-tech-specific
type: string
brief: >
The fully-qualified class name of the [Java Database Connectivity (JDBC)](https://docs.oracle.com/javase/8/docs/technotes/guides/jdbc/) driver used to connect.
examples: ['org.postgresql.Driver', 'com.microsoft.sqlserver.jdbc.SQLServerDriver']
- id: name
tag: call-level
type: string
required:
conditional: >
Required, if applicable and no more-specific attribute is defined.
brief: >
If no [tech-specific attribute](#call-level-attributes-for-specific-technologies)
is defined, this attribute is used to report the name of the database being accessed.
For commands that switch the database, this should be set to the target database
(even if the command fails).
note: >
In some SQL databases, the database name to be used is called "schema name".
examples: [ 'customers', 'main' ]
- id: statement
tag: call-level
type: string
required:
conditional: >
Required if applicable.
brief: >
The database statement being executed.
note: The value may be sanitized to exclude sensitive information.
examples: ['SELECT * FROM wuser_table', 'SET mykey "WuValue"']
- id: operation
tag: call-level
type: string
required:
conditional: Required, if `db.statement` is not applicable.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

would be cool to be able to use attribute reference in descriptions as well =)

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, also for generated Javadoc, etc. But that's a rather complex feature as we would need to parse the markdown in the tool then.

brief: >
The name of the operation being executed, e.g. the [MongoDB command name](https://docs.mongodb.com/manual/reference/command/#database-operations)
such as `findAndModify`.
note: >
While it would semantically make sense to set this, e.g., to a SQL keyword like `SELECT` or `INSERT`,
it is not recommended to attempt any client-side parsing of `db.statement` just to get this property
(the back end can do that if required).
examples: ['findAndModify', 'HMSET']
- ref: net.peer.name
tag: connection-level
required:
conditional: See below.
- ref: net.peer.ip
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Being able to reference other attributes is very nice!

tag: connection-level
required:
conditional: See below.
- ref: net.peer.port
tag: connection-level
required:
conditional: Required if using a port other than the default port for this DBMS.
- ref: net.transport
tag: connection-level
required:
conditional: Recommended in general, required for in-process databases (`"inproc"`).
constraints:
- any_of:
- 'net.peer.name'
- 'net.peer.ip'

- id: db.mssql
prefix: db.mssql
extends: db
brief: >
Connection-level attributes for Microsoft SQL Server
attributes:
- id: instance_name
tag: connection-level-tech-specific
type: string
note: >
If setting a `db.mssql.instance_name`, `net.peer.port` is no longer
required (but still recommended if non-standard).
brief: >
The Microsoft SQL Server [instance name](https://docs.microsoft.com/en-us/sql/connect/jdbc/building-the-connection-url?view=sql-server-ver15)
connecting to. This name is used to determine the port of a named instance.
examples: 'MSSQLSERVER'

- id: db.cassandra
prefix: db.cassandra
extends: db
brief: >
Call-level attributes for Cassandra
attributes:
- id: keyspace
type: string
required: always
tag: call-level-tech-specific
brief: >
The name of the keyspace being accessed. To be used instead of the generic `db.name` attribute.
examples: 'mykeyspace'

- id: db.hbase
prefix: db.hbase
extends: db
brief: >
Call-level attributes for Apache HBase
attributes:
- id: namespace
type: string
required: always
tag: call-level-tech-specific
brief: >
The [HBase namespace](https://hbase.apache.org/book.html#_namespace) being accessed.
To be used instead of the generic `db.name` attribute.
examples: 'default'

- id: db.redis
prefix: db.redis
extends: db
brief: >
Call-level attributes for Redis
attributes:
- id: database_index
type: number
required:
conditional: Required, if other than the default database (`0`).
tag: call-level-tech-specific
brief: >
The index of the database being accessed as used in the [`SELECT` command](https://redis.io/commands/select), provided as an integer.
To be used instead of the generic `db.name` attribute.
examples: [0, 1, 15]

- id: db.mongodb
prefix: db.mongodb
extends: db
brief: >
Call-level attributes for MongoDB
attributes:
- id: collection
type: string
required: always
tag: call-level-tech-specific
brief: >
The collection being accessed within the database stated in `db.name`.
examples: [ 'customers', 'products' ]

- id: db.tech
brief: "Semantic convention group for specific technologies"
constraints:
- include: 'db.cassandra'
- include: 'db.hbase'
- include: 'db.redis'
- include: 'db.mongodb'
thisthat marked this conversation as resolved.
Show resolved Hide resolved
Loading