Reorganize http/grpc section and fix more gloss terms

Author: kbatuigas

modules/ai-agents/pages/observability/concepts.adoc

@@ -6,7 +6,7 @@
 :learning-objective-2: Interpret transcript structure for debugging and monitoring
 :learning-objective-3: Distinguish between transcripts and audit logs
 
-Redpanda automatically captures glossterm:transcript[,transcripts] (also referred to as execution logs or traces) for both AI agents and MCP servers, providing complete glossterm:observability[] into how your agentic systems operate.
+Redpanda automatically captures glossterm:transcript[,transcripts] (also referred to as execution logs or traces) for both AI agents and MCP servers, providing complete glossterm:observability (o11y)[,observability] into how your agentic systems operate.
 
 After reading this page, you will be able to:
 
@@ -16,7 +16,7 @@ After reading this page, you will be able to:
 
 == What are transcripts
 
-The AI Gateway and every glossterm:ai-agent[,agent] and glossterm:mcp-server[,MCP server] in your Agentic Data Plane (ADP) automatically emit OpenTelemetry traces to a glossterm:topic[] called `redpanda.otel_traces`. These traces provide detailed observability into operations, creating complete transcripts.
+The AI Gateway and every glossterm:AI agent[,agent] and glossterm:MCP server[] in your Agentic Data Plane (ADP) automatically emit OpenTelemetry traces to a glossterm:topic[] called `redpanda.otel_traces`. These traces provide detailed observability into operations, creating complete transcripts.
 
 Transcripts capture:
 
@@ -31,7 +31,7 @@ With 100% sampling, every operation is captured, enabling comprehensive debuggin
 
 == Traces and spans
 
-glossterm:opentelemetry[,OpenTelemetry] traces provide a complete picture of how a request flows through your system:
+glossterm:OpenTelemetry[] traces provide a complete picture of how a request flows through your system:
 
 * A _trace_ represents the entire lifecycle of a request (for example, a tool invocation from start to finish).
 * A _span_ represents a single unit of work within that trace (such as a data processing operation or an external API call).
@@ -54,11 +54,11 @@ Agent transcripts contain these span types:
 | Measure total request duration and identify slow agent invocations.
 
 | `agent`
-| Internal agent processing that represents reasoning and decision-making. Shows time spent in the LLM reasoning loop, including context processing, tool selection, and response generation. Multiple `agent` spans may appear when the agent iterates through its reasoning loop.
+| Internal agent processing that represents reasoning and decision-making. Shows time spent in the glossterm:large language model (LLM)[,LLM] reasoning loop, including context processing, tool selection, and response generation. Multiple `agent` spans may appear when the agent iterates through its reasoning loop.
 | Track reasoning time and identify iteration patterns.
 
 | `invoke_agent`
-| Agent and sub-agent invocation in multi-agent architectures, following the https://opentelemetry.io/docs/specs/semconv/gen-ai/gen-ai-agent-spans/[OpenTelemetry agent invocation semantic conventions^]. Represents one agent calling another via the A2A protocol.
+| Agent and sub-agent invocation in multi-agent architectures, following the https://opentelemetry.io/docs/specs/semconv/gen-ai/gen-ai-agent-spans/[OpenTelemetry agent invocation semantic conventions^]. Represents one agent calling another via the glossterm:Agent2Agent (A2A) protocol[,A2A protocol].
 | Trace calls between root agents and sub-agents, measure cross-agent latency, and identify which sub-agent was invoked.
 
 | `openai`, `anthropic`, or other LLM providers
@@ -256,12 +256,12 @@ Each span captures a unit of work. Here's what a typical MCP tool invocation loo
 }
 ----
 
-* **traceId** links all spans in the same request across services
-* **spanId** uniquely identifies this span
-* **name** identifies the operation or tool
-* **instrumentationScope.name** identifies which layer created the span (`rpcn-mcp` for MCP tools, `redpanda-connect` for internal processing)
-* **attributes** contain operation-specific metadata
-* **status.code** indicates success (0) or error (2)
+* `traceId` links all spans in the same request across services
+* `spanId` uniquely identifies this span
+* `name` identifies the operation or tool
+* `instrumentationScope.name` identifies which layer created the span (`rpcn-mcp` for MCP tools, `redpanda-connect` for internal processing)
+* `attributes` contain operation-specific metadata
+* `status.code` indicates success (0) or error (2)
 
 === Parent-child relationships
 
