How to Customize PagerDuty Custom Details in Grafana: The Hidden Override Method

Why It Matters

Streamlined PagerDuty payloads accelerate on‑call response and reduce alert fatigue, directly improving incident resolution efficiency for SRE and DBA teams.

Key Takeaways

• Override `firing` key reduces incident payload size.
• Custom details improve on‑call response speed.
• Grafana merges user details over defaults automatically.
• Resolved key can also be overridden for clean closures.
• Notification templates enable conditional, multi‑line payloads.

Pulse Analysis

Integrations between Grafana and PagerDuty are a staple of modern observability stacks, yet many teams stumble over the default behavior that bundles every label and annotation into the incident details. This verbose output not only clutters the PagerDuty UI but also forces engineers to sift through irrelevant data during high‑pressure incidents. Understanding why the payload is so expansive—Grafana’s internal "defaultDetails" map—provides the first clue that the system is designed for extensibility, not for terse messaging.

The breakthrough comes from Grafana’s mergeDetails function, which prioritizes user‑defined key/value pairs over its built‑in templates. By simply adding a custom key called "firing" (or "resolved") in the PagerDuty contact point’s Details section, the default text block is replaced with a concise value drawn from common labels, such as {{ .CommonLabels.alertname }}. This approach scales: teams can add additional keys like "cluster" or "environment" to surface the most critical context. For more sophisticated formatting, Grafana supports Notification Templates, allowing conditional sections and multi‑line layouts that still respect the same override mechanism.

From a business perspective, cleaner incident data translates into faster triage, more accurate routing rules, and reduced cognitive load for on‑call engineers. Downstream integrations—Slack, Microsoft Teams, or custom webhooks—inherit the streamlined payload, ensuring consistent messaging across the organization. While overriding the entire "__text_alert_list" template is possible, it affects all contact points and should be used cautiously. Adopting the targeted "firing" override offers a low‑risk, high‑reward improvement that aligns observability tooling with enterprise incident‑management best practices.