database moved to the main spec (open-telemetry#19)

* database moved to the main spec

* added required column and addressed few comments

* addressed feedback about host name consistency in examples

* Update semantic-conventions.md

Co-Authored-By: Daniel Khan <[email protected]>

* Update work_in_progress/typedspans/README.md

Co-Authored-By: Daniel Khan <[email protected]>

* Update semantic-conventions.md

Co-Authored-By: Daniel Khan <[email protected]>

* Update semantic-conventions.md

Co-Authored-By: Daniel Khan <[email protected]>

* Update semantic-conventions.md

Co-Authored-By: Daniel Khan <[email protected]>

* Update semantic-conventions.md

Co-Authored-By: Daniel Khan <[email protected]>

semantic-conventions.md

@@ -1 +1,49 @@
 # Semantic Conventions
+
+This document defines reserved attributes that can be used to add operation and
+protocol specific information.
+
+In OpenTelemetry spans can be created freely and it’s up to the implementor to
+annotate them with attributes specific to the represented operation. Spans
+represent specific operations in and between systems. Some of these operations
+represent calls that use well-known protocols like HTTP or database calls.
+Depending on the protocol and the type of operation, additional information
+is needed to represent and analyze a span correctly in monitoring systems. It is
+also important to unify how this attribution is made in different languages.
+This way, the operator will not need to learn specifics of a language and
+telemetry collected from multi-language micro-service can still be easily
+correlated and cross-analyzed.
+
+## Databases client calls
+
+For database client call the `SpanKind` MUST be `Client`.
+
+Span `name` should be set to low cardinality value representing the statement
+executed on the database. It may be stored procedure name (without argument), sql
+statement without variable arguments, etc. When it's impossible to get any
+meaningful representation of the span `name`, it can be populated using the same
+value as `db.instance`.
+
+Note, Redis, Cassandra, HBase and other storage systems may reuse the same
+attribute names.
+
+| Attribute name | Notes and examples                                           | Required? |
+| :------------- | :----------------------------------------------------------- | --------- |
+| `component`    | Database driver name or database name (when known) `JDBI`, `jdbc`, `odbc`, `postgreSQL`. | Yes       |
+| `db.type`      | Database type. For any SQL database, `"sql"`. For others, the lower-case database category, e.g. `"cassandra"`, `"hbase"`, or `"redis"`. | Yes       |
+| `db.instance`  | Database instance name. E.g., In java, if the jdbc.url=`"jdbc:mysql://db.example.com:3306/customers"`, the instance name is `"customers"`. | Yes       |
+| `db.statement` | A database statement for the given database type. Note, that the value may be sanitized to exclude sensitive information. E.g., for `db.type="sql"`, `"SELECT * FROM wuser_table"`; for `db.type="redis"`, `"SET mykey 'WuValue'"`. | Yes       |
+| `db.user`      | Username for accessing database. E.g., `"readonly_user"` or `"reporting_user"` | No        |
+
+For database client calls, peer information can be populated and interpreted as
+follows:
+
+| Attribute name  | Notes and examples                                           | Required |
+| :-------------- | :----------------------------------------------------------- | -------- |
+| `peer.address`  | JDBC substring like `"mysql://db.example.com:3306"`          | Yes      |
+| `peer.hostname` | Remote hostname. `db.example.com`                            | Yes      |
+| `peer.ipv4`     | Remote IPv4 address as a `.`-separated tuple. E.g., `"127.0.0.1"` | No       |
+| `peer.ipv6`     | Remote IPv6 address as a string of colon-separated 4-char hex tuples. E.g., `"2001:0db8:85a3:0000:0000:8a2e:0370:7334"` | No       |
+| `peer.port`     | Remote port. E.g., `80` (integer)                            | No       |
+| `peer.service`  | Remote service name. Can be database friendly name or `db.instance` | No       |
+

work_in_progress/typedspans/README.md

@@ -69,20 +69,17 @@ Represents an inbound HTTP request.
 - Request Headers
 - Response Headers
 
-
 #### Database Client
 Represents a database call.
 
 ##### Attributes
-- Database Name
-- Database Vendor
-- Database Type
-- Database User
-- Endpoint
-- Statement
+
+These attributes are not covered in the [main spec](../semantic-conventions.md):
+
 - Channel Type (e.g. TCP)
 - Rows Returned
 - Roundtrips
+- Arguments of db.statement
 
 #### gRPC Client
 Represents an outbound gRPC request.
@@ -177,4 +174,4 @@ Here is [a POC for HTTP Client Spans for Node.js and OpenCensus](https://github.
 ## Action Items
 - Define all types
 - Agree on type and attribute naming conventions
-- Specify each type and agree on mandatory and optional attributes per type
+- Specify each type and agree on mandatory and optional attributes per type