Move http to main spec (#82)

* Moved HTTP Client to semantic conventions * Moved HTTP server * Update semantic-conventions.md Co-Authored-By: Sergey Kanzhelev <[email protected]> * Simplified attribute names. * Added note on using lower cardinality names if a framework can infer them. * Update semantic-conventions.md Co-Authored-By: Sergey Kanzhelev <[email protected]> * Cahnge status to status_code * Add component * Update semantic-conventions.md Co-Authored-By: Sergey Kanzhelev <[email protected]> * Added optional status_text attribute * Removed attributes covered in the main spec from OC and OT work in progress files.
open-telemetry · Jun 13, 2019 · 4ac49aa · 4ac49aa
1 parent b696ecc
commit 4ac49aa
Show file tree

Hide file tree

Showing 4 changed files with 54 additions and 18 deletions.
diff --git a/semantic-conventions.md b/semantic-conventions.md
@@ -14,6 +14,50 @@ 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.
 
+## HTTP client
+
+This span type represents an outbound HTTP request.
+
+For a HTTP client span, `SpanKind` MUST be `Client`.
+
+Given an [RFC 3986](https://www.ietf.org/rfc/rfc3986.txt) compliant URI of the form
+`scheme:[//authority]path[?query][#fragment]`, the span name of the span SHOULD
+be set to to the URI path value.
+
+If a framework can identify a value that represents the identity of the request
+and has a lower cardinality than the URI path, this value MUST be used for the span name instead.
+
+| Attribute name | Notes and examples                                           | Required? |
+| :------------- | :----------------------------------------------------------- | --------- |
+| `component`    | Denotes the type of the span and needs to be `http`. | Yes |
+| `http.method` | HTTP request method. E.g. `"GET"`. | Yes |
+| `http.url` | HTTP host. E.g. `"https://example.com:779/users/187a34"`. | Yes |
+| `http.status_code` | [HTTP response status code](https://tools.ietf.org/html/rfc7231). E.g. `200` | No |
+| `http.status_text` | [HTTP reason phrase](https://www.ietf.org/rfc/rfc2616.txt). E.g. `OK` | No |
+
+## HTTP server
+
+This span type represents an inbound HTTP request.
+
+For a HTTP server span, `SpanKind` MUST be `Server`.
+
+Given an inbound request for a route (e.g. `"/users/:userID?"` the `name`
+attribute of the span SHOULD be set to this route.
+
+If the route can not be determined, the `name` attribute MUST be set to the [RFC 3986 URI](https://www.ietf.org/rfc/rfc3986.txt) path value.
+
+If a framework can identify a value that represents the identity of the request
+and has a lower cardinality than the URI path or route, this value MUST be used for the span name instead.
+
+| Attribute name | Notes and examples                                           | Required? |
+| :------------- | :----------------------------------------------------------- | --------- |
+| `component`    | Denotes the type of the span and needs to be `http`. | Yes |
+| `http.method` | HTTP request method. E.g. `"GET"`. | Yes |
+| `http.url` | HTTP host. E.g. `"https://example.com:779/users/187a34"`. | Yes |
+| `http.route` | The matched route. E.g. `"/users/:userID?"`. | No |
+| `http.status_code` | [HTTP response status code](https://tools.ietf.org/html/rfc7231). E.g. `200` | No |
+| `http.status_text` | [HTTP reason phrase](https://www.ietf.org/rfc/rfc2616.txt). E.g. `OK` | No |
+
 ## Databases client calls
 
 For database client call the `SpanKind` MUST be `Client`.

diff --git a/work_in_progress/opencensus/HTTP.md b/work_in_progress/opencensus/HTTP.md
@@ -113,15 +113,14 @@ request represents the incoming request. For a client, request represents the ou
 All attributes are optional, but collector should make the best effort to
 collect those.
 
+> Work in progress! Please note, that the list below only contains attributes that aren't contained in the [OpenTelemetry main spec](../semantic-conventions.md) (yet):
+
 | Attribute name            | Description                 | Type   |Example value              |
 |---------------------------|-----------------------------|--------|---------------------------|
 | "http.host"               | Request URL host            | string | `example.com:779`         |
-| "http.method"             | Request URL method          | string | `GET`                     |
 | "http.path"               | Request URL path. If empty - set to `/` | `/users/25f4c31d`  |
-| "http.route"              | Matched request URL route   | string | `/users/:userID`          |
-| "http.user_agent"         | Request user-agent. Do not inject attribute if user-agent is empty. | string | `HTTPClient/1.2` |
-| "http.status_code"        | Response status code        | int64  | `200`                     |
-| "http.url"                | Absolute request URL        | string | `https://example.com:779/path/12314/?q=ddds#123` |
+| "http.user_agent"         | Request user-agent. Do not inject attribute if user-agent is empty. | string | `HTTPClient/1.2` |               |
+
 
 Exporters should always export the collected attributes. Exporters should map the collected
 attributes to backend's known attributes/labels.

diff --git a/work_in_progress/opentracing/semantic_conventions.md b/work_in_progress/opentracing/semantic_conventions.md
@@ -14,12 +14,10 @@ Changes to this file affect the OpenTracing specification version. Additions sho
 
 Span tags apply to **the entire Span**; as such, they apply to the entire timerange of the Span, not a particular moment with a particular timestamp: those sorts of events are best modelled as Span log fields (per the table in the next subsection of this document).
 
+> Work in progress! Please note, that the list below only contains attributes that aren't contained in the [OpenTelemetry main spec](../semantic-conventions.md) (yet):
+
 | Span tag name | Type | Notes and examples |
 |:--------------|:-----|:-------------------|
-| `component` | string  | The software package, framework, library, or module that generated the associated Span. E.g., `"grpc"`, `"django"`, `"JDBI"`. |
-| `http.method` | string | HTTP method of the request for the associated Span. E.g., `"GET"`, `"POST"` |
-| `http.status_code` | integer | HTTP response status code for the associated Span. E.g., 200, 503, 404 |
-| `http.url` | string | URL of the request being handled in this segment of the trace, in standard URI format. E.g., `"https://domain.net/path/to?resource=here"` |
 | `message_bus.destination` | string | An address at which messages can be exchanged. E.g. A Kafka record has an associated `"topic name"` that can be extracted by the instrumented producer or consumer and stored using this tag. |
 | `peer.address` | string | Remote "address", suitable for use in a networking client library. This may be a `"ip:port"`, a bare `"hostname"`, a FQDN or various connection strings |
 | `peer.hostname` | string | Remote hostname. E.g., `"opentracing.io"`, `"internal.dns.name"` |

diff --git a/work_in_progress/typedspans/README.md b/work_in_progress/typedspans/README.md
@@ -42,11 +42,8 @@ See [this document by @discostu105](https://docs.google.com/spreadsheets/d/1H0S0
 Represents an outbound HTTP request.
 
 ##### Attributes
+These attributes are not covered in the [main spec](../semantic-conventions.md):
 
-- Method
-- Host
-- Path
-- Status Code
 - Route
 - User Agent
 - Parameters
@@ -57,11 +54,9 @@ Represents an outbound HTTP request.
 Represents an inbound HTTP request.
 
 ##### Attributes
-- Method
-- Host
-- Path
-- Status Code
-- Route
+
+These attributes are not covered in the [main spec](../semantic-conventions.md):
+
 - User Agent
 - Webserver Name
 - Remote Address