@sentry/junior-datadog 0.25.0

package/LICENSE

@@ -0,0 +1,201 @@
+Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+   any Contribution intentionally submitted for inclusion in the Work
+   by You to the Licensor shall be under the terms and conditions of
+   this License, without any additional terms or conditions.
+   Notwithstanding the above, nothing herein shall supersede or modify
+   the terms of any separate license agreement you may have executed
+   with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+   names, trademarks, service marks, or product names of the Licensor,
+   except as required for reasonable and customary use in describing the
+   origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+   agreed to in writing, Licensor provides the Work (and each
+   Contributor provides its Contributions) on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+   implied, including, without limitation, any warranties or conditions
+   of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+   PARTICULAR PURPOSE. You are solely responsible for determining the
+   appropriateness of using or redistributing the Work and assume any
+   risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+   whether in tort (including negligence), contract, or otherwise,
+   unless required by applicable law (such as deliberate and grossly
+   negligent acts) or agreed to in writing, shall any Contributor be
+   liable to You for damages, including any direct, indirect, special,
+   incidental, or consequential damages of any character arising as a
+   result of this License or out of the use or inability to use the
+   Work (including but not limited to damages for loss of goodwill,
+   work stoppage, computer failure or malfunction, or any and all
+   other commercial damages or losses), even if such Contributor
+   has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+   the Work or Derivative Works thereof, You may choose to offer,
+   and charge a fee for, acceptance of support, warranty, indemnity,
+   or other liability obligations and/or rights consistent with this
+   License. However, in accepting such obligations, You may act only
+   on Your own behalf and on Your sole responsibility, not on behalf
+   of any other Contributor, and only if You agree to indemnify,
+   defend, and hold each Contributor harmless for any liability
+   incurred by, or claims asserted against, such Contributor by reason
+   of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,44 @@
+# @sentry/junior-datadog
+
+`@sentry/junior-datadog` adds read-only Datadog telemetry workflows to Junior through Datadog's hosted MCP server.
+
+Install it alongside `@sentry/junior`:
+
+```bash
+pnpm add @sentry/junior @sentry/junior-datadog
+```
+
+Then register the plugin package in `juniorNitro(...)`:
+
+```ts title="nitro.config.ts"
+juniorNitro({
+  pluginPackages: ["@sentry/junior-datadog"],
+});
+```
+
+This package does not use `DD_API_KEY`, `DD_APP_KEY`, or a shared workspace integration. Each user connects their own Datadog account the first time Junior calls a Datadog MCP tool. Junior sends the OAuth link privately and resumes the thread automatically after the user authorizes.
+
+Junior intentionally keeps this package read-only by limiting the MCP tool surface to search, fetch, and log analytics tools. The plugin does not expose notebook writes, monitor edits, or other mutating Datadog tools.
+
+## Datadog site
+
+The packaged manifest defaults to the US1 endpoint (`mcp.datadoghq.com`) and enables the `core`, `apm`, and `error-tracking` toolsets. Teams on other Datadog sites (US3, US5, EU, AP1, AP2, GovCloud) set `DATADOG_SITE` in their Junior deployment env to their site host (e.g. `us5.datadoghq.com`, `datadoghq.eu`, `ddog-gov.com`). No code changes or plugin copy needed. See the [Datadog plugin docs](https://junior.sentry.dev/extend/datadog-plugin/) for the full site table.
+
+## Optional channel defaults
+
+If a Slack channel usually investigates the same Datadog environment or service, store that as a conversation-scoped default:
+
+```bash
+jr-rpc config set datadog.env prod
+jr-rpc config set datadog.service checkout
+```
+
+These defaults are optional fallbacks. If a user names a different env or service in a request, Junior should follow the explicit request instead.
+
+## Auth model
+
+- Datadog MCP requires user-based OAuth (OAuth 2.1 + PKCE) and does not accept shared bearer tokens here.
+- This package is not suitable for fully headless or unattended automation.
+- Users can disconnect from Junior App Home with `Unlink`, or by asking Junior to disconnect Datadog.
+
+Full setup guide: https://junior.sentry.dev/extend/datadog-plugin/

package/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "@sentry/junior-datadog",
+  "version": "0.25.0",
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "files": [
+    "plugin.yaml",
+    "skills"
+  ]
+}

