semantic-conventions/model/http/common.yaml

groups:
  - id: attributes.http.common
    type: attribute_group
    brief: "Describes HTTP attributes."
    attributes:
      - ref: http.request.method
        requirement_level: required
      - ref: http.response.status_code
        requirement_level:
          conditionally_required: If and only if one was received/sent.
      - ref: error.type
        requirement_level:
          conditionally_required: If request has ended with an error.
        examples: ['timeout', 'java.net.UnknownHostException', 'server_certificate_invalid', '500']
        note: |
          If the request fails with an error before response status code was sent or received,
          `error.type` SHOULD be set to exception type (its fully-qualified class name, if applicable)
          or a component-specific low cardinality error identifier.

          If response status code was sent or received and status indicates an error according to [HTTP span status definition](/docs/http/http-spans.md),
          `error.type` SHOULD be set to the status code number (represented as a string), an exception type (if thrown) or a component-specific error identifier.

          The `error.type` value SHOULD be predictable and SHOULD have low cardinality.
          Instrumentations SHOULD document the list of errors they report.

          The cardinality of `error.type` within one instrumentation library SHOULD be low, but
          telemetry consumers that aggregate data from multiple instrumentation libraries and applications
          should be prepared for `error.type` to have high cardinality at query time, when no
          additional filters are applied.

          If the request has completed successfully, instrumentations SHOULD NOT set `error.type`.          
      - ref: network.protocol.name
        examples: ['http', 'spdy']
        requirement_level:
          conditionally_required: If not `http` and `network.protocol.version` is set.
      - ref: network.protocol.version
        examples: ['1.0', '1.1', '2', '3']

  - id: attributes.http.client
    type: attribute_group
    brief: 'HTTP Client attributes'
    extends: attributes.http.common
    attributes:
      - ref: server.address
        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: >
          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
        requirement_level: required
        brief: >
          Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to.          
      - ref: url.scheme
        requirement_level: opt_in
        examples: ["http", "https"]
      - ref: url.template
        requirement_level: opt_in
        note: >
          The `url.template` MUST have low cardinality. It is not usually available on HTTP clients, but may be known by the application or specialized HTTP instrumentation.          

  - id: attributes.http.server
    type: attribute_group
    brief: 'HTTP Server attributes'
    extends: attributes.http.common
    attributes:
      - ref: http.route
        requirement_level:
          conditionally_required: If and only if it's available
      - ref: server.address
        brief: >
          Name of the local HTTP server that received the request.          
        note: >
          See [Setting `server.address` and `server.port` attributes](/docs/http/http-spans.md#setting-serveraddress-and-serverport-attributes).          
      - ref: server.port
        brief: >
          Port of the local HTTP server that received the request.          
        note: >
          See [Setting `server.address` and `server.port` attributes](/docs/http/http-spans.md#setting-serveraddress-and-serverport-attributes).          
        requirement_level:
          conditionally_required: If available and `server.address` is set.
      - ref: url.scheme
        requirement_level: required
        examples: ["http", "https"]
        note: >
          The scheme of the original client request, if known
          (e.g. from [Forwarded#proto](https://developer.mozilla.org/docs/Web/HTTP/Headers/Forwarded#proto),
          [X-Forwarded-Proto](https://developer.mozilla.org/docs/Web/HTTP/Headers/X-Forwarded-Proto),
          or a similar header).
          Otherwise, the scheme of the immediate peer request.