Update observability docs

docs-site/assets/kagent-docs/snippets/examples/a2a-port-warning.md

@@ -0,0 +1,2 @@
+> [!WARNING]
+> A default installation sets `config.server.auth.mode` to `insecure`. In this mode any caller that can reach the port can invoke any Agent. Do not expose port `8083` outside the cluster. For the wider identity model, see [Identity]({{< link path="about/substrate-runtime/identity" >}}).

docs-site/assets/kagent-docs/snippets/examples/mcp-endpoint-warning.md

@@ -0,0 +1,2 @@
+> [!WARNING]
+> A default installation sets `config.server.auth.mode` to `insecure`. In this mode the endpoint accepts every request and reads the caller's identity from an `X-User-Id` header that the caller sets itself, defaulting to `admin@kagent.dev`. The endpoint can invoke agents, create checkpoints, and create Sessions. Do not expose port `8083` outside the cluster. For the wider identity model, see [Identity]({{< link path="about/substrate-runtime/identity" >}}).

docs-site/assets/kagent-docs/snippets/observability/actor-state-records.md

@@ -0,0 +1 @@
+In your logging backend, select the records with the body `Actor state changed`, and filter them by the `ate.actor.name` attribute.

docs-site/assets/kagent-docs/snippets/observability/claude-logs-backend.md

@@ -0,0 +1 @@
+Loki in the [OTel stack]({{< link path="observability/otel-stack" >}}) is one such backend.

docs-site/assets/kagent-docs/snippets/observability/grafana-password.md

@@ -0,0 +1 @@
+For the password, see [Explore the telemetry in Grafana]({{< link path="observability/otel-stack#explore-the-telemetry-in-grafana" >}}).

docs-site/assets/kagent-docs/snippets/observability/substrate-otel-setup.md

@@ -0,0 +1 @@
+The [OTel stack]({{< link path="observability/otel-stack#send-agent-substrate-telemetry-to-the-collector" >}}) and [Lightweight OTel stack]({{< link path="observability/lightweight-otel-stack" >}}) guides set both.

docs-site/assets/kagent-docs/snippets/observability/tracing-backend.md

@@ -0,0 +1 @@
+The [OTel stack]({{< link path="observability/otel-stack" >}}) sends traces to Tempo, and the [Lightweight OTel stack]({{< link path="observability/lightweight-otel-stack" >}}) sends traces to Jaeger. Both guides turn on tracing.

docs-site/content/kagent/1.x/about/substrate-runtime/networking-and-egress.md