package/plugin.yaml

@@ -0,0 +1,36 @@
+name: datadog
+description: Query Datadog telemetry (logs, metrics, traces, monitors, incidents, dashboards) via Datadog's hosted MCP server
+
+config-keys:
+  - env
+  - service
+
+# Datadog orgs are region-pinned. The MCP hostname must match the customer's
+# Datadog site. Non-US1 operators set DATADOG_SITE to their site host (e.g.
+# `us5.datadoghq.com`, `datadoghq.eu`, `ap1.datadoghq.com`, `ddog-gov.com`).
+# US1 operators can leave DATADOG_SITE unset and the default applies.
+env-vars:
+  DATADOG_SITE:
+    default: datadoghq.com
+
+mcp:
+  url: https://mcp.${DATADOG_SITE}/api/unstable/mcp-server/mcp?toolsets=core,apm,error-tracking
+  allowed-tools:
+    - analyze_datadog_logs
+    - get_datadog_incident
+    - get_datadog_metric
+    - get_datadog_metric_context
+    - get_datadog_notebook
+    - get_datadog_trace
+    - search_datadog_dashboards
+    - search_datadog_events
+    - search_datadog_hosts
+    - search_datadog_incidents
+    - search_datadog_logs
+    - search_datadog_metrics
+    - search_datadog_monitors
+    - search_datadog_notebooks
+    - search_datadog_rum_events
+    - search_datadog_service_dependencies
+    - search_datadog_services
+    - search_datadog_spans

