semantic-conventions/semantic_conventions/trace/http.yaml

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]