@@ -114,7 +114,6 @@ kagent sets this up from two resources. Every ModelConfig that holds an `apiKeyS
 
 A credential is declared on a rule as a `replace_headers` entry. The entry names the header to replace, an optional prefix such as `Bearer `, and either a reference that a registered credential provider resolves or a JWT that Agent Substrate issues to assert the Actor's identity. The gateway replaces the header only when the request already sends it. A request that omits the placeholder header is forwarded unchanged, without the credential, rather than being denied.
 
-> [!NOTE]
-> Replacement happens only on a connection that the gateway terminates, and only when a credential provider is configured for the reference. If either is missing, the request reaches the destination without the credential. The request fails closed when replacement is attempted and fails. `403` is returned when the provider does not hold the credential or refuses to release it, and `503` is returned when the provider is unreachable.
+Replacement happens only on a connection that the gateway terminates, and only when a credential provider is configured for the reference. If either is missing, the request reaches the destination without the credential. The request fails closed when replacement is attempted and fails. `403` is returned when the provider does not hold the credential or refuses to release it, and `503` is returned when the provider is unreachable.
 
 Replacement also works on a cleartext `http` rule, where the gateway does not originate TLS to the destination. The credential is then readable by anything on the path between the gateway and the destination unless something outside the gateway encrypts that segment. Prefer an `https` destination for any host that takes a credential.

docs-site/content/kagent/1.x/examples/a2a-agents.md

@@ -28,8 +28,7 @@ Both forms replace the `/api/a2a/<namespace>/<agent-name>/` URL paths that kagen
 
 A caller addresses the Agent rather than one conversation. The message's `contextId` selects the conversation. Omitting both a `contextId` and a task ID starts a new {{< gloss "Session" >}}Session{{< /gloss >}}, and repeating a `contextId` continues that Session.
 
-> [!WARNING]
-> A default installation sets `config.server.auth.mode` to `insecure`. In this mode any caller that can reach the port can invoke any Agent. Do not expose port `8083` outside the cluster. For the wider identity model, see [Identity]({{< link path="about/substrate-runtime/identity" >}}).
+{{< reuse "kagent-docs/snippets/examples/a2a-port-warning.md" >}}
 
 ### A2A methods
 

docs-site/content/kagent/1.x/examples/agents-via-mcp.md

@@ -19,8 +19,7 @@ The MCP server is part of the controller's HTTP port rather than a separate depl
 - **Sessions**: The handler is stateless, so each request stands alone and a client does not need to establish a session first.
 - **Extensions**: The server advertises the `io.modelcontextprotocol/tasks` extension, which changes how invocations behave. For more information, see [Invoke without waiting](#invoke-without-waiting).
 
-> [!WARNING]
-> A default installation sets `config.server.auth.mode` to `insecure`. In this mode the endpoint accepts every request and reads the caller's identity from an `X-User-Id` header that the caller sets itself, defaulting to `admin@kagent.dev`. The endpoint can invoke agents, create checkpoints, and create Sessions. Do not expose port `8083` outside the cluster. For the wider identity model, see [Identity]({{< link path="about/substrate-runtime/identity" >}}).
+{{< reuse "kagent-docs/snippets/examples/mcp-endpoint-warning.md" >}}
 
 ## Before you begin
 

docs-site/content/kagent/1.x/get-started/your-first-mcp-tool.md

@@ -85,8 +85,7 @@ kagent records what it discovered on the server's status, so the tool names come
 
    When the two values differ, kagent is still compiling, or compilation failed. A binding that names a RemoteMCPServer that does not exist in the namespace fails at the `ResolvedRefs` condition with the reason `ReferenceResolutionFailed`.
 
-   > [!WARNING]
-   > kagent resolves the server, but it does not check the tool names against the tools that the server actually serves. A misspelled tool name compiles into a ready revision, and the only symptom is an agent that never calls the tool that you expected. If a bound tool appears to be missing, check the spelling against the server's catalog.
+   kagent resolves the server, but it does not check the tool names against the tools that the server actually serves. A misspelled tool name compiles into a ready revision, and the only symptom is an agent that never calls the tool that you expected. If a bound tool appears to be missing, check the spelling against the server's catalog.
 
 ## Create a Session that has the tool
 

docs-site/content/kagent/1.x/observability/audit-prompts.md

@@ -58,7 +58,7 @@ Agent Substrate suspends an Actor as soon as a response completes. The controlle
 1. [Install kagent]({{< link path="setup/installation" >}}).
 2. [Create your first agent]({{< link path="get-started/your-first-agent" >}}), so that you have an {{< gloss "Agent" >}}Agent{{< /gloss >}} to send requests to. That guide also installs the kagent CLI. The steps on this page need the {{< reuse "kagent-docs/versions/kagent.md" >}} CLI, because the CLIs of other releases, newer ones included, do not have the Session commands that these steps use. To check your version, run `kagent version`.
 3. Install [`jq`](https://jqlang.org/download/), to read the Session ID and revision out of the CLI's JSON output.
-4. Set up a tracing backend, and turn on tracing. The [OTel stack]({{< link path="observability/otel-stack" >}}) sends traces to Tempo, and the [Lightweight OTel stack]({{< link path="observability/lightweight-otel-stack" >}}) sends traces to Jaeger. Both guides turn on tracing for you.
+4. Set up a tracing backend, and turn on tracing. {{< reuse "kagent-docs/snippets/observability/tracing-backend.md" >}}
 
 ## Turn on content capture
 
@@ -86,7 +86,7 @@ Turn on content capture in the kagent Helm release, then create a Session that p
      --set config.runtimeDefaults.telemetry.captureContent=true
    ```
 