package/skills/datadog/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: datadog
+description: Query live Datadog telemetry (logs, metrics, traces, spans, monitors, incidents, dashboards, services, hosts) through Datadog's hosted MCP server. Use when users ask to investigate production behavior in Datadog — searching logs, checking monitor status, inspecting traces or spans, looking up incidents, finding services, or correlating metrics. Do not use it for Sentry issues, repository/source-code work, or ticketing.
+uses-config: datadog.env datadog.service
+---
+
+# Datadog Operations
+
+Use this skill for Datadog observability investigations in the harness.
+
+## Reference loading
+
+Load references conditionally based on the request:
+
+| Need                                               | Read                                                                                                                       |
+| -------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
+| Any Datadog operation                              | [references/api-surface.md](references/api-surface.md)                                                                     |
+| Log search, metric query, trace lookup, incidents  | [references/common-use-cases.md](references/common-use-cases.md), [references/query-syntax.md](references/query-syntax.md) |
+| Auth failures, permission errors, or tool failures | [references/troubleshooting-workarounds.md](references/troubleshooting-workarounds.md)                                     |
+
+## Workflow
+
+1. Resolve the operation and target:
+
+- Determine whether the request is a log search, metric query, trace/span inspection, monitor lookup, incident lookup, dashboard/notebook lookup, service/host listing, or service-dependency map.
+- Prefer explicit env, service, host, monitor/incident IDs, trace IDs, or Datadog URLs when the user provides them.
+- When the user did not specify a scope, treat `datadog.env` and `datadog.service` conversation config as optional defaults. Explicit user input always wins over config.
+- Only set or change `datadog.env` and `datadog.service` when the user explicitly asks to store a default for this conversation or channel.
+- If the request refers to an earlier telemetry item indirectly (an incident, trace, or monitor already mentioned in the thread), inspect the current thread for the existing ID or URL before asking the user to restate it.
+- Ask one concise follow-up only when a search is genuinely under-specified, for example when the user asks about "errors" with no env, service, or time window hint and the thread has no prior context.
+
+2. Use the active Datadog MCP tools:
+
+- `loadSkill` returns `available_tools` for this skill, including the exact `tool_name` values and input schemas exposed in this turn.
+- Call those exact tool names directly. Use `searchTools` only if you need to rediscover or filter the active Datadog tools later in the same turn.
+- Start narrow: pick the single most direct tool for the request before reaching for broader search.
+  - Known incident ID → `get_datadog_incident`
+  - Known trace ID → `get_datadog_trace`
+  - Known notebook ID → `get_datadog_notebook`
+  - Known metric name → `get_datadog_metric` (and `get_datadog_metric_context` when the user wants available tags or dimensions)
+- For exploratory questions, prefer one `search_datadog_*` call with a tight query, then one follow-up fetch if needed.
+- For "what is the current error rate / log volume / top offenders" style questions, prefer `analyze_datadog_logs` (SQL-style aggregation) over pulling raw log pages back through `search_datadog_logs`.
+- For service-topology questions ("what calls checkout?", "what does the payment API depend on?"), prefer `search_datadog_service_dependencies` over manually stitching spans together.
+- Use `search_datadog_monitors` for "is this alerting?" or "what is monitor X doing?"; use `search_datadog_incidents` / `get_datadog_incident` for incident context.
+- Use `search_datadog_rum_events` only when the user asks about real-user / browser telemetry, not for backend issues.
+
+3. Bound every query:
+
+- Always constrain time windows. Default to the last 15 minutes for "right now" questions and the last 24 hours for retrospective questions; otherwise use the window the user named.
+- Always include `env:` when `datadog.env` is set or the user named an env.
+- Always include `service:` when the user named a service or `datadog.service` is set and the tool is service-scoped.
+- Cap result size. Prefer the default or small page sizes; do not page through thousands of logs when an aggregate tool answers the question.
+
+4. Report the result:
+
+- Return the concrete answer first (counts, status, incident severity, trace timing, top offenders), then a short evidence block.
+- Include Datadog deep links (e.g. `https://app.datadoghq.com/logs?query=...`, `https://app.datadoghq.com/apm/trace/<id>`, `https://app.datadoghq.com/incidents/<id>`) so Slack users can click through.
+- Preserve interesting spans, log lines, or metric values inline only when they are the evidence for the answer. Do not dump raw tool output.
+- Keep routine tool chatter silent. Do not narrate each MCP search or fetch step.
+
+## Guardrails
+
+- Read-only only in this skill. Do not create, edit, mute, or resolve monitors, incidents, notebooks, dashboards, SLOs, or feature flags — the plugin intentionally does not expose those tools.
+- Log, RUM, APM, and incident payloads can contain PII or sensitive customer data. Quote only the minimum needed to answer the question. Do not paste full raw log bodies or span payloads when a summary plus a deep link is enough.
+- If Datadog authorization is required, let the MCP OAuth flow pause and resume the thread automatically instead of asking the user to handle credentials manually.
+- If a Datadog tool returns a generic `403`, `permission denied`, or similar, stop and tell the user the current Datadog connection could not access the requested resource. Do not guess at missing RBAC scopes.
+- If Datadog responds with `429 Too Many Requests`, wait briefly and retry the same query once. If it still fails, report the throttle and stop.
+- For large traces that the server marks as truncated, report that fact; do not pretend the shown spans are complete.
+- Do not use this skill for Sentry issues, Linear/GitHub ticketing, or source-code investigation. Hand those off to the matching skill.

package/skills/datadog/references/api-surface.md

