open-telemetry
/
semantic-conventions
mirror of https://github.com/open-telemetry/semantic-conventions.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

YAML Model for Semantic Conventions (#571) 

* First model draft

* Fix checkstyle

* Generate network table from YAML

* HTTP semantic convention tables

* Fix requirements order

* Add code and basic documentation

* Missing \n

* Remove tool

* Add General and HTTP semantic convention

* Update table style

* yaml->semantic_conventions

* Fix small errors

* Fix docfx errors

* Update Makefile to use otel Docker repo

Co-authored-by: Armin Ruech <armin.ruech@dynatrace.com>
This commit is contained in:
Giovanni Liva 2020-08-27 22:18:51 +02:00 committed by GitHub
parent be35f68e5a
commit 521dfd99aa
7 changed files with 562 additions and 65 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
Makefile
View File

@ -1,11 +1,13 @@
# All documents to be used in spell check.
ALL_DOCS := $(shell find . -name '*.md' -not -path './.github/*' -type f | grep -v ^./node_modules | sort)
PWD := $(shell pwd)
TOOLS_DIR := ./.tools
MISSPELL_BINARY=$(TOOLS_DIR)/misspell
MARKDOWN_LINK_CHECK=markdown-link-check
MARKDOWN_LINT=markdownlint
.PHONY: install-misspell
install-misspell:
go build -o $(MISSPELL_BINARY) github.com/client9/misspell/cmd/misspell
@ -34,3 +36,7 @@ install-markdown-lint:
markdown-lint:
@echo $(ALL_DOCS)
@for f in $(ALL_DOCS); do echo $$f; $(MARKDOWN_LINT) -c .markdownlint.yaml $$f || exit 1; done
.PHONY: table-generation
table-generation:
docker run --rm -v $(PWD)/semantic_conventions:/source -v $(PWD)/specification:/spec otel/semconvgen -f /source markdown -md /spec

228
semantic_conventions/syntax.md Normal file
View File

@ -0,0 +1,228 @@
# Semantic Convention YAML Language
First, the syntax with a pseudo [EBNF](https://en.wikipedia.org/wiki/Extended_Backus-Naur_form) grammar is presented.
Then, the semantic of each field is described.
## Syntax
All attributes are lower case.
```bnf
groups ::= semconv
| semconv groups
semconv ::= id brief [note] [prefix] [extends] [span_kind] attributes [constraints]
id ::= string
brief ::= string
note ::= string
prefix ::= string
# extends MUST point to an existing semconv id
extends ::= string
span_kind ::= "client"
| "server"
| "producer"
| "consumer"
| "internal"
attributes ::= (id type brief examples | ref [brief] [examples]) [required] [note]
# ref MUST point to an existing attribute id
ref ::= id
type ::= "string"
| "number"
| "boolean"
| "string[]"
| "number[]"
| "boolean[]"
| enum
enum ::= [allow_custom_values] members
allow_custom_values := boolean
members ::= member {member}
member ::= id value [brief] [note]
required ::= "always"
| "conditional" <condition>
examples ::= <example_value> {<example_value>}
constraints ::= constraint {constraint}
constraint ::= any_of
| include
any_of ::= id {id}
include ::= id
```
## Semantics
### Groups
Groups contain the list of semantic conventions and it is the root node of each yaml file.
### Semantic Convention
The field `semconv` represents a semantic convention and it is made by:
- `id`, string that uniquely identifies the semantic convention.
- `brief`, string, a brief description of the semantic convention.
- `note`, optional string, a more elaborate description of the semantic convention.
It defaults to an empty string.
- `prefix`, optional string, prefix for the attributes for this semantic convention.
It defaults to an empty string.
- `extends`, optional string, reference another semantic convention `id`.
It inherits the prefix, constraints, and all attributes defined in the specified semantic convention.
- `span_kind`, optional enum, specifies the kind of the span.
- `attributes`, list of attributes that belong to the semantic convention.
- `constraints`, optional list, additional constraints (See later). It defaults to an empty list.
### Attributes
An attribute is defined by:
- `id`, string that uniquely identifies the attribute.
- `type`, either a string literal denoting the type or an enum definition (See later).
The accepted strings literals are:
* "string": String attributes.
* "number": Numeric attributes.
* "boolean": Boolean attributes.
* "string[]": Array of strings attributes.
* "number[]": Array of numbers attributes.
* "boolean[]": Array of booleans attributes.
- `ref`, optional string, reference an existing attribute, see later.
- `required`, optional, specifies if the attribute is mandatory.
Can be "always", or "conditional". When omitted, the attribute is not required.
When set to "conditional",the string provided as `<condition>` MUST specify
the conditions under which the attribute is required.
- `brief`, string, brief description of the attribute.
- `note`, optional string, additional notes to the attribute. It defaults to an empty string.
- `examples`, sequence/dictionary of example values for the attribute.
They are optional for boolean and enum attributes.
Example values must be of the same type of the attribute.
If only a single example is provided, it can directly be reported without encapsulating it into a sequence/dictionary.
Examples for setting the `examples` field:
A single example value for a string attribute. All the following three representations are equivalent:
```yaml
examples: 'this is a single string'
```
or
```yaml
examples: ['this is a single string']
```
or
```yaml
examples:
- 'this is a single string'
```
Attention, the following will throw a type mismatch error because a string type as example value is expected and not an array of string:
```yaml
examples:
- ['this is an error']
examples: [['this is an error']]
```
Multiple example values for a string attribute:
```yaml
examples: ['this is a single string', 'this is another one']
```
or
```yaml
examples:
- 'this is a single string'
- 'this is another one'
```
A single example value for an array of strings attribute:
```yaml
examples: ['first element of first array', 'second element of first array']
```
or
```yaml
examples:
- ['first element of first array', 'second element of first array']
```
Attention, the following will throw a type mismatch error because an array of strings as type for the example values is expected and not a string:
```yaml
examples: 'this is an error'
```
Multiple example values for an array of string attribute:
```yaml
examples: [ ['first element of first array', 'second element of first array'], ['first element of second array', 'second element of second array'] ]
```
or
```yaml
examples:
- ['first element of first array', 'second element of first array']
- ['first element of second array', 'second element of second array']
```
### Ref
`ref` MUST have an id of an existing attribute. When it is set, `id` and `type` MUST not be present.
`ref` is useful for specifying that an existing attribute of another semantic convention is part of
the current semantic convention and inherit its `brief`, `note`, and `example` values. However, if these
fields are present in the current attribute definition, they override the inherited values.
### Type
An attribute type can either be a string, number, boolean, array of strings, array of numbers,
array of booleans, or an enumeration. If it is an enumeration, additional fields are required:
- `allow_custom_values`, optional boolean, set to false to not accept values
other than the specified members. It defaults to `true`.
- `members`, list of enum entries.
An enum entry has the following fields:
- `id`, string that uniquely identifies the enum entry.
- `value`, string, number, or boolean, value of the enum entry.
- `brief`, optional string, brief description of the enum entry value. It defaults to the value of `id`.
- `note`, optional string, longer description. It defaults to an empty string.
### Constraints
Allow to define additional requirements on the semantic convention.
Currently, it supports `any_of` and `include`.
#### Any Of
`any_of` accepts a list of sequences. Each sequence contains a list of attribute ids that are required.
`any_of` enforces that all attributes of at least one of the sequences are set.
#### Include
`include` accepts a semantic conventions `id`. It includes as part of this semantic convention all constraints
and required attributes that are not already defined in the current semantic convention.

97
semantic_conventions/trace/general.yaml Normal file
View File

@ -0,0 +1,97 @@
groups:
- id: network
prefix: net
brief: >
These attributes may be used for any network related operation.
attributes:
- id: transport
type:
allow_custom_values: false
members:
- id: IP.TCP
value: "IP.TCP"
- id: IP.UDP
value: "IP.UDP"
- id: IP
value: "IP"
brief: 'Another IP-based protocol'
- id: Unix
value: "Unix"
brief: 'Unix Domain socket. See below.'
- id: pipe
value: "pipe"
brief: 'Named or anonymous pipe. See note below.'
- id: inproc
value: "inproc"
brief: 'In-process communication.'
note: >
Signals that there is only in-process communication not using a "real" network protocol
in cases where network attributes would normally be expected. Usually all other network
attributes can be left out in that case.
- id: other
value: "other"
brief: 'Something else (non IP-based).'
brief: >
Transport protocol used. See note below.
examples: 'IP.TCP'
- id: peer.ip
type: string
brief: >
Remote address of the peer (dotted decimal for IPv4 or
[RFC5952](https://tools.ietf.org/html/rfc5952) for IPv6)
examples: '127.0.0.1'
- id: peer.port
type: number
brief: 'Remote port number.'
examples: [80, 8080, 443]
- id: peer.name
type: string
brief: 'Remote hostname or similar, see note below.'
examples: 'example.com'
- id: host.ip
type: string
brief: 'Like `net.peer.ip` but for the host IP. Useful in case of a multi-IP host.'
examples: '192.168.0.1'
- id: host.port
type: number
brief: 'Like `net.peer.port` but for the host port.'
examples: 35555
- id: host.name
type: string
brief: 'Local hostname or similar, see note below.'
examples: 'localhost'
- id: peer
prefix: peer
brief: "Operations that access some remote service."
attributes:
- id: service
type: string
brief: >
The [`service.name`](../../resource/semantic_conventions/README.md#service)
of the remote service. SHOULD be equal to the actual `service.name`
resource attribute of the remote service if any.
examples: "AuthTokenCache"
- id: identity
prefix: enduser
brief: >
These attributes may be used for any operation with an authenticated and/or authorized enduser.
attributes:
- id: id
type: string
brief: >
Username or client_id extracted from the access token or
[Authorization](https://tools.ietf.org/html/rfc7235#section-4.2)
header in the inbound request from outside the system.
examples: 'username'
- id: role
type: string
brief: 'Actual/assumed role the client is making the request under extracted from token or application security context.'
examples: 'admin'
- id: scope
type: string
brief: >
Scopes or granted authorities the client currently possesses extracted from token
or application security context. The value would come from the scope associated
with an [OAuth 2.0 Access Token](https://tools.ietf.org/html/rfc6749#section-3.3)
or an attribute value in a [SAML 2.0 Assertion](http://docs.oasis-open.org/security/saml/Post2.0/sstc-saml-tech-overview-2.0.html).
examples: 'read:message, write:files'

147
semantic_conventions/trace/http.yaml Normal file
View File

@ -0,0 +1,147 @@
groups:
- id: http
prefix: http
brief: 'This document defines semantic conventions for HTTP client and server Spans.'
note: >
These conventions can be used for http and https schemes
and various HTTP versions like 1.1, 2 and SPDY.
attributes:
- id: method
type: string
required: always
brief: 'HTTP request method.'
examples: ["GET", "POST", "HEAD"]
- id: url
type: string
brief: >
Full HTTP request URL in the form `scheme://host[:port]/path?query[#fragment]`.
Usually the fragment is not transmitted over HTTP, but if it is known, it should be included nevertheless.
examples: ['https://www.foo.bar/search?q=OpenTelemetry#SemConv']
- id: target
type: string
brief: 'The full request target as passed in a HTTP request line or equivalent.'
examples: ['/path/12314/?q=ddds#123']
- id: host
type: string
brief: >
The value of the [HTTP host header](https://tools.ietf.org/html/rfc7230#section-5.4).
When the header is empty or not present, this attribute should be the same.
examples: ['www.example.org']
- id: scheme
type: string
brief: 'The URI scheme identifying the used protocol.'
examples: ["http", "https"]
- id: status_code
type: number
required:
conditional: If and only if one was received/sent.
brief: '[HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6).'
examples: [200]
- id: status_text
type: string
brief: '[HTTP reason phrase](https://tools.ietf.org/html/rfc7230#section-3.1.2).'
examples: ['OK']
- id: flavor
type:
# Default value: `true`. If false, it helps the code gen tool to
# encode checks that only accept the listed values.
allow_custom_values: true
members:
- id: HTTP_1_0
value: '1.0'
brief: 'HTTP 1.0'
- id: HTTP_1_1
value: '1.1'
brief: 'HTTP 1.1'
- id: HTTP_2_0
value: '2.0'
brief: 'HTTP 2'
- id: SPDY
value: 'SPDY'
brief: 'SPDY protocol.'
- id: QUIC
value: 'QUIC'
brief: 'QUIC protocol.'
brief: 'Kind of HTTP protocol used'
note: >
If `net.transport` is not specified, it can be assumed to be `IP.TCP` except if `http.flavor`
is `QUIC`, in which case `IP.UDP` is assumed.
examples: ['1.0']
- id: user_agent
type: string
brief: 'Value of the [HTTP User-Agent](https://tools.ietf.org/html/rfc7231#section-5.5.3) header sent by the client.'
examples: ['CERN-LineMode/2.15 libwww/2.17b3']
- id: request_content_length
type: number
brief: >
The size of the request payload body in bytes. This is the number of bytes transferred excluding headers and
is often, but not always, present as the [Content-Length](https://tools.ietf.org/html/rfc7230#section-3.3.2)
header. For requests using transport encoding, this should be the compressed size.
examples: 3495
- id: request_content_length_uncompressed
type: number
brief: >
The size of the uncompressed request payload body after transport decoding. Not set if transport encoding not used.
examples: 5493
- id: response_content_length
type: number
brief: >
The size of the response payload body in bytes. This is the number of bytes transferred excluding headers and
is often, but not always, present as the [Content-Length](https://tools.ietf.org/html/rfc7230#section-3.3.2)
header. For requests using transport encoding, this should be the compressed size.
examples: 3495
- id: response_content_length_uncompressed
type: number
brief: >
The size of the uncompressed response payload body after transport decoding. Not set if transport encoding not used.
examples: 5493
constraints:
- include: network
- id: http.client
prefix: http
extends: http
span_kind: client
brief: 'Semantic Convention for HTTP Client'
constraints:
- any_of:
- [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]
- id: http.server
prefix: http
extends: http
span_kind: server
brief: 'Semantic Convention for HTTP Server'
attributes:
- id: server_name
type: string
brief: >
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).
note: >
`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. open-telemetry/opentelemetry-python/pull/148).
It is thus preferred to supply the raw data that is available.
examples: ['example.com']
- id: route
type: string
brief: >
The matched route (path template).
examples: '/users/:userID?'
- id: client_ip
type: string
brief: >
The IP address of the original client behind all proxies, if
known (e.g. from [X-Forwarded-For](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-For)).
note: >
This is not necessarily the same as `net.peer.ip`, which would identify the network-level peer, which may be a proxy.
examples: '83.164.160.102'
constraints:
- any_of:
- [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]

1
semantic_conventions/version.properties Normal file
View File

@ -0,0 +1 @@
version=1

83
specification/trace/semantic_conventions/http.md
View File

@ -70,29 +70,39 @@ Note that the items marked with [1] are different from the mapping defined in th
## Common Attributes
| Attribute name | Notes and examples | Required? |
| :------------- | :----------------------------------------------------------- | --------- |
| `http.method` | HTTP request method. E.g. `"GET"`. | Yes |
| `http.url` | Full HTTP request URL in the form `scheme://host[:port]/path?query[#fragment]`. Usually the fragment is not transmitted over HTTP, but if it is known, it should be included nevertheless. | Defined later. |
| `http.target` | The full request target as passed in a [HTTP request line][] or equivalent, e.g. `"/path/12314/?q=ddds#123"`. | Defined later. |
| `http.host` | The value of the [HTTP host header][]. When the header is empty or not present, this attribute should be the same. | Defined later. |
| `http.scheme` | The URI scheme identifying the used protocol: `"http"` or `"https"` | Defined later. |
| `http.status_code` | [HTTP response status code][]. E.g. `200` (integer) | If and only if one was received/sent. |
| `http.status_text` | [HTTP reason phrase][]. E.g. `"OK"` | No |
| `http.flavor` | Kind of HTTP protocol used: `"1.0"`, `"1.1"`, `"2"`, `"SPDY"` or `"QUIC"`. | No |
| `http.user_agent` | Value of the HTTP [User-Agent][] header sent by the client. | No |
| `http.request_content_length` | The size of the request payload body in bytes. This is the number of bytes transferred excluding headers and is often, but not always, present as the [Content-Length][] header. For requests using transport encoding, this should be the compressed size. | No |
| `http.request_content_length_uncompressed` | The size of the uncompressed request payload body after transport decoding. Not set if transport encoding not used. | No |
| `http.response_content_length` | The size of the response payload body in bytes. This is the number of bytes transferred excluding headers and is often, but not always, present as the [Content-Length][] header. For requests using transport encoding, this should be the compressed size. | No |
| `http.response_content_length_uncompressed` | The size of the uncompressed response payload body after transport decoding. Not set if transport encoding not used. | No |
<!-- semconv http -->
| Attribute | Type | Description | Example | Required |
|---|---|---|---|---|
| `http.method` | string | HTTP request method. | `GET`<br>`POST`<br>`HEAD` | Yes |
| `http.url` | string | Full HTTP request URL in the form `scheme://host[:port]/path?query[#fragment]`. Usually the fragment is not transmitted over HTTP, but if it is known, it should be included nevertheless. | `https://www.foo.bar/search?q=OpenTelemetry#SemConv` | No |
| `http.target` | string | The full request target as passed in a HTTP request line or equivalent. | `/path/12314/?q=ddds#123` | No |
| `http.host` | string | The value of the [HTTP host header](https://tools.ietf.org/html/rfc7230#section-5.4). When the header is empty or not present, this attribute should be the same. | `www.example.org` | No |
| `http.scheme` | string | The URI scheme identifying the used protocol. | `http`<br>`https` | No |
| `http.status_code` | number | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | Conditional<br>If and only if one was received/sent. |
| `http.status_text` | string | [HTTP reason phrase](https://tools.ietf.org/html/rfc7230#section-3.1.2). | `OK` | No |
| `http.flavor` | string | Kind of HTTP protocol used [1] | `1.0` | No |
| `http.user_agent` | string | Value of the [HTTP User-Agent](https://tools.ietf.org/html/rfc7231#section-5.5.3) header sent by the client. | `CERN-LineMode/2.15 libwww/2.17b3` | No |
| `http.request_content_length` | number | The size of the request payload body in bytes. This is the number of bytes transferred excluding headers and is often, but not always, present as the [Content-Length](https://tools.ietf.org/html/rfc7230#section-3.3.2) header. For requests using transport encoding, this should be the compressed size. | `3495` | No |
| `http.request_content_length_uncompressed` | number | The size of the uncompressed request payload body after transport decoding. Not set if transport encoding not used. | `5493` | No |
| `http.response_content_length` | number | The size of the response payload body in bytes. This is the number of bytes transferred excluding headers and is often, but not always, present as the [Content-Length](https://tools.ietf.org/html/rfc7230#section-3.3.2) header. For requests using transport encoding, this should be the compressed size. | `3495` | No |
| `http.response_content_length_uncompressed` | number | The size of the uncompressed response payload body after transport decoding. Not set if transport encoding not used. | `5493` | No |
**[1]:** If `net.transport` is not specified, it can be assumed to be `IP.TCP` except if `http.flavor` is `QUIC`, in which case `IP.UDP` is assumed.
`http.flavor` MUST be one of the following or, if none of the listed values apply, a custom value:
| Value | Description |
|---|---|
| `1.0` | HTTP 1.0 |
| `1.1` | HTTP 1.1 |
| `2.0` | HTTP 2 |
| `SPDY` | SPDY protocol. |
| `QUIC` | QUIC protocol. |
<!-- endsemconv -->
It is recommended to also use the general [network attributes][], especially `net.peer.ip`. If `net.transport` is not specified, it can be assumed to be `IP.TCP` except if `http.flavor` is `QUIC`, in which case `IP.UDP` is assumed.
[network attributes]: span-general.md#general-network-connection-attributes
[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
[User-Agent]: https://tools.ietf.org/html/rfc7231#section-5.5.3
[Content-Length]: https://tools.ietf.org/html/rfc7230#section-3.3.2
## HTTP client
@ -103,12 +113,15 @@ 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.
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):
<!-- semconv http.client -->
**Additional attribute requirements:** At least one of the following sets of attributes is required:
* `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`
* `http.scheme`, [`net.peer.name`](span-general.md), [`net.peer.port`](span-general.md), `http.target`
* `http.scheme`, [`net.peer.ip`](span-general.md), [`net.peer.port`](span-general.md), `http.target`
<!-- endsemconv -->
Note that in some cases `http.host` might be different
from the `net.peer.name`
@ -188,24 +201,24 @@ 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.
| 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] |
| `http.route` | The matched route (path template). (TODO: Define whether to prepend application root) E.g. `"/users/:userID?"`. | No |
| `http.client_ip` | The IP address of the original client behind all proxies, if known (e.g. from [X-Forwarded-For][]). Note that this is not necessarily the same as `net.peer.ip`, which would identify the network-level peer, which may be a proxy. | No |
<!-- semconv http.server -->
| Attribute | Type | Description | Example | Required |
|---|---|---|---|---|
| `http.server_name` | string | 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] | `example.com` | See below |
| `http.route` | string | The matched route (path template). | `/users/:userID?` | No |
| `http.client_ip` | string | The IP address of the original client behind all proxies, if known (e.g. from [X-Forwarded-For](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-For)). [2] | `83.164.160.102` | No |
[HTTP request line]: https://tools.ietf.org/html/rfc7230#section-3.1.1
[HTTP host header]: https://tools.ietf.org/html/rfc7230#section-5.4
[X-Forwarded-For]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-For
**[1]:** `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. open-telemetry/opentelemetry-python/pull/148). It is thus preferred to supply the raw data that is available.
**[1]**: `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. <https://github.com/open-telemetry/opentelemetry-python/pull/148>).
It is thus preferred to supply the raw data that *is* available.
Namely, one of the following sets is required (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):
**[2]:** This is not necessarily the same as `net.peer.ip`, which would identify the network-level peer, which may be a proxy.
**Additional attribute requirements:** At least one of the following sets of attributes is required:
* `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.scheme`, `http.server_name`, [`net.host.port`](span-general.md), `http.target`
* `http.scheme`, [`net.host.name`](span-general.md), [`net.host.port`](span-general.md), `http.target`
* `http.url`
<!-- endsemconv -->
Of course, more than the required attributes can be supplied, but this is recommended only if they cannot be inferred from the sent ones.
For example, `http.server_name` has shown great value in practice, as bogus HTTP Host headers occur often in the wild.

65
specification/trace/semantic_conventions/span-general.md
View File

@ -26,32 +26,33 @@ while the `net.host.*` properties describe the local end.
In an ideal situation, not accounting for proxies, multiple IP addresses or host names,
the `net.peer.*` properties of a client are equal to the `net.host.*` properties of the server and vice versa.
| Attribute name | Notes and examples |
| :--------------- | :-------------------------------------------------------------------------------- |
| `net.transport` | Transport protocol used. See [note below](#net.transport). |
| `net.peer.ip` | Remote address of the peer (dotted decimal for IPv4 or [RFC5952][] for IPv6) |
| `net.peer.port` | Remote port number as an integer. E.g., `80`. |
| `net.peer.name` | Remote hostname or similar, see [note below](#net.name). |
| `net.host.ip` | Like `net.peer.ip` but for the host IP. Useful in case of a multi-IP host. |
| `net.host.port` | Like `net.peer.port` but for the host port. |
| `net.host.name` | Local hostname or similar, see [note below](#net.name). |
<a name="nettransport-attribute">
<!-- semconv network -->
| Attribute | Type | Description | Example | Required |
|---|---|---|---|---|
| `net.transport` | string enum | Transport protocol used. See note below. | `IP.TCP` | No |
| `net.peer.ip` | string | Remote address of the peer (dotted decimal for IPv4 or [RFC5952](https://tools.ietf.org/html/rfc5952) for IPv6) | `127.0.0.1` | No |
| `net.peer.port` | number | Remote port number. | `80`<br>`8080`<br>`443` | No |
| `net.peer.name` | string | Remote hostname or similar, see note below. | `example.com` | No |
| `net.host.ip` | string | Like `net.peer.ip` but for the host IP. Useful in case of a multi-IP host. | `192.168.0.1` | No |
| `net.host.port` | number | Like `net.peer.port` but for the host port. | `35555` | No |
| `net.host.name` | string | Local hostname or similar, see note below. | `localhost` | No |
[RFC5952]: https://tools.ietf.org/html/rfc5952
`net.transport` MUST be one of the following:
<a name="net.transport"></a>
| Value | Description |
|---|---|
| `IP.TCP` | IP.TCP |
| `IP.UDP` | IP.UDP |
| `IP` | Another IP-based protocol |
| `Unix` | Unix Domain socket. See below. |
| `pipe` | Named or anonymous pipe. See note below. |
| `inproc` | In-process communication. [1] |
| `other` | Something else (non IP-based). |
### `net.transport` attribute
This attribute should be set to the name of the transport layer protocol (or the relevant protocol below the "application protocol"). One of these strings should be used:
* `IP.TCP`
* `IP.UDP`
* `IP`: Another IP-based protocol.
* `Unix`: Unix Domain socket. See note below.
* `pipe`: Named or anonymous pipe. See note below.
* `inproc`: Signals that there is only in-process communication not using a "real" network protocol in cases where network attributes would normally be expected. Usually all other network attributes can be left out in that case.
* `other`: Something else (not IP-based).
**[1]:** Signals that there is only in-process communication not using a "real" network protocol in cases where network attributes would normally be expected. Usually all other network attributes can be left out in that case.
<!-- endsemconv -->
For `Unix` and `pipe`, since the connection goes over the file system instead of being directly to a known peer, `net.peer.name` is the only attribute that usually makes sense (see description of `net.peer.name` below).
<a name="net.name"></a>
@ -77,9 +78,11 @@ This attribute may be used for any operation that accesses some remote service.
Users can define what the name of a service is based on their particular semantics in their distributed system.
Instrumentations SHOULD provide a way for users to configure this name.
| Attribute name | Notes and examples |
| :-------------- | :-------------------------------------------------------------------------------- |
| `peer.service` | The [`service.name`](../../resource/semantic_conventions/README.md#service) of the remote service. SHOULD be equal to the actual `service.name` resource attribute of the remote service if any. |
<!-- semconv peer -->
| Attribute | Type | Description | Example | Required |
|---|---|---|---|---|
| `peer.service` | string | The [`service.name`](../../resource/semantic_conventions/README.md#service) of the remote service. SHOULD be equal to the actual `service.name` resource attribute of the remote service if any. | `AuthTokenCache` | No |
<!-- endsemconv -->
Examples of `peer.service` that users may specify:
@ -90,11 +93,13 @@ Examples of `peer.service` that users may specify:
These attributes may be used for any operation with an authenticated and/or authorized enduser.
| Attribute name | Notes and examples |
| :-------------- | :-------------------------------------------------------------------------------- |
| `enduser.id` | Username or client_id extracted from the access token or [Authorization] header in the inbound request from outside the system. |
| `enduser.role` | Actual/assumed role the client is making the request under extracted from token or application security context. |
| `enduser.scope` | Scopes or granted authorities the client currently possesses extracted from token or application security context. The value would come from the scope associated with an [OAuth 2.0 Access Token] or an attribute value in a [SAML 2.0 Assertion]. |
<!-- semconv identity -->
| Attribute | Type | Description | Example | Required |
|---|---|---|---|---|
| `enduser.id` | string | Username or client_id extracted from the access token or [Authorization](https://tools.ietf.org/html/rfc7235#section-4.2) header in the inbound request from outside the system. | `username` | No |
| `enduser.role` | string | Actual/assumed role the client is making the request under extracted from token or application security context. | `admin` | No |
| `enduser.scope` | string | Scopes or granted authorities the client currently possesses extracted from token or application security context. The value would come from the scope associated with an [OAuth 2.0 Access Token](https://tools.ietf.org/html/rfc6749#section-3.3) or an attribute value in a [SAML 2.0 Assertion](http://docs.oasis-open.org/security/saml/Post2.0/sstc-saml-tech-overview-2.0.html). | `read:message, write:files` | No |
<!-- endsemconv -->
These attributes describe the authenticated user driving the user agent making requests to the instrumented
system. It is expected this information would be propagated unchanged from node-to-node within the system