@@ -308,7 +308,7 @@ The `events` array captures what happened and when. Use `timeUnixNano` to see ex
 [[opentelemetry-traces-topic]]
 == How Redpanda stores trace data
 
-The `redpanda.otel_traces` topic stores OpenTelemetry spans using Redpanda's glossterm:schema-registry[] wire format, with a custom Protobuf schema named `redpanda.otel_traces-value` that follows the https://opentelemetry.io/docs/specs/otel/protocol/[OpenTelemetry Protocol (glossterm:otlp[])^] specification. Spans include attributes following OpenTelemetry https://opentelemetry.io/docs/specs/semconv/gen-ai/[semantic conventions for generative AI^], such as `gen_ai.operation.name` and `gen_ai.conversation.id`. The schema is automatically registered in the Schema Registry with the topic, so Kafka clients can consume and deserialize trace data correctly.
+The `redpanda.otel_traces` topic stores OpenTelemetry spans using Redpanda's glossterm:Schema Registry[] wire format, with a custom Protobuf schema named `redpanda.otel_traces-value` that follows the https://opentelemetry.io/docs/specs/otel/protocol/[OpenTelemetry Protocol (OTLP)^] specification. Spans include attributes following OpenTelemetry https://opentelemetry.io/docs/specs/semconv/gen-ai/[semantic conventions for generative AI^], such as `gen_ai.operation.name` and `gen_ai.conversation.id`. The schema is automatically registered in the Schema Registry with the topic, so Kafka clients can consume and deserialize trace data correctly.
 
 Redpanda manages both the `redpanda.otel_traces` topic and its schema automatically. If you delete either the topic or the schema, they are recreated automatically. However, deleting the topic permanently deletes all trace data, and the topic comes back empty. Do not produce your own data to this topic. It is reserved for OpenTelemetry traces.
 

modules/ai-agents/pages/observability/ingest-custom-traces.adoc

@@ -1,7 +1,7 @@
 = Ingest OpenTelemetry Traces from Custom Agents
 :description: Configure a Redpanda Connect pipeline to ingest OTEL traces from custom agents into Redpanda for unified observability.
 :page-topic-type: how-to
-:learning-objective-1: Configure a Redpanda Connect pipeline to receive OpenTelemetry traces from custom agents via HTTP and publish them to redpanda.otel_traces
+:learning-objective-1: Configure a Redpanda Connect pipeline to receive OpenTelemetry traces from custom agents via HTTP and publish them to `redpanda.otel_traces`
 :learning-objective-2: Validate trace data format and compatibility with existing MCP server traces
 :learning-objective-3: Secure the ingestion endpoint using authentication mechanisms
 
@@ -30,7 +30,7 @@ If you're using LangChain with OpenTelemetry tracing, you can send traces to Red
 . Deploy a Redpanda Connect pipeline using the `otlp_http` input to receive OTLP traces over HTTP. Create the pipeline in the **Connect** page of your cluster, or see the <<configure-the-ingestion-pipeline,Configure the ingestion pipeline>> section below for a sample configuration.
 
 . Configure your OTEL exporter to send traces to your Redpanda Connect pipeline using environment variables:
-
++
 [,bash]
 ----
 # Configure LangChain OTEL integration
@@ -97,17 +97,22 @@ For complete trace structure details, see xref:ai-agents:observability/concepts.
 
 == Configure the ingestion pipeline
 
-Create a Redpanda Connect pipeline that receives HTTP requests containing OTLP traces and publishes them to the `redpanda.otel_traces` topic. The pipeline uses the `otlp_http` input component, which is specifically designed to receive OpenTelemetry Protocol data.
+Create a Redpanda Connect pipeline that receives OTLP traces and publishes them to the `redpanda.otel_traces` topic. Choose HTTP or gRPC transport based on your agent's requirements.
 
 === Create the pipeline configuration
 
-Create a pipeline configuration file that defines the OTLP HTTP ingestion endpoint.
+Create a pipeline configuration file that defines the OTLP ingestion endpoint.
 
+[tabs]
+====
+HTTP::
++
+--
 The `otlp_http` input component:
 
 * Exposes an OpenTelemetry Collector HTTP receiver
 * Accepts traces at the standard `/v1/traces` endpoint
