Set span kind on span definitions or change ambiguous spans to attribute groups (#1890)

lmolkova · web-flow · commit 152a9c3cc4c6 · 2025-02-12T10:45:31.000-08:00
diff --git a/.chloggen/1889.yaml b/.chloggen/1889.yaml
diff --git a/docs/faas/aws-lambda.md b/docs/faas/aws-lambda.md
@@ -42,7 +42,7 @@ The following attributes SHOULD be set:
 Also consider setting other attributes of the [`faas` resource][faasres] and [trace][faas] conventions
 and the [cloud resource conventions][cloud]. The following AWS Lambda-specific attribute MAY also be set:
 
-<!-- semconv span.aws.lambda -->
+<!-- semconv span.aws.lambda.server -->
 <!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
 <!-- see templates/registry/markdown/snippet.md.j2 -->
 <!-- prettier-ignore-start -->
diff --git a/docs/faas/faas-spans.md b/docs/faas/faas-spans.md
@@ -38,7 +38,7 @@ Refer to the [Recording Errors](/docs/general/recording-errors.md) document for
 
 If Spans following this convention are produced, a Resource of type `faas` MUST exist following the [Resource semantic convention](../resource/faas.md).
 
-<!-- semconv span.faas -->
+<!-- semconv faas.attributes -->
 <!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
 <!-- see templates/registry/markdown/snippet.md.j2 -->
 <!-- prettier-ignore-start -->
@@ -242,7 +242,7 @@ This section describes how to handle the span creation and additional attributes
 A datasource function is triggered as a response to some data source operation such as a database or filesystem read/write.
 FaaS instrumentations that produce `faas` spans with trigger `datasource`, SHOULD use the following set of attributes.
 
-<!-- semconv span.faas.datasource -->
+<!-- semconv span.faas.datasource.server -->
 <!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
 <!-- see templates/registry/markdown/snippet.md.j2 -->
 <!-- prettier-ignore-start -->
@@ -287,7 +287,7 @@ This way, it is possible to correlate each individual message with its invocatio
 
 A function is scheduled to be executed regularly. The following additional attributes are recommended.
 
-<!-- semconv span.faas.timer -->
+<!-- semconv span.faas.timer.server -->
 <!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
 <!-- see templates/registry/markdown/snippet.md.j2 -->
 <!-- prettier-ignore-start -->
diff --git a/docs/gen-ai/gen-ai-spans.md b/docs/gen-ai/gen-ai-spans.md
@@ -164,7 +164,7 @@ Additional output format details may be recorded in the future in the `gen_ai.ou
 
 ## Execute Tool Span
 
-<!-- semconv span.gen_ai.client.execute_tool -->
+<!-- semconv span.gen_ai.execute_tool.internal -->
 <!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
 <!-- see templates/registry/markdown/snippet.md.j2 -->
 <!-- prettier-ignore-start -->
diff --git a/docs/messaging/messaging-spans.md b/docs/messaging/messaging-spans.md
@@ -369,7 +369,7 @@ Messaging attributes are organized into the following namespaces:
 
 Messaging system-specific attributes MUST be defined in the corresponding `messaging.{system}` namespace.
 
-<!-- semconv span.messaging -->
+<!-- semconv messaging.attributes -->
 <!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
 <!-- see templates/registry/markdown/snippet.md.j2 -->
 <!-- prettier-ignore-start -->
diff --git a/docs/rpc/connect-rpc.md b/docs/rpc/connect-rpc.md
@@ -16,7 +16,7 @@ described on this page.
 
 Below is a table of attributes that SHOULD be included on client and server Connect RPC measurements.
 
-<!-- semconv span.rpc.connect_rpc(tag=connect_rpc-tech-specific) -->
+<!-- semconv rpc.connect_rpc.attributes -->
 <!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
 <!-- see templates/registry/markdown/snippet.md.j2 -->
 <!-- prettier-ignore-start -->
diff --git a/docs/rpc/grpc.md b/docs/rpc/grpc.md
@@ -16,7 +16,7 @@ described on this page.
 
 Below is a table of attributes that SHOULD be included on client and server gRPC measurements.
 
-<!-- semconv span.rpc.grpc(tag=grpc-tech-specific) -->
+<!-- semconv rpc.grpc.attributes -->
 <!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
 <!-- see templates/registry/markdown/snippet.md.j2 -->
 <!-- prettier-ignore-start -->
diff --git a/docs/rpc/json-rpc.md b/docs/rpc/json-rpc.md
@@ -14,7 +14,7 @@ described on this page.
 
 `rpc.system` MUST be set to `"jsonrpc"`.
 
-<!-- semconv span.rpc.jsonrpc(tag=jsonrpc-tech-specific) -->
+<!-- semconv rpc.jsonrpc.attributes -->
 <!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
 <!-- see templates/registry/markdown/snippet.md.j2 -->
 <!-- prettier-ignore-start -->
diff --git a/model/aws/lambda-spans.yaml b/model/aws/lambda-spans.yaml
@@ -1,6 +1,7 @@
 groups:
-  - id: span.aws.lambda
+  - id: span.aws.lambda.server
     type: span
+    span_kind: server
     stability: development
     brief: >
       Span attributes used by AWS Lambda (in addition to general `faas` attributes).
diff --git a/model/faas/spans.yaml b/model/faas/spans.yaml
@@ -1,6 +1,6 @@
 groups:
-  - id: span.faas
-    type: span
+  - id: faas.attributes
+    type: attribute_group
     stability: development
     brief: >
       This semantic convention describes an instance of a function that
@@ -21,8 +21,9 @@ groups:
       - ref: faas.invocation_id
       - ref: cloud.resource_id
 
-  - id: span.faas.datasource
+  - id: span.faas.datasource.server
     type: span
+    span_kind: server
     stability: development
     brief: >
       Semantic Convention for FaaS triggered as a response to some data
@@ -35,8 +36,9 @@ groups:
       - ref: faas.document.time
       - ref: faas.document.name
 
-  - id: span.faas.timer
+  - id: span.faas.timer.server
     type: span
+    span_kind: server
     stability: development
     brief: >
       Semantic Convention for FaaS scheduled to be executed regularly.
@@ -49,7 +51,7 @@ groups:
     type: span
     stability: development
     brief: >
-      Contains additional attributes for incoming FaaS spans.
+      Describes an incoming FaaS span.
     attributes:
       - ref: faas.coldstart
       - ref: faas.trigger
diff --git a/model/gen-ai/spans.yaml b/model/gen-ai/spans.yaml
@@ -184,9 +184,10 @@ groups:
         requirement_level:
           conditionally_required: If provided by the application.
 
-  - id: span.gen_ai.client.execute_tool
+  - id: span.gen_ai.execute_tool.internal
     type: span
     stability: development
+    span_kind: internal
     brief: Describes tool execution span.
     note: |
       `gen_ai.operation.name` SHOULD be `execute_tool`.
diff --git a/model/messaging/spans.yaml b/model/messaging/spans.yaml
@@ -28,8 +28,8 @@ groups:
         # - ref: messaging.system
         #   sampling_relevant: true
 
-  - id: span.messaging
-    type: span
+  - id: messaging.attributes
+    type: attribute_group  # TODO: this should be a span - https://github.com/open-telemetry/semantic-conventions/issues/1891
     stability: development
     brief: >
         Defines a full set of attributes used in messaging systems.
diff --git a/model/rpc/spans.yaml b/model/rpc/spans.yaml
@@ -61,44 +61,34 @@ groups:
       - ref: network.type
         requirement_level: recommended
 
-  - id: span.rpc.grpc
-    type: span
+  - id: rpc.grpc.attributes
     stability: development
-    extends: rpc
+    type: attribute_group
     brief: 'Tech-specific attributes for gRPC.'
     attributes:
       - ref: rpc.grpc.status_code
-        tag: grpc-tech-specific
         requirement_level: required
       - ref: rpc.grpc.request.metadata
-        tag: grpc-tech-specific
         requirement_level: opt_in
       - ref: rpc.grpc.response.metadata
-        tag: grpc-tech-specific
         requirement_level: opt_in
 
-  - id: span.rpc.jsonrpc
-    type: span
+  - id: rpc.jsonrpc.attributes
+    type: attribute_group
     stability: development
-    extends: rpc
     brief: 'Tech-specific attributes for [JSON RPC](https://www.jsonrpc.org/).'
     attributes:
       - ref: rpc.jsonrpc.version
-        tag: jsonrpc-tech-specific
         requirement_level:
           conditionally_required: If other than the default version (`1.0`)
       - ref: rpc.jsonrpc.request_id
-        tag: jsonrpc-tech-specific
         requirement_level: recommended
       - ref: rpc.jsonrpc.error_code
-        tag: jsonrpc-tech-specific
         requirement_level:
           conditionally_required: If response is not successful.
       - ref: rpc.jsonrpc.error_message
-        tag: jsonrpc-tech-specific
         requirement_level: recommended
       - ref: rpc.method
-        tag: jsonrpc-tech-specific
         requirement_level: required
         note: >
           This is always required for jsonrpc. See the note in the general
@@ -123,19 +113,15 @@ groups:
       - ref: rpc.message.uncompressed_size
         requirement_level: recommended
 
-  - id: span.rpc.connect_rpc
-    type: span
+  - id: rpc.connect_rpc.attributes
+    type: attribute_group
     stability: development
-    extends: rpc
     brief: 'Tech-specific attributes for Connect RPC.'
     attributes:
       - ref: rpc.connect_rpc.error_code
-        tag: connect_rpc-tech-specific
         requirement_level:
           conditionally_required: If response is not successful and if error code available.
       - ref: rpc.connect_rpc.request.metadata
-        tag: connect_rpc-tech-specific
         requirement_level: opt_in
       - ref: rpc.connect_rpc.response.metadata
-        tag: connect_rpc-tech-specific
         requirement_level: opt_in
