Use SHOULD instead of MUST for span kinds on DB, GenAI and FaaS (#…

…1506)

.chloggen/1506.yaml

@@ -0,0 +1,4 @@
+change_type: enhancement
+component: db, gen-ai, faas
+note: Relax wording for span kind - use SHOULD instead of MUST for logical operations.
+issues: [1315, 1506]

docs/database/database-spans.md

@@ -45,7 +45,11 @@ linkTitle: Client Calls
 >   for at least six months after it starts emitting both sets of conventions.
 > * SHOULD drop the environment variable in the next major version.
 
-**Span kind:** MUST always be `CLIENT`.
+**Span kind:** SHOULD be `CLIENT`. It MAY be set to `INTERNAL` on spans representing
+in-memory database calls.
+It's RECOMMENDED to use `CLIENT` kind when database system being instrumented usually
+runs in a different process than its client or when database calls happen over
+instrumented protocol such as HTTP.
 
 Span that describes database call SHOULD cover the duration of the corresponding call as if it was observed by the caller (such as client application).
 For example, if a transient issue happened and was retried within this database call, the corresponding span should cover the duration of the logical operation

docs/faas/aws-lambda.md

@@ -32,7 +32,7 @@ use cases.
 
 ## All triggers
 
-For all events, a span with kind `SERVER` MUST be created corresponding to the function invocation unless stated
+For all events, a span with kind `SERVER` SHOULD be created corresponding to the function invocation unless stated
 otherwise below. Unless stated otherwise below, the name of the span MUST be set to the function name from the
 Lambda `Context`.
 
@@ -153,13 +153,13 @@ business logic, not the Lambda framework, automatic instrumentation mechanisms w
 not be able to instrument the processing of the individual messages. Instrumentation SHOULD provide utilities
 for creating message processing spans within user code.
 
-The span kind for both types of SQS spans MUST be `CONSUMER`.
+The span kind for both types of SQS spans SHOULD be `CONSUMER`.
 
 ### SQS Event
 
 For the SQS event span, if all the messages in the event have the same event source, the name of the span MUST
 be `<event source> process`. If there are multiple sources in the batch, the name MUST be
-`multiple_sources process`. The parent MUST be the `SERVER` span corresponding to the function invocation.
+`multiple_sources process`. The parent SHOULD be the `SERVER` span corresponding to the function invocation.
 
 For every message in the event, the [message system attributes][] (not message attributes, which are provided by
 the user) SHOULD be checked for the key `AWSTraceHeader`. If it is present, an OpenTelemetry `Context` SHOULD be

docs/faas/faas-spans.md

@@ -125,7 +125,7 @@ The span attribute `faas.invocation_id` differs from the [resource attribute][Fa
 
 This section describes incoming FaaS invocations as they are reported by the FaaS instance itself.
 
-For incoming FaaS spans, the span kind MUST be `Server`.
+For incoming FaaS spans, the span kind SHOULD be `SERVER`.
 
 ### Incoming FaaS Span attributes
 
@@ -182,7 +182,7 @@ In principle, the above considerations apply to any resource attribute that fulf
 
 This section describes outgoing FaaS invocations as they are reported by a client calling a FaaS instance.
 
-For outgoing FaaS spans, the span kind MUST be `Client`.
+For outgoing FaaS spans, the span kind SHOULD be `CLIENT`.
 
 The values reported by the client for the attributes listed below SHOULD be equal to
 the corresponding [FaaS resource attributes][] and [Cloud resource attributes][],
@@ -304,7 +304,7 @@ In this case, it is responsibility of the framework or instrumentation library t
 
 ## Example
 
-This example shows the FaaS attributes for a (non-FaaS) process hosted on Google Cloud Platform (Span A with kind `Client`), which invokes a Lambda function called "my-lambda-function" in Amazon Web Services (Span B with kind `Server`).
+This example shows the FaaS attributes for a (non-FaaS) process hosted on Google Cloud Platform (Span A with kind `CLIENT`), which invokes a Lambda function called "my-lambda-function" in Amazon Web Services (Span B with kind `SERVER`).
 
 | Attribute Kind | Attribute               | Span A (Client, GCP)   | Span B (Server, AWS Lambda) |
 | -------------- | ----------------------- | ---------------------- | -- |

docs/gen-ai/gen-ai-spans.md

@@ -18,7 +18,11 @@ linkTitle: Generative AI traces
 
 A request to an Generative AI is modeled as a span in a trace.
 
-**Span kind:** MUST always be `CLIENT`.
+**Span kind:** SHOULD be `CLIENT`. It MAY be set to `INTERNAL` on spans representing
+call to models running in the same process.
+It's RECOMMENDED to use `CLIENT` kind when GenAI system being instrumented usually
+runs in a different process than its client or when GenAI call happens over
+instrumented protocol such as HTTP.
 
 ## Name
 

docs/http/http-spans.md

@@ -131,7 +131,7 @@ This span type represents an outbound HTTP request. There are two ways this can
    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.
 
-For an HTTP client span, `SpanKind` MUST be `Client`.
+For an HTTP client span, `SpanKind` MUST be `CLIENT`.
 
 <!-- semconv trace.http.client -->
 <!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
@@ -370,7 +370,7 @@ Application developers MAY overwrite potentially inaccurate values of `server.*`
 
 This span type represents an inbound HTTP request.
 
-For an HTTP server span, `SpanKind` MUST be `Server`.
+For an HTTP server span, `SpanKind` MUST be `SERVER`.
 
 <!-- semconv trace.http.server -->
 <!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->