From 34eb0ba63e10a8e598c08e7c3aafc4c128c0125e Mon Sep 17 00:00:00 2001 From: gfuller Date: Thu, 16 Jul 2020 11:09:03 -0700 Subject: [PATCH 01/20] add http metric label spec --- .../semantic_conventions/http-metrics.md | 42 +++++++++++++++++++ 1 file changed, 42 insertions(+) create mode 100644 specification/metrics/semantic_conventions/http-metrics.md diff --git a/specification/metrics/semantic_conventions/http-metrics.md b/specification/metrics/semantic_conventions/http-metrics.md new file mode 100644 index 00000000000..36290ef6259 --- /dev/null +++ b/specification/metrics/semantic_conventions/http-metrics.md @@ -0,0 +1,42 @@ +# General + +The conventions described in this section are http specific. + +**Discaimer:** These are initial http labels but more may be added in the future. + +## Summarizing http labels + +### Justification + +Http calls are generally fully described by Spans. By adding http labels +to metrics it allows for finely tuned aggregation on those metrics. + +### Convention + +Labels applied to these metric recordings should follow the http attribute semantic +conventions of the spans from which they are derived, see +[http common attributes](../../trace/semantic_conventions/http.md#common-attributes). +To avoid high cardinality the following attributes should not be included as labels +on http metrics: + +`http.user_agent` + +`http.request_content_length` + +`http.request_content_length_uncompressed` + +`http.response_content_length` + +`http.response_content_length_uncompressed` + + + +To avoid high cardinality the following attributes should be altered: + +`http.url`: parameterized urls can lead to high cardinality which is why urls should +follow the same convention as +[http span names](../../trace/semantic_conventions/http.md#name). + +`http.target`: Similar to `http.url`, parameterized targets can lead to high +cardinality which is why urls should follow the same convention as +[http span names](../../trace/semantic_conventions/http.md#name). \ No newline at end of file From 18a3e67e6f6e5c2d8c2f3b901122dfe6cdfee0cf Mon Sep 17 00:00:00 2001 From: gfuller Date: Thu, 16 Jul 2020 13:15:12 -0700 Subject: [PATCH 02/20] typo --- specification/metrics/semantic_conventions/http-metrics.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/metrics/semantic_conventions/http-metrics.md b/specification/metrics/semantic_conventions/http-metrics.md index 36290ef6259..29a1581ab3e 100644 --- a/specification/metrics/semantic_conventions/http-metrics.md +++ b/specification/metrics/semantic_conventions/http-metrics.md @@ -38,5 +38,5 @@ follow the same convention as [http span names](../../trace/semantic_conventions/http.md#name). `http.target`: Similar to `http.url`, parameterized targets can lead to high -cardinality which is why urls should follow the same convention as +cardinality which is why targets should follow the same convention as [http span names](../../trace/semantic_conventions/http.md#name). \ No newline at end of file From 028d345e599cf2f8329038cd535b7375ce4e2cc5 Mon Sep 17 00:00:00 2001 From: gfuller Date: Tue, 21 Jul 2020 10:18:49 -0700 Subject: [PATCH 03/20] update attribute locations and clarify which to inlcude, alter and exclude --- .../semantic_conventions/http-metrics.md | 48 +++++++++++++------ 1 file changed, 33 insertions(+), 15 deletions(-) diff --git a/specification/metrics/semantic_conventions/http-metrics.md b/specification/metrics/semantic_conventions/http-metrics.md index 29a1581ab3e..3f2b2b3f837 100644 --- a/specification/metrics/semantic_conventions/http-metrics.md +++ b/specification/metrics/semantic_conventions/http-metrics.md @@ -13,30 +13,48 @@ to metrics it allows for finely tuned aggregation on those metrics. ### Convention +### Labels + Labels applied to these metric recordings should follow the http attribute semantic conventions of the spans from which they are derived, see [http common attributes](../../trace/semantic_conventions/http.md#common-attributes). -To avoid high cardinality the following attributes should not be included as labels -on http metrics: - -`http.user_agent` -`http.request_content_length` +#### Included labels -`http.request_content_length_uncompressed` +Below is a table of the attributes that **should** be included as labels +and whether they should be on server, client, or both http metrics: -`http.response_content_length` +| Attribute name | Span kind| Notes | +|-------------------|----------|-------| +| `http.method` | Both || +| `http.host` | Both || +| `http.scheme` | Both || +| `http.status_code`| Both || +| `http.status_text`| Both || +| `http.flavor` | Both || +| `net.peer.name` | Client | see [http client attributes](../../trace/semantic_conventions/http.md#http-client) for details on when to use this over `http.host` and `net.peer.ip`| +| `net.peer.port` | Client |see [http client attributes](../../trace/semantic_conventions/http.md#http-client) for details on when to use this over `http.host`| +| `net.peer.ip` | Client |see [http client attributes](../../trace/semantic_conventions/http.md#http-client) for details on when to use this over `http.host`| +| `http.server_name`| Server || +| `http.route` | Server || -`http.response_content_length_uncompressed` +#### Altered labels +To avoid high cardinality the following attributes should be altered: +| Attribute name | Span kind| Alteration | Notes| +|-------------------|----------|------------|------| +|`http.url` | Both | Parameterized urls should follow the same convention as [http span names](../../trace/semantic_conventions/http.md#name)| See [http server semantic conventions](../../trace/semantic_conventions/http.md#http-server-semantic-conventions) for details on when to use alternate attributes on server http metrics| +|`http.target` | Both | Parameterized targets should follow the same convention as [http span names](../../trace/semantic_conventions/http.md#name)|| -To avoid high cardinality the following attributes should be altered: + #### Excluded labels -`http.url`: parameterized urls can lead to high cardinality which is why urls should -follow the same convention as -[http span names](../../trace/semantic_conventions/http.md#name). + To avoid high cardinality some attributes **should not** be included as labels + on http metrics. Below is a list of them: -`http.target`: Similar to `http.url`, parameterized targets can lead to high -cardinality which is why targets should follow the same convention as -[http span names](../../trace/semantic_conventions/http.md#name). \ No newline at end of file + http.user_agent + http.request_content_length + http.request_content_length_uncompressed + http.response_content_length + http.response_content_length_uncompressed + http.client_ip From 6f0e55d10d34ec08d3e1452bc06c6a7ba7006483 Mon Sep 17 00:00:00 2001 From: gfuller Date: Tue, 21 Jul 2020 14:06:21 -0700 Subject: [PATCH 04/20] add metric instruments list --- .../semantic_conventions/http-metrics.md | 17 +++++++++++++---- 1 file changed, 13 insertions(+), 4 deletions(-) diff --git a/specification/metrics/semantic_conventions/http-metrics.md b/specification/metrics/semantic_conventions/http-metrics.md index 3f2b2b3f837..5e78e4bd62f 100644 --- a/specification/metrics/semantic_conventions/http-metrics.md +++ b/specification/metrics/semantic_conventions/http-metrics.md @@ -9,13 +9,22 @@ The conventions described in this section are http specific. ### Justification Http calls are generally fully described by Spans. By adding http labels -to metrics it allows for finely tuned aggregation on those metrics. +to metric events it allows for finely tuned aggregation. ### Convention +### Metric Instruments + +Below is a table of the metric instruments that **should** be used for http spans: + +| Name | Span kind | Type | Units | Description | +|-------------------------------------|-----------|---------------|---------------|-------------| +| `http.{span.kind}.request.duration` | Both | ValueRecorder | milliseconds | measure a request duration | +| `http.{span.kind}.request.size` | Both | ValueRecorder | requests | measure the bytes of a request message body | + ### Labels -Labels applied to these metric recordings should follow the http attribute semantic +Labels applied to metric events should follow the http attribute semantic conventions of the spans from which they are derived, see [http common attributes](../../trace/semantic_conventions/http.md#common-attributes). @@ -49,8 +58,8 @@ To avoid high cardinality the following attributes should be altered: #### Excluded labels - To avoid high cardinality some attributes **should not** be included as labels - on http metrics. Below is a list of them: + To avoid high cardinality some http attributes that are on spans **should not** be included as labels + on http metric events. Below is a list of them: http.user_agent http.request_content_length From d5d15cc3608891807937301cf1566cdefa6d28ca Mon Sep 17 00:00:00 2001 From: gfuller Date: Wed, 22 Jul 2020 11:12:58 -0700 Subject: [PATCH 05/20] simplify intro sections, add requirement columns, clarify labels, fix normative directives and more --- .../semantic_conventions/http-metrics.md | 88 +++++++++---------- 1 file changed, 41 insertions(+), 47 deletions(-) diff --git a/specification/metrics/semantic_conventions/http-metrics.md b/specification/metrics/semantic_conventions/http-metrics.md index 5e78e4bd62f..afa5e90f7bf 100644 --- a/specification/metrics/semantic_conventions/http-metrics.md +++ b/specification/metrics/semantic_conventions/http-metrics.md @@ -1,69 +1,63 @@ # General -The conventions described in this section are http specific. +The conventions described in this section are http specific. Http calls are generally fully described by Spans. By adding http labels +to metric events it allows for finely tuned filtering. -**Discaimer:** These are initial http labels but more may be added in the future. - -## Summarizing http labels - -### Justification - -Http calls are generally fully described by Spans. By adding http labels -to metric events it allows for finely tuned aggregation. - -### Convention +**Discaimer:** These are initial http metric instruments and labels but more may be added in the future. ### Metric Instruments -Below is a table of the metric instruments that **should** be used for http spans: +Below is a table of the metric instruments that MUST be used for http spans. They MUST be of the specified +type and units. -| Name | Span kind | Type | Units | Description | -|-------------------------------------|-----------|---------------|---------------|-------------| -| `http.{span.kind}.request.duration` | Both | ValueRecorder | milliseconds | measure a request duration | -| `http.{span.kind}.request.size` | Both | ValueRecorder | requests | measure the bytes of a request message body | +| Name | Span kind | Type | Units | Description | +|-------------------------------------|-----------------|---------------|---------------|-------------| +| `http.{span.kind}.request.duration` | Client & Server | ValueRecorder | milliseconds | measure a request duration | ### Labels -Labels applied to metric events should follow the http attribute semantic -conventions of the spans from which they are derived, see -[http common attributes](../../trace/semantic_conventions/http.md#common-attributes). +In order to make metric events as filterable as span events, http attributes +of spans should have a corresponding label on the metric event. See [http common attributes](../../trace/semantic_conventions/http.md#common-attributes) +for a list of attributes that should have corresponding labels. Due to cardinality issues some attributes MUST NOT have corresponding labels. +Below describes the details for specific attributes. #### Included labels -Below is a table of the attributes that **should** be included as labels -and whether they should be on server, client, or both http metrics: - -| Attribute name | Span kind| Notes | -|-------------------|----------|-------| -| `http.method` | Both || -| `http.host` | Both || -| `http.scheme` | Both || -| `http.status_code`| Both || -| `http.status_text`| Both || -| `http.flavor` | Both || -| `net.peer.name` | Client | see [http client attributes](../../trace/semantic_conventions/http.md#http-client) for details on when to use this over `http.host` and `net.peer.ip`| -| `net.peer.port` | Client |see [http client attributes](../../trace/semantic_conventions/http.md#http-client) for details on when to use this over `http.host`| -| `net.peer.ip` | Client |see [http client attributes](../../trace/semantic_conventions/http.md#http-client) for details on when to use this over `http.host`| -| `http.server_name`| Server || -| `http.route` | Server || +Below is a table of the attributes that SHOULD be included as labels +and whether they should be on server, client, or both types of http metric events: + +| Attribute name | Span kind | Required | Notes | +|-------------------|---------------------|----------|-------| +| `http.method` | Client & Server | Yes || +| `http.host` | Client & Server | see [http client attributes](../../trace/semantic_conventions/http.md#http-client) || +| `http.scheme` | Client & Server | No || +| `http.status_code`| Client & Server | No || +| `http.status_text`| Client & Server | No || +| `http.flavor` | Client & Server | No || +| `net.peer.name` | Client | see [http client attributes](../../trace/semantic_conventions/http.md#http-client) | see [http client attributes](../../trace/semantic_conventions/http.md#http-client) for details on when to use this over `http.host` and `net.peer.ip`| +| `net.peer.port` | Client | see [http client attributes](../../trace/semantic_conventions/http.md#http-client) |see [http client attributes](../../trace/semantic_conventions/http.md#http-client) for details on when to use this over `http.host`| +| `net.peer.ip` | Client | see [http client attributes](../../trace/semantic_conventions/http.md#http-client) |see [http client attributes](../../trace/semantic_conventions/http.md#http-client) for details on when to use this over `http.host`| +| `http.server_name`| Server | see [http server attributes](../../trace/semantic_conventions/http.md#http-server-semantic-conventions) || +| `http.route` | Server | No || #### Altered labels -To avoid high cardinality the following attributes should be altered: +To avoid high cardinality the following span attributes SHOULD be altered when added as labels to http metric events: -| Attribute name | Span kind| Alteration | Notes| -|-------------------|----------|------------|------| -|`http.url` | Both | Parameterized urls should follow the same convention as [http span names](../../trace/semantic_conventions/http.md#name)| See [http server semantic conventions](../../trace/semantic_conventions/http.md#http-server-semantic-conventions) for details on when to use alternate attributes on server http metrics| -|`http.target` | Both | Parameterized targets should follow the same convention as [http span names](../../trace/semantic_conventions/http.md#name)|| +| Attribute name | Span kind | Required | Alteration | Notes| +|-------------------|---------------------|----------|------------|------| +|`http.url` | Client & Server | see [http client attributes](../../trace/semantic_conventions/http.md#http-client) | Parameterized urls should follow the same convention as [http span names](../../trace/semantic_conventions/http.md#name)| See [http server semantic conventions](../../trace/semantic_conventions/http.md#http-server-semantic-conventions) for details on when to use alternate attributes on server http metrics| +|`http.target` | Client & Server | see [http client attributes](../../trace/semantic_conventions/http.md#http-client) | Parameterized targets should follow the same convention as [http span names](../../trace/semantic_conventions/http.md#name)|| #### Excluded labels - To avoid high cardinality some http attributes that are on spans **should not** be included as labels + To avoid high cardinality some http attributes that are on spans SHOULD NOT be included as labels on http metric events. Below is a list of them: - http.user_agent - http.request_content_length - http.request_content_length_uncompressed - http.response_content_length - http.response_content_length_uncompressed - http.client_ip +* `http.user_agent` +* `http.request_content_length` +* `http.request_content_length_uncompressed` +* `http.response_content_length` +* `http.response_content_length_uncompressed` +* `http.client_ip` +* `{any attribute that captures duration}` From 09116fcee9616057a877a5d31b4cefa5fffa48f7 Mon Sep 17 00:00:00 2001 From: gfuller Date: Wed, 22 Jul 2020 11:15:49 -0700 Subject: [PATCH 06/20] fix HTTP strings --- .../semantic_conventions/http-metrics.md | 30 +++++++++---------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/specification/metrics/semantic_conventions/http-metrics.md b/specification/metrics/semantic_conventions/http-metrics.md index afa5e90f7bf..a0949ca003b 100644 --- a/specification/metrics/semantic_conventions/http-metrics.md +++ b/specification/metrics/semantic_conventions/http-metrics.md @@ -1,13 +1,13 @@ # General -The conventions described in this section are http specific. Http calls are generally fully described by Spans. By adding http labels +The conventions described in this section are HTTP specific. HTTP calls are generally fully described by Spans. By adding HTTP labels to metric events it allows for finely tuned filtering. -**Discaimer:** These are initial http metric instruments and labels but more may be added in the future. +**Discaimer:** These are initial HTTP metric instruments and labels but more may be added in the future. ### Metric Instruments -Below is a table of the metric instruments that MUST be used for http spans. They MUST be of the specified +Below is a table of the metric instruments that MUST be used for HTTP spans. They MUST be of the specified type and units. | Name | Span kind | Type | Units | Description | @@ -16,28 +16,28 @@ type and units. ### Labels -In order to make metric events as filterable as span events, http attributes -of spans should have a corresponding label on the metric event. See [http common attributes](../../trace/semantic_conventions/http.md#common-attributes) +In order to make metric events as filterable as span events, HTTP attributes +of spans should have a corresponding label on the metric event. See [HTTP common attributes](../../trace/semantic_conventions/http.md#common-attributes) for a list of attributes that should have corresponding labels. Due to cardinality issues some attributes MUST NOT have corresponding labels. Below describes the details for specific attributes. #### Included labels Below is a table of the attributes that SHOULD be included as labels -and whether they should be on server, client, or both types of http metric events: +and whether they should be on server, client, or both types of HTTP metric events: | Attribute name | Span kind | Required | Notes | |-------------------|---------------------|----------|-------| | `http.method` | Client & Server | Yes || -| `http.host` | Client & Server | see [http client attributes](../../trace/semantic_conventions/http.md#http-client) || +| `http.host` | Client & Server | see [HTTP client attributes](../../trace/semantic_conventions/http.md#http-client) || | `http.scheme` | Client & Server | No || | `http.status_code`| Client & Server | No || | `http.status_text`| Client & Server | No || | `http.flavor` | Client & Server | No || -| `net.peer.name` | Client | see [http client attributes](../../trace/semantic_conventions/http.md#http-client) | see [http client attributes](../../trace/semantic_conventions/http.md#http-client) for details on when to use this over `http.host` and `net.peer.ip`| -| `net.peer.port` | Client | see [http client attributes](../../trace/semantic_conventions/http.md#http-client) |see [http client attributes](../../trace/semantic_conventions/http.md#http-client) for details on when to use this over `http.host`| -| `net.peer.ip` | Client | see [http client attributes](../../trace/semantic_conventions/http.md#http-client) |see [http client attributes](../../trace/semantic_conventions/http.md#http-client) for details on when to use this over `http.host`| -| `http.server_name`| Server | see [http server attributes](../../trace/semantic_conventions/http.md#http-server-semantic-conventions) || +| `net.peer.name` | Client | see [HTTP client attributes](../../trace/semantic_conventions/http.md#http-client) | see [HTTP client attributes](../../trace/semantic_conventions/http.md#http-client) for details on when to use this over `http.host` and `net.peer.ip`| +| `net.peer.port` | Client | see [HTTP client attributes](../../trace/semantic_conventions/http.md#http-client) |see [HTTP client attributes](../../trace/semantic_conventions/http.md#http-client) for details on when to use this over `http.host`| +| `net.peer.ip` | Client | see [HTTP client attributes](../../trace/semantic_conventions/http.md#http-client) |see [HTTP client attributes](../../trace/semantic_conventions/http.md#http-client) for details on when to use this over `http.host`| +| `http.server_name`| Server | see [HTTP server attributes](../../trace/semantic_conventions/http.md#http-server-semantic-conventions) || | `http.route` | Server | No || #### Altered labels @@ -46,13 +46,13 @@ To avoid high cardinality the following span attributes SHOULD be altered when a | Attribute name | Span kind | Required | Alteration | Notes| |-------------------|---------------------|----------|------------|------| -|`http.url` | Client & Server | see [http client attributes](../../trace/semantic_conventions/http.md#http-client) | Parameterized urls should follow the same convention as [http span names](../../trace/semantic_conventions/http.md#name)| See [http server semantic conventions](../../trace/semantic_conventions/http.md#http-server-semantic-conventions) for details on when to use alternate attributes on server http metrics| -|`http.target` | Client & Server | see [http client attributes](../../trace/semantic_conventions/http.md#http-client) | Parameterized targets should follow the same convention as [http span names](../../trace/semantic_conventions/http.md#name)|| +|`http.url` | Client & Server | see [HTTP client attributes](../../trace/semantic_conventions/http.md#http-client) | Parameterized urls should follow the same convention as [HTTP span names](../../trace/semantic_conventions/http.md#name)| See [HTTP server semantic conventions](../../trace/semantic_conventions/http.md#http-server-semantic-conventions) for details on when to use alternate attributes on server HTTP metrics| +|`http.target` | Client & Server | see [HTTP client attributes](../../trace/semantic_conventions/http.md#http-client) | Parameterized targets should follow the same convention as [HTTP span names](../../trace/semantic_conventions/http.md#name)|| #### Excluded labels - To avoid high cardinality some http attributes that are on spans SHOULD NOT be included as labels - on http metric events. Below is a list of them: + To avoid high cardinality some HTTP attributes that are on spans SHOULD NOT be included as labels + on HTTP metric events. Below is a list of them: * `http.user_agent` * `http.request_content_length` From 14c0a983560765a8e3cf4e6b57ab723230679d68 Mon Sep 17 00:00:00 2001 From: gfuller Date: Thu, 23 Jul 2020 10:01:46 -0700 Subject: [PATCH 07/20] add count metric instrument and shorten duration metric name --- specification/metrics/semantic_conventions/http-metrics.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/specification/metrics/semantic_conventions/http-metrics.md b/specification/metrics/semantic_conventions/http-metrics.md index a0949ca003b..2134b54e975 100644 --- a/specification/metrics/semantic_conventions/http-metrics.md +++ b/specification/metrics/semantic_conventions/http-metrics.md @@ -10,9 +10,10 @@ to metric events it allows for finely tuned filtering. Below is a table of the metric instruments that MUST be used for HTTP spans. They MUST be of the specified type and units. -| Name | Span kind | Type | Units | Description | -|-------------------------------------|-----------------|---------------|---------------|-------------| -| `http.{span.kind}.request.duration` | Client & Server | ValueRecorder | milliseconds | measure a request duration | +| Name | Span kind | Type | Units | Description | +|-------------------------------------|-----------------|---------------|--------------|-------------| +| `http.{span.kind}.duration` | Client & Server | ValueRecorder | milliseconds | measure a request duration | +| `http.{span.kind}.request` | Client & Server | Count | requests | measure number of requests | ### Labels From b3e8bf25f4981698d72dac944aec8b5817818506 Mon Sep 17 00:00:00 2001 From: gfuller Date: Fri, 24 Jul 2020 13:38:24 -0700 Subject: [PATCH 08/20] remove dependency on http.md, add more notes and examples and general cleanup --- .../semantic_conventions/http-metrics.md | 105 +++++++++++------- 1 file changed, 63 insertions(+), 42 deletions(-) diff --git a/specification/metrics/semantic_conventions/http-metrics.md b/specification/metrics/semantic_conventions/http-metrics.md index 2134b54e975..9b9d2d31393 100644 --- a/specification/metrics/semantic_conventions/http-metrics.md +++ b/specification/metrics/semantic_conventions/http-metrics.md @@ -1,7 +1,8 @@ # General -The conventions described in this section are HTTP specific. HTTP calls are generally fully described by Spans. By adding HTTP labels -to metric events it allows for finely tuned filtering. +The conventions described in this section are HTTP specific. HTTP calls are +generally fully described by Spans so a lot of the data below can be derived +from them. By adding HTTP labels to metric events it allows for finely tuned filtering. **Discaimer:** These are initial HTTP metric instruments and labels but more may be added in the future. @@ -17,48 +18,68 @@ type and units. ### Labels -In order to make metric events as filterable as span events, HTTP attributes -of spans should have a corresponding label on the metric event. See [HTTP common attributes](../../trace/semantic_conventions/http.md#common-attributes) -for a list of attributes that should have corresponding labels. Due to cardinality issues some attributes MUST NOT have corresponding labels. -Below describes the details for specific attributes. +When creating metric events, the following labels SHOULD be added: #### Included labels -Below is a table of the attributes that SHOULD be included as labels +Below is a table of the labels that SHOULD be included on metric events and whether they should be on server, client, or both types of HTTP metric events: -| Attribute name | Span kind | Required | Notes | -|-------------------|---------------------|----------|-------| -| `http.method` | Client & Server | Yes || -| `http.host` | Client & Server | see [HTTP client attributes](../../trace/semantic_conventions/http.md#http-client) || -| `http.scheme` | Client & Server | No || -| `http.status_code`| Client & Server | No || -| `http.status_text`| Client & Server | No || -| `http.flavor` | Client & Server | No || -| `net.peer.name` | Client | see [HTTP client attributes](../../trace/semantic_conventions/http.md#http-client) | see [HTTP client attributes](../../trace/semantic_conventions/http.md#http-client) for details on when to use this over `http.host` and `net.peer.ip`| -| `net.peer.port` | Client | see [HTTP client attributes](../../trace/semantic_conventions/http.md#http-client) |see [HTTP client attributes](../../trace/semantic_conventions/http.md#http-client) for details on when to use this over `http.host`| -| `net.peer.ip` | Client | see [HTTP client attributes](../../trace/semantic_conventions/http.md#http-client) |see [HTTP client attributes](../../trace/semantic_conventions/http.md#http-client) for details on when to use this over `http.host`| -| `http.server_name`| Server | see [HTTP server attributes](../../trace/semantic_conventions/http.md#http-server-semantic-conventions) || -| `http.route` | Server | No || - -#### Altered labels - -To avoid high cardinality the following span attributes SHOULD be altered when added as labels to http metric events: - -| Attribute name | Span kind | Required | Alteration | Notes| -|-------------------|---------------------|----------|------------|------| -|`http.url` | Client & Server | see [HTTP client attributes](../../trace/semantic_conventions/http.md#http-client) | Parameterized urls should follow the same convention as [HTTP span names](../../trace/semantic_conventions/http.md#name)| See [HTTP server semantic conventions](../../trace/semantic_conventions/http.md#http-server-semantic-conventions) for details on when to use alternate attributes on server HTTP metrics| -|`http.target` | Client & Server | see [HTTP client attributes](../../trace/semantic_conventions/http.md#http-client) | Parameterized targets should follow the same convention as [HTTP span names](../../trace/semantic_conventions/http.md#name)|| - - #### Excluded labels - - To avoid high cardinality some HTTP attributes that are on spans SHOULD NOT be included as labels - on HTTP metric events. Below is a list of them: - -* `http.user_agent` -* `http.request_content_length` -* `http.request_content_length_uncompressed` -* `http.response_content_length` -* `http.response_content_length_uncompressed` -* `http.client_ip` -* `{any attribute that captures duration}` +| Label name | Type | Recommended | Notes and examples | +|--------------------|-----------------|-------------------|--------------------| +| `http.method` | Client & Server | Yes | The HTTP request method. E.g. `"GET"` | +| `http.host` | Client & Server | see [label substitution](#label-substitution) | The value of the [HTTP host header][]. When the header is empty or not present, this label should be the same. | +| `http.scheme` | Client & Server | Optional | The URI scheme identifying the used protocol: `"http"` or `"https"` | +| `http.status_code` | Client & Server | Optional | [HTTP response status code][]. E.g. `200` (integer) | +| `http.status_text` | Client & Server | Optional | [HTTP reason phrase][]. E.g. `"OK"` | +| `http.flavor` | Client & Server | Optional | Kind of HTTP protocol used: `"1.0"`, `"1.1"`, `"2"`, `"SPDY"` or `"QUIC"`. | +| `net.peer.name` | Client | see [1] in [label substitution](#label-substitution) | The name of the service the request is going to. | +| `net.peer.port` | Client | see [1] in [label substitution](#label-substitution) | The port of the service the request is going to. E.g. `8080` | +| `net.peer.ip` | Client | see [1] in [label substitution](#label-substitution) | The IP address of the service the request is going to. E.g. `255.255.255.0` | +| `http.server_name` | Server | see [2] [label substitution](#label-substitution) | The primary server name of the matched virtual host. This should be obtained via configuration. If no such configuration can be obtained, this label MUST NOT be set ( `net.host.name` should be used instead). | +| `http.route` | Server | Optional | The matched route (path template). (TODO: Define whether to prepend application root) E.g. `"/users/:userID?"`. | + +[HTTP host header]: https://tools.ietf.org/html/rfc7230#section-5.4 +[HTTP response status code]: https://tools.ietf.org/html/rfc7231#section-6 +[HTTP reason phrase]: https://tools.ietf.org/html/rfc7230#section-3.1.2 + +#### Parameterized labels + +To avoid high cardinality the following labels SHOULD substitute any parameters when added as labels to http metric events as described below: + +| Label name | Type | Recommended | Notes and examples | +|-------------------|-----------------|-------------|---------------------| +|`http.url` | Client & Server | see [1] & [2] in [label substitution](#label-substitution) | The originally requested URL | +|`http.target` | Client & Server | see [1] & [2] in [label substitution](#label-substitution) | The full request target as passed in a [HTTP request line][] or equivalent, e.g. `"/path/{id}/?q={}"`. | + +[HTTP request line]: https://tools.ietf.org/html/rfc7230#section-3.1.1 + +Many REST APIs encode parameters into URI path, e.g. `/api/users/123` where `123` +is a user id, which creates high cardinality value space not suitable for labels on metric events. +In case of HTTP servers, these endpoints are often mapped by the server +frameworks to more concise _HTTP routes_, e.g. `/api/users/{user_id}`, which are +recommended as the low cardinality label values. However, the same approach usually +does not work for HTTP client labels, especially when instrumentation is provided +by a lower-level middleware that is not aware of the specifics of how the URIs +are formed. Therefore, HTTP client labels SHOULD be using conservative, low +cardinality names formed from the available parameters of an HTTP request, +such as `"HTTP {METHOD_NAME}"`. These labels MUST NOT default to using URI +path. + +#### Label substitution + +**[1]** For client metric labels, one of the following sets of labels is RECOMMENDED (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` +* `http.scheme`, `http.host`, `http.target` +* `http.scheme`, `net.peer.name`, `net.peer.port`, `http.target` +* `http.scheme`, `net.peer.ip`, `net.peer.port`, `http.target` + +**[2]** For server metric labels, `http.url` is usually not readily available on the server side but would have to be assembled in a cumbersome and sometimes lossy process from other information (see e.g. ). +It is thus preferred to supply the raw data that *is* available. +Namely, one of the following sets is RECOMMENDED (in order of usual preference unless for a particular web server/framework it is known that some other set is preferable for some reason; all strings must be non-empty): + +* `http.scheme`, `http.host`, `http.target` +* `http.scheme`, `http.server_name`, `net.host.port`, `http.target` +* `http.scheme`, `net.host.name`, `net.host.port`, `http.target` +* `http.url` \ No newline at end of file From 7e0c3066017b99ab309021f2b2e0f315a4502ec9 Mon Sep 17 00:00:00 2001 From: gfuller Date: Fri, 24 Jul 2020 13:45:12 -0700 Subject: [PATCH 09/20] replace span.kind with type --- .../metrics/semantic_conventions/http-metrics.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/specification/metrics/semantic_conventions/http-metrics.md b/specification/metrics/semantic_conventions/http-metrics.md index 9b9d2d31393..0d9d295b634 100644 --- a/specification/metrics/semantic_conventions/http-metrics.md +++ b/specification/metrics/semantic_conventions/http-metrics.md @@ -11,10 +11,10 @@ from them. By adding HTTP labels to metric events it allows for finely tuned fil Below is a table of the metric instruments that MUST be used for HTTP spans. They MUST be of the specified type and units. -| Name | Span kind | Type | Units | Description | -|-------------------------------------|-----------------|---------------|--------------|-------------| -| `http.{span.kind}.duration` | Client & Server | ValueRecorder | milliseconds | measure a request duration | -| `http.{span.kind}.request` | Client & Server | Count | requests | measure number of requests | +| Name | Type | Instrument | Units | Description | +|------------------------|-----------------|---------------|--------------|-------------| +| `http.{type}.duration` | Client & Server | ValueRecorder | milliseconds | measure a request duration | +| `http.{type}.request` | Client & Server | Count | requests | measure number of requests | ### Labels From 4d2ec7f0ad7d4e07c3459da201dbcd14b90d863b Mon Sep 17 00:00:00 2001 From: gfuller Date: Fri, 24 Jul 2020 13:54:13 -0700 Subject: [PATCH 10/20] add missing labels and cleanup links --- .../metrics/semantic_conventions/http-metrics.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/specification/metrics/semantic_conventions/http-metrics.md b/specification/metrics/semantic_conventions/http-metrics.md index 0d9d295b634..32ea37678c7 100644 --- a/specification/metrics/semantic_conventions/http-metrics.md +++ b/specification/metrics/semantic_conventions/http-metrics.md @@ -29,14 +29,16 @@ and whether they should be on server, client, or both types of HTTP metric event |--------------------|-----------------|-------------------|--------------------| | `http.method` | Client & Server | Yes | The HTTP request method. E.g. `"GET"` | | `http.host` | Client & Server | see [label substitution](#label-substitution) | The value of the [HTTP host header][]. When the header is empty or not present, this label should be the same. | -| `http.scheme` | Client & Server | Optional | The URI scheme identifying the used protocol: `"http"` or `"https"` | +| `http.scheme` | Client & Server | see [label substitution](#label-substitution) | The URI scheme identifying the used protocol: `"http"` or `"https"` | | `http.status_code` | Client & Server | Optional | [HTTP response status code][]. E.g. `200` (integer) | | `http.status_text` | Client & Server | Optional | [HTTP reason phrase][]. E.g. `"OK"` | | `http.flavor` | Client & Server | Optional | Kind of HTTP protocol used: `"1.0"`, `"1.1"`, `"2"`, `"SPDY"` or `"QUIC"`. | | `net.peer.name` | Client | see [1] in [label substitution](#label-substitution) | The name of the service the request is going to. | | `net.peer.port` | Client | see [1] in [label substitution](#label-substitution) | The port of the service the request is going to. E.g. `8080` | | `net.peer.ip` | Client | see [1] in [label substitution](#label-substitution) | The IP address of the service the request is going to. E.g. `255.255.255.0` | -| `http.server_name` | Server | see [2] [label substitution](#label-substitution) | The primary server name of the matched virtual host. This should be obtained via configuration. If no such configuration can be obtained, this label MUST NOT be set ( `net.host.name` should be used instead). | +| `http.server_name` | Server | see [2] in [label substitution](#label-substitution) | The primary server name of the matched virtual host. This should be obtained via configuration. If no such configuration can be obtained, this label MUST NOT be set ( `net.host.name` should be used instead). | +| `net.host.name` | Server | see [2] in [label substitution](#label-substitution) | The name of the host. | +| `net.host.port` | Server | see [2] in [label substitution](#label-substitution) | The port of the host. | | `http.route` | Server | Optional | The matched route (path template). (TODO: Define whether to prepend application root) E.g. `"/users/:userID?"`. | [HTTP host header]: https://tools.ietf.org/html/rfc7230#section-5.4 @@ -49,8 +51,8 @@ To avoid high cardinality the following labels SHOULD substitute any parameters | Label name | Type | Recommended | Notes and examples | |-------------------|-----------------|-------------|---------------------| -|`http.url` | Client & Server | see [1] & [2] in [label substitution](#label-substitution) | The originally requested URL | -|`http.target` | Client & Server | see [1] & [2] in [label substitution](#label-substitution) | The full request target as passed in a [HTTP request line][] or equivalent, e.g. `"/path/{id}/?q={}"`. | +|`http.url` | Client & Server | see [label substitution](#label-substitution) | The originally requested URL | +|`http.target` | Client & Server | see [label substitution](#label-substitution) | The full request target as passed in a [HTTP request line][] or equivalent, e.g. `"/path/{id}/?q={}"`. | [HTTP request line]: https://tools.ietf.org/html/rfc7230#section-3.1.1 From b87fcb88f33b9568c92fe639c7c6198b3189c08e Mon Sep 17 00:00:00 2001 From: gfuller Date: Fri, 24 Jul 2020 13:58:28 -0700 Subject: [PATCH 11/20] substitution->alternatives and remove section not needed --- .../semantic_conventions/http-metrics.md | 26 ++++++++----------- 1 file changed, 11 insertions(+), 15 deletions(-) diff --git a/specification/metrics/semantic_conventions/http-metrics.md b/specification/metrics/semantic_conventions/http-metrics.md index 32ea37678c7..7ce38a04095 100644 --- a/specification/metrics/semantic_conventions/http-metrics.md +++ b/specification/metrics/semantic_conventions/http-metrics.md @@ -18,27 +18,23 @@ type and units. ### Labels -When creating metric events, the following labels SHOULD be added: - -#### Included labels - Below is a table of the labels that SHOULD be included on metric events and whether they should be on server, client, or both types of HTTP metric events: | Label name | Type | Recommended | Notes and examples | |--------------------|-----------------|-------------------|--------------------| | `http.method` | Client & Server | Yes | The HTTP request method. E.g. `"GET"` | -| `http.host` | Client & Server | see [label substitution](#label-substitution) | The value of the [HTTP host header][]. When the header is empty or not present, this label should be the same. | -| `http.scheme` | Client & Server | see [label substitution](#label-substitution) | The URI scheme identifying the used protocol: `"http"` or `"https"` | +| `http.host` | Client & Server | see [label alternatives](#label-alternatives) | The value of the [HTTP host header][]. When the header is empty or not present, this label should be the same. | +| `http.scheme` | Client & Server | see [label alternatives](#label-alternatives) | The URI scheme identifying the used protocol: `"http"` or `"https"` | | `http.status_code` | Client & Server | Optional | [HTTP response status code][]. E.g. `200` (integer) | | `http.status_text` | Client & Server | Optional | [HTTP reason phrase][]. E.g. `"OK"` | | `http.flavor` | Client & Server | Optional | Kind of HTTP protocol used: `"1.0"`, `"1.1"`, `"2"`, `"SPDY"` or `"QUIC"`. | -| `net.peer.name` | Client | see [1] in [label substitution](#label-substitution) | The name of the service the request is going to. | -| `net.peer.port` | Client | see [1] in [label substitution](#label-substitution) | The port of the service the request is going to. E.g. `8080` | -| `net.peer.ip` | Client | see [1] in [label substitution](#label-substitution) | The IP address of the service the request is going to. E.g. `255.255.255.0` | -| `http.server_name` | Server | see [2] in [label substitution](#label-substitution) | The primary server name of the matched virtual host. This should be obtained via configuration. If no such configuration can be obtained, this label MUST NOT be set ( `net.host.name` should be used instead). | -| `net.host.name` | Server | see [2] in [label substitution](#label-substitution) | The name of the host. | -| `net.host.port` | Server | see [2] in [label substitution](#label-substitution) | The port of the host. | +| `net.peer.name` | Client | see [1] in [label alternatives](#label-alternatives) | The name of the service the request is going to. | +| `net.peer.port` | Client | see [1] in [label alternatives](#label-alternatives) | The port of the service the request is going to. E.g. `8080` | +| `net.peer.ip` | Client | see [1] in [label alternatives](#label-alternatives) | The IP address of the service the request is going to. E.g. `255.255.255.0` | +| `http.server_name` | Server | see [2] in [label alternatives](#label-alternatives) | The primary server name of the matched virtual host. This should be obtained via configuration. If no such configuration can be obtained, this label MUST NOT be set ( `net.host.name` should be used instead). | +| `net.host.name` | Server | see [2] in [label alternatives](#label-alternatives) | The name of the host. | +| `net.host.port` | Server | see [2] in [label alternatives](#label-alternatives) | The port of the host. | | `http.route` | Server | Optional | The matched route (path template). (TODO: Define whether to prepend application root) E.g. `"/users/:userID?"`. | [HTTP host header]: https://tools.ietf.org/html/rfc7230#section-5.4 @@ -51,8 +47,8 @@ To avoid high cardinality the following labels SHOULD substitute any parameters | Label name | Type | Recommended | Notes and examples | |-------------------|-----------------|-------------|---------------------| -|`http.url` | Client & Server | see [label substitution](#label-substitution) | The originally requested URL | -|`http.target` | Client & Server | see [label substitution](#label-substitution) | The full request target as passed in a [HTTP request line][] or equivalent, e.g. `"/path/{id}/?q={}"`. | +|`http.url` | Client & Server | see [label alternatives](#label-alternatives) | The originally requested URL | +|`http.target` | Client & Server | see [label alternatives](#label-alternatives) | The full request target as passed in a [HTTP request line][] or equivalent, e.g. `"/path/{id}/?q={}"`. | [HTTP request line]: https://tools.ietf.org/html/rfc7230#section-3.1.1 @@ -68,7 +64,7 @@ cardinality names formed from the available parameters of an HTTP request, such as `"HTTP {METHOD_NAME}"`. These labels MUST NOT default to using URI path. -#### Label substitution +#### Label alternatives **[1]** For client metric labels, one of the following sets of labels is RECOMMENDED (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): From e2ce1b3a92b4d9bbf1cc800ec900289c33e5539e Mon Sep 17 00:00:00 2001 From: gfuller1 Date: Thu, 30 Jul 2020 15:09:04 -0700 Subject: [PATCH 12/20] make request count metric instrument plural --- specification/metrics/semantic_conventions/http-metrics.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/metrics/semantic_conventions/http-metrics.md b/specification/metrics/semantic_conventions/http-metrics.md index 7ce38a04095..113fb17effe 100644 --- a/specification/metrics/semantic_conventions/http-metrics.md +++ b/specification/metrics/semantic_conventions/http-metrics.md @@ -14,7 +14,7 @@ type and units. | Name | Type | Instrument | Units | Description | |------------------------|-----------------|---------------|--------------|-------------| | `http.{type}.duration` | Client & Server | ValueRecorder | milliseconds | measure a request duration | -| `http.{type}.request` | Client & Server | Count | requests | measure number of requests | +| `http.{type}.requests` | Client & Server | Count | requests | measure number of requests | ### Labels From 952d1ae9411db492f11b279301f1f8a6ac374e96 Mon Sep 17 00:00:00 2001 From: gfuller1 Date: Thu, 30 Jul 2020 15:09:23 -0700 Subject: [PATCH 13/20] formatting --- specification/metrics/semantic_conventions/http-metrics.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/metrics/semantic_conventions/http-metrics.md b/specification/metrics/semantic_conventions/http-metrics.md index 113fb17effe..b1ad75a755e 100644 --- a/specification/metrics/semantic_conventions/http-metrics.md +++ b/specification/metrics/semantic_conventions/http-metrics.md @@ -14,7 +14,7 @@ type and units. | Name | Type | Instrument | Units | Description | |------------------------|-----------------|---------------|--------------|-------------| | `http.{type}.duration` | Client & Server | ValueRecorder | milliseconds | measure a request duration | -| `http.{type}.requests` | Client & Server | Count | requests | measure number of requests | +| `http.{type}.requests` | Client & Server | Count | requests | measure number of requests | ### Labels From c27d66d8f77314c2329360e54e08d031e18dfbf1 Mon Sep 17 00:00:00 2001 From: gfuller1 Date: Wed, 5 Aug 2020 16:35:08 -0700 Subject: [PATCH 14/20] clarify type column --- .../semantic_conventions/http-metrics.md | 45 +++++++++---------- 1 file changed, 22 insertions(+), 23 deletions(-) diff --git a/specification/metrics/semantic_conventions/http-metrics.md b/specification/metrics/semantic_conventions/http-metrics.md index b1ad75a755e..f14f7c1619b 100644 --- a/specification/metrics/semantic_conventions/http-metrics.md +++ b/specification/metrics/semantic_conventions/http-metrics.md @@ -11,31 +11,30 @@ from them. By adding HTTP labels to metric events it allows for finely tuned fil Below is a table of the metric instruments that MUST be used for HTTP spans. They MUST be of the specified type and units. -| Name | Type | Instrument | Units | Description | -|------------------------|-----------------|---------------|--------------|-------------| -| `http.{type}.duration` | Client & Server | ValueRecorder | milliseconds | measure a request duration | -| `http.{type}.requests` | Client & Server | Count | requests | measure number of requests | +| Name | Type | Instrument | Units | Description | +|------------------------|---------------------|---------------|--------------|-------------| +| `http.{type}.duration` | `client` & `server` | ValueRecorder | milliseconds | measure a request duration | ### Labels Below is a table of the labels that SHOULD be included on metric events and whether they should be on server, client, or both types of HTTP metric events: -| Label name | Type | Recommended | Notes and examples | -|--------------------|-----------------|-------------------|--------------------| -| `http.method` | Client & Server | Yes | The HTTP request method. E.g. `"GET"` | -| `http.host` | Client & Server | see [label alternatives](#label-alternatives) | The value of the [HTTP host header][]. When the header is empty or not present, this label should be the same. | -| `http.scheme` | Client & Server | see [label alternatives](#label-alternatives) | The URI scheme identifying the used protocol: `"http"` or `"https"` | -| `http.status_code` | Client & Server | Optional | [HTTP response status code][]. E.g. `200` (integer) | -| `http.status_text` | Client & Server | Optional | [HTTP reason phrase][]. E.g. `"OK"` | -| `http.flavor` | Client & Server | Optional | Kind of HTTP protocol used: `"1.0"`, `"1.1"`, `"2"`, `"SPDY"` or `"QUIC"`. | -| `net.peer.name` | Client | see [1] in [label alternatives](#label-alternatives) | The name of the service the request is going to. | -| `net.peer.port` | Client | see [1] in [label alternatives](#label-alternatives) | The port of the service the request is going to. E.g. `8080` | -| `net.peer.ip` | Client | see [1] in [label alternatives](#label-alternatives) | The IP address of the service the request is going to. E.g. `255.255.255.0` | -| `http.server_name` | Server | see [2] in [label alternatives](#label-alternatives) | The primary server name of the matched virtual host. This should be obtained via configuration. If no such configuration can be obtained, this label MUST NOT be set ( `net.host.name` should be used instead). | -| `net.host.name` | Server | see [2] in [label alternatives](#label-alternatives) | The name of the host. | -| `net.host.port` | Server | see [2] in [label alternatives](#label-alternatives) | The port of the host. | -| `http.route` | Server | Optional | The matched route (path template). (TODO: Define whether to prepend application root) E.g. `"/users/:userID?"`. | +| Label name | Type | Recommended | Notes and examples | +|--------------------|---------------------|-------------------|--------------------| +| `http.method` | `client` & `server` | Yes | The HTTP request method. E.g. `"GET"` | +| `http.host` | `client` & `server` | see [label alternatives](#label-alternatives) | The value of the [HTTP host header][]. When the header is empty or not present, this label should be the same. | +| `http.scheme` | `client` & `server` | see [label alternatives](#label-alternatives) | The URI scheme identifying the used protocol: `"http"` or `"https"` | +| `http.status_code` | `client` & `server` | Optional | [HTTP response status code][]. E.g. `200` (integer) | +| `http.status_text` | `client` & `server` | Optional | [HTTP reason phrase][]. E.g. `"OK"` | +| `http.flavor` | `client` & `server` | Optional | Kind of HTTP protocol used: `"1.0"`, `"1.1"`, `"2"`, `"SPDY"` or `"QUIC"`. | +| `net.peer.name` | `client` | see [1] in [label alternatives](#label-alternatives) | The name of the service the request is going to. | +| `net.peer.port` | `client` | see [1] in [label alternatives](#label-alternatives) | The port of the service the request is going to. E.g. `8080` | +| `net.peer.ip` | `client` | see [1] in [label alternatives](#label-alternatives) | The IP address of the service the request is going to. E.g. `255.255.255.0` | +| `http.server_name` | `server` | see [2] in [label alternatives](#label-alternatives) | The primary server name of the matched virtual host. This should be obtained via configuration. If no such configuration can be obtained, this label MUST NOT be set ( `net.host.name` should be used instead). | +| `net.host.name` | `server` | see [2] in [label alternatives](#label-alternatives) | The name of the host. | +| `net.host.port` | `server` | see [2] in [label alternatives](#label-alternatives) | The port of the host. | +| `http.route` | `server` | Optional | The matched route (path template). (TODO: Define whether to prepend application root) E.g. `"/users/:userID?"`. | [HTTP host header]: https://tools.ietf.org/html/rfc7230#section-5.4 [HTTP response status code]: https://tools.ietf.org/html/rfc7231#section-6 @@ -45,10 +44,10 @@ and whether they should be on server, client, or both types of HTTP metric event To avoid high cardinality the following labels SHOULD substitute any parameters when added as labels to http metric events as described below: -| Label name | Type | Recommended | Notes and examples | -|-------------------|-----------------|-------------|---------------------| -|`http.url` | Client & Server | see [label alternatives](#label-alternatives) | The originally requested URL | -|`http.target` | Client & Server | see [label alternatives](#label-alternatives) | The full request target as passed in a [HTTP request line][] or equivalent, e.g. `"/path/{id}/?q={}"`. | +| Label name | Type | Recommended | Notes and examples | +|-------------------|---------------------|-------------|---------------------| +|`http.url` | `client` & `server` | see [label alternatives](#label-alternatives) | The originally requested URL | +|`http.target` | `client` & `server` | see [label alternatives](#label-alternatives) | The full request target as passed in a [HTTP request line][] or equivalent, e.g. `"/path/{id}/?q={}"`. | [HTTP request line]: https://tools.ietf.org/html/rfc7230#section-3.1.1 From 7b59ac09bffe6dbdaf293d8fb07b453224eb3f3a Mon Sep 17 00:00:00 2001 From: gfuller1 Date: Wed, 5 Aug 2020 17:02:14 -0700 Subject: [PATCH 15/20] update intro and fix units --- .../metrics/semantic_conventions/http-metrics.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/specification/metrics/semantic_conventions/http-metrics.md b/specification/metrics/semantic_conventions/http-metrics.md index f14f7c1619b..9aac78c7628 100644 --- a/specification/metrics/semantic_conventions/http-metrics.md +++ b/specification/metrics/semantic_conventions/http-metrics.md @@ -1,26 +1,26 @@ # General -The conventions described in this section are HTTP specific. HTTP calls are -generally fully described by Spans so a lot of the data below can be derived -from them. By adding HTTP labels to metric events it allows for finely tuned filtering. +The conventions described in this section are HTTP specific. When HTTP operations occur, +metric events about those operations will be generated and reported to provide insight into the +operations. By adding HTTP labels to metric events it allows for finely tuned filtering. **Discaimer:** These are initial HTTP metric instruments and labels but more may be added in the future. ### Metric Instruments -Below is a table of the metric instruments that MUST be used for HTTP spans. They MUST be of the specified +The following metric instruments MUST be used to describe HTTP operations. They MUST be of the specified type and units. -| Name | Type | Instrument | Units | Description | -|------------------------|---------------------|---------------|--------------|-------------| -| `http.{type}.duration` | `client` & `server` | ValueRecorder | milliseconds | measure a request duration | +| Name | Type | Instrument | Units | Description | +|------------------------|---------------------|---------------|---------|-------------| +| `http.{type}.duration` | `client` & `server` | ValueRecorder | seconds | measure a request duration | ### Labels Below is a table of the labels that SHOULD be included on metric events and whether they should be on server, client, or both types of HTTP metric events: -| Label name | Type | Recommended | Notes and examples | +| Name | Type | Recommended | Notes and examples | |--------------------|---------------------|-------------------|--------------------| | `http.method` | `client` & `server` | Yes | The HTTP request method. E.g. `"GET"` | | `http.host` | `client` & `server` | see [label alternatives](#label-alternatives) | The value of the [HTTP host header][]. When the header is empty or not present, this label should be the same. | From 1ba7a15f43fa1792fa8e6a959b30773c69b37b09 Mon Sep 17 00:00:00 2001 From: gfuller1 Date: Wed, 5 Aug 2020 17:44:27 -0700 Subject: [PATCH 16/20] breakout metric instrument table --- .../metrics/semantic_conventions/http-metrics.md | 16 +++++++++++++--- 1 file changed, 13 insertions(+), 3 deletions(-) diff --git a/specification/metrics/semantic_conventions/http-metrics.md b/specification/metrics/semantic_conventions/http-metrics.md index 9aac78c7628..bc2c2342cb0 100644 --- a/specification/metrics/semantic_conventions/http-metrics.md +++ b/specification/metrics/semantic_conventions/http-metrics.md @@ -11,9 +11,19 @@ operations. By adding HTTP labels to metric events it allows for finely tuned fi The following metric instruments MUST be used to describe HTTP operations. They MUST be of the specified type and units. -| Name | Type | Instrument | Units | Description | -|------------------------|---------------------|---------------|---------|-------------| -| `http.{type}.duration` | `client` & `server` | ValueRecorder | seconds | measure a request duration | +#### HTTP Server +Below is a table of HTTP server metric instruments. + +| Name | Instrument | Units | Description | +|------------------------|---------------|--------------|-------------| +| `http.server.duration` | ValueRecorder | milliseconds | measures the duration of the inbound HTTP request | + +#### HTTP Client +Below is a table of HTTP client metric instruments. + +| Name | Instrument | Units | Description | +|------------------------|---------------|--------------|-------------| +| `http.client.duration` | ValueRecorder | milliseconds | measure the duration of the outbound HTTP request | ### Labels From bdcbdd5c73056932c50183ab4de394637f2ae7f0 Mon Sep 17 00:00:00 2001 From: Graham Fuller Date: Thu, 13 Aug 2020 15:18:33 -0700 Subject: [PATCH 17/20] remove http.route since it is the same as http.target after http.target is simplified --- specification/metrics/semantic_conventions/http-metrics.md | 1 - 1 file changed, 1 deletion(-) diff --git a/specification/metrics/semantic_conventions/http-metrics.md b/specification/metrics/semantic_conventions/http-metrics.md index bc2c2342cb0..84b6e1f3eee 100644 --- a/specification/metrics/semantic_conventions/http-metrics.md +++ b/specification/metrics/semantic_conventions/http-metrics.md @@ -44,7 +44,6 @@ and whether they should be on server, client, or both types of HTTP metric event | `http.server_name` | `server` | see [2] in [label alternatives](#label-alternatives) | The primary server name of the matched virtual host. This should be obtained via configuration. If no such configuration can be obtained, this label MUST NOT be set ( `net.host.name` should be used instead). | | `net.host.name` | `server` | see [2] in [label alternatives](#label-alternatives) | The name of the host. | | `net.host.port` | `server` | see [2] in [label alternatives](#label-alternatives) | The port of the host. | -| `http.route` | `server` | Optional | The matched route (path template). (TODO: Define whether to prepend application root) E.g. `"/users/:userID?"`. | [HTTP host header]: https://tools.ietf.org/html/rfc7230#section-5.4 [HTTP response status code]: https://tools.ietf.org/html/rfc7231#section-6 From 7de9d45a0ab29f48fd23ccdc1d6c82fc26152867 Mon Sep 17 00:00:00 2001 From: Graham Fuller Date: Thu, 20 Aug 2020 10:51:56 -0700 Subject: [PATCH 18/20] update net labels to link to definition --- .../metrics/semantic_conventions/http-metrics.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/specification/metrics/semantic_conventions/http-metrics.md b/specification/metrics/semantic_conventions/http-metrics.md index 84b6e1f3eee..f965abd7351 100644 --- a/specification/metrics/semantic_conventions/http-metrics.md +++ b/specification/metrics/semantic_conventions/http-metrics.md @@ -35,15 +35,15 @@ and whether they should be on server, client, or both types of HTTP metric event | `http.method` | `client` & `server` | Yes | The HTTP request method. E.g. `"GET"` | | `http.host` | `client` & `server` | see [label alternatives](#label-alternatives) | The value of the [HTTP host header][]. When the header is empty or not present, this label should be the same. | | `http.scheme` | `client` & `server` | see [label alternatives](#label-alternatives) | The URI scheme identifying the used protocol: `"http"` or `"https"` | -| `http.status_code` | `client` & `server` | Optional | [HTTP response status code][]. E.g. `200` (integer) | +| `http.status_code` | `client` & `server` | Optional | [HTTP response status code][]. E.g. `200` (String) | | `http.status_text` | `client` & `server` | Optional | [HTTP reason phrase][]. E.g. `"OK"` | | `http.flavor` | `client` & `server` | Optional | Kind of HTTP protocol used: `"1.0"`, `"1.1"`, `"2"`, `"SPDY"` or `"QUIC"`. | -| `net.peer.name` | `client` | see [1] in [label alternatives](#label-alternatives) | The name of the service the request is going to. | -| `net.peer.port` | `client` | see [1] in [label alternatives](#label-alternatives) | The port of the service the request is going to. E.g. `8080` | -| `net.peer.ip` | `client` | see [1] in [label alternatives](#label-alternatives) | The IP address of the service the request is going to. E.g. `255.255.255.0` | +| `net.peer.name` | `client` | see [1] in [label alternatives](#label-alternatives) | See [general network connection attributes](../../trace/semantic_conventions/span-general.md#general-network-connection-attributes) | +| `net.peer.port` | `client` | see [1] in [label alternatives](#label-alternatives) | See [general network connection attributes](../../trace/semantic_conventions/span-general.md#general-network-connection-attributes) | +| `net.peer.ip` | `client` | see [1] in [label alternatives](#label-alternatives) | See [general network connection attributes](../../trace/semantic_conventions/span-general.md#general-network-connection-attributes) | | `http.server_name` | `server` | see [2] in [label alternatives](#label-alternatives) | The primary server name of the matched virtual host. This should be obtained via configuration. If no such configuration can be obtained, this label MUST NOT be set ( `net.host.name` should be used instead). | -| `net.host.name` | `server` | see [2] in [label alternatives](#label-alternatives) | The name of the host. | -| `net.host.port` | `server` | see [2] in [label alternatives](#label-alternatives) | The port of the host. | +| `net.host.name` | `server` | see [2] in [label alternatives](#label-alternatives) | See [general network connection attributes](../../trace/semantic_conventions/span-general.md#general-network-connection-attributes) | +| `net.host.port` | `server` | see [2] in [label alternatives](#label-alternatives) | See [general network connection attributes](../../trace/semantic_conventions/span-general.md#general-network-connection-attributes) | [HTTP host header]: https://tools.ietf.org/html/rfc7230#section-5.4 [HTTP response status code]: https://tools.ietf.org/html/rfc7231#section-6 From d42005981a31a611b79cac3e290a7b629017b130 Mon Sep 17 00:00:00 2001 From: Graham Fuller Date: Fri, 21 Aug 2020 09:53:25 -0700 Subject: [PATCH 19/20] add lowercase requirement to http.scheme --- specification/metrics/semantic_conventions/http-metrics.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/metrics/semantic_conventions/http-metrics.md b/specification/metrics/semantic_conventions/http-metrics.md index f965abd7351..1e178abc517 100644 --- a/specification/metrics/semantic_conventions/http-metrics.md +++ b/specification/metrics/semantic_conventions/http-metrics.md @@ -34,7 +34,7 @@ and whether they should be on server, client, or both types of HTTP metric event |--------------------|---------------------|-------------------|--------------------| | `http.method` | `client` & `server` | Yes | The HTTP request method. E.g. `"GET"` | | `http.host` | `client` & `server` | see [label alternatives](#label-alternatives) | The value of the [HTTP host header][]. When the header is empty or not present, this label should be the same. | -| `http.scheme` | `client` & `server` | see [label alternatives](#label-alternatives) | The URI scheme identifying the used protocol: `"http"` or `"https"` | +| `http.scheme` | `client` & `server` | see [label alternatives](#label-alternatives) | The URI scheme identifying the used protocol in lowercase: `"http"` or `"https"` | | `http.status_code` | `client` & `server` | Optional | [HTTP response status code][]. E.g. `200` (String) | | `http.status_text` | `client` & `server` | Optional | [HTTP reason phrase][]. E.g. `"OK"` | | `http.flavor` | `client` & `server` | Optional | Kind of HTTP protocol used: `"1.0"`, `"1.1"`, `"2"`, `"SPDY"` or `"QUIC"`. | From d607daf06d22043b90524cf461a91c1f01394f33 Mon Sep 17 00:00:00 2001 From: gfuller1 Date: Fri, 28 Aug 2020 10:48:27 -0700 Subject: [PATCH 20/20] formatting --- .../metrics/semantic_conventions/http-metrics.md | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/specification/metrics/semantic_conventions/http-metrics.md b/specification/metrics/semantic_conventions/http-metrics.md index 1e178abc517..e5de51ccd8e 100644 --- a/specification/metrics/semantic_conventions/http-metrics.md +++ b/specification/metrics/semantic_conventions/http-metrics.md @@ -6,26 +6,28 @@ operations. By adding HTTP labels to metric events it allows for finely tuned fi **Discaimer:** These are initial HTTP metric instruments and labels but more may be added in the future. -### Metric Instruments +## Metric Instruments The following metric instruments MUST be used to describe HTTP operations. They MUST be of the specified type and units. -#### HTTP Server +### HTTP Server + Below is a table of HTTP server metric instruments. | Name | Instrument | Units | Description | |------------------------|---------------|--------------|-------------| | `http.server.duration` | ValueRecorder | milliseconds | measures the duration of the inbound HTTP request | -#### HTTP Client +### HTTP Client + Below is a table of HTTP client metric instruments. | Name | Instrument | Units | Description | |------------------------|---------------|--------------|-------------| | `http.client.duration` | ValueRecorder | milliseconds | measure the duration of the outbound HTTP request | -### Labels +## Labels Below is a table of the labels that SHOULD be included on metric events and whether they should be on server, client, or both types of HTTP metric events: @@ -49,7 +51,7 @@ and whether they should be on server, client, or both types of HTTP metric event [HTTP response status code]: https://tools.ietf.org/html/rfc7231#section-6 [HTTP reason phrase]: https://tools.ietf.org/html/rfc7230#section-3.1.2 -#### Parameterized labels +### Parameterized labels To avoid high cardinality the following labels SHOULD substitute any parameters when added as labels to http metric events as described below: @@ -72,7 +74,7 @@ cardinality names formed from the available parameters of an HTTP request, such as `"HTTP {METHOD_NAME}"`. These labels MUST NOT default to using URI path. -#### Label alternatives +### Label alternatives **[1]** For client metric labels, one of the following sets of labels is RECOMMENDED (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): @@ -88,4 +90,4 @@ Namely, one of the following sets is RECOMMENDED (in order of usual preference u * `http.scheme`, `http.host`, `http.target` * `http.scheme`, `http.server_name`, `net.host.port`, `http.target` * `http.scheme`, `net.host.name`, `net.host.port`, `http.target` -* `http.url` \ No newline at end of file +* `http.url`