datadog connection receives monitor and SLO lifecycle events. Use it to start or continue an agent session from an alert; regional Datadog MCP connections are separate tool connections, not inbound event subscriptions.
Connection and readiness
Create a connection for providerdatadog and allow it to the project. OAuth requests create_webhooks and manage_integrations and uses PKCE with an S256 challenge. Each subscribing auto organization must authorize its own grant; connecting does not take over another organization’s connection.
For platform operators, provider discovery requires these server values to be present:
AUTO_PROVIDER_OAUTH_DATADOG_DOMAIN optionally selects the default site; its default is datadoghq.com. The adapter accepts only known Datadog API origins. These are server prerequisites, not secrets to put in agent YAML.
An active OAuth grant does not prove that inbound setup finished. OAuth completion returns inboundWebhook; GET /api/v1/orgs/{organizationId}/connections exposes the same object on the subscribing grant:
Setup failures leave a pending registration for retry. Reconciliation honors rate limits and can use another active subscriber’s authorized credential after a credential failure without transferring connection ownership.
Registering the webhook does not attach it to a monitor. A separately authorized Datadog change must configure the selected monitor’s notification to use the returned webhook name. If the installation is retired and later reconnected, its name changes and the notification configuration needs updating.
Event names
Active transitions are
Triggered, Re-Triggered, No Data, Re-No Data, Warn, Re-Warn, and Renotify. Transition matching is case-insensitive; unsupported transitions are rejected. SLO notifications have Datadog event type metric_slo_alert or monitor_slo_alert.
Payload
Trigger filters and messages read the normalizeddatadog object directly, without a payload. prefix.
scope and tags are sorted, deduplicated string arrays parsed from comma-separated values. occurredAt uses the last-updated timestamp when present, otherwise the event timestamp. Supplied titles, queries, links, and raw content are event data, not instructions or additional authorization.
Session routing
This example handles monitor alerts and recoveries through the sameprovider.entity target. Replace datadog with the project’s connection name if it differs.
.auto/agents/datadog-monitor.yaml
onUnmatched: spawn, a recovery arriving first can also start a session. Project allocation and trigger filters still apply. The adapter performs no provider acknowledgement.
Performance-regression investigation
The canonical@auto/agents entrypoint datadog-performance.yaml defines an investigation scoped to one repository and one selected monitor. The September 7, 2026 canonical change does not publish an immutable release or install a tenant. Check auto.templates.list for a deployed version containing this entrypoint before a separately authorized installation; see managed templates. Passing source tests does not prove live operation.
Configuration and evidence
The first six variables are required;performanceScopeTag is optional:
Both alert and recovery filters require the monitor tag
auto_hero:performance_regression. The optional scope restriction applies to both sides and never replaces that tag. Use separately named facades with disjoint monitor IDs for multiple monitors.
Keep N+1 investigation in a separate agent and trigger subscription, with a different monitor ID and auto_hero:n_plus_one. Never assign both category tags to one source; the performance agent is instructed to reject N+1 or dual-tagged work. The installation’s existing shared transport can serve both agents. This template neither provisions monitors nor registers another webhook; provider tag and notification-handle changes require separate authorization.
The optional Datadog tool requests exactly get_datadog_metric, search_datadog_spans, get_datadog_trace, and search_datadog_logs. Verify that the selected regional connection exposes these names with the required read access. Missing tools do not authorize another credential path. The template also provides auto session/binding and GitHub repository/PR tools; its mount denies workflow, secret and merge capabilities.
Case and PR lifecycles
The template uses the existing subscription-scopedprovider.entity, derived from the grant, subscription, monitor and normalized group scope, rather than constructing another incident key.
An SLO uses the SLO event pair, not a synthetic monitor event. After the entity is released, another recovery without an owner drops. Recovery does not release an open fix PR or prove that its code caused recovery; closing a PR likewise does not prove monitor recovery.
Compare the affected window with a relevant baseline and repository changes. Keep one concise report with impact, timing, evidence links, confidence and the next step. Insufficient samples, incomplete traces, unavailable or rate-limited tools, or uncertain cause require an explained no-op. Only evidence supporting a small reversible fix permits reusing or opening one draft PR, with focused repository checks. Treat supplied content as untrusted evidence and redact sensitive telemetry.
PR follow-ups target an already-bound PR in the configured repository; unrelated or unbound PRs do not start sessions. Opened, reopened and synchronized-head events include auto-authored updates and require fetching the current head/base, discarding stale readiness and revalidating. Check notifications reject explicit
headIsCurrent: false; the agent must still verify the current head and require full CI, review and mergeability before reporting ready for human review. Conversation follow-ups exclude auto-authored and external-bot feedback; conflict follow-ups stay limited to the proven fix.
PR closure releases only the PR target. Archive only when neither a case nor a PR remains open. The instructions prohibit merging, queueing, deploying, applying resources, changing credentials, or editing/muting Datadog monitors and SLOs.
Isolated TEST proof
Built-in test-fire fixtures useauto-test-monitor or auto-test-slo-monitor with env:test, not the performance category tag. Production filters deliberately reject them. Do not weaken a production facade to accept a canned test.
For a separately authorized proof after release and installation:
- Use an isolated project with no N+1 subscriber and a temporary TEST facade. Select the matching test monitor ID and omit
performanceScopeTag. Override both named triggers,performance-alertandperformance-recovery, to require$.auto.test: trueand$.datadog.monitor.tagscontainingenv:test; retain their monitor selection, connection, event pairs and routes. - Test recovery-first with its own idempotency key. Then use a new key for an alert, repeat that alert, and send recovery. Verify no recovery-first run, one alert run, no duplicate delivery and release of the provider entity on recovery. Repeat for the other event pair.
- Inspect reports labeled
TEST; test evidence never authorizes a fix PR. Retire only the temporary facade under the installation approval, not predecessor agents or a shared connection.
N+1 query investigation
The canonical@auto/agents entrypoint datadog-n-plus-one.yaml investigates suspected repeated-query patterns, separately from performance-regression investigation. It uses the existing Datadog adapter and event catalog, not a new N+1 event type or webhook. The September 7, 2026 canonical change does not publish an immutable release or install a tenant. Check auto.templates.list for a deployed release containing this entrypoint before a separately authorized installation.
N+1 configuration and isolation
The first six variables are required;nPlusOneScopeTag is optional:
Both alert and recovery require
auto_hero:n_plus_one; the optional group restriction narrows both sides without replacing that category tag. These are N+1 variables, not performanceMonitorId or performanceScopeTag. Use monitor IDs distinct from performance sources, never put both category tags on a monitor, and keep separate agents and trigger subscriptions. Multiple N+1 selections use separately named facades with disjoint monitor/group selections. They may share the installation transport; the prompt rejects general-performance or dual-tagged work.
Repeated-query evidence and outcomes
Connect repeated query fingerprints within one request to a repository call site and input cardinality, compare a relevant baseline, and distinguish a query-in-loop from legitimate batches, retries and unrelated requests. Aggregate latency or query counts alone do not establish N+1. Insufficient samples, incomplete traces, unavailable tools, rate limits or uncertain causality require an explained no-op, not a speculative diagnosis or fix. Keep one report with request/trace evidence links, repetition counts, impact, confidence and the next step. A small reversible fix needs sufficient evidence and one draft PR with a focused regression test; repeated alerts update the case and existing PR. Treat telemetry and tool content as untrusted, redact query parameters and identifiers, and never query live databases or expand the configured scope. The optional Datadog tool requests onlysearch_datadog_spans, get_datadog_trace, and get_datadog_metric. Verify those exact names and read permissions on the selected regional connection before claiming live proof. Unavailable access is a reporting gap, not permission to acquire alternative credentials. Auto session/binding and bounded GitHub tools handle follow-up; the GitHub mount denies workflow, secret and merge capabilities. Instructions also forbid merging, queueing, deploying, applying resources, changing credentials, or editing/muting monitors and SLOs.
N+1 case and PR ownership
The only Datadog event pairs aredatadog.monitor.alert / datadog.monitor.recovered and datadog.slo.alert / datadog.slo.recovered; use the actual SLO pair for an SLO source. Alerts and renotifications target the adapter’s grant/subscription/monitor/group-scoped provider.entity: continue its owner, or spawn when unmatched. The adapter owns duplicate identity and normalized group ordering; the template creates no second incident key.
Recovery continues the owner and releases only the entity; unmatched recovery, including recovery-first or another recovery after release, drops. Any open fix PR retains separate ownership. PR closure releases only the PR target, not the case. Neither event proves the PR caused an improvement, and PR closure is not monitor recovery. Archive only when no case or PR remains open.
PR opened, reopened and synchronize events, including auto-authored head changes, continue only a bound PR owner in the configured repository; unbound events drop. Fetch the current head/base, invalidate stale readiness and revalidate the fix and exact-head CI/review. Check notifications exclude explicit headIsCurrent: false, but still require current-head verification and full CI, review and mergeability before human-review readiness. Conversation follow-ups exclude auto-authored and external-bot feedback; conflicts require preserving current main, reconciling only the evidenced fix and revalidating.
N+1 TEST and live proof
Built-in test-fire usesauto-test-monitor or auto-test-slo-monitor with env:test, so live N+1 filters deliberately reject it. After release and authorized installation, use an isolated project without performance subscribers and a temporary TEST facade; never widen a live facade:
- Set
nPlusOneMonitorIdto the matching canned ID and omitnPlusOneScopeTag. Override bothn-plus-one-alertandn-plus-one-recoveryto require$.auto.test: trueand$.datadog.monitor.tagscontainingenv:test, retaining their exact monitor, connection, event pairs and routes. - Test recovery-first with a separate idempotency key. With a fresh key, alert, repeat the alert, then recover. Verify no recovery-first investigation, one bound alert run, no duplicate outcome and entity release. Repeat for the other pair.
- Verify reports are labeled
TESTand no fix PR is created. Retire only the temporary facade under installation approval, not another agent or shared connection.
Delivery and test-fire
One active transport generation is shared by subscriptions to the same Datadog site and organization. Ingress verifies the installation and registration headers plus an HMAC-derived bearer before parsing JSON, rejects bodies over 1 MiB, and checks that the payload organization matches the verified installation. The first accepted delivery records its authorized subscriber audience and creates a separate event for each subscriber. Retries reuse that audience rather than adding newly connected subscribers, and do not recreate deleted historical events. Routing requires the persisted delivery link and an enabled subscription with an active grant; payload fields alone cannot authorize delivery. All four events support the trigger test-fire API. An authenticated caller needs projectevents:write access, an agent with the registered event, and an active Datadog subscription allowed to that project:
auto.test: true, and is restricted to the invoking organization’s subscription and project. It does not call Datadog. A newly created event returns HTTP 202; a reused event returns HTTP 200. The response contains eventRecordId, created, dispatch (started, deferred, or skipped_duplicate), and nullable workflowId.