@@ -0,0 +1,95 @@
+# API Surface
+
+Use this reference for any Datadog operation.
+
+## Runtime contract
+
+- `loadSkill` returns `available_tools` for this skill, including the exact Datadog MCP `tool_name` values exposed in the current turn.
+- Call those exact `tool_name` values directly.
+- Use `searchTools` only when you need to rediscover or filter the active Datadog tools later in the same turn.
+- Do not hardcode raw Datadog MCP tool names in advance. Tool discovery is part of the workflow.
+- Return concrete findings plus Datadog deep links for navigation.
+
+## Provider surface
+
+The packaged plugin points at Datadog's hosted remote MCP server and enables the `core`, `apm`, and `error-tracking` toolsets. Tool exposure is intentionally limited to the read-oriented surface below.
+
+### Tools exposed in this skill
+
+| Tool                                  | Intent                                                                              |
+| ------------------------------------- | ----------------------------------------------------------------------------------- |
+| `search_datadog_logs`                 | Search raw log events by filter (service, host, env, status, query, time window).   |
+| `analyze_datadog_logs`                | SQL-style aggregation over logs for counts, group-bys, top-N, and numeric analysis. |
+| `search_datadog_events`               | Datadog Events API: deployments, infra changes, alerts, status events.              |
+| `search_datadog_metrics`              | List available metrics by name pattern, tag, or service.                            |
+| `get_datadog_metric`                  | Query a specific metric time series over a time window.                             |
+| `get_datadog_metric_context`          | Fetch metadata and available tag dimensions for a metric.                           |
+| `search_datadog_spans`                | Search APM spans by service, operation, tags, time, error state.                    |
+| `get_datadog_trace`                   | Fetch a full trace by trace ID.                                                     |
+| `search_datadog_services`             | List services from the Software Catalog with ownership and tag metadata.            |
+| `search_datadog_service_dependencies` | Upstream/downstream service map for a service, or services owned by a team.         |
+| `search_datadog_hosts`                | List monitored hosts with tags and health state.                                    |
+| `search_datadog_monitors`             | List monitors, their statuses, and alert conditions.                                |
+| `search_datadog_incidents`            | List incidents with severity, state, and metadata.                                  |
+| `get_datadog_incident`                | Retrieve a specific incident by ID (timeline detail may be absent).                 |
+| `search_datadog_dashboards`           | List available dashboards.                                                          |
+| `search_datadog_notebooks`            | List Datadog notebooks by author, tag, or content.                                  |
+| `get_datadog_notebook`                | Fetch a notebook by ID.                                                             |
+| `search_datadog_rum_events`           | Search Datadog RUM (Real User Monitoring) events for browser / frontend issues.     |
+
+### Tools intentionally not exposed
+
+- Notebook mutations (`create_datadog_notebook`, `edit_datadog_notebook`).
+- Monitor, SLO, or incident mutations.
+- Feature-flag, DBM, and security toolsets (the packaged URL does not request them).
+
+If a user asks for a mutation, stop and explain that this skill is read-only.
+
+## Operation patterns
+
+| Intent                                           | Minimum tool pattern                                                                                                                               |
+| ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| "Why is service X failing right now?"            | `search_datadog_monitors` + `analyze_datadog_logs` (top error counts by status or message) + optionally `get_datadog_trace` for one failing trace. |
+| "Show me errors for service X in the last hour." | `analyze_datadog_logs` for counts/top-N first; only fall back to `search_datadog_logs` if the user asked for specific log lines.                   |
+| "What is the status of monitor X?"               | `search_datadog_monitors` with the monitor name/tag, then cite state + last transition time.                                                       |
+| "Tell me about incident INC-123."                | `get_datadog_incident` directly. Only fall back to `search_datadog_incidents` if no ID is known.                                                   |
+| "What depends on the checkout service?"          | `search_datadog_service_dependencies` scoped to that service.                                                                                      |
+| "How did this trace spend its time?"             | `get_datadog_trace` by ID; cite the slowest spans.                                                                                                 |
+| "What tag values are valid for this metric?"     | `get_datadog_metric_context` before `get_datadog_metric`.                                                                                          |
+| "Which hosts are unhealthy?"                     | `search_datadog_hosts` filtered by health/tags.                                                                                                    |
+| "Find slow page loads."                          | `search_datadog_rum_events` with a page/speed filter.                                                                                              |
+
+## Config helpers
+
+Use these commands only when the user explicitly asks to inspect or store Datadog defaults for the current conversation/channel.
+
+Resolve env default:
+
+```bash
+jr-rpc config get datadog.env
+```
+
+Set env default:
+
+```bash
+jr-rpc config set datadog.env prod
+```
+
+Resolve service default:
+
+```bash
+jr-rpc config get datadog.service
+```
+
+Set service default:
+
+```bash
+jr-rpc config set datadog.service checkout
+```
+
+## Content expectations
+
+- Translate Slack-thread wording into stable observability language (env, service, status, span, monitor, incident, host).
+- Preserve material URLs present in the conversation (Sentry, GitHub, dashboards, prior Datadog links) when they add evidence.
+- Include Datadog deep links (`https://app.datadoghq.com/...`) with the answer so users can click through.
+- Label assumptions clearly when the thread leaves important details uncertain (chosen env, chosen time window, chosen service).

