[chore] ensure gen_ai docs contain correctly formatted lists (#3077)

thompson-tomo · web-flow · commit 12ba4cb653ab · 2025-11-24T22:15:48.000Z
diff --git a/docs/gen-ai/aws-bedrock.md b/docs/gen-ai/aws-bedrock.md
@@ -37,7 +37,6 @@ for [Gen AI Spans](gen-ai-spans.md).
 These attributes track input data and metadata for a request to an AWS Bedrock model. The attributes include general Generative AI
 attributes and ones specific the AWS Bedrock.
 
-<!-- markdownlint-disable -->
 <!-- semconv span.aws.bedrock.client -->
 <!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
 <!-- see templates/registry/markdown/snippet.md.j2 -->
@@ -112,9 +111,8 @@ Instrumentations SHOULD document the list of errors they report.
 **[4] `gen_ai.conversation.id`:** Instrumentations SHOULD populate conversation id when they have it readily available
 for a given operation, for example:
 
--  when client framework being instrumented manages conversation history
+- when client framework being instrumented manages conversation history
 (see [LlamaIndex chat store](https://docs.llamaindex.ai/en/stable/module_guides/storing/chat_stores/))
-
 - when instrumenting GenAI client libraries that maintain conversation on the backend side
 (see [AWS Bedrock agent sessions](https://docs.aws.amazon.com/bedrock/latest/userguide/agents-session-state.html),
 [OpenAI Assistant threads](https://platform.openai.com/docs/api-reference/threads))
@@ -267,6 +265,5 @@ populating this attribute.
 <!-- prettier-ignore-end -->
 <!-- END AUTOGENERATED TEXT -->
 <!-- endsemconv -->
-<!-- markdownlint-restore -->
 
 [DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status
diff --git a/docs/gen-ai/azure-ai-inference.md b/docs/gen-ai/azure-ai-inference.md
@@ -44,7 +44,6 @@ The Semantic Conventions for [Azure AI Inference](https://learn.microsoft.com/az
 
 `gen_ai.provider.name` MUST be set to `"azure.ai.inference"` and SHOULD be provided **at span creation time**.
 
-<!-- markdownlint-disable -->
 <!-- semconv span.azure.ai.inference.client -->
 <!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
 <!-- see templates/registry/markdown/snippet.md.j2 -->
@@ -102,9 +101,8 @@ Instrumentations SHOULD document the list of errors they report.
 **[3] `gen_ai.conversation.id`:** Instrumentations SHOULD populate conversation id when they have it readily available
 for a given operation, for example:
 
--  when client framework being instrumented manages conversation history
+- when client framework being instrumented manages conversation history
 (see [LlamaIndex chat store](https://docs.llamaindex.ai/en/stable/module_guides/storing/chat_stores/))
-
 - when instrumenting GenAI client libraries that maintain conversation on the backend side
 (see [AWS Bedrock agent sessions](https://docs.aws.amazon.com/bedrock/latest/userguide/agents-session-state.html),
 [OpenAI Assistant threads](https://platform.openai.com/docs/api-reference/threads))
@@ -116,6 +114,7 @@ libraries.
 **[4] `gen_ai.output.type`:** when applicable and if the request includes an output format.
 
 **[5] `gen_ai.output.type`:** This attribute SHOULD be set to the output type requested by the client:
+
 - `json` for structured outputs with defined or undefined schema
 - `image` for image output
 - `speech` for speech output
@@ -240,7 +239,6 @@ populating this attribute.
 <!-- prettier-ignore-end -->
 <!-- END AUTOGENERATED TEXT -->
 <!-- endsemconv -->
-<!-- markdownlint-restore -->
 
 ### Embedding
 
diff --git a/docs/gen-ai/gen-ai-agent-spans.md b/docs/gen-ai/gen-ai-agent-spans.md
@@ -48,7 +48,6 @@ The semantic conventions for GenAI agents extend and override the semantic conve
 
 ### Create agent span
 
-<!-- markdownlint-disable -->
 <!-- semconv span.gen_ai.create_agent.client -->
 <!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
 <!-- see templates/registry/markdown/snippet.md.j2 -->
@@ -166,11 +165,9 @@ Instrumentations SHOULD document the list of errors they report.
 <!-- prettier-ignore-end -->
 <!-- END AUTOGENERATED TEXT -->
 <!-- endsemconv -->
-<!-- markdownlint-restore -->
 
 ### Invoke agent span
 
-<!-- markdownlint-disable -->
 <!-- semconv span.gen_ai.invoke_agent.client -->
 <!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
 <!-- see templates/registry/markdown/snippet.md.j2 -->
@@ -193,6 +190,7 @@ in a different process than its caller or when the agent invocation happens over
 instrumented protocol such as HTTP.
 
 Examples of span kinds for different agent scenarios:
+
 - `CLIENT`: Remote agent services (e.g., OpenAI Assistants API, AWS Bedrock Agents)
 - `INTERNAL`: In-process agents (e.g., LangChain agents, CrewAI agents)
 
@@ -260,9 +258,8 @@ Instrumentations SHOULD document the list of errors they report.
 **[4] `gen_ai.conversation.id`:** Instrumentations SHOULD populate conversation id when they have it readily available
 for a given operation, for example:
 
--  when client framework being instrumented manages conversation history
+- when client framework being instrumented manages conversation history
 (see [LlamaIndex chat store](https://docs.llamaindex.ai/en/stable/module_guides/storing/chat_stores/))
-
 - when instrumenting GenAI client libraries that maintain conversation on the backend side
 (see [AWS Bedrock agent sessions](https://docs.aws.amazon.com/bedrock/latest/userguide/agents-session-state.html),
 [OpenAI Assistant threads](https://platform.openai.com/docs/api-reference/threads))
@@ -417,7 +414,6 @@ populating this attribute.
 <!-- prettier-ignore-end -->
 <!-- END AUTOGENERATED TEXT -->
 <!-- endsemconv -->
-<!-- markdownlint-restore -->
 
 ## Execute tool span
 
diff --git a/docs/gen-ai/gen-ai-events.md b/docs/gen-ai/gen-ai-events.md
@@ -41,7 +41,6 @@ GenAI instrumentations MAY capture user inputs sent to the model and responses r
 
 ## Event: `event.gen_ai.client.inference.operation.details`
 
-<!-- markdownlint-disable -->
 <!-- semconv event.gen_ai.client.inference.operation.details -->
 <!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
 <!-- see templates/registry/markdown/snippet.md.j2 -->
@@ -93,9 +92,8 @@ Instrumentations SHOULD document the list of errors they report.
 **[3] `gen_ai.conversation.id`:** Instrumentations SHOULD populate conversation id when they have it readily available
 for a given operation, for example:
 
--  when client framework being instrumented manages conversation history
+- when client framework being instrumented manages conversation history
 (see [LlamaIndex chat store](https://docs.llamaindex.ai/en/stable/module_guides/storing/chat_stores/))
-
 - when instrumenting GenAI client libraries that maintain conversation on the backend side
 (see [AWS Bedrock agent sessions](https://docs.aws.amazon.com/bedrock/latest/userguide/agents-session-state.html),
 [OpenAI Assistant threads](https://platform.openai.com/docs/api-reference/threads))
@@ -220,11 +218,9 @@ populating this attribute.
 <!-- prettier-ignore-end -->
 <!-- END AUTOGENERATED TEXT -->
 <!-- endsemconv -->
-<!-- markdownlint-restore -->
 
 ## Event: `event.gen_ai.evaluation.result`
 
-<!-- markdownlint-disable -->
 <!-- semconv event.gen_ai.evaluation.result -->
 <!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
 <!-- see templates/registry/markdown/snippet.md.j2 -->
@@ -268,6 +264,5 @@ event with the corresponding operation when span id is not available.
 <!-- prettier-ignore-end -->
 <!-- END AUTOGENERATED TEXT -->
 <!-- endsemconv -->
-<!-- markdownlint-restore -->
 
 [DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status
diff --git a/docs/gen-ai/gen-ai-spans.md b/docs/gen-ai/gen-ai-spans.md
@@ -45,7 +45,6 @@ linkTitle: Spans
 
 ### Inference
 
-<!-- markdownlint-disable -->
 <!-- semconv span.gen_ai.inference.client -->
 <!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
 <!-- see templates/registry/markdown/snippet.md.j2 -->
@@ -125,9 +124,8 @@ Instrumentations SHOULD document the list of errors they report.
 **[4] `gen_ai.conversation.id`:** Instrumentations SHOULD populate conversation id when they have it readily available
 for a given operation, for example:
 
--  when client framework being instrumented manages conversation history
+- when client framework being instrumented manages conversation history
 (see [LlamaIndex chat store](https://docs.llamaindex.ai/en/stable/module_guides/storing/chat_stores/))
-
 - when instrumenting GenAI client libraries that maintain conversation on the backend side
 (see [AWS Bedrock agent sessions](https://docs.aws.amazon.com/bedrock/latest/userguide/agents-session-state.html),
 [OpenAI Assistant threads](https://platform.openai.com/docs/api-reference/threads))
@@ -280,11 +278,9 @@ populating this attribute.
 <!-- prettier-ignore-end -->
 <!-- END AUTOGENERATED TEXT -->
 <!-- endsemconv -->
-<!-- markdownlint-restore -->
 
 ### Embeddings
 
-<!-- markdownlint-disable -->
 <!-- semconv span.gen_ai.embeddings.client -->
 <!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
 <!-- see templates/registry/markdown/snippet.md.j2 -->
@@ -352,11 +348,9 @@ Instrumentations SHOULD document the list of errors they report.
 <!-- prettier-ignore-end -->
 <!-- END AUTOGENERATED TEXT -->
 <!-- endsemconv -->
-<!-- markdownlint-restore -->
 
 ### Execute tool span
 
-<!-- markdownlint-disable -->
 <!-- semconv span.gen_ai.execute_tool.internal -->
 <!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
 <!-- see templates/registry/markdown/snippet.md.j2 -->
@@ -443,7 +437,6 @@ deserialize it to an object. When recorded on spans, it MAY be recorded as a JSO
 <!-- prettier-ignore-end -->
 <!-- END AUTOGENERATED TEXT -->
 <!-- endsemconv -->
-<!-- markdownlint-restore -->
 
 ## Capturing instructions, inputs, and outputs
 
@@ -463,7 +456,6 @@ Application developers should choose an appropriate usage pattern based on
 application needs and maturity:
 
 1. [Default] Don't record instructions, inputs, or outputs.
-
 2. Record instructions, inputs, and outputs on the GenAI spans using corresponding
    attributes (`gen_ai.system_instructions`, `gen_ai.input.messages`,
    `gen_ai.output.messages`).
@@ -474,7 +466,6 @@ application needs and maturity:
 
    See [Recording content on attributes](#recording-content-on-attributes)
    section for more details.
-
 3. Store content externally and record references on the spans.
 
    This pattern is recommended in production environments where telemetry volume
diff --git a/docs/gen-ai/openai.md b/docs/gen-ai/openai.md
@@ -46,7 +46,6 @@ The Semantic Conventions for [OpenAI](https://openai.com/) extend and override t
 
 ### Inference
 
-<!-- markdownlint-disable -->
 <!-- semconv span.openai.inference.client -->
 <!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
 <!-- see templates/registry/markdown/snippet.md.j2 -->
@@ -107,9 +106,8 @@ Instrumentations SHOULD document the list of errors they report.
 **[4] `gen_ai.conversation.id`:** Instrumentations SHOULD populate conversation id when they have it readily available
 for a given operation, for example:
 
--  when client framework being instrumented manages conversation history
+- when client framework being instrumented manages conversation history
 (see [LlamaIndex chat store](https://docs.llamaindex.ai/en/stable/module_guides/storing/chat_stores/))
-
 - when instrumenting GenAI client libraries that maintain conversation on the backend side
 (see [AWS Bedrock agent sessions](https://docs.aws.amazon.com/bedrock/latest/userguide/agents-session-state.html),
 [OpenAI Assistant threads](https://platform.openai.com/docs/api-reference/threads))
@@ -121,6 +119,7 @@ libraries.
 **[5] `gen_ai.output.type`:** when applicable and if the request includes an output format.
 
 **[6] `gen_ai.output.type`:** This attribute SHOULD be set to the output type requested by the client:
+
 - `json` for structured outputs with defined or undefined schema
 - `image` for image output
 - `speech` for speech output
@@ -254,7 +253,6 @@ populating this attribute.
 <!-- prettier-ignore-end -->
 <!-- END AUTOGENERATED TEXT -->
 <!-- endsemconv -->
-<!-- markdownlint-restore -->
 
 ### Embeddings
 
@@ -271,7 +269,6 @@ Reports the usage of tokens following the common [gen_ai.client.token.usage](./g
 
 Additional attributes:
 
-<!-- markdownlint-disable -->
 <!-- semconv metric_attributes.openai -->
 <!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
 <!-- see templates/registry/markdown/snippet.md.j2 -->
@@ -287,15 +284,13 @@ Additional attributes:
 <!-- prettier-ignore-end -->
 <!-- END AUTOGENERATED TEXT -->
 <!-- endsemconv -->
-<!-- markdownlint-restore -->
 
 ### Metric: `gen_ai.client.operation.duration`
 
 Measures the to complete an operation following the common [gen_ai.client.operation.duration](./gen-ai-metrics.md#metric-gen_aiclientoperationduration) definition.
 
 Additional attributes:
 
-<!-- markdownlint-disable -->
 <!-- semconv metric_attributes.openai -->
 <!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
 <!-- see templates/registry/markdown/snippet.md.j2 -->
@@ -311,6 +306,5 @@ Additional attributes:
 <!-- prettier-ignore-end -->
 <!-- END AUTOGENERATED TEXT -->
 <!-- endsemconv -->
-<!-- markdownlint-restore -->
 
 [DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status
diff --git a/model/gen-ai/spans.yaml b/model/gen-ai/spans.yaml
@@ -78,9 +78,8 @@ groups:
           Instrumentations SHOULD populate conversation id when they have it readily available
           for a given operation, for example:
 
-          -  when client framework being instrumented manages conversation history
+          - when client framework being instrumented manages conversation history
           (see [LlamaIndex chat store](https://docs.llamaindex.ai/en/stable/module_guides/storing/chat_stores/))
-
           - when instrumenting GenAI client libraries that maintain conversation on the backend side
           (see [AWS Bedrock agent sessions](https://docs.aws.amazon.com/bedrock/latest/userguide/agents-session-state.html),
           [OpenAI Assistant threads](https://platform.openai.com/docs/api-reference/threads))
@@ -132,6 +131,7 @@ groups:
       - ref: gen_ai.output.type
         note: |
           This attribute SHOULD be set to the output type requested by the client:
+
           - `json` for structured outputs with defined or undefined schema
           - `image` for image output
           - `speech` for speech output
@@ -267,6 +267,7 @@ groups:
       instrumented protocol such as HTTP.
 
       Examples of span kinds for different agent scenarios:
+
       - `CLIENT`: Remote agent services (e.g., OpenAI Assistants API, AWS Bedrock Agents)
       - `INTERNAL`: In-process agents (e.g., LangChain agents, CrewAI agents)
     extends: attributes.gen_ai.inference.client
