semantic-conventions/semantic_conventions/trace/http.yaml

groups:
  - id: trace.http.common
    prefix: http
    extends: attributes.http.common
    type: attribute_group
    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: user_agent
        type: string
        brief: 'Value of the [HTTP User-Agent](https://www.rfc-editor.org/rfc/rfc9110.html#field.user-agent) header sent by the client.'
        examples: ['CERN-LineMode/2.15 libwww/2.17b3']
      - id: request_content_length
        type: int
        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://www.rfc-editor.org/rfc/rfc9110.html#field.content-length)
          header. For requests using transport encoding, this should be the compressed size.          
        examples: 3495
      - id: response_content_length
        type: int
        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://www.rfc-editor.org/rfc/rfc9110.html#field.content-length)
          header. For requests using transport encoding, this should be the compressed size.          
        examples: 3495
      - ref: http.method
        sampling_relevant: true
      - ref: net.sock.peer.addr
      - ref: net.sock.peer.port
      - ref: net.sock.peer.name
      - ref: net.sock.family
        examples: ['inet', 'inet6']

  - id: trace.http.client
    prefix: http
    type: span
    extends: attributes.http.client
    span_kind: client
    brief: 'Semantic Convention for HTTP Client'
    attributes:
      - id: url
        type: string
        requirement_level: required
        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.            
        note: >
          `http.url` MUST NOT contain credentials passed via URL in form of `https://username:password@www.example.com/`.
          In such case the attribute's value should be `https://www.example.com/`.          
        sampling_relevant: true
        examples: ['https://www.foo.bar/search?q=OpenTelemetry#SemConv']
      - id: resend_count
        type: int
        brief: >
          The ordinal number of request resending attempt (for any reason, including redirects).          
        note: >
          The resend count SHOULD be updated each time an HTTP request gets resent by the client, regardless of what
          was the cause of the resending (e.g. redirection, authorization failure, 503 Server Unavailable, network issues,
          or any other).          
        requirement_level:
          recommended: if and only if request was retried.
        examples: 3
      - ref: net.peer.name
        sampling_relevant: true
        requirement_level: required
        brief: >
          Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to.          
        note: |
          Determined by using the first of the following that applies

          - Host identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource)
            if it's sent in absolute-form
          - Host identifier of the `Host` header

          SHOULD NOT be set if capturing it would require an extra DNS lookup.          
      - ref: net.peer.port
        sampling_relevant: true
        requirement_level:
          conditionally_required: If not default (`80` for `http` scheme, `443` for `https`).
        brief: >
          Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to.          
        note: >
          When [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) is absolute URI, `net.peer.name` MUST match
          URI port identifier, otherwise it MUST match `Host` header port identifier.          

  - id: trace.http.server
    prefix: http
    type: span
    extends: attributes.http.server
    span_kind: server
    brief: 'Semantic Convention for HTTP Server'
    attributes:
      - id: target
        type: string
        brief: 'The full request target as passed in a HTTP request line or equivalent.'
        requirement_level: required
        sampling_relevant: true
        examples: ['/path/12314/?q=ddds']
      - 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.sock.peer.addr`, which would
            identify the network-level peer, which may be a proxy.

            This attribute should be set when a source of information different
            from the one used for `net.sock.peer.addr`, is available even if that other
            source just confirms the same value as `net.sock.peer.addr`.
            Rationale: For `net.sock.peer.addr`, one typically does not know if it
            comes from a proxy, reverse proxy, or the actual client. Setting
            `http.client_ip` when it's the same as `net.sock.peer.addr` means that
            one is at least somewhat confident that the address is not that of
            the closest proxy.            
        examples: '83.164.160.102'
      - ref: http.scheme
        sampling_relevant: true
      - ref: net.host.name
        requirement_level: required
        sampling_relevant: true
        brief: >
          Name of the local HTTP server that received the request.          
        note: |
          Determined by using the first of the following that applies

          - The [primary server name](/specification/trace/semantic_conventions/http.md#http-server-definitions) of the matched virtual host. MUST only
            include host identifier.
          - Host identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource)
            if it's sent in absolute-form.
          - Host identifier of the `Host` header

          SHOULD NOT be set if only IP address is available and capturing name would require a reverse DNS lookup.          

      - ref: net.host.port
        sampling_relevant: true
        requirement_level:
          conditionally_required: If not default (`80` for `http` scheme, `443` for `https`).
        brief: >
          Port of the local HTTP server that received the request.          
        note: |
          Determined by using the first of the following that applies

          - Port identifier of the [primary server host](/specification/trace/semantic_conventions/http.md#http-server-definitions) of the matched virtual host.
          - Port identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource)
            if it's sent in absolute-form.
          - Port identifier of the `Host` header          
      - ref: net.sock.host.addr
        requirement_level: opt_in
      - ref: net.sock.host.port