package/skills/datadog/references/common-use-cases.md

@@ -0,0 +1,84 @@
+# Common Use Cases
+
+Use these patterns to shape concrete Datadog requests.
+
+## 1. Triage "service X is failing right now"
+
+- Default the time window to the last 15 minutes unless the user gave a different one.
+- Constrain by `service:` and `env:` (explicit user input wins; fall back to `datadog.service` / `datadog.env`).
+- `search_datadog_monitors` for `service:<x>` first — a firing monitor usually names the failure mode.
+- Then `analyze_datadog_logs` to aggregate by status/level/message to find the top error shape.
+- If the user asks "why", fetch one representative failing trace with `get_datadog_trace` or `search_datadog_spans` filtered to `service:<x> status:error`.
+- Report monitor state, top error, and one failing trace link — not a dump.
+
+## 2. "Is this monitor alerting?"
+
+- Use `search_datadog_monitors` with the monitor name, tag, or ID.
+- Report state (`OK`, `Warn`, `Alert`, `No Data`), last transition, and the monitor link.
+- If the monitor is in `No Data`, note that explicitly — it is not the same as healthy.
+
+## 3. "Tell me about incident INC-123" or "What is the status of the Redis incident?"
+
+- If the user named the incident ID, go straight to `get_datadog_incident`.
+- If only a topic was named, use `search_datadog_incidents` filtered by active/severity and scan for a match in the thread's time window.
+- Report severity, state, owner, and link to the incident.
+- Note that incident timeline detail may be absent from the MCP response; do not fabricate timeline entries.
+
+## 4. Log search with a specific query
+
+- Default to `search_datadog_logs` only when the user explicitly wants raw log lines.
+- Constrain with `service:`, `env:`, `status:`, `host:`, or `@<faceted_field>:` as appropriate (see `query-syntax.md`).
+- Cap page size and time window to avoid huge responses.
+- Report a short summary plus a Datadog logs deep link. Quote only the minimum log content.
+
+## 5. "What are the top errors for service X right now?"
+
+- Prefer `analyze_datadog_logs` with a SQL-style `GROUP BY status` or `GROUP BY @http.status_code` / `GROUP BY @error.kind`.
+- Report the top 3-5 buckets with counts, not an exhaustive table.
+- Include the aggregated query link so the user can open the same view in Datadog.
+
+## 6. Trace inspection by ID
+
+- Use `get_datadog_trace` with the trace ID.
+- Cite the top 3 slowest or error-tagged spans (service, operation, duration, error state).
+- If the server marks the trace as truncated, say so — some spans are not present.
+
+## 7. Span search for a known error pattern
+
+- Use `search_datadog_spans` with explicit filters like `service:<x> status:error resource_name:"..."` and a bounded time window.
+- Report span counts plus the most illustrative span's trace link.
+
+## 8. Service topology lookup
+
+- Use `search_datadog_service_dependencies` to answer "what calls X?" or "what does X depend on?" or "what does team Y own?".
+- Return the dependency list with service names and link back to the Service Catalog page.
+
+## 9. Metric lookup
+
+- Use `search_datadog_metrics` when the user is unsure of the metric name.
+- Once the metric name is known, use `get_datadog_metric` with the time window and tag filters.
+- Use `get_datadog_metric_context` before querying if the user wants to know which tags (`env`, `service`, `host`, ...) are usable.
+- Report headline numbers (current, peak, delta) plus a metric explorer link.
+
+## 10. Host health
+
+- Use `search_datadog_hosts` filtered by tag, role, or `down:true`.
+- Return counts, the list of unhealthy hosts (names + tags), and a host map link.
+
+## 11. RUM / frontend slowness
+
+- Use `search_datadog_rum_events` only when the user asked about end-user / browser experience.
+- Constrain to `@type:error`, slow page loads, or specific views; bound the time window.
+- Do not use RUM for backend errors — those live in logs/APM.
+
+## 12. Dashboards and notebooks
+
+- `search_datadog_dashboards` to list dashboards by topic, team, or tag — useful for "do we already have a dashboard for X?".
+- `search_datadog_notebooks` + `get_datadog_notebook` for reading existing investigation notebooks.
+- This skill does not create or edit dashboards or notebooks. If the user asks, stop and say so.
+
+## 13. Storing channel defaults
+
+- Use `jr-rpc config set datadog.env <env>` only when the user explicitly asks to store an env default for the conversation/channel.
+- Use `jr-rpc config set datadog.service <service>` only when the user explicitly asks to store a service default for the conversation/channel.
+- Treat both defaults as optional fallbacks. Explicit user input wins whenever a request names a different env or service.