-   For an agent on the `claude` runtime, also set `config.runtimeDefaults.telemetry.logs.endpoint` to the address of your collector, and send the logs to a backend that stores them, such as Loki in the [OTel stack]({{< link path="observability/otel-stack" >}}). Without log export, the replies of a `claude` agent are not recorded.
+   For an agent on the `claude` runtime, also set `config.runtimeDefaults.telemetry.logs.endpoint` to the address of your collector, and send the logs to a backend that stores them. {{< reuse "kagent-docs/snippets/observability/claude-logs-backend.md" >}} Without log export, the replies of a `claude` agent are not recorded.
 
 3. Wait for the controller to roll out.
    ```bash
@@ -138,7 +138,7 @@ Send a request that contains a distinctive phrase, then find that phrase in the
       ```bash
       kubectl port-forward -n telemetry svc/kube-prometheus-stack-grafana 3000:80
       ```
-   2. In your browser, open Grafana at [http://localhost:3000](http://localhost:3000), and log in. For the password, see [Explore the telemetry in Grafana]({{< link path="observability/otel-stack#explore-the-telemetry-in-grafana" >}}).
+   2. In your browser, open Grafana at [http://localhost:3000](http://localhost:3000), and log in. {{< reuse "kagent-docs/snippets/observability/grafana-password.md" >}}
    3. Open **Explore**, select the **Tempo** data source, and select the **TraceQL** query type.
    4. Run the following query, which returns the model calls whose request contains the phrase.
       ```text

docs-site/content/kagent/1.x/observability/lightweight-otel-stack.md

@@ -338,7 +338,7 @@ Check each signal in turn: traces in Jaeger, metrics in Prometheus, and logs in
       kubectl port-forward -n telemetry svc/jaeger 16686:16686
       ```
    2. In your browser, open Jaeger at [http://localhost:16686](http://localhost:16686).
-   3. From the **Service** list, select `my-first-agent`, and click **Find Traces**. To see Agent Substrate's own work, select one of its services instead: `ateapi`, `atenet-router`, `atelet`, `atecontroller`, or `ateom-gvisor`. For what each service reports, see [Agent Substrate traces]({{< link path="observability/tracing#agent-substrate-traces" >}}).
+   3. From the **Service** list, select `my-first-agent`, and click **Find Traces**. To see Agent Substrate's own work, select one of its services instead: `ateapi`, `atelet`, `atecontroller`, or `ateom-gvisor`. For what each service reports, see [Agent Substrate traces]({{< link path="observability/tracing#agent-substrate-traces" >}}).
 
 2. Review the metrics in Prometheus.
    1. Forward the Prometheus port, and leave the command running.

docs-site/content/kagent/1.x/observability/otel-stack.md

@@ -504,7 +504,7 @@ Log in to Grafana, and query each backend from the **Explore** view.
    {{% tab name="Traces" %}}
    Select the **Tempo** data source, then select the **Search** query type. From the **Service Name** list, select `my-first-agent`, the service that the Agent reports as, and run the query. Open a trace to see the controller, proxy, and agent runtime spans of one request.
 
-   To see Agent Substrate's own work, select one of its services from the **Service Name** list instead: `ateapi`, `atenet-router`, `atelet`, `atecontroller`, or `ateom-gvisor`. For what each service reports, see [Agent Substrate traces]({{< link path="observability/tracing#agent-substrate-traces" >}}).
+   To see Agent Substrate's own work, select one of its services from the **Service Name** list instead: `ateapi`, `atelet`, `atecontroller`, or `ateom-gvisor`. For what each service reports, see [Agent Substrate traces]({{< link path="observability/tracing#agent-substrate-traces" >}}).
    {{% /tab %}}
    {{% tab name="Logs" %}}
    Select the **Loki** data source, and run the following query to show the state changes of your agent's Actor. Agent Substrate names the Actor `session-` followed by the Session ID, so replace `<session-id>` with the value of `$SESSION_ID` from the previous section.