From 4dfa80db19d78ba21db83ca4f43e7f6a1944c058 Mon Sep 17 00:00:00 2001 From: Yusuke Tsutsumi Date: Sat, 9 May 2020 20:35:48 -0700 Subject: [PATCH] Moving span operation clarification to api Feedback states that the clarification around the meaning of the span start and end times could be more generic. Starting a proposal around by adding an example to the API. --- specification/trace/api.md | 16 +++++++++++++++- specification/trace/semantic_conventions/http.md | 12 ------------ 2 files changed, 15 insertions(+), 13 deletions(-) diff --git a/specification/trace/api.md b/specification/trace/api.md index c55143973e0..cbdc88ec233 100644 --- a/specification/trace/api.md +++ b/specification/trace/api.md @@ -225,7 +225,21 @@ hypothetical account information: | `get_account/{accountId}` | Also good (using the "HTTP route") | The `Span`'s start and end timestamps reflect the elapsed real time of the -operation. A `Span`'s start time SHOULD be set to the current time on [span +operation. + +For example, an http server span should start right when the request has begun being handled by the server, and end when the response has been completely sent. +This would include the following, if they are present in that particular +request-response cycle: + +- receiving the HTTP request +- parsing of the HTTP request +- parsing of the body of the HTTP request +- any web server middleware that is applied +- business logic +- construction of the HTTP response +- sending of the HTTP response + +A `Span`'s start time SHOULD be set to the current time on [span creation](#span-creation). After the `Span` is created, it SHOULD be possible to change the its name, set its `Attribute`s, and add `Link`s and `Event`s. These MUST NOT be changed after the `Span`'s end time has been set. diff --git a/specification/trace/semantic_conventions/http.md b/specification/trace/semantic_conventions/http.md index 155e41ebd8d..2aa4e1063d7 100644 --- a/specification/trace/semantic_conventions/http.md +++ b/specification/trace/semantic_conventions/http.md @@ -96,12 +96,6 @@ For an HTTP client span, `SpanKind` MUST be `Client`. If set, `http.url` must be the originally requested URL, before any HTTP-redirects that may happen when executing the request. -The span start time SHOULD be as close as possible to the time the client began -the request. - -The span end time SHOULD be as close as possible to the time the client finished -receiving the response to the request. - One of the following sets of attributes is required (in order of usual preference unless for a particular web client/framework it is known that some other set is preferable for some reason; all strings must be non-empty): * `http.url` @@ -187,12 +181,6 @@ If the route does not include the application root, it SHOULD be prepended to th If the route cannot be determined, the `name` attribute MUST be set as defined in the general semantic conventions for HTTP. -The span start time SHOULD be as close as possible to the time the server began -handling the request. - -The span end time SHOULD be as close as possible to the time the server completed -the response. - | Attribute name | Notes and examples | Required? | | :------------- | :----------------------------------------------------------- | --------- | | `http.server_name` | The primary server name of the matched virtual host. This should be obtained via configuration. If no such configuration can be obtained, this attribute MUST NOT be set ( `net.host.name` should be used instead). | [1] |