package/skills/datadog/references/query-syntax.md

@@ -0,0 +1,77 @@
+# Query Syntax
+
+Use this reference when forming Datadog log queries, span queries, and log analytics (`analyze_datadog_logs`) SQL.
+
+## Log search query syntax
+
+Datadog log search queries are tag-and-facet based. Core building blocks:
+
+| Form               | Meaning                                                              |
+| ------------------ | -------------------------------------------------------------------- |
+| `service:<name>`   | Reserved attribute — service emitting the log.                       |
+| `env:<name>`       | Reserved attribute — deployment environment tag.                     |
+| `host:<name>`      | Reserved attribute — emitting host.                                  |
+| `status:<level>`   | Log level: `error`, `warn`, `info`, `debug`, etc.                    |
+| `source:<name>`    | Log source integration (e.g. `nginx`, `python`).                     |
+| `@<field>:<value>` | Faceted attribute (custom JSON field), e.g. `@http.status_code:500`. |
+| `"some phrase"`    | Free-text phrase search.                                             |
+| `AND`, `OR`, `-`   | Boolean ops; `-` negates. Default operator between terms is `AND`.   |
+| `(a OR b) AND c`   | Parenthesized boolean expression.                                    |
+
+Common examples:
+
+- `service:checkout env:prod status:error`
+- `service:api env:prod @http.status_code:(500 OR 502 OR 503)`
+- `service:worker -status:info "timeout"`
+- `@error.kind:DatabaseError env:prod`
+
+Tips:
+
+- Prefer `@<field>:` form over free-text search when the field exists. Facet matches are cheaper and more precise.
+- `status` and `@http.status_code` are different. `status` is the log level; `@http.status_code` is the HTTP response code.
+- Reserved attributes (`service`, `env`, `host`, `status`, `source`) do not take the `@` prefix. Custom fields do.
+
+## Span / APM search
+
+APM span search shares the same query language, plus a few APM-specific attributes:
+
+| Attribute          | Meaning                                    |
+| ------------------ | ------------------------------------------ |
+| `service:<name>`   | Service emitting the span.                 |
+| `env:<name>`       | Deployment environment tag.                |
+| `operation_name:X` | Span operation name (e.g. `http.request`). |
+| `resource_name:X`  | Endpoint or handler.                       |
+| `status:error`     | Span is marked as an error.                |
+| `duration:>500ms`  | Range filter on span duration.             |
+
+## `analyze_datadog_logs` SQL
+
+`analyze_datadog_logs` takes SQL-like aggregations over the same log data. Prefer it for counts, top-N, group-bys, and time-bucketed analytics instead of paging raw logs.
+
+Conventions:
+
+- Wrap log query filters in a `WHERE` clause using the same log-search query syntax (quoted as a string).
+- Use `COUNT(*)` for volume, `COUNT(DISTINCT <field>)` for unique cardinality.
+- `GROUP BY` faceted fields (without `@` in the SQL form — the tool's schema specifies how to reference them; follow the tool's input schema exactly).
+- Cap with `ORDER BY ... DESC LIMIT N` — top 5-10 is usually enough.
+
+Example intents (shape — not a literal string; call the tool with the input schema it advertises):
+
+- Top 10 services by error count in the last hour.
+- HTTP 5xx count by status code in the last 15 minutes, grouped by `@http.status_code`.
+- Log volume by `host` over the last hour to spot a noisy emitter.
+
+## Time windows
+
+- For "right now" questions, default to the last 15 minutes.
+- For "what happened earlier today" questions, default to the last 24 hours.
+- For incident-linked questions, prefer a window that brackets the incident `created` time.
+- Always include a time window — unbounded queries are slow and easy to misinterpret.
+
+## What to cite back
+
+- The exact query string used (`service:checkout env:prod status:error`) — users often want to click through.
+- A Datadog deep link that encodes the same filter:
+  - `https://app.datadoghq.com/logs?query=<url-encoded-query>&from_ts=<ms>&to_ts=<ms>`
+  - `https://app.datadoghq.com/apm/traces?query=<url-encoded-query>`
+- The time window you used.

