From 4ac49aa1e86633887f49ab1f58221b78b4888e24 Mon Sep 17 00:00:00 2001 From: Daniel Khan Date: Thu, 13 Jun 2019 08:35:40 +0200 Subject: [PATCH] Move http to main spec (#82) * Moved HTTP Client to semantic conventions * Moved HTTP server * Update semantic-conventions.md Co-Authored-By: Sergey Kanzhelev * 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 * Cahnge status to status_code * Add component * Update semantic-conventions.md Co-Authored-By: Sergey Kanzhelev * Added optional status_text attribute * Removed attributes covered in the main spec from OC and OT work in progress files. --- semantic-conventions.md | 44 +++++++++++++++++++ work_in_progress/opencensus/HTTP.md | 9 ++-- .../opentracing/semantic_conventions.md | 6 +-- work_in_progress/typedspans/README.md | 13 ++---- 4 files changed, 54 insertions(+), 18 deletions(-) diff --git a/semantic-conventions.md b/semantic-conventions.md index a212c32ebab..a6931a17290 100644 --- 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 index a2fd7e35fc7..c9378fde630 100644 --- 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 index d563dbba77a..11cd3ce17a3 100644 --- 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 index 8aa184cb8e1..ec94d09e019 100644 --- 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