Add typed spans working document (open-telemetry#14)

* Add typed spans working document

* Restructuring and scoping

- Added motivation
- Provided a broader scope and less implementation details, like naming or mandatory fields
- Removed tables

work_in_progress/typedspans/README.md

@@ -0,0 +1,180 @@
+
+# Typed Spans (Draft Proposal)
+
+In OpenCensus and OpenTracing spans can be created freely and it’s up to the
+implementor to annotate them with attributes specific to the represented operation.
+This document proposes to add type information to spans and to define and reserve
+mandatory and optional attributes depending on the span type.
+
+## Motivation
+
+Spans represent specific operations in and between systems.
+
+Examples for such operations are
+
+- Local operations like method invocations
+- HTTP requests (inbound and outbound)
+- Database operations
+- Queue/Message publish and consume
+- gRPC calls
+- Generic RPC operations
+
+Depending on the type of an operation, additional information is needed to
+represent and analyze a span correctly in monitoring systems.
+
+While both OpenCensus and OpenTracing define conventions that define some reserved
+attributes that can be used to add operation-specific information, there is no
+mechanism to specify the type of an operation and to ensure that all needed
+attributes are set.
+
+### Proposed types
+
+Below is a list of types and attributes per type.
+This document does not include the final naming of attributes and types.
+It is assumed that there will be naming conventions that will be applied eventually.
+
+There is also no distinction between mandatory and optional attributes as it is assumed
+that there will be a dedicated discussion and document for each type linked in this document.
+
+See [this document by @discostu105](https://docs.google.com/spreadsheets/d/1H0S0BROOgX7zndWF_WL8jb9IW1PN7j3IeryekhX5sKU/edit#gid=0) for type and attribute mappings that exist in OpenCensus and OpenTracing today.
+
+#### HTTP Client
+Represents an outbound HTTP request.
+
+##### Attributes
+
+- Method
+- Host
+- Path
+- Status Code
+- Route
+- User Agent
+- Parameters
+- Request Headers
+- Response Headers
+
+#### HTTP Server
+Represents an inbound HTTP request.
+
+##### Attributes
+- Method
+- Host
+- Path
+- Status Code
+- Route
+- User Agent
+- Webserver Name
+- Remote Address
+- Parameters
+- Request Headers
+- Response Headers
+
+
+#### Database Client
+Represents a database call.
+
+##### Attributes
+- Database Name
+- Database Vendor
+- Database Type
+- Database User
+- Endpoint
+- Statement
+- Channel Type (e.g. TCP)
+- Rows Returned
+- Roundtrips
+
+#### gRPC Client
+Represents an outbound gRPC request.
+
+##### Attributes
+- Service Endpoint
+- Channel Type (e.g. TCP)
+- Channel Endpoint
+- Service Name
+- Service Method
+
+
+#### gRPC Server
+Represents an inbound gRPC request.
+
+##### Detail Document
+https://github.com/open-telemetry/opentelemetry-specification/blob/master/work_in_progress/gRPC/gRPC.md
+
+##### Attributes
+- Message Id
+- Message Compressed Size
+- Message Uncompressed Size
+
+#### gRPC Client
+Represents an inbound gRPC request.
+
+##### Detail Document
+https://github.com/open-telemetry/opentelemetry-specification/blob/master/work_in_progress/gRPC/gRPC.md
+
+##### Attributes
+- Message Id
+- Message Compressed Size
+- Message Uncompressed Size
+
+#### Remoting Client
+Represents an outbound RPC request.
+
+##### Attributes
+- Service Endpoint
+- Channel Type (e.g. TCP)
+- Channel Endpoint
+- Service Name
+- Service Method
+
+
+#### Remoting Server
+Represents an inbound RPC request.
+
+##### Attributes
+- Service Method
+- Service Name
+- Service Endpoint
+- Protocol Name
+
+
+#### Messaging Consumer
+Represents an inbound message.
+
+##### Attributes
+- Vendor Name
+- Destination Name
+- Destination Type
+- Channel Type
+- Channel Endpoint
+- Operation Type
+- Message Id
+- Correlation Id
+
+#### Messaging Producer
+Represents an outbound message.
+
+##### Attributes
+- Vendor Name
+- Destination Name
+- Channel Type
+- Channel Endpoint
+- Message Id
+- Correlation Id
+
+## Proposal
+* Add a field `CanonicalType` that contains the type of span
+* Define mandatory and optional attributes per span type
+* Provide an API that supports creating typed spans and ensures that at least all
+  mandatory attributes for this `CanonicalType` are present
+
+## Challenges and Objections
+- Some mandatory attributes for a given type may not be available at the time of creation
+
+### POC
+Here is [a POC for HTTP Client Spans for Node.js and OpenCensus](https://github.com/danielkhan/opencensus-node-typed-span-sample)
+
+## Action Items
+- Define all types
+- Agree on type and attribute naming conventions
+- Specify each type and agree on mandatory and optional attributes per type