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: request.method_original
        type: string
        requirement_level:
          conditionally_required: If and only if it's different than `http.request.method`.
        brief: Original HTTP method sent by the client in the request line.
        examples: ["GeT", "ACL", "foo"]
      - id: request.body.size
        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.body.size
        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.request.method
        sampling_relevant: true
      - ref: network.transport
        requirement_level:
          conditionally_required: If not default (`tcp` for `HTTP/1.1` and `HTTP/2`, `udp` for `HTTP/3`).
      - ref: network.type
      - ref: user_agent.original

  - id: trace.http.client
    prefix: http
    type: span
    extends: attributes.http.client
    span_kind: client
    brief: 'Semantic Convention for HTTP Client'
    attributes:
      - 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: server.address
        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

          If an HTTP client request is explicitly made to an IP address, e.g. `http://x.x.x.x:8080`, then
          `server.address` SHOULD be the IP address `x.x.x.x`. A DNS lookup SHOULD NOT be used.          
      - ref: server.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, `server.port` MUST match
          URI port identifier, otherwise it MUST match `Host` header port identifier.          
      - ref: server.socket.domain
      - ref: server.socket.address
      - ref: server.socket.port
      - ref: url.full
        sampling_relevant: true
        requirement_level: required


  - id: trace.http.server
    prefix: http
    type: span
    extends: attributes.http.server
    span_kind: server
    brief: 'Semantic Convention for HTTP Server'
    attributes:
      - ref: server.address
        requirement_level: recommended
        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/http/http-spans.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: server.port
        sampling_relevant: true
        requirement_level:
          recommended: 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/http/http-spans.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: server.socket.address
        requirement_level: opt_in
        brief: Local socket address. Useful in case of a multi-IP host.
      - ref: server.socket.port
        requirement_level: opt_in
        brief: Local socket port. Useful in case of a multi-port host.
      - ref: client.address
        note: >
            The IP address of the original client behind all proxies, if
            known (e.g. from [Forwarded](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Forwarded),
            [X-Forwarded-For](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-For), or a similar header).
            Otherwise, the immediate client peer address.            
        examples: ['83.164.160.102']
      - ref: client.port
        brief: >
            The port of the original client behind all proxies, if
            known (e.g. from [Forwarded](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Forwarded) or a similar header).
            Otherwise, the immediate client peer port.            
      - ref: client.socket.address
      - ref: client.socket.port
      - ref: url.path
        requirement_level: required
        sampling_relevant: true
      - ref: url.query
        requirement_level:
          conditionally_required: If and only if one was received/sent.
        sampling_relevant: true
      - ref: url.scheme
        sampling_relevant: true
        requirement_level: required
        examples: ["http", "https"]