semantic-conventions/model/http/spans.yaml

groups:
  - id: span.http.client
    type: span
    extends: attributes.http.client
    span_kind: client
    stability: stable
    brief: >
      This span represents an outbound HTTP request.      
    note: |
      There are two ways HTTP client spans can be implemented in an instrumentation:

      1. Instrumentations SHOULD create an HTTP span for each attempt to send an HTTP request over the wire.
         In case the request is resent, the resend attempts MUST follow the [HTTP resend spec](#http-request-retries-and-redirects).
         In this case, instrumentations SHOULD NOT (also) emit a logical encompassing HTTP client span.

      2. If for some reason it is not possible to emit a span for each send attempt (because e.g. the instrumented library does not expose hooks that would allow this),
         instrumentations MAY create an HTTP span for the top-most operation of the HTTP client.
         In this case, the `url.full` MUST be the absolute URL that was originally requested, before any HTTP-redirects that may happen when executing the request.

      **Span name:** refer to the [Span Name](/docs/http/http-spans.md#name) section.

      **Span kind** MUST be `CLIENT`.

      **Span status:** refer to the [Span Status](/docs/http/http-spans.md#status) section.      
    attributes:
      - ref: http.request.method
        sampling_relevant: true
      - ref: http.request.method_original
        requirement_level:
          conditionally_required: If and only if it's different than `http.request.method`.
      - ref: http.request.resend_count
        requirement_level:
          recommended: if and only if request was retried.
      - ref: http.request.header
        requirement_level: opt_in
      - ref: http.response.header
        requirement_level: opt_in
      - ref: server.address
        sampling_relevant: true
      - ref: server.port
        sampling_relevant: true
      - ref: url.full
        sampling_relevant: true
        requirement_level: required
      - ref: user_agent.original
        requirement_level: opt_in
      - ref: url.scheme
      - ref: network.peer.address
      - ref: network.peer.port
        requirement_level:
          recommended: If `network.peer.address` is set.
      - ref: network.transport
        requirement_level: opt_in
        note: >
          Generally `tcp` for `HTTP/1.0`, `HTTP/1.1`, and `HTTP/2`. Generally `udp` for `HTTP/3`.
          Other obscure implementations are possible.          
      - ref: http.request.size
        requirement_level: opt_in
      - ref: http.response.size
        requirement_level: opt_in
      - ref: http.request.body.size
        requirement_level: opt_in
      - ref: http.response.body.size
        requirement_level: opt_in
      - ref: user_agent.synthetic.type
        requirement_level: opt_in

  - id: span.http.server
    type: span
    extends: attributes.http.server
    span_kind: server
    brief: >
      This span represents an inbound HTTP request.      
    note: |
      **Span name:** refer to the [Span Name](/docs/http/http-spans.md#name) section.

      **Span kind** MUST be `SERVER`.

      **Span status:** refer to the [Span Status](/docs/http/http-spans.md#status) section.      
    stability: stable
    attributes:
      - ref: http.request.method
        sampling_relevant: true
      - ref: http.request.method_original
        requirement_level:
          conditionally_required: If and only if it's different than `http.request.method`.
      - ref: http.route
      - ref: http.request.header
        sampling_relevant: true
        requirement_level: opt_in
      - ref: http.response.header
        requirement_level: opt_in
      - ref: server.address
        sampling_relevant: true
      - ref: server.port
        sampling_relevant: true
      - ref: network.local.address
        requirement_level: opt_in
        brief: Local socket address. Useful in case of a multi-IP host.
      - ref: network.local.port
        requirement_level: opt_in
        brief: Local socket port. Useful in case of a multi-port host.
      - ref: client.address
        sampling_relevant: true
        note: >
            The IP address of the original client behind all proxies, if
            known (e.g. from [Forwarded#for](https://developer.mozilla.org/docs/Web/HTTP/Headers/Forwarded#for),
            [X-Forwarded-For](https://developer.mozilla.org/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
        requirement_level: opt_in
        brief: The port of whichever client was captured in `client.address`.
      - 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
      - ref: user_agent.original
        sampling_relevant: true
      - ref: network.peer.address
      - ref: network.peer.port
        requirement_level:
          recommended: If `network.peer.address` is set.
      - ref: network.transport
        requirement_level: opt_in
        note: >
          Generally `tcp` for `HTTP/1.0`, `HTTP/1.1`, and `HTTP/2`. Generally `udp` for `HTTP/3`.
          Other obscure implementations are possible.          
      - ref: http.request.size
        requirement_level: opt_in
      - ref: http.response.size
        requirement_level: opt_in
      - ref: http.request.body.size
        requirement_level: opt_in
      - ref: http.response.body.size
        requirement_level: opt_in
      - ref: user_agent.synthetic.type
        requirement_level: opt_in