-* Converts incoming OTLP data into individual Redpanda OTEL v1 Protobuf messages and publishes them to the `redpanda.otel_traces` topic
+* Converts incoming OTLP data into individual Redpanda OTEL v1 Protobuf messages
 
 The following example shows a minimal pipeline configuration. Redpanda Cloud automatically injects authentication handling, so you don't need to configure `auth_token` in the input.
 
@@ -126,13 +131,18 @@ output:
       - mechanism: "REDPANDA_CLOUD_SERVICE_ACCOUNT"
     topic: "redpanda.otel_traces"
 ----
+--
 
-The `otlp_http` input automatically handles format conversion, so no processors are needed for basic trace ingestion. Each span becomes a separate message in the `redpanda.otel_traces` topic.
+gRPC::
++
+--
+The `otlp_grpc` input component:
 
-[[use-grpc]]
-==== Alternative: Use gRPC instead of HTTP
+* Exposes an OpenTelemetry Collector gRPC receiver
+* Accepts traces via the OTLP gRPC protocol
+* Converts incoming OTLP data into individual Redpanda OTEL v1 Protobuf messages
 
-If your custom agent requires gRPC transport, use the `otlp_grpc` input instead:
+The following example shows a minimal pipeline configuration. Redpanda Cloud automatically injects authentication handling.
 
 [,yaml]
 ----
@@ -150,7 +160,11 @@ output:
     topic: "redpanda.otel_traces"
 ----
 
-Clients must include the authentication token in gRPC metadata as `authorization: Bearer <token>`.
+NOTE: Clients must include the authentication token in gRPC metadata as `authorization: Bearer <token>`.
+--
+====
+
+The OTLP input automatically handles format conversion, so no processors are needed for basic trace ingestion. Each span becomes a separate message in the `redpanda.otel_traces` topic.
 
 === Deploy the pipeline in Redpanda Cloud
 

modules/ai-agents/pages/observability/transcripts.adoc

@@ -25,7 +25,7 @@ After reading this page, you will be able to:
 
 === Filter transcripts
 
-Use filters to narrow down transcripts and quickly locate specific executions. When you use any of the filters, the transcript list updates to show only matching results.
+Use filters to narrow down transcripts and quickly locate specific executions. When you use any of the filters, the transcript table updates to show only matching results.
 
 The Transcripts view provides several quick-filter buttons:
 
@@ -38,7 +38,7 @@ The Transcripts view provides several quick-filter buttons:
 
 You can combine multiple filters to narrow results further. For example, use *Tool Calls* and *Errors Only* together to investigate failed tool executions.
 
-Toggle *Full traces* on to see the complete execution context, in grayed-out text, for the filtered transcripts.
+Toggle *Full traces* on to see the complete execution context, in grayed-out text, for the filtered transcripts in the table.
 
 ==== Filter by attribute
 
@@ -59,7 +59,7 @@ Click on any bar in the timeline to zoom into transcripts from that specific tim
 
 [NOTE]
 ====
-When viewing time ranges with many transcripts (hundreds or thousands), the table displays a subset of the data to maintain performance and usability. The timeline bar indicates the actual time range of data currently loaded into the view, which may be narrower than your selected time range. 
+When viewing time ranges with many transcripts (hundreds or thousands), the table displays a subset of the data to maintain performance and usability. The timeline bar indicates the actual time range of data currently loaded into view, which may be narrower than your selected time range. 
 
 Refer to the timeline header to check the exact range and count of visible transcripts, for example, "Showing 100 of 299 transcripts from 13:17 to 15:16".
 ====
@@ -74,13 +74,11 @@ The transcript table shows:
 
 To view nested operations, expand any parent span. To learn more about span hierarchies and cross-service traces, see xref:ai-agents:observability/concepts.adoc[].
 
-// TODO: Confirm how gateway traces appear
-
-Click any span to view details in the right panel:
+Click any span to view details in the panel:
 
 * **Summary tab**: High-level overview with token usage, operation counts, and conversation history.
 * **Attributes tab**: Structured metadata for debugging (see xref:ai-agents:observability/concepts.adoc#key-attributes-by-layer[standard attributes by layer]).
-* **Raw data tab**: Complete glossterm:opentelemetry[] span in JSON format. You can also view raw transcript data in the `redpanda.otel_traces` topic.
+* **Raw data tab**: Complete glossterm:OpenTelemetry[] span in JSON format. You can also view raw transcript data in the `redpanda.otel_traces` topic.
 
 [NOTE]
 ====