package/skills/datadog/references/troubleshooting-workarounds.md

@@ -0,0 +1,47 @@
+# Troubleshooting and Workarounds
+
+Use this reference when Datadog MCP calls fail or return unexpected results.
+
+## Authentication and connection
+
+| Symptom                                                            | Likely cause                                                | What to do                                                                                                                     |
+| ------------------------------------------------------------------ | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| Tool call returns an authorization-required signal before running. | User has not yet completed the Datadog OAuth flow in Slack. | Let the runtime DM the user the authorization link and pause the turn. Do not prompt for credentials manually.                 |
+| Tool call returned `401` mid-session.                              | OAuth token expired or was revoked.                         | Expect Junior's MCP layer to resurface the authorization flow. Retry once the user has re-authorized; do not loop before that. |
+| OAuth callback did not resume the thread.                          | User closed the browser before the redirect completed.      | Ask the user to retry the request — the OAuth flow will restart and complete if they finish it this time.                      |
+
+## Permission and scope errors
+
+- A Datadog API returning `403 Forbidden` or `permission denied` means the user's Datadog role cannot read that resource (metrics, APM, incidents, RUM, etc.).
+- Stop and tell the user the current Datadog connection could not access the requested data. Suggest they verify their Datadog role/team.
+- Do not guess specific missing permission names unless Datadog explicitly named one in the error.
+- Do not loop retrying a 403.
+
+## Rate limits
+
+- Datadog throttles the unstable MCP endpoint. A `429 Too Many Requests` response is expected under load.
+- Retry the same query once after a short wait.
+- If it fails again, report the throttle and stop. Do not fall back to larger scans that will throttle harder.
+
+## Query returned no results
+
+- Double-check that `env:` and `service:` match real values. Datadog tag values are case-sensitive.
+- Widen the time window before widening the filter. Many "no results" cases are just too narrow a window.
+- If searching logs with `@<field>:value`, confirm the field exists as a facet; custom log attributes must be facetized in Datadog to be searchable.
+- If an expected monitor or incident is missing, the user's account may not have access to that workspace or team.
+
+## Too many results / large payloads
+
+- Prefer `analyze_datadog_logs` with `GROUP BY` + `LIMIT` over paging raw logs.
+- For traces marked truncated by the server, say so in the reply. Do not pretend the shown spans are complete.
+- Quote only the minimum log / span / metric content needed as evidence. Link to Datadog for the rest.
+
+## Multiple Datadog sites
+
+- The packaged plugin defaults to the US1 endpoint (`mcp.datadoghq.com`). The manifest declares `DATADOG_SITE` in its `env-vars` block with a default of `datadoghq.com` and references it from `mcp.url` as `${DATADOG_SITE}`, so non-US1 operators (US3, US5, EU, AP1, AP2, GovCloud) set `DATADOG_SITE` in their Junior deployment env to their site host (e.g. `us5.datadoghq.com`, `datadoghq.eu`, `ddog-gov.com`). Users hitting auth failures against the wrong regional endpoint should have the operator confirm `DATADOG_SITE` is set correctly.
+- If the user's Datadog account lives on a different site than the deployment is configured for, advise the operator to update the `DATADOG_SITE` environment variable. Do not try to work around this silently inside a turn.
+
+## Read-only scope
+
+- This skill intentionally exposes only read-oriented Datadog tools.
+- If the user asks to create a notebook, edit a monitor, mute an alert, or resolve an incident, stop and tell them those actions are not in scope. Do not attempt to approximate the mutation from read tools.