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 documents to be used in spell check.
ALL_DOCS := $(shell find . -name '*.md' -not -path './.github/*' -type f | grep -v ^./node_modules | sort) ALL_DOCS := $(shell find . -name '*.md' -not -path './.github/*' -type f | grep -v ^./node_modules | sort)
PWD := $(shell pwd)
TOOLS_DIR := ./.tools TOOLS_DIR := ./.tools
MISSPELL_BINARY=$(TOOLS_DIR)/misspell MISSPELL_BINARY=$(TOOLS_DIR)/misspell
MARKDOWN_LINK_CHECK=markdown-link-check MARKDOWN_LINK_CHECK=markdown-link-check
MARKDOWN_LINT=markdownlint MARKDOWN_LINT=markdownlint
.PHONY: install-misspell .PHONY: install-misspell
install-misspell: install-misspell:
go build -o $(MISSPELL_BINARY) github.com/client9/misspell/cmd/misspell go build -o $(MISSPELL_BINARY) github.com/client9/misspell/cmd/misspell
@ -34,3 +36,7 @@ install-markdown-lint:
markdown-lint: markdown-lint:
@echo $(ALL_DOCS) @echo $(ALL_DOCS)
@for f in $(ALL_DOCS); do echo $$f; $(MARKDOWN_LINT) -c .markdownlint.yaml $$f || exit 1; done @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 ## Common Attributes
| Attribute name | Notes and examples | Required? | <!-- semconv http -->
| :------------- | :----------------------------------------------------------- | --------- | | Attribute | Type | Description | Example | 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.method` | string | HTTP request method. | `GET`<br>`POST`<br>`HEAD` | Yes |
| `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.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.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.target` | string | The full request target as passed in a HTTP request line or equivalent. | `/path/12314/?q=ddds#123` | No |
| `http.scheme` | The URI scheme identifying the used protocol: `"http"` or `"https"` | Defined later. | | `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.status_code` | [HTTP response status code][]. E.g. `200` (integer) | If and only if one was received/sent. | | `http.scheme` | string | The URI scheme identifying the used protocol. | `http`<br>`https` | No |
| `http.status_text` | [HTTP reason phrase][]. E.g. `"OK"` | 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.flavor` | Kind of HTTP protocol used: `"1.0"`, `"1.1"`, `"2"`, `"SPDY"` or `"QUIC"`. | No | | `http.status_text` | string | [HTTP reason phrase](https://tools.ietf.org/html/rfc7230#section-3.1.2). | `OK` | No |
| `http.user_agent` | Value of the HTTP [User-Agent][] header sent by the client. | No | | `http.flavor` | string | Kind of HTTP protocol used [1] | `1.0` | 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.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_uncompressed` | The size of the uncompressed request payload body after transport decoding. Not set if transport encoding not used. | 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.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.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_uncompressed` | The size of the uncompressed response payload body after transport decoding. Not set if transport encoding not used. | 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. 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 [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 ## 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, If set, `http.url` must be the originally requested URL,
before any HTTP-redirects that may happen when executing the request. 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.url`
* `http.scheme`, `http.host`, `http.target` * `http.scheme`, `http.host`, `http.target`
* `http.scheme`, `net.peer.name`, `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`, `net.peer.port`, `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 Note that in some cases `http.host` might be different
from the `net.peer.name` 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. 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? | <!-- semconv http.server -->
| :------------- | :----------------------------------------------------------- | --------- | | Attribute | Type | Description | Example | 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.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.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 | | `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 **[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.
[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. <https://github.com/open-telemetry/opentelemetry-python/pull/148>). **[2]:** This is not necessarily the same as `net.peer.ip`, which would identify the network-level peer, which may be a proxy.
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): **Additional attribute requirements:** At least one of the following sets of attributes is required:
* `http.scheme`, `http.host`, `http.target` * `http.scheme`, `http.host`, `http.target`
* `http.scheme`, `http.server_name`, `net.host.port`, `http.target` * `http.scheme`, `http.server_name`, [`net.host.port`](span-general.md), `http.target`
* `http.scheme`, `net.host.name`, `net.host.port`, `http.target` * `http.scheme`, [`net.host.name`](span-general.md), [`net.host.port`](span-general.md), `http.target`
* `http.url` * `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. 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. 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, 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. 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 | <a name="nettransport-attribute">
| :--------------- | :-------------------------------------------------------------------------------- | <!-- semconv network -->
| `net.transport` | Transport protocol used. See [note below](#net.transport). | | Attribute | Type | Description | Example | Required |
| `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.transport` | string enum | Transport protocol used. See note below. | `IP.TCP` | No |
| `net.peer.name` | Remote hostname or similar, see [note below](#net.name). | | `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.host.ip` | Like `net.peer.ip` but for the host IP. Useful in case of a multi-IP host. | | `net.peer.port` | number | Remote port number. | `80`<br>`8080`<br>`443` | No |
| `net.host.port` | Like `net.peer.port` but for the host port. | | `net.peer.name` | string | Remote hostname or similar, see note below. | `example.com` | No |
| `net.host.name` | Local hostname or similar, see [note below](#net.name). | | `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 **[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.
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).
<!-- 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). 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> <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. 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. Instrumentations SHOULD provide a way for users to configure this name.
| Attribute name | Notes and examples | <!-- semconv peer -->
| :-------------- | :-------------------------------------------------------------------------------- | | Attribute | Type | Description | Example | Required |
| `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. | |---|---|---|---|---|
| `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: 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. These attributes may be used for any operation with an authenticated and/or authorized enduser.
| Attribute name | Notes and examples | <!-- semconv identity -->
| :-------------- | :-------------------------------------------------------------------------------- | | Attribute | Type | Description | Example | Required |
| `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.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.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]. | | `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 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 system. It is expected this information would be propagated unchanged from node-to-node within the system