discord.tmpl

Overview

The `discord.tmpl` file is a Go template used by the Alertmanager component of the monitoring system to format alert notifications sent to Discord channels. Its primary purpose is to generate human-readable and well-structured alert messages that provide clear context about the status and details of alerts triggered by Prometheus.

This template is part of the alerting configuration for the ShapeShift Unchained platform, enabling the delivery of timely and informative alerts directly into Discord channels. It complements the alert routing and notification logic defined in Alertmanager’s configuration, ensuring that messages are clear, concise, and actionable for the on-call teams.

Detailed Explanation

The file defines two template blocks:

1. discord.title

• Purpose:
  Generates the title of the Discord notification message. This title summarizes the alert status and the alert name, providing a quick overview in the notification header or embed title.

• Template Definition:

  {{ define "discord.title" }}
  Unchained Alert {{ .Status | title }}: {{ .GroupLabels.alertname }}
  {{ end }}
  

• Parameters (Context Variables):

  • .Status: The current status of the alert group (e.g., "firing", "resolved"). The template applies the title function to capitalize the first letter.

  • .GroupLabels.alertname: The name of the alert group, typically the alert rule name.

• Return Value:
  A string title formatted as:
  Unchained Alert <Status>: <AlertName>

• Example Usage:
  If the alert group status is firing and the alert name is UnchainedStatefulSetDown, the resulting title would be:
  Unchained Alert Firing: UnchainedStatefulSetDown

2. discord.message

• Purpose:
  Constructs the detailed message body for the Discord notification. It iterates over all alerts in the group, formatting each alert’s severity, summary, description, and labels in a readable markdown style.

• Template Definition:

  {{ define "discord.message" }}
  {{ range .Alerts }}
  **{{ .Labels.severity | toUpper }}**
  
  **Alert:** {{ .Annotations.summary }}
  **Description:** {{ .Annotations.description }}
  
  **Details:**
  {{ range .Labels.SortedPairs }}{{ printf "- %s: %s\n" .Name .Value }}{{ end }}
  {{ end }}
  {{ end }}
  

• Parameters (Context Variables):

  • .Alerts: A list of alert objects in the current group.

  • For each .Alert:

    • .Labels.severity: Severity level of the alert (e.g., critical, warning).

    • .Annotations.summary: A short summary of the alert condition.

    • .Annotations.description: A detailed description explaining the alert.

    • .Labels.SortedPairs: A sorted list of label key-value pairs for the alert, providing additional contextual metadata.

• Return Value:
  A markdown-formatted string with:

  • The severity in uppercase and bold.

  • The alert summary and description.

  • A list of labels and their values for detailed context.

• Example Usage:
  For an alert with:

  • Severity: critical

  • Summary: Unchained stateful set is currently down

  • Description: Service foo has been down for more than 15 minutes

  • Labels: namespace=unchained, statefulset=foo

  The generated message would be:

  **CRITICAL**
  
  **Alert:** Unchained stateful set is currently down
  **Description:** Service foo has been down for more than 15 minutes
  
  **Details:**
  - namespace: unchained
  - statefulset: foo
  

Implementation Details

• The template uses Go’s text/template syntax with custom functions:

  • title: Capitalizes the first letter of the string.

  • toUpper: Converts strings to uppercase.

• It leverages iteration (range) to process multiple alerts in a notification batch.

• Sorting label pairs (SortedPairs) ensures consistent and predictable label order in messages.

• The markdown formatting (**bold**, - list items) is tailored for Discord's message rendering for clarity.

Interaction with Other System Components

• Alertmanager:
  This template is referenced by Alertmanager’s notification configuration for Discord receivers. When Alertmanager routes alerts to Discord, it uses the discord.title and discord.message templates to construct the message payload sent via webhooks.

• Prometheus Alerting Rules:
  Prometheus evaluates alert rules and forwards firing alerts to Alertmanager. The alerts include metadata (labels and annotations) that populate this template.

• Discord Webhooks:
  The formatted messages generated by this template are sent to Discord channels through webhook URLs configured in Alertmanager's receivers. This integration ensures operational teams receive alerts in their communication channels.

• Alert Routing and Grouping:
  Alerts are grouped and batched by Alertmanager before being passed to this template, which then formats all alerts in a group within one message.

Usage Example in Alertmanager Configuration

receivers:
  - name: "discord_critical"
    webhook_configs:
    - url: "https://discord.com/api/webhooks/..."
      send_resolved: true
      http_config:
        # ...
      message: |
        {{ template "discord.message" . }}
      title: |
        {{ template "discord.title" . }}

Visual Diagram

flowchart TD
    A[Alertmanager] -->|Passes Alert Group| B["discord.title" Template]
    A -->|Passes Alert Group| C["discord.message" Template]
    B --> D[Formatted Title String]
    C --> E[Formatted Message Body]
    D & E --> F[Discord Notification Payload]
    F --> G[Discord Webhook]
    G --> H[Discord Channel]

    subgraph Template Rendering
        B
        C
    end

    style A fill:#f9f,stroke:#333,stroke-width:1px
    style G fill:#4f8ef7,stroke:#333,stroke-width:1px,color:#fff
    style H fill:#7289da,stroke:#333,stroke-width:1px,color:#fff

Summary

• The discord.tmpl file defines Go templates for formatting alert titles and messages sent to Discord.

• It improves alert readability and context for teams monitoring the ShapeShift Unchained platform.

• It works in conjunction with Prometheus alert rules and Alertmanager routing to deliver meaningful notifications.

• The template uses Go templating features to dynamically generate markdown content tailored for Discord.

• This templating approach enables flexible, maintainable, and clear alert communication.

*End of documentation for `discord.tmpl`*