From f912bbd43094bfdc9f97c141d93466d7f61838b0 Mon Sep 17 00:00:00 2001
From: Martin Linzmayer <martin.linzmayer@sentry.io>
Date: Thu, 11 Jun 2026 11:34:20 +0200
Subject: [PATCH] docs(agent): add agent observability section

---
 docs/platforms/php/agent/index.mdx | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/docs/platforms/php/agent/index.mdx b/docs/platforms/php/agent/index.mdx
index 4bbaef2fb53cd..206a609bcc914 100644
--- a/docs/platforms/php/agent/index.mdx
+++ b/docs/platforms/php/agent/index.mdx
@@ -119,3 +119,13 @@ The default builder-created client includes fallback delivery. If the local
 agent handoff fails, the client sends the envelope directly to Sentry using the
 normal SDK HTTP client. This preserves delivery, but the request loses the
 latency benefit while the agent is unavailable.
+
+## Observability
+
+To monitor events sent through the agent, add a dashboard widget in Sentry.
+Click "Add Widget" on a dashboard, then select the "Errors" dataset. Choose a
+time-series visualization, set the Y-Axis to `count()`, and add
+`sentry.php.agent` to Group by.
+
+The chart shows error counts grouped by the `sentry.php.agent` tag, so you can
+see how many events were